Add methods that make it easy to copy an entity with a new ID or copy…

… an unidentified entity and give it an ID

Sources/JSONAPI/Resource/Entity.swift

@@ -383,10 +383,15 @@ extension Entity where MetaType == NoMetadata, LinksType == NoLinks, EntityRawId
 public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 
 	/// An Entity.Pointer is a `ToOneRelationship` with no metadata or links.
-	/// This is just a convenient way to reference an Entity given that
+	/// This is just a convenient way to reference an Entity so that
 	/// other Entities' Relationships can be built up from it.
 	public typealias Pointer = ToOneRelationship<Entity, NoMetadata, NoLinks>
 
+	/// Entity.Pointers is a `ToManyRelationship` with no metadata or links.
+	/// This is just a convenient way to reference a bunch of Entities so
+	/// that other Entities' Relationships can be built up from them.
+	public typealias Pointers = ToManyRelationship<Entity, NoMetadata, NoLinks>
+
 	/// Get a pointer to this entity that can be used as a
 	/// relationship to another entity.
 	public var pointer: Pointer {
@@ -398,6 +403,27 @@ public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 	}
 }
 
+// MARK: Identifying Unidentified Entities
+public extension Entity where EntityRawIdType == Unidentified {
+	/// Create a new Entity from this one with a newly created
+	/// unique Id of the given type.
+	public func identified<RawIdType: CreatableRawIdType>(byType: RawIdType.Type) -> Entity<Description, MetaType, LinksType, RawIdType> {
+		return .init(attributes: attributes, relationships: relationships, meta: meta, links: links)
+	}
+
+	/// Create a new Entity from this one with the given Id.
+	public func identified<RawIdType: JSONAPI.RawIdType>(by id: RawIdType) -> Entity<Description, MetaType, LinksType, RawIdType> {
+		return .init(id: Entity<Description, MetaType, LinksType, RawIdType>.Identifier(rawValue: id), attributes: attributes, relationships: relationships, meta: meta, links: links)
+	}
+}
+
+public extension Entity where EntityRawIdType: CreatableRawIdType {
+	/// Create a copy of this Entity with a new unique Id.
+	public func withNewIdentifier() -> Entity {
+		return Entity(attributes: attributes, relationships: relationships, meta: meta, links: links)
+	}
+}
+
 // MARK: Attribute Access
 public extension EntityProxy {
 	/// Access the attribute at the given keypath. This just

Tests/JSONAPITests/Entity/EntityTests.swift

@@ -101,6 +101,36 @@ class EntityTests: XCTestCase {
 	}
 }
 
+// MARK: - Identifying entity copies
+extension EntityTests {
+	func test_copyIdentifiedByType() {
+		let unidentifiedEntity = UnidentifiedTestEntity(attributes: .init(me: .init(value: "hello")), relationships: .none, meta: .none, links: .none)
+
+		let identifiedCopy = unidentifiedEntity.identified(byType: String.self)
+
+		XCTAssertEqual(unidentifiedEntity.attributes, identifiedCopy.attributes)
+		XCTAssertEqual(unidentifiedEntity.relationships, identifiedCopy.relationships)
+	}
+
+	func test_copyIdentifiedByValue() {
+		let unidentifiedEntity = UnidentifiedTestEntity(attributes: .init(me: .init(value: "hello")), relationships: .none, meta: .none, links: .none)
+
+		let identifiedCopy = unidentifiedEntity.identified(by: "hello")
+
+		XCTAssertEqual(unidentifiedEntity.attributes, identifiedCopy.attributes)
+		XCTAssertEqual(unidentifiedEntity.relationships, identifiedCopy.relationships)
+		XCTAssertEqual(identifiedCopy.id, "hello")
+	}
+
+	func test_copyWithNewId() {
+		let identifiedEntity = TestEntity1(attributes: .none, relationships: .none, meta: .none, links: .none)
+
+		let identifiedCopy = identifiedEntity.withNewIdentifier()
+
+		XCTAssertNotEqual(identifiedEntity.id, identifiedCopy.id)
+	}
+}
+
 // MARK: - Encode/Decode
 extension EntityTests {