Add ability to differentiate between things that _act_ like Entities and things that _are_ entities in the sense that the latter are persisted between client and server but the former is just a clientside convenience.

Author: mattpolzin

Sources/JSONAPI/Resource/Entity.swift

@@ -16,11 +16,15 @@ public typealias Attributes = Codable & Equatable
 
 /// Can be used as `Relationships` Type for Entities that do not
 /// have any Relationships.
-public struct NoRelationships: Relationships {}
+public struct NoRelationships: Relationships {
+	public static var none: NoRelationships { return .init() }
+}
 
 /// Can be used as `Attributes` Type for Entities that do not
 /// have any Attributes.
-public struct NoAttributes: Attributes {}
+public struct NoAttributes: Attributes {
+	public static var none: NoAttributes { return .init() }
+}
 
 /// An `EntityDescription` describes a JSON API
 /// Resource Object. The Resource Object
@@ -34,10 +38,10 @@ public protocol EntityDescription {
 	static var type: String { get }
 }
 
-/// EntityType is the protocol that Entity conforms to. This
-/// protocol lets other types accept any Entity as a generic
-/// specialization.
-public protocol EntityType: PrimaryResource {
+/// EntityProxy is a protocol that can be used to create
+/// types that _act_ like Entities but cannot be encoded
+/// or decoded as Entities.
+public protocol EntityProxy: Equatable {
 	associatedtype Description: EntityDescription
 	associatedtype EntityRawIdType: JSONAPI.MaybeRawId
 
@@ -59,17 +63,24 @@ public protocol EntityType: PrimaryResource {
 	var relationships: Relationships { get }
 }
 
+extension EntityProxy {
+	/// The JSON API compliant "type" of this `Entity`.
+	public static var type: String { return Description.type }
+}
+
+/// EntityType is the protocol that Entity conforms to. This
+/// protocol lets other types accept any Entity as a generic
+/// specialization.
+public protocol EntityType: EntityProxy, PrimaryResource {
+}
+
 public protocol IdentifiableEntityType: EntityType, Relatable where EntityRawIdType: JSONAPI.RawIdType {}
 
 /// An `Entity` is a single model type that can be
 /// encoded to or decoded from a JSON API
 /// "Resource Object."
 /// See https://jsonapi.org/format/#document-resource-objects
 public struct Entity<Description: JSONAPI.EntityDescription, EntityRawIdType: JSONAPI.MaybeRawId>: EntityType {
-	
-	/// The JSON API compliant "type" of this `Entity`.
-	public static var type: String { return Description.type }
-	
 	/// The `Entity`'s Id. This can be of type `Unidentified` if
 	/// the entity is being created clientside and the
 	/// server is being asked to create a unique Id. Otherwise,
@@ -155,21 +166,21 @@ public extension Entity where EntityRawIdType: JSONAPI.RawIdType {
 }
 
 // MARK: Attribute Access
-public extension Entity {
+public extension EntityProxy {
 	/// Access the attribute at the given keypath. This just
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
 	subscript<T, TFRM: Transformer>(_ path: KeyPath<Description.Attributes, TransformedAttribute<T, TFRM>>) -> TFRM.To {
 		return attributes[keyPath: path].value
 	}
-	
+
 	/// Access the attribute at the given keypath. This just
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
 	subscript<T, TFRM: Transformer>(_ path: KeyPath<Description.Attributes, TransformedAttribute<T, TFRM>?>) -> TFRM.To? {
 		return attributes[keyPath: path]?.value
 	}
-	
+
 	/// Access the attribute at the given keypath. This just
 	/// allows you to write `entity[\.propertyName]` instead
 	/// of `entity.relationships.propertyName`.
@@ -179,18 +190,18 @@ public extension Entity {
 }
 
 // MARK: Relationship Access
-public extension Entity {
+public extension EntityProxy {
 	/// Access to an Id of a `ToOneRelationship`.
 	/// This allows you to write `entity ~> \.other` instead
 	/// of `entity.relationships.other.id`.
-	public static func ~><OtherEntity: OptionalRelatable>(entity: Entity, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity>>) -> OtherEntity.WrappedIdentifier {
+	public static func ~><OtherEntity: OptionalRelatable>(entity: Self, path: KeyPath<Description.Relationships, ToOneRelationship<OtherEntity>>) -> OtherEntity.WrappedIdentifier {
 		return entity.relationships[keyPath: path].id
 	}
 
 	/// Access to all Ids of a `ToManyRelationship`.
 	/// This allows you to write `entity ~> \.others` instead
 	/// of `entity.relationships.others.ids`.
-	public static func ~><OtherEntity: Relatable>(entity: Entity, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity>>) -> [OtherEntity.Identifier] {
+	public static func ~><OtherEntity: Relatable>(entity: Self, path: KeyPath<Description.Relationships, ToManyRelationship<OtherEntity>>) -> [OtherEntity.Identifier] {
 		return entity.relationships[keyPath: path].ids
 	}
 }

Sources/JSONAPI/Resource/Id.swift

@@ -35,7 +35,7 @@ public struct Unidentified: MaybeRawId, CustomStringConvertible {
 }
 
 public protocol MaybeId: Codable {
-	associatedtype EntityType: JSONAPI.EntityType
+	associatedtype EntityType: JSONAPI.EntityProxy
 	associatedtype RawType: MaybeRawId
 }
 
@@ -53,7 +53,7 @@ public protocol CreatableIdType: IdType {
 
 /// An Entity ID. These IDs can be encoded to or decoded from
 /// JSON API IDs.
-public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityType>: Codable, Equatable, MaybeId {
+public struct Id<RawType: MaybeRawId, EntityType: JSONAPI.EntityProxy>: Codable, Equatable, MaybeId {
 
 	public let rawValue: RawType
 

Tests/JSONAPITests/Poly/PolyProxyTests.swift

@@ -0,0 +1,141 @@
+//
+//  PolyProxyTests.swift
+//  JSONAPITests
+//
+//  Created by Mathew Polzin on 11/29/18.
+//
+
+import XCTest
+import JSONAPI
+
+public class PolyProxyTests: XCTestCase {
+	func test_generalReasonableness() {
+		XCTAssertNotEqual(decoded(type: User.self, data: poly_user_stub_1), decoded(type: User.self, data: poly_user_stub_2))
+		XCTAssertEqual(User.type, "users")
+	}
+
+	func test_UserADecode() {
+		let polyUserA = decoded(type: User.self, data: poly_user_stub_1)
+		let userA = decoded(type: UserA.self, data: poly_user_stub_1)
+
+		XCTAssertEqual(polyUserA.userA, userA)
+		XCTAssertNil(polyUserA.userB)
+		XCTAssertEqual(polyUserA[\.name], "Ken Moore")
+		XCTAssertEqual(polyUserA.id, "1")
+		XCTAssertEqual(polyUserA.relationships, .none)
+	}
+
+	func test_UserAEncode() {
+		test_DecodeEncodeEquality(type: User.self, data: poly_user_stub_1)
+		test_DecodeEncodeEquality(type: User.self, data: poly_user_stub_2)
+	}
+
+	func test_UserBDecode() {
+		let polyUserB = decoded(type: User.self, data: poly_user_stub_2)
+		let userB = decoded(type: UserB.self, data: poly_user_stub_2)
+
+		XCTAssertEqual(polyUserB.userB, userB)
+		XCTAssertNil(polyUserB.userA)
+		XCTAssertEqual(polyUserB[\.name], "Ken Less")
+		XCTAssertEqual(polyUserB.id, "2")
+		XCTAssertEqual(polyUserB.relationships, .none)
+	}
+}
+
+// MARK: - Test types
+public extension PolyProxyTests {
+	public enum UserDescription1: EntityDescription {
+		public static var type: String { return "users" }
+
+		public struct Attributes: JSONAPI.Attributes {
+			let firstName: Attribute<String>
+			let lastName: Attribute<String>
+		}
+
+		public typealias Relationships = NoRelationships
+	}
+
+	public enum UserDescription2: EntityDescription {
+		public static var type: String { return "users" }
+
+		public struct Attributes: JSONAPI.Attributes {
+			let name: Attribute<[String]>
+		}
+
+		public typealias Relationships = NoRelationships
+	}
+
+	public typealias UserA = Entity<UserDescription1>
+	public typealias UserB = Entity<UserDescription2>
+
+	public typealias User = Poly2<UserA, UserB>
+}
+
+extension Poly2: EntityProxy where A == PolyProxyTests.UserA, B == PolyProxyTests.UserB {
+
+	public var userA: PolyProxyTests.UserA? {
+		return a
+	}
+
+	public var userB: PolyProxyTests.UserB? {
+		return b
+	}
+
+	public var id: Id<EntityRawIdType, PolyProxyTests.User> {
+		switch self {
+		case .a(let a):
+			return Id(rawValue: a.id.rawValue)
+		case .b(let b):
+			return Id(rawValue: b.id.rawValue)
+		}
+	}
+
+	public var attributes: SharedUserDescription.Attributes {
+		switch self {
+		case .a(let a):
+			return .init(name: .init(value: "\(a[\.firstName]) \(a[\.lastName])"))
+		case .b(let b):
+			return .init(name: .init(value: b[\.name].joined(separator: " ")))
+		}
+	}
+
+	public var relationships: NoRelationships {
+		return .none
+	}
+
+	public enum SharedUserDescription: EntityDescription {
+		public static var type: String { return A.type }
+
+		public struct Attributes: JSONAPI.Attributes {
+			let name: Attribute<String>
+		}
+
+		public typealias Relationships = NoRelationships
+	}
+
+	public typealias Description = SharedUserDescription
+
+	public typealias EntityRawIdType = A.EntityRawIdType
+}
+
+// MARK: - Test stubs
+private let poly_user_stub_1 = """
+{
+	"id": "1",
+	"type": "users",
+	"attributes": {
+		"firstName": "Ken",
+		"lastName": "Moore"
+	}
+}
+""".data(using: .utf8)!
+
+private let poly_user_stub_2 = """
+{
+	"id": "2",
+	"type": "users",
+	"attributes": {
+		"name": ["Ken", "Less"]
+	}
+}
+""".data(using: .utf8)!