abstract away document comparison

Feature/indentation

JSONAPI.playground/Pages/Full Client & Server Example.xcplaygroundpage/Contents.swift

@@ -1,67 +1,69 @@
 import Foundation
 import JSONAPI
+import Poly
 
 // MARK: - Preamble (setup)
 
-// We make String a CreatableRawIdType. This is actually done in
+// Make String a CreatableRawIdType. This is actually done in
 // this Playground's Entities.swift file, so it is commented out here.
 /*
-var GlobalStringId: Int = 0
-extension String: CreatableRawIdType {
-	public static func unique() -> String {
-		GlobalStringId += 1
-		return String(GlobalStringId)
-	}
-}
-*/
+ var globalStringId: Int = 0
+ extension String: CreatableRawIdType {
+ public static func unique() -> String {
+ globalStringId += 1
+ return String(globalStringId)
+ }
+ }
+ */
 
-// We create a typealias given that we do not expect JSON:API Resource
+// Create a typealias because we do not expect JSON:API Resource
 // Objects for this particular API to have Metadata or Links associated
 // with them. We also expect them to have String Identifiers.
-typealias JSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, String>
+typealias JSONEntity<Description: ResourceObjectDescription> = JSONAPI.ResourceObject<Description, NoMetadata, NoLinks, String>
 
-// Similarly, we create a typealias for unidentified entities. JSON:API
+// Similarly, create a typealias for unidentified entities. JSON:API
 // only allows unidentified entities (i.e. no "id" field) for client
 // requests that create new entities. In these situations, the server
 // is expected to assign the new entity a unique ID.
-typealias UnidentifiedJSONEntity<Description: EntityDescription> = JSONAPI.Entity<Description, NoMetadata, NoLinks, Unidentified>
+typealias UnidentifiedJSONEntity<Description: ResourceObjectDescription> = JSONAPI.ResourceObject<Description, NoMetadata, NoLinks, Unidentified>
 
-// We create typealiases given that we do not expect JSON:API Relationships
-// for this particular API to have Metadata or Links associated
-// with them.
+// Create relationship typealiases because we do not expect
+// JSON:API Relationships for this particular API to have
+// Metadata or Links associated with them.
 typealias ToOneRelationship<Entity: Identifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
 typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
 
-// We create a typealias for a Document given that we do not expect
+// Create a typealias for a Document because we do not expect
 // JSON:API Documents for this particular API to have Metadata, Links,
-// useful Errors, or a JSON:API Object (i.e. APIDescription).
-typealias Document<PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, UnknownJSONAPIError>
+// useful Errors, or an APIDescription (The *SPEC* calls this
+// "API Description" the "JSON:API Object").
+typealias Document<PrimaryResourceBody: JSONAPI.ResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, BasicJSONAPIError<String>>
 
 // MARK: Entity Definitions
 
-enum AuthorDescription: EntityDescription {
-	public static var jsonType: String { return "authors" }
+enum AuthorDescription: ResourceObjectDescription {
+    public static var jsonType: String { return "authors" }
 
-	public struct Attributes: JSONAPI.Attributes {
-		public let name: Attribute<String>
-	}
+    public struct Attributes: JSONAPI.Attributes {
+        public let name: Attribute<String>
+    }
 
-	public typealias Relationships = NoRelationships
+    public typealias Relationships = NoRelationships
 }
 
 typealias Author = JSONEntity<AuthorDescription>
 
-enum ArticleDescription: EntityDescription {
-	public static var jsonType: String { return "articles" }
+enum ArticleDescription: ResourceObjectDescription {
+    public static var jsonType: String { return "articles" }
 
-	public struct Attributes: JSONAPI.Attributes {
-		public let title: Attribute<String>
-		public let abstract: Attribute<String>
-	}
+    public struct Attributes: JSONAPI.Attributes {
+        public let title: Attribute<String>
+        public let abstract: Attribute<String>
+    }
 
-	public struct Relationships: JSONAPI.Relationships {
-		public let author: ToOneRelationship<Author>
-	}
+    public struct Relationships: JSONAPI.Relationships {
+        public let author: ToOneRelationship<Author>
+    }
 }
 
 typealias Article = JSONEntity<ArticleDescription>
@@ -82,38 +84,38 @@ typealias SingleArticleDocument = Document<SingleResourceBody<Article>, NoInclud
 // that creates a document. Note that this document is the entirety
 // of a JSON:API response body.
 func articleDocument(includeAuthor: Bool) -> Either<SingleArticleDocument, SingleArticleDocumentWithIncludes> {
-	// Let's pretend all of this is coming from a database:
+    // Let's pretend all of this is coming from a database:
 
-	let authorId = Author.Identifier(rawValue: "1234")
+    let authorId = Author.Identifier(rawValue: "1234")
 
-	let article = Article(id: .init(rawValue: "5678"),
-						  attributes: .init(title: .init(value: "JSON:API in Swift"),
-											abstract: .init(value: "Not yet written")),
-						  relationships: .init(author: .init(id: authorId)),
-						  meta: .none,
-						  links: .none)
+    let article = Article(id: .init(rawValue: "5678"),
+                          attributes: .init(title: .init(value: "JSON:API in Swift"),
+                                            abstract: .init(value: "Not yet written")),
+                          relationships: .init(author: .init(id: authorId)),
+                          meta: .none,
+                          links: .none)
 
-	let document = SingleArticleDocument(apiDescription: .none,
-										 body: .init(entity: article),
-										 includes: .none,
-										 meta: .none,
-										 links: .none)
+    let document = SingleArticleDocument(apiDescription: .none,
+                                         body: .init(resourceObject: article),
+                                         includes: .none,
+                                         meta: .none,
+                                         links: .none)
 
-	switch includeAuthor {
-	case false:
-		return .a(document)
+    switch includeAuthor {
+    case false:
+        return .init(document)
 
-	case true:
-		let author = Author(id: authorId,
-							attributes: .init(name: .init(value: "Janice Bluff")),
-							relationships: .none,
-							meta: .none,
-							links: .none)
+    case true:
+        let author = Author(id: authorId,
+                            attributes: .init(name: .init(value: "Janice Bluff")),
+                            relationships: .none,
+                            meta: .none,
+                            links: .none)
 
-		let includes: Includes<SingleArticleDocumentWithIncludes.Include> = .init(values: [.init(author)])
+        let includes: Includes<SingleArticleDocumentWithIncludes.Include> = .init(values: [.init(author)])
 
-		return .b(document.including(.init(values: [.init(author)])))
-	}
+        return .init(document.including(includes))
+    }
 }
 
 let encoder = JSONEncoder()
@@ -123,8 +125,8 @@ encoder.outputFormatting = .prettyPrinted
 let responseBody = articleDocument(includeAuthor: true)
 let responseData = try! encoder.encode(responseBody)
 
-// Next step would be encoding and setting as the HTTP body of a response.
-// we will just print it out instead:
+// Next step would be setting the HTTP body of a response.
+// We will just print it out instead:
 print("-----")
 print(String(data: responseData, encoding: .utf8)!)
 
@@ -138,31 +140,31 @@ print(String(data: otherResponseData, encoding: .utf8)!)
 // MARK: - Client Pseudo-example
 
 enum NetworkError: Swift.Error {
-	case serverError
-	case quantityMismatch
+    case serverError
+    case quantityMismatch
 }
 
 // Skipping over all the API stuff, here's a chunk of code that will
 // decode a document. We will assume we have made a request for a
 // single article including the author.
 func docode(articleResponseData: Data) throws -> (article: Article, author: Author) {
-	let decoder = JSONDecoder()
-	decoder.keyDecodingStrategy = .convertFromSnakeCase
+    let decoder = JSONDecoder()
+    decoder.keyDecodingStrategy = .convertFromSnakeCase
 
-	let articleDocument = try decoder.decode(SingleArticleDocumentWithIncludes.self, from: articleResponseData)
+    let articleDocument = try decoder.decode(SingleArticleDocumentWithIncludes.self, from: articleResponseData)
 
-	switch articleDocument.body {
-	case .data(let data):
-		let authors = data.includes[Author.self]
+    switch articleDocument.body {
+    case .data(let data):
+        let authors = data.includes[Author.self]
 
-		guard authors.count == 1 else {
-			throw NetworkError.quantityMismatch
-		}
+        guard authors.count == 1 else {
+            throw NetworkError.quantityMismatch
+        }
 
-		return (article: data.primary.value, author: authors[0])
-	case .errors(let errors, meta: _, links: _):
-		throw NetworkError.serverError
-	}
+        return (article: data.primary.value, author: authors[0])
+    case .errors(let errors, meta: _, links: _):
+        throw NetworkError.serverError
+    }
 }
 
 let response = try! docode(articleResponseData: responseData)

JSONAPI.playground/Pages/Full Document Verbose Generation.xcplaygroundpage/Contents.swift

@@ -64,7 +64,7 @@ struct ToManyRelationshipLinks: JSONAPI.Links {
 }
 
 /// Description of an Author entity.
-enum AuthorDescription: EntityDescription {
+enum AuthorDescription: ResourceObjectDescription {
 	static var jsonType: String { return "authors" }
 
 	struct Attributes: JSONAPI.Attributes {
@@ -76,10 +76,10 @@ enum AuthorDescription: EntityDescription {
 	}
 }
 
-typealias Author = JSONAPI.Entity<AuthorDescription, EntityMetadata, EntityLinks, String>
+typealias Author = JSONAPI.ResourceObject<AuthorDescription, EntityMetadata, EntityLinks, String>
 
 /// Description of an Article entity.
-enum ArticleDescription: EntityDescription {
+enum ArticleDescription: ResourceObjectDescription {
 	static var jsonType: String { return "articles" }
 
 	struct Attributes: JSONAPI.Attributes {
@@ -96,7 +96,7 @@ enum ArticleDescription: EntityDescription {
 	}
 }
 
-typealias Article = JSONAPI.Entity<ArticleDescription, EntityMetadata, EntityLinks, String>
+typealias Article = JSONAPI.ResourceObject<ArticleDescription, EntityMetadata, EntityLinks, String>
 
 /// Metadata associated with the API Description
 struct APIDescriptionMetadata: JSONAPI.Meta {
@@ -196,7 +196,7 @@ let documentLinks = SingleArticleDocumentLinks(otherArticlesByPrimaryAuthor: .in
 																				   meta: .init(expiry: tomorrow)))
 
 let singleArticleDocument = SingleArticleDocument(apiDescription: apiDescription,
-												  body: .init(entity: article),
+												  body: .init(resourceObject: article),
 												  includes: .init(values: [.init(author1), .init(author2), .init(author3)]),
 												  meta: documentMetadata,
 												  links: documentLinks)

JSONAPI.playground/Pages/PATCHing.xcplaygroundpage/Contents.swift

@@ -0,0 +1,124 @@
+//: [Previous](@previous)
+
+import Foundation
+import JSONAPI
+
+/*******
+
+ Please enjoy these examples, but allow me the forced casting and the lack of error checking for the sake of brevity.
+
+ This playground focuses on receiving a resource, making some changes, and then creating a request body for a PATCH request.
+ As with all examples in these playround pages, no actual networking code will be provided.
+
+ ********/
+
+// Mock up a server response
+let mockDogData = """
+{
+    "data": {
+        "id": "1234",
+        "type": "dogs",
+        "attributes": {
+            "name": "Sparky"
+        },
+        "relationships": {
+            "owner": {
+                "data": null
+            }
+        }
+    }
+}
+""".data(using: .utf8)!
+
+//
+// MARK: - EXAMPLE 1 (Mutable Attributes)
+//
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse = try! JSONDecoder().decode(MutableDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog = parsedResponse.body.primaryResource!.value
+print("Received dog named: \(dog.name)")
+
+// change the dog's name
+let changedDog = dog.tappingAttributes { $0.name = .init(value: "Julia") }
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest = MutableDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest = try! JSONEncoder().encode(patchRequest)
+print("----")
+print(String(data: encodedPatchRequest, encoding:.utf8)!)
+
+
+//
+// MARK: - EXAMPLE 2 (Immutable Attributes)
+//
+print()
+print("####")
+print()
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse2 = try! JSONDecoder().decode(SingleDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog2 = parsedResponse2.body.primaryResource!.value
+print("Received dog named: \(dog2.name)")
+
+// change the dog's name
+let changedDog2 = dog2.replacingAttributes { _ in
+    return .init(name: .init(value: "Nigel"))
+}
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest2 = SingleDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog2),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest2 = try! JSONEncoder().encode(patchRequest2)
+print("----")
+print(String(data: encodedPatchRequest2, encoding:.utf8)!)
+
+
+//
+// MARK: - EXAMPLE 3 (Change relationship)
+//
+print()
+print("####")
+print()
+
+// pretend to have requested a Dog and received the mock data
+// now parse it.
+let parsedResponse3 = try! JSONDecoder().decode(SingleDogDocument.self, from: mockDogData)
+
+// extract our Dog (skipping over any robustness to handle errors)
+var dog3 = parsedResponse2.body.primaryResource!.value
+print("Received dog with owner: \(dog3 ~> \.owner)")
+
+// give the dog an owner
+let changedDog3 = dog3.replacingRelationships { _ in
+    return .init(owner: .init(id: Id(rawValue: "1")))
+}
+
+// create a document to be used as a request body for a PATCH request
+let patchRequest3 = SingleDogDocument(apiDescription: .none,
+                                      body: .init(resourceObject: changedDog3),
+                                      includes: .none,
+                                      meta: .none,
+                                      links: .none)
+
+// encode and send off to server
+let encodedPatchRequest3 = try! JSONEncoder().encode(patchRequest3)
+print("----")
+print(String(data: encodedPatchRequest3, encoding:.utf8)!)

JSONAPI.playground/Pages/Sparse Fieldsets Example.xcplaygroundpage/Contents.swift

@@ -0,0 +1,72 @@
+
+import JSONAPI
+import Foundation
+
+// MARK: - Resource Object
+
+enum ThingWithPropertiesDescription: JSONAPI.ResourceObjectDescription {
+    static let jsonType: String = "thing"
+
+    //
+    // NOTE: `JSONAPI.SparsableAttributes` as opposed to `JSONAPI.Attributes`
+    //
+    struct Attributes: JSONAPI.SparsableAttributes {
+        let stringThing: Attribute<String>
+        let numberThing: Attribute<Double>
+        let boolThing: Attribute<Bool?>
+
+        //
+        // NOTE: Special implementation of `CodingKeys`
+        //
+        enum CodingKeys: String, JSONAPI.SparsableCodingKey {
+            case stringThing
+            case numberThing
+            case boolThing
+        }
+    }
+
+    typealias Relationships = NoRelationships
+}
+
+typealias ThingWithProperties = JSONAPI.ResourceObject<ThingWithPropertiesDescription, NoMetadata, NoLinks, String>
+
+// MARK: - Document
+
+//
+// NOTE: Using `JSONAPI.EncodableResourceBody` which means the document type will be `Encodable` but not `Decodable`.
+//
+typealias Document<PrimaryResourceBody: JSONAPI.EncodableResourceBody, IncludeType: JSONAPI.Include> = JSONAPI.Document<PrimaryResourceBody, NoMetadata, NoLinks, IncludeType, NoAPIDescription, BasicJSONAPIError<String>>
+
+//
+// NOTE: Using `JSONAPI.EncodablePrimaryResource` which means the `ResourceBody` will be `Encodable` but not `Decodable.
+//
+typealias SingleDocument<T: JSONAPI.EncodablePrimaryResource> = Document<SingleResourceBody<T>, NoIncludes>
+
+// MARK: - Resource Initialization
+
+let resource = ThingWithProperties(id: .init(rawValue: "1234"),
+                                   attributes: .init(stringThing: .init(value: "hello world"),
+                                                     numberThing: .init(value: 10),
+                                                     boolThing: .init(value: nil)),
+                                   relationships: .none,
+                                   meta: .none,
+                                   links: .none)
+//
+// NOTE: Creating a sparse resource that will only encode
+//       the attribute named "stringThing"
+//
+let sparseResource = resource.sparse(with: [.stringThing])
+
+// MARK: - Encoding
+
+let encoder = JSONEncoder()
+
+let sparseResourceDoc = SingleDocument(apiDescription: .none,
+                                       body: .init(resourceObject: sparseResource),
+                                       includes: .none,
+                                       meta: .none,
+                                       links: .none)
+
+let data = try! encoder.encode(sparseResourceDoc)
+
+print(String(data: data, encoding: .utf8)!)

JSONAPI.playground/Pages/Test Library.xcplaygroundpage/Contents.swift

@@ -2,7 +2,7 @@
 
 import Foundation
 import JSONAPI
-import JSONAPITestLib
+import JSONAPITesting
 
 /*******
 
@@ -11,12 +11,12 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 ********/
 
 // MARK: - Literal Expressibility
-// The JSONAPITestLib provides literal expressibility for key types to
+// The JSONAPITesting framework provides literal expressibility for key types to
 // make creating tests easier
 let dog = Dog(id: "1234", attributes: Dog.Attributes(name: "Buddy"), relationships: Dog.Relationships(owner: nil), meta: .none, links: .none)
 
 // MARK: - JSON API structure checking
-// The JSONAPITestLib provides a `check` function for each Entity type
+// The JSONAPITesting framework provides a `check` function for each Entity type
 // that uses reflection to catch mistakes that are not forbidden by
 // Swift's type system but will result in unexpected results when
 // encoding/decoding. It is a good idea to add a `check` to each of

JSONAPI.playground/Pages/Usage.xcplaygroundpage/Contents.swift

@@ -8,38 +8,39 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 
 ********/
 
+
 // MARK: - Create a request or response body with one Dog in it
 let dogFromCode = try! Dog(name: "Buddy", owner: nil)
 
-typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
-
-let singleDogDocument = SingleDogDocument(apiDescription: .none, body: .init(entity: dogFromCode), includes: .none, meta: .none, links: .none)
+let singleDogDocument = SingleDogDocument(apiDescription: .none, body: .init(resourceObject: dogFromCode), includes: .none, meta: .none, links: .none)
 
 let singleDogData = try! JSONEncoder().encode(singleDogDocument)
 
+
 // MARK: - Parse a request or response body with one Dog in it
 let dogResponse = try! JSONDecoder().decode(SingleDogDocument.self, from: singleDogData)
 let dogFromData = dogResponse.body.primaryResource?.value
 let dogOwner: Person.Identifier? = dogFromData.flatMap { $0 ~> \.owner }
 
-// MARKL - Parse a request or response body with one Dog in it using an alternative model
-typealias AltSingleDogDocument = JSONAPI.Document<SingleResourceBody<AlternativeDog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, UnknownJSONAPIError>
+
+// MARK: - Parse a request or response body with one Dog in it using an alternative model
+typealias AltSingleDogDocument = JSONAPI.Document<SingleResourceBody<AlternativeDog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
 let altDogResponse = try! JSONDecoder().decode(AltSingleDogDocument.self, from: singleDogData)
 let altDogFromData = altDogResponse.body.primaryResource?.value
 let altDogHuman: Person.Identifier? = altDogFromData.flatMap { $0 ~> \.human }
 
+
 // MARK: - Create a request or response with multiple people and dogs and houses included
 let personIds = [Person.Identifier(), Person.Identifier()]
 let dogs = try! [Dog(name: "Buddy", owner: personIds[0]), Dog(name: "Joy", owner: personIds[0]), Dog(name: "Travis", owner: personIds[1])]
 let houses = [House(attributes: .none, relationships: .none, meta: .none, links: .none), House(attributes: .none, relationships: .none, meta: .none, links: .none)]
 let people = try! [Person(id: personIds[0], name: ["Gary", "Doe"], favoriteColor: "Orange-Red", friends: [], dogs: [dogs[0], dogs[1]], home: houses[0]), Person(id: personIds[1], name: ["Elise", "Joy"], favoriteColor: "Red", friends: [], dogs: [dogs[2]], home: houses[1])]
 
-typealias BatchPeopleDocument = JSONAPI.Document<ManyResourceBody<Person>, NoMetadata, NoLinks, Include2<Dog, House>, NoAPIDescription, UnknownJSONAPIError>
-
 let includes = dogs.map { BatchPeopleDocument.Include($0) } + houses.map { BatchPeopleDocument.Include($0) }
-let batchPeopleDocument = BatchPeopleDocument(apiDescription: .none, body: .init(entities: people), includes: .init(values: includes), meta: .none, links: .none)
+let batchPeopleDocument = BatchPeopleDocument(apiDescription: .none, body: .init(resourceObjects: people), includes: .init(values: includes), meta: .none, links: .none)
 let batchPeopleData = try! JSONEncoder().encode(batchPeopleDocument)
 
+
 // MARK: - Parse a request or response body with multiple people in it and dogs and houses included
 
 let peopleResponse = try! JSONDecoder().decode(BatchPeopleDocument.self, from: batchPeopleData)
@@ -51,16 +52,18 @@ print("-----")
 print(peopleResponse)
 print("-----")
 
+
 // MARK: - Pass successfully parsed body to other parts of the code
 
 if case let .data(bodyData) = peopleResponse.body {
-	print("first person's name: \(bodyData.primary.values[0][\.fullName])")
+	print("first person's name: \(bodyData.primary.values[0].fullName)")
 } else {
 	print("no body data")
 }
 
-// MARK: - Work in the abstract
 
+// MARK: - Work in the abstract
+print("-----")
 func process<T: JSONAPIDocument>(document: T) {
 	guard case let .data(body) = document.body else {
 		return
@@ -68,3 +71,29 @@ func process<T: JSONAPIDocument>(document: T) {
 	let x: T.Body.Data = body
 }
 process(document: peopleResponse)
+
+// MARK: - Work with errors
+typealias ErrorDoc = JSONAPI.Document<NoResourceBody, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
+
+let mockErrorData =
+"""
+{
+    "errors": [
+        {
+            "status": "500",
+            "title": "Internal Server Error",
+            "detail": "Server fell over while parsing your request."
+        }
+    ]
+}
+""".data(using: .utf8)!
+
+let errorResponse = try! JSONDecoder().decode(ErrorDoc.self, from: mockErrorData)
+
+switch errorResponse.body {
+case .data:
+    print("cool, data!")
+case .errors(let errors, let meta, let links):
+    let errorDetails = errors.compactMap { $0.payload?.detail }
+    print("error details: \(errorDetails)")
+}

JSONAPI.playground/Sources/Entities.swift

@@ -15,21 +15,21 @@ Please enjoy these examples, but allow me the forced casting and the lack of err
 ********/
 
 // MARK: - String as CreatableRawIdType
-var GlobalStringId: Int = 0
+var globalStringId: Int = 0
 extension String: CreatableRawIdType {
 	public static func unique() -> String {
-		GlobalStringId += 1
-		return String(GlobalStringId)
+		globalStringId += 1
+		return String(globalStringId)
 	}
 }
 
 // MARK: - typealiases for convenience
-public typealias ExampleEntity<Description: EntityDescription> = Entity<Description, NoMetadata, NoLinks, String>
+public typealias ExampleEntity<Description: ResourceObjectDescription> = ResourceObject<Description, NoMetadata, NoLinks, String>
 public typealias ToOne<E: Identifiable> = ToOneRelationship<E, NoMetadata, NoLinks>
 public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoMetadata, NoLinks>
 
 // MARK: - A few resource objects (entities)
-public enum PersonDescription: EntityDescription {
+public enum PersonDescription: ResourceObjectDescription {
 
 	public static var jsonType: String { return "people" }
 	
@@ -62,13 +62,13 @@ public enum PersonDescription: EntityDescription {
 
 public typealias Person = ExampleEntity<PersonDescription>
 
-public extension Entity where Description == PersonDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
-	public init(id: Person.Id? = nil,name: [String], favoriteColor: String, friends: [Person], dogs: [Dog], home: House) throws {
-		self = Person(id: id ?? Person.Id(), attributes: .init(name: .init(value: name), favoriteColor: .init(value: favoriteColor)), relationships: .init(friends: .init(entities: friends), dogs: .init(entities: dogs), home: .init(entity: home)), meta: .none, links: .none)
+public extension ResourceObject where Description == PersonDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
+	init(id: Person.Id? = nil,name: [String], favoriteColor: String, friends: [Person], dogs: [Dog], home: House) throws {
+		self = Person(id: id ?? Person.Id(), attributes: .init(name: .init(value: name), favoriteColor: .init(value: favoriteColor)), relationships: .init(friends: .init(resourceObjects: friends), dogs: .init(resourceObjects: dogs), home: .init(resourceObject: home)), meta: .none, links: .none)
 	}
 }
 
-public enum DogDescription: EntityDescription {
+public enum DogDescription: ResourceObjectDescription {
 
 	public static var jsonType: String { return "dogs" }
 
@@ -91,7 +91,7 @@ public enum DogDescription: EntityDescription {
 
 public typealias Dog = ExampleEntity<DogDescription>
 
-public enum AlternativeDogDescription: EntityDescription {
+public enum AlternativeDogDescription: ResourceObjectDescription {
 
 	public static var jsonType: String { return "dogs" }
 
@@ -119,17 +119,40 @@ public enum AlternativeDogDescription: EntityDescription {
 
 public typealias AlternativeDog = ExampleEntity<AlternativeDogDescription>
 
-public extension Entity where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
-	public init(name: String, owner: Person?) throws {
-		self = Dog(attributes: .init(name: .init(value: name)), relationships: DogDescription.Relationships(owner: .init(entity: owner)), meta: .none, links: .none)
+public enum MutableDogDescription: ResourceObjectDescription {
+
+    public static var jsonType: String { return "dogs" }
+
+    public struct Attributes: JSONAPI.Attributes {
+        public var name: Attribute<String>
+
+        public init(name: Attribute<String>) {
+            self.name = name
+        }
+    }
+
+    public struct Relationships: JSONAPI.Relationships {
+        public var owner: ToOne<Person?>
+
+        public init(owner: ToOne<Person?>) {
+            self.owner = owner
+        }
+    }
+}
+
+public typealias MutableDog = ExampleEntity<MutableDogDescription>
+
+public extension ResourceObject where Description == DogDescription, MetaType == NoMetadata, LinksType == NoLinks, EntityRawIdType == String {
+	init(name: String, owner: Person?) throws {
+		self = Dog(attributes: .init(name: .init(value: name)), relationships: DogDescription.Relationships(owner: .init(resourceObject: owner)), meta: .none, links: .none)
 	}
 
-	public init(name: String, owner: Person.Id) throws {
+	init(name: String, owner: Person.Id) throws {
 		self = Dog(attributes: .init(name: .init(value: name)), relationships: .init(owner: .init(id: owner)), meta: .none, links: .none)
 	}
 }
 
-public enum HouseDescription: EntityDescription {
+public enum HouseDescription: ResourceObjectDescription {
 
 	public static var jsonType: String { return "houses" }
 
@@ -139,4 +162,8 @@ public enum HouseDescription: EntityDescription {
 
 public typealias House = ExampleEntity<HouseDescription>
 
+public typealias SingleDogDocument = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
 
+public typealias MutableDogDocument = JSONAPI.Document<SingleResourceBody<MutableDog>, NoMetadata, NoLinks, NoIncludes, NoAPIDescription, BasicJSONAPIError<String>>
+
+public typealias BatchPeopleDocument = JSONAPI.Document<ManyResourceBody<Person>, NoMetadata, NoLinks, Include2<Dog, House>, NoAPIDescription, BasicJSONAPIError<String>>

JSONAPI.playground/contents.xcplayground

@@ -1,7 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<playground version='6.0' target-platform='macos' executeOnSourceChanges='false'>
+<playground version='6.0' target-platform='macos'>
     <pages>
         <page name='Test Library'/>
         <page name='Usage'/>
+        <page name='Full Client &amp; Server Example'/>
+        <page name='Full Document Verbose Generation'/>
+        <page name='Sparse Fieldsets Example'/>
+        <page name='PATCHing'/>
     </pages>
 </playground>

JSONAPI.podspec

@@ -0,0 +1,141 @@
+#
+#  Be sure to run `pod spec lint JSONAPI.podspec' to ensure this is a
+#  valid spec and to remove all comments including this before submitting the spec.
+#
+#  To learn more about Podspec attributes see https://docs.cocoapods.org/specification.html
+#  To see working Podspecs in the CocoaPods repo see https://github.com/CocoaPods/Specs/
+#
+
+Pod::Spec.new do |spec|
+
+  # ―――  Spec Metadata  ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  These will help people to find your library, and whilst it
+  #  can feel like a chore to fill in it's definitely to your advantage. The
+  #  summary should be tweet-length, and the description more in depth.
+  #
+
+  spec.name         = "MP-JSONAPI"
+  spec.version      = "2.5.0"
+  spec.summary      = "Swift Codable JSON API framework."
+
+  # This description is used to generate tags and improve search results.
+  #   * Think: What does it do? Why did you write it? What is the focus?
+  #   * Try to keep it short, snappy and to the point.
+  #   * Write the description between the DESC delimiters below.
+  #   * Finally, don't worry about the indent, CocoaPods strips it!
+  spec.description  = <<-DESC
+  A Swift package for encoding to- and decoding from JSON API compliant requests and responses.
+
+See the JSON API Spec here: https://jsonapi.org/format/
+                   DESC
+
+  spec.homepage     = "https://github.com/mattpolzin/JSONAPI"
+  # spec.screenshots  = "www.example.com/screenshots_1.gif", "www.example.com/screenshots_2.gif"
+
+
+  # ―――  Spec License  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Licensing your code is important. See https://choosealicense.com for more info.
+  #  CocoaPods will detect a license file if there is a named LICENSE*
+  #  Popular ones are 'MIT', 'BSD' and 'Apache License, Version 2.0'.
+  #
+
+  # spec.license      = "MIT"
+  spec.license      = { :type => "MIT", :file => "LICENSE.txt" }
+
+
+  # ――― Author Metadata  ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Specify the authors of the library, with email addresses. Email addresses
+  #  of the authors are extracted from the SCM log. E.g. $ git log. CocoaPods also
+  #  accepts just a name if you'd rather not provide an email address.
+  #
+  #  Specify a social_media_url where others can refer to, for example a twitter
+  #  profile URL.
+  #
+
+  spec.author             = { "Mathew Polzin" => "matt.polzin@gmail.com" }
+  # Or just: spec.author    = "Mathew Polzin"
+  # spec.authors            = { "Mathew Polzin" => "matt.polzin@gmail.com" }
+  # spec.social_media_url   = "https://twitter.com/Mathew Polzin"
+
+  # ――― Platform Specifics ――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  If this Pod runs only on iOS or OS X, then specify the platform and
+  #  the deployment target. You can optionally include the target after the platform.
+  #
+
+  # spec.platform     = :ios
+  # spec.platform     = :ios, "5.0"
+
+  #  When using multiple platforms
+  spec.ios.deployment_target = "8.0"
+  spec.osx.deployment_target = "10.9"
+  # spec.watchos.deployment_target = "2.0"
+  # spec.tvos.deployment_target = "9.0"
+
+
+  # ――― Source Location ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Specify the location from where the source should be retrieved.
+  #  Supports git, hg, bzr, svn and HTTP.
+  #
+
+  spec.source       = { :git => "https://github.com/mattpolzin/JSONAPI.git", :tag => "#{spec.version}" }
+
+
+  # ――― Source Code ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  CocoaPods is smart about how it includes source code. For source files
+  #  giving a folder will include any swift, h, m, mm, c & cpp files.
+  #  For header files it will include any header in the folder.
+  #  Not including the public_header_files will make all headers public.
+  #
+
+  spec.source_files  = "Sources/JSONAPI/**/*.{swift}"
+  # spec.exclude_files = "Classes/Exclude"
+
+  # spec.public_header_files = "Classes/**/*.h"
+
+
+  # ――― Resources ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  A list of resources included with the Pod. These are copied into the
+  #  target bundle with a build phase script. Anything else will be cleaned.
+  #  You can preserve files from being cleaned, please don't preserve
+  #  non-essential files like tests, examples and documentation.
+  #
+
+  # spec.resource  = "icon.png"
+  # spec.resources = "Resources/*.png"
+
+  # spec.preserve_paths = "FilesToSave", "MoreFilesToSave"
+
+
+  # ――― Project Linking ―――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  Link your library with frameworks, or libraries. Libraries do not include
+  #  the lib prefix of their name.
+  #
+
+  # spec.frameworks = "SomeFramework", "AnotherFramework"
+
+  # spec.library   = "iconv"
+  # spec.libraries = "iconv", "xml2"
+
+
+  # ――― Project Settings ――――――――――――――――――――――――――――――――――――――――――――――――――――――――― #
+  #
+  #  If your library depends on compiler flags you can set them in the xcconfig hash
+  #  where they will only apply to your library. If you depend on other Podspecs
+  #  you can include multiple dependencies to ensure it works.
+
+  spec.swift_version = "5.1"
+  spec.module_name   = "JSONAPI"
+  # spec.requires_arc = true
+
+  # spec.xcconfig = { "HEADER_SEARCH_PATHS" => "$(SDKROOT)/usr/include/libxml2" }
+  spec.dependency "Poly", "~> 2.2"
+
+end

LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2018 Mathew Polzin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Package.resolved

@@ -1,7 +1,15 @@
 {
   "object": {
     "pins": [
-
+      {
+        "package": "Poly",
+        "repositoryURL": "https://github.com/mattpolzin/Poly.git",
+        "state": {
+          "branch": null,
+          "revision": "18cd995be5c28c4dfdc1464e54ee0efb03e215bf",
+          "version": "2.3.0"
+        }
+      }
     ]
   },
   "version": 1

Package.swift

@@ -1,30 +1,38 @@
-// swift-tools-version:4.2
+// swift-tools-version:5.1
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
 
 let package = Package(
     name: "JSONAPI",
+    platforms: [
+        .macOS(.v10_10),
+        .iOS(.v10)
+    ],
     products: [
         .library(
             name: "JSONAPI",
             targets: ["JSONAPI"]),
-		.library(
-			name: "JSONAPITestLib",
-			targets: ["JSONAPITestLib"])
+        .library(
+            name: "JSONAPITesting",
+            targets: ["JSONAPITesting"])
     ],
     dependencies: [
+        .package(url: "https://github.com/mattpolzin/Poly.git", .upToNextMajor(from: "2.3.0")),
     ],
     targets: [
         .target(
             name: "JSONAPI",
-            dependencies: []),
-		.target(
-			name: "JSONAPITestLib",
-			dependencies: ["JSONAPI"]),
+            dependencies: ["Poly"]),
+        .target(
+            name: "JSONAPITesting",
+            dependencies: ["JSONAPI"]),
         .testTarget(
             name: "JSONAPITests",
-            dependencies: ["JSONAPITestLib"])
+            dependencies: ["JSONAPI", "JSONAPITesting"]),
+        .testTarget(
+            name: "JSONAPITestingTests",
+            dependencies: ["JSONAPI", "JSONAPITesting"])
     ],
-  	swiftLanguageVersions: [.v4_2]
+    swiftLanguageVersions: [.v5]
 )

Sources/JSONAPI/Document/APIDescription.swift

@@ -7,58 +7,58 @@
 
 /// This is what the JSON API Spec calls the "JSON:API Object"
 public protocol APIDescriptionType: Codable, Equatable {
-	associatedtype Meta
+    associatedtype Meta
 }
 
 /// This is what the JSON API Spec calls the "JSON:API Object"
 public struct APIDescription<Meta: JSONAPI.Meta>: APIDescriptionType {
-	public let version: String
-	public let meta: Meta
+    public let version: String
+    public let meta: Meta
 
-	public init(version: String, meta: Meta) {
-		self.version = version
-		self.meta = meta
-	}
+    public init(version: String, meta: Meta) {
+        self.version = version
+        self.meta = meta
+    }
 }
 
 /// Can be used as `APIDescriptionType` for Documents that do not
 /// have any API Description (a.k.a. "JSON:API Object").
 public struct NoAPIDescription: APIDescriptionType, CustomStringConvertible {
-	public typealias Meta = NoMetadata
+    public typealias Meta = NoMetadata
 
-	public init() {}
+    public init() {}
 
-	public static var none: NoAPIDescription { return .init() }
+    public static var none: NoAPIDescription { return .init() }
 
-	public var description: String { return "No JSON:API Object" }
+    public var description: String { return "No JSON:API Object" }
 }
 
 extension APIDescription {
-	private enum CodingKeys: String, CodingKey {
-		case version
-		case meta
-	}
+    private enum CodingKeys: String, CodingKey {
+        case version
+        case meta
+    }
 
-	public init(from decoder: Decoder) throws {
-		let container = try decoder.container(keyedBy: CodingKeys.self)
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
 
-		// The spec says that if a version is not specified, it should be assumed to be at least 1.0
-		version = (try? container.decode(String.self, forKey: .version)) ?? "1.0"
+        // The spec says that if a version is not specified, it should be assumed to be at least 1.0
+        version = (try? container.decode(String.self, forKey: .version)) ?? "1.0"
 
-		if let metaVal = NoMetadata() as? Meta {
-			meta = metaVal
-		} else {
-			meta = try container.decode(Meta.self, forKey: .meta)
-		}
-	}
+        if let metaVal = NoMetadata() as? Meta {
+            meta = metaVal
+        } else {
+            meta = try container.decode(Meta.self, forKey: .meta)
+        }
+    }
 
-	public func encode(to encoder: Encoder) throws {
-		var container = encoder.container(keyedBy: CodingKeys.self)
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
 
-		try container.encode(version, forKey: .version)
+        try container.encode(version, forKey: .version)
 
-		if Meta.self != NoMetadata.self {
-			try container.encode(meta, forKey: .meta)
-		}
-	}
+        if Meta.self != NoMetadata.self {
+            try container.encode(meta, forKey: .meta)
+        }
+    }
 }

Sources/JSONAPI/Document/DocumentDecodingError.swift

@@ -0,0 +1,11 @@
+//
+//  DocumentDecodingErro.swift
+//  
+//
+//  Created by Mathew Polzin on 10/20/19.
+//
+
+public enum JSONAPIDocumentDecodingError: Swift.Error {
+    case foundErrorDocumentWhenExpectingSuccess
+    case foundSuccessDocumentWhenExpectingError
+}

Sources/JSONAPI/Document/Error.swift

@@ -1,27 +0,0 @@
-//
-//  Error.swift
-//  JSONAPI
-//
-//  Created by Mathew Polzin on 11/10/18.
-//
-
-public protocol JSONAPIError: Swift.Error, Equatable, Codable {
-	static var unknown: Self { get }
-}
-
-public enum UnknownJSONAPIError: JSONAPIError {
-	case unknownError
-	
-	public init(from decoder: Decoder) throws {
-		self = .unknown
-	}
-
-	public func encode(to encoder: Encoder) throws {
-		var container = encoder.singleValueContainer()
-		try container.encode("unknown")
-	}
-	
-	public static var unknown: UnknownJSONAPIError {
-		return .unknownError
-	}
-}

Sources/JSONAPI/Document/Includes.swift

@@ -5,71 +5,85 @@
 //  Created by Mathew Polzin on 11/10/18.
 //
 
-public typealias Include = Poly
+import Poly
 
-public struct Includes<I: Include>: Codable, Equatable {
-	public static var none: Includes { return .init(values: []) }
-	
-	let values: [I]
-	
-	public init(values: [I]) {
-		self.values = values
-	}
-	
-	public init(from decoder: Decoder) throws {
-		var container = try decoder.unkeyedContainer()
-		
-		// If not parsing includes, no need to loop over them.
-		guard I.self != NoIncludes.self else {
-			values = []
-			return
-		}
-		
-		var valueAggregator = [I]()
-		while !container.isAtEnd {
-			valueAggregator.append(try container.decode(I.self))
-		}
-		
-		values = valueAggregator
-	}
+public typealias Include = EncodableJSONPoly
 
-	public func encode(to encoder: Encoder) throws {
-		var container = encoder.unkeyedContainer()
+/// A structure holding zero or more included Resource Objects.
+/// The resources are accessed by their type using a subscript.
+///
+/// If you have
+///
+///     let includes: Includes<Include2<Thing1, Thing2>> = ...
+///
+/// then you can access all `Thing1` included resources with
+///
+///     let includedThings = includes[Thing1.self]
+public struct Includes<I: Include>: Encodable, Equatable {
+    public static var none: Includes { return .init(values: []) }
 
-		guard I.self != NoIncludes.self else {
-			throw JSONAPIEncodingError.illegalEncoding("Attempting to encode Include0, which should be represented by the absense of an 'included' entry altogether.")
-		}
+    public let values: [I]
 
-		for value in values {
-			try container.encode(value)
-		}
-	}
-	
-	public var count: Int {
-		return values.count
-	}
+    public init(values: [I]) {
+        self.values = values
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.unkeyedContainer()
+
+        guard I.self != NoIncludes.self else {
+            throw JSONAPIEncodingError.illegalEncoding("Attempting to encode Include0, which should be represented by the absense of an 'included' entry altogether.")
+        }
+
+        for value in values {
+            try container.encode(value)
+        }
+    }
+
+    public var count: Int {
+        return values.count
+    }
+}
+
+extension Includes: Decodable where I: Decodable {
+    public init(from decoder: Decoder) throws {
+        var container = try decoder.unkeyedContainer()
+
+        // If not parsing includes, no need to loop over them.
+        guard I.self != NoIncludes.self else {
+            values = []
+            return
+        }
+
+        var valueAggregator = [I]()
+        while !container.isAtEnd {
+            valueAggregator.append(try container.decode(I.self))
+        }
+
+        values = valueAggregator
+    }
 }
 
 extension Includes {
-	public func appending(_ other: Includes<I>) -> Includes {
-		return Includes(values: values + other.values)
-	}
+    public func appending(_ other: Includes<I>) -> Includes {
+        return Includes(values: values + other.values)
+    }
 }
 
 public func +<I: Include>(_ left: Includes<I>, _ right: Includes<I>) -> Includes<I> {
-	return left.appending(right)
+    return left.appending(right)
 }
 
 extension Includes: CustomStringConvertible {
-	public var description: String {
-		return "Includes(\(String(describing: values))"
-	}
+    public var description: String {
+        return "Includes(\(String(describing: values))"
+    }
 }
 
 extension Includes where I == NoIncludes {
-	public init() {
-		values = []
-	}
+    public init() {
+        values = []
+    }
 }
 
 // MARK: - 0 includes
@@ -79,71 +93,87 @@ public typealias NoIncludes = Include0
 // MARK: - 1 include
 public typealias Include1 = Poly1
 extension Includes where I: _Poly1 {
-	public subscript(_ lookup: I.A.Type) -> [I.A] {
-		return values.compactMap { $0.a }
-	}
+    public subscript(_ lookup: I.A.Type) -> [I.A] {
+        return values.compactMap { $0.a }
+    }
 }
 
 // MARK: - 2 includes
 public typealias Include2 = Poly2
 extension Includes where I: _Poly2 {
-	public subscript(_ lookup: I.B.Type) -> [I.B] {
-		return values.compactMap { $0.b }
-	}
+    public subscript(_ lookup: I.B.Type) -> [I.B] {
+        return values.compactMap { $0.b }
+    }
 }
 
 // MARK: - 3 includes
 public typealias Include3 = Poly3
 extension Includes where I: _Poly3 {
-	public subscript(_ lookup: I.C.Type) -> [I.C] {
-		return values.compactMap { $0.c }
-	}
+    public subscript(_ lookup: I.C.Type) -> [I.C] {
+        return values.compactMap { $0.c }
+    }
 }
 
 // MARK: - 4 includes
 public typealias Include4 = Poly4
 extension Includes where I: _Poly4 {
-	public subscript(_ lookup: I.D.Type) -> [I.D] {
-		return values.compactMap { $0.d }
-	}
+    public subscript(_ lookup: I.D.Type) -> [I.D] {
+        return values.compactMap { $0.d }
+    }
 }
 
 // MARK: - 5 includes
 public typealias Include5 = Poly5
 extension Includes where I: _Poly5 {
-	public subscript(_ lookup: I.E.Type) -> [I.E] {
-		return values.compactMap { $0.e }
-	}
+    public subscript(_ lookup: I.E.Type) -> [I.E] {
+        return values.compactMap { $0.e }
+    }
 }
 
 // MARK: - 6 includes
 public typealias Include6 = Poly6
 extension Includes where I: _Poly6 {
-	public subscript(_ lookup: I.F.Type) -> [I.F] {
-		return values.compactMap { $0.f }
-	}
+    public subscript(_ lookup: I.F.Type) -> [I.F] {
+        return values.compactMap { $0.f }
+    }
 }
 
 // MARK: - 7 includes
 public typealias Include7 = Poly7
 extension Includes where I: _Poly7 {
-	public subscript(_ lookup: I.G.Type) -> [I.G] {
-		return values.compactMap { $0.g }
-	}
+    public subscript(_ lookup: I.G.Type) -> [I.G] {
+        return values.compactMap { $0.g }
+    }
 }
 
 // MARK: - 8 includes
 public typealias Include8 = Poly8
 extension Includes where I: _Poly8 {
-	public subscript(_ lookup: I.H.Type) -> [I.H] {
-		return values.compactMap { $0.h }
-	}
+    public subscript(_ lookup: I.H.Type) -> [I.H] {
+        return values.compactMap { $0.h }
+    }
 }
 
 // MARK: - 9 includes
 public typealias Include9 = Poly9
 extension Includes where I: _Poly9 {
-	public subscript(_ lookup: I.I.Type) -> [I.I] {
-		return values.compactMap { $0.i }
-	}
+    public subscript(_ lookup: I.I.Type) -> [I.I] {
+        return values.compactMap { $0.i }
+    }
+}
+
+// MARK: - 10 includes
+public typealias Include10 = Poly10
+extension Includes where I: _Poly10 {
+    public subscript(_ lookup: I.J.Type) -> [I.J] {
+        return values.compactMap { $0.j }
+    }
+}
+
+// MARK: - 11 includes
+public typealias Include11 = Poly11
+extension Includes where I: _Poly11 {
+    public subscript(_ lookup: I.K.Type) -> [I.K] {
+        return values.compactMap { $0.k }
+    }
 }

Sources/JSONAPI/Document/ResourceBody.swift

@@ -5,110 +5,139 @@
 //  Created by Mathew Polzin on 11/10/18.
 //
 
-public protocol MaybePrimaryResource: Equatable, Codable {}
+/// This protocol allows for a `SingleResourceBody` to contain a `null`
+/// data object where `ManyResourceBody` cannot (because an empty
+/// array should be used for no results).
+public protocol OptionalEncodablePrimaryResource: Equatable, Encodable {}
 
-/// A PrimaryResource is a type that can be used in the body of a JSON API
+/// An `EncodablePrimaryResource` is a `CodablePrimaryResource` that only supports encoding.
+public protocol EncodablePrimaryResource: OptionalEncodablePrimaryResource {}
+
+/// This protocol allows for `SingleResourceBody` to contain a `null`
+/// data object where `ManyResourceBody` cannot (because an empty
+/// array should be used for no results).
+public protocol OptionalCodablePrimaryResource: OptionalEncodablePrimaryResource, Decodable {}
+
+/// A `CodablePrimaryResource` is a type that can be used in the body of a JSON API
 /// document as the primary resource.
-public protocol PrimaryResource: MaybePrimaryResource {}
+public protocol CodablePrimaryResource: EncodablePrimaryResource, OptionalCodablePrimaryResource {}
 
-extension Optional: MaybePrimaryResource where Wrapped: PrimaryResource {}
+extension Optional: OptionalEncodablePrimaryResource where Wrapped: EncodablePrimaryResource {}
 
-/// A ResourceBody is a representation of the body of the JSON API Document.
+extension Optional: OptionalCodablePrimaryResource where Wrapped: CodablePrimaryResource {}
+
+/// An `EncodableResourceBody` is a `ResourceBody` that only supports being
+/// encoded. It is actually weaker than `ResourceBody`, which supports both encoding
+/// and decoding.
+public protocol EncodableResourceBody: Equatable, Encodable {}
+
+/// A `CodableResourceBody` is a representation of the body of the JSON:API Document.
 /// It can either be one resource (which can be specified as optional or not)
 /// or it can contain many resources (and array with zero or more entries).
-public protocol ResourceBody: Codable, Equatable {
+public protocol CodableResourceBody: Decodable, EncodableResourceBody {}
+
+/// A `ResourceBody` that has the ability to take on more primary
+/// resources by appending another similarly typed `ResourceBody`.
+public protocol ResourceBodyAppendable {
+    func appending(_ other: Self) -> Self
 }
 
-public protocol AppendableResourceBody: ResourceBody {
-	func appending(_ other: Self) -> Self
+public func +<R: ResourceBodyAppendable>(_ left: R, right: R) -> R {
+    return left.appending(right)
 }
 
-public func +<R: AppendableResourceBody>(_ left: R, right: R) -> R {
-	return left.appending(right)
+/// A type allowing for a document body containing 1 primary resource.
+/// If the `Entity` specialization is an `Optional` type, the body can contain
+/// 0 or 1 primary resources.
+public struct SingleResourceBody<Entity: JSONAPI.OptionalEncodablePrimaryResource>: EncodableResourceBody {
+    public let value: Entity
+
+    public init(resourceObject: Entity) {
+        self.value = resourceObject
+    }
 }
 
-public struct SingleResourceBody<Entity: JSONAPI.MaybePrimaryResource>: ResourceBody {
-	public let value: Entity
+/// A type allowing for a document body containing 0 or more primary resources.
+public struct ManyResourceBody<Entity: JSONAPI.EncodablePrimaryResource>: EncodableResourceBody, ResourceBodyAppendable {
+    public let values: [Entity]
 
-	public init(entity: Entity) {
-		self.value = entity
-	}
-}
+    public init(resourceObjects: [Entity]) {
+        values = resourceObjects
+    }
 
-public struct ManyResourceBody<Entity: JSONAPI.PrimaryResource>: AppendableResourceBody {
-	public let values: [Entity]
-
-	public init(entities: [Entity]) {
-		values = entities
-	}
-
-	public func appending(_ other: ManyResourceBody) -> ManyResourceBody {
-		return ManyResourceBody(entities: values + other.values)
-	}
+    public func appending(_ other: ManyResourceBody) -> ManyResourceBody {
+        return ManyResourceBody(resourceObjects: values + other.values)
+    }
 }
 
 /// Use NoResourceBody to indicate you expect a JSON API document to not
 /// contain a "data" top-level key.
-public struct NoResourceBody: ResourceBody {
-	public static var none: NoResourceBody { return NoResourceBody() }
+public struct NoResourceBody: CodableResourceBody {
+    public static var none: NoResourceBody { return NoResourceBody() }
 }
 
 // MARK: Codable
 extension SingleResourceBody {
-	public init(from decoder: Decoder) throws {
-		let container = try decoder.singleValueContainer()
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
 
-		let anyNil: Any? = nil
-		if container.decodeNil(),
-			let val = anyNil as? Entity {
-			value = val
-			return
-		}
+        let anyNil: Any? = nil
+        let nilValue = anyNil as? Entity
+        guard value != nilValue else {
+            try container.encodeNil()
+            return
+        }
 
-		value = try container.decode(Entity.self)
-	}
+        try container.encode(value)
+    }
+}
 
-	public func encode(to encoder: Encoder) throws {
-		var container = encoder.singleValueContainer()
+extension SingleResourceBody: Decodable, CodableResourceBody where Entity: OptionalCodablePrimaryResource {
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
 
-		if (value as Any?) == nil {
-			try container.encodeNil()
-			return
-		}
+        let anyNil: Any? = nil
+        if container.decodeNil(),
+            let val = anyNil as? Entity {
+            value = val
+            return
+        }
 
-		try container.encode(value)
-	}
+        value = try container.decode(Entity.self)
+    }
 }
 
 extension ManyResourceBody {
-	public init(from decoder: Decoder) throws {
-		var container = try decoder.unkeyedContainer()
-		var valueAggregator = [Entity]()
-		while !container.isAtEnd {
-			valueAggregator.append(try container.decode(Entity.self))
-		}
-		values = valueAggregator
-	}
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.unkeyedContainer()
 
-	public func encode(to encoder: Encoder) throws {
-		var container = encoder.unkeyedContainer()
+        for value in values {
+            try container.encode(value)
+        }
+    }
+}
 
-		for value in values {
-			try container.encode(value)
-		}
-	}
+extension ManyResourceBody: Decodable, CodableResourceBody where Entity: CodablePrimaryResource {
+    public init(from decoder: Decoder) throws {
+        var container = try decoder.unkeyedContainer()
+        var valueAggregator = [Entity]()
+        while !container.isAtEnd {
+            valueAggregator.append(try container.decode(Entity.self))
+        }
+        values = valueAggregator
+    }
 }
 
 // MARK: CustomStringConvertible
 
 extension SingleResourceBody: CustomStringConvertible {
-	public var description: String {
-		return "PrimaryResourceBody(\(String(describing: value)))"
-	}
+    public var description: String {
+        return "PrimaryResourceBody(\(String(describing: value)))"
+    }
 }
 
 extension ManyResourceBody: CustomStringConvertible {
-	public var description: String {
-		return "PrimaryResourceBody(\(String(describing: values)))"
-	}
+    public var description: String {
+        return "PrimaryResourceBody(\(String(describing: values)))"
+    }
 }

Sources/JSONAPI/EmptyObjectDecoder.swift

@@ -0,0 +1,215 @@
+//
+//  EmptyObjectDecoder.swift
+//  JSONAPI
+//
+//  Created by Mathew Polzin on 7/2/19.
+//
+
+/// `EmptyObjectDecoder` exists internally for the sole purpose of
+/// allowing certain fallback logic paths to attempt to create `Decodable`
+/// types from empty containers (specifically in a way that is agnostic
+/// of any given encoding). In other words, this serves the same purpose
+/// as `JSONDecoder().decode(Thing.self, from: "{}".data(using: .utf8)!)`
+/// without needing to use a third party or `Foundation` library decoder.
+struct EmptyObjectDecoder: Decoder {
+
+    var codingPath: [CodingKey] = []
+
+    var userInfo: [CodingUserInfoKey : Any] = [:]
+
+    func container<Key>(keyedBy type: Key.Type) throws -> KeyedDecodingContainer<Key> where Key : CodingKey {
+        return KeyedDecodingContainer(EmptyKeyedContainer())
+    }
+
+    func unkeyedContainer() throws -> UnkeyedDecodingContainer {
+        return EmptyUnkeyedContainer()
+    }
+
+    func singleValueContainer() throws -> SingleValueDecodingContainer {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeSingleValue
+    }
+}
+
+enum EmptyObjectDecodingError: Swift.Error {
+    case emptyObjectCannotBeSingleValue
+    case emptyObjectCannotBeUnkeyedValues
+    case emptyObjectCannotHaveKeyedValues
+    case emptyObjectCannotHaveNestedContainers
+    case emptyObjectCannotHaveSuper
+}
+
+struct EmptyUnkeyedContainer: UnkeyedDecodingContainer {
+    var codingPath: [CodingKey] { return [] }
+
+    var count: Int? { return 0 }
+
+    var isAtEnd: Bool { return true }
+
+    var currentIndex: Int { return 0 }
+
+    mutating func decodeNil() throws -> Bool {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Bool.Type) throws -> Bool {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: String.Type) throws -> String {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Double.Type) throws -> Double {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Float.Type) throws -> Float {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Int.Type) throws -> Int {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Int8.Type) throws -> Int8 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Int16.Type) throws -> Int16 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Int32.Type) throws -> Int32 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: Int64.Type) throws -> Int64 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: UInt.Type) throws -> UInt {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: UInt8.Type) throws -> UInt8 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: UInt16.Type) throws -> UInt16 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: UInt32.Type) throws -> UInt32 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode(_ type: UInt64.Type) throws -> UInt64 {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func decode<T>(_ type: T.Type) throws -> T where T : Decodable {
+        throw EmptyObjectDecodingError.emptyObjectCannotBeUnkeyedValues
+    }
+
+    mutating func nestedContainer<NestedKey>(keyedBy type: NestedKey.Type) throws -> KeyedDecodingContainer<NestedKey> where NestedKey : CodingKey {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveNestedContainers
+    }
+
+    mutating func nestedUnkeyedContainer() throws -> UnkeyedDecodingContainer {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveNestedContainers
+    }
+
+    mutating func superDecoder() throws -> Decoder {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveSuper
+    }
+}
+
+struct EmptyKeyedContainer<Key: CodingKey>: KeyedDecodingContainerProtocol {
+    var codingPath: [CodingKey] { return [] }
+
+    var allKeys: [Key] { return [] }
+
+    func contains(_ key: Key) -> Bool {
+        return false
+    }
+
+    func decodeNil(forKey key: Key) throws -> Bool {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Bool.Type, forKey key: Key) throws -> Bool {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: String.Type, forKey key: Key) throws -> String {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Double.Type, forKey key: Key) throws -> Double {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Float.Type, forKey key: Key) throws -> Float {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Int.Type, forKey key: Key) throws -> Int {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Int8.Type, forKey key: Key) throws -> Int8 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Int16.Type, forKey key: Key) throws -> Int16 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Int32.Type, forKey key: Key) throws -> Int32 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: Int64.Type, forKey key: Key) throws -> Int64 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: UInt.Type, forKey key: Key) throws -> UInt {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: UInt8.Type, forKey key: Key) throws -> UInt8 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: UInt16.Type, forKey key: Key) throws -> UInt16 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: UInt32.Type, forKey key: Key) throws -> UInt32 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode(_ type: UInt64.Type, forKey key: Key) throws -> UInt64 {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func decode<T>(_ type: T.Type, forKey key: Key) throws -> T where T : Decodable {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveKeyedValues
+    }
+
+    func nestedContainer<NestedKey>(keyedBy type: NestedKey.Type, forKey key: Key) throws -> KeyedDecodingContainer<NestedKey> where NestedKey : CodingKey {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveNestedContainers
+    }
+
+    func nestedUnkeyedContainer(forKey key: Key) throws -> UnkeyedDecodingContainer {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveNestedContainers
+    }
+
+    func superDecoder() throws -> Decoder {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveSuper
+    }
+
+    func superDecoder(forKey key: Key) throws -> Decoder {
+        throw EmptyObjectDecodingError.emptyObjectCannotHaveSuper
+    }
+}