Merge pull request #83 from mattpolzin/add-relationship-id-metadata

Add id metadata to relationships.

Author: mattpolzin

.github/workflows/tests.yml

@@ -18,8 +18,11 @@ jobs:
           - swift:5.2-focal
           - swift:5.2-centos8
           - swift:5.2-amazonlinux2
-          - swiftlang/swift:nightly-5.3-xenial
-          - swiftlang/swift:nightly-5.3-bionic
+          - swift:5.3-xenial
+          - swift:5.3-bionic
+          - swift:5.3-focal
+          - swift:5.3-centos8
+          - swift:5.3-amazonlinux2
     container: ${{ matrix.image }}
     steps:
     - name: Checkout code

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

@@ -30,8 +30,8 @@ typealias UnidentifiedJSONEntity<Description: ResourceObjectDescription> = JSONA
 // 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: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoMetadata, NoLinks>
-typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoMetadata, NoLinks>
+typealias ToOneRelationship<Entity: JSONAPIIdentifiable> = JSONAPI.ToOneRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
+typealias ToManyRelationship<Entity: Relatable> = JSONAPI.ToManyRelationship<Entity, NoIdMetadata, NoMetadata, NoLinks>
 
 // Create a typealias for a Document because we do not expect
 // JSON:API Documents for this particular API to have Metadata, Links,

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

@@ -72,7 +72,7 @@ enum AuthorDescription: ResourceObjectDescription {
 	}
 
 	struct Relationships: JSONAPI.Relationships {
-		let articles: ToManyRelationship<Article, ToManyRelationshipMetadata, ToManyRelationshipLinks>
+		let articles: ToManyRelationship<Article, NoIdMetadata, ToManyRelationshipMetadata, ToManyRelationshipLinks>
 	}
 }
 
@@ -88,11 +88,11 @@ enum ArticleDescription: ResourceObjectDescription {
 
 	struct Relationships: JSONAPI.Relationships {
 		/// The primary attributed author of the article.
-		let primaryAuthor: ToOneRelationship<Author, NoMetadata, NoLinks>
+		let primaryAuthor: ToOneRelationship<Author, NoIdMetadata, NoMetadata, NoLinks>
 		/// All authors excluding the primary author.
 		/// It is customary to print the primary author's
 		/// name first, followed by the other authors.
-		let otherAuthors: ToManyRelationship<Author, ToManyRelationshipMetadata, ToManyRelationshipLinks>
+		let otherAuthors: ToManyRelationship<Author, NoIdMetadata, ToManyRelationshipMetadata, ToManyRelationshipLinks>
 	}
 }
 

JSONAPI.playground/Sources/Entities.swift

@@ -25,8 +25,8 @@ extension String: CreatableRawIdType {
 
 // MARK: - typealiases for convenience
 public typealias ExampleEntity<Description: ResourceObjectDescription> = ResourceObject<Description, NoMetadata, NoLinks, String>
-public typealias ToOne<E: JSONAPIIdentifiable> = ToOneRelationship<E, NoMetadata, NoLinks>
-public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoMetadata, NoLinks>
+public typealias ToOne<E: JSONAPIIdentifiable> = ToOneRelationship<E, NoIdMetadata, NoMetadata, NoLinks>
+public typealias ToMany<E: Relatable> = ToManyRelationship<E, NoIdMetadata, NoMetadata, NoLinks>
 
 // MARK: - A few resource objects (entities)
 public enum PersonDescription: ResourceObjectDescription {

JSONAPI.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |spec|
   #
 
   spec.name         = "MP-JSONAPI"
-  spec.version      = "4.0.0"
+  spec.version      = "5.0.0"
   spec.summary      = "Swift Codable JSON API framework."
 
   # This description is used to generate tags and improve search results.

Package.resolved

@@ -28,3 +28,10 @@ public struct NoMetadata: Meta, CustomStringConvertible {
 
     public var description: String { return "No Metadata" }
 }
+
+/// The type of metadata found in a Resource Identifier Object.
+///
+/// It is sometimes more legible to differentiate between types of metadata
+/// even when the underlying type is the same. This typealias is only here
+/// to make code more easily understandable.
+public typealias NoIdMetadata = NoMetadata

Sources/JSONAPI/Meta/Meta.swift

@@ -33,107 +33,173 @@ public struct MetaRelationship<MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>
 
 /// A `ResourceObject` relationship that can be encoded to or decoded from
 /// a JSON API "Resource Linkage."
+///
 /// See https://jsonapi.org/format/#document-resource-object-linkage
+///
 /// A convenient typealias might make your code much more legible: `One<ResourceObjectDescription>`
-public struct ToOneRelationship<Identifiable: JSONAPI.JSONAPIIdentifiable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
+///
+/// The `IdMetaType` (if not `NoIdMetadata`) will be parsed out of the Resource Identifier Object.
+/// (see https://jsonapi.org/format/#document-resource-identifier-objects)
+///
+/// The `MetaType` (if not `NoMetadata`) will be parsed out of the Relationship Object.
+/// (see https://jsonapi.org/format/#document-resource-object-relationships)
+public struct ToOneRelationship<Identifiable: JSONAPI.JSONAPIIdentifiable, IdMetaType: JSONAPI.Meta, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
 
     public let id: Identifiable.ID
 
+    public let idMeta: IdMetaType
+
     public let meta: MetaType
     public let links: LinksType
 
+    public init(id: (Identifiable.ID, IdMetaType), meta: MetaType, links: LinksType) {
+        self.id = id.0
+        self.idMeta = id.1
+        self.meta = meta
+        self.links = links
+    }
+}
+
+extension ToOneRelationship where IdMetaType == NoIdMetadata {
     public init(id: Identifiable.ID, meta: MetaType, links: LinksType) {
         self.id = id
+        self.idMeta = .none
         self.meta = meta
         self.links = links
     }
 }
 
 extension ToOneRelationship where MetaType == NoMetadata, LinksType == NoLinks {
+    public init(id: (Identifiable.ID, IdMetaType)) {
+        self.init(id: id, meta: .none, links: .none)
+    }
+}
+
+extension ToOneRelationship where IdMetaType == NoIdMetadata, MetaType == NoMetadata, LinksType == NoLinks {
     public init(id: Identifiable.ID) {
         self.init(id: id, meta: .none, links: .none)
     }
 }
 
 extension ToOneRelationship {
-    public init<T: ResourceObjectType>(resourceObject: T, meta: MetaType, links: LinksType) where T.Id == Identifiable.ID {
+    public init<T: ResourceObjectType>(resourceObject: T, meta: MetaType, links: LinksType) where T.Id == Identifiable.ID, IdMetaType == NoIdMetadata {
         self.init(id: resourceObject.id, meta: meta, links: links)
     }
 }
 
-extension ToOneRelationship where MetaType == NoMetadata, LinksType == NoLinks {
+extension ToOneRelationship where MetaType == NoMetadata, LinksType == NoLinks, IdMetaType == NoIdMetadata {
     public init<T: ResourceObjectType>(resourceObject: T) where T.Id == Identifiable.ID {
         self.init(id: resourceObject.id, meta: .none, links: .none)
     }
 }
 
-extension ToOneRelationship where Identifiable: OptionalRelatable {
+extension ToOneRelationship where Identifiable: OptionalRelatable, IdMetaType == NoIdMetadata {
     public init<T: ResourceObjectType>(resourceObject: T?, meta: MetaType, links: LinksType) where T.Id == Identifiable.Wrapped.ID {
         self.init(id: resourceObject?.id, meta: meta, links: links)
     }
 }
 
-extension ToOneRelationship where Identifiable: OptionalRelatable, MetaType == NoMetadata, LinksType == NoLinks {
+extension ToOneRelationship where Identifiable: OptionalRelatable, MetaType == NoMetadata, LinksType == NoLinks, IdMetaType == NoIdMetadata {
     public init<T: ResourceObjectType>(resourceObject: T?) where T.Id == Identifiable.Wrapped.ID {
         self.init(id: resourceObject?.id, meta: .none, links: .none)
     }
 }
 
 /// An ResourceObject relationship that can be encoded to or decoded from
 /// a JSON API "Resource Linkage."
+///
 /// See https://jsonapi.org/format/#document-resource-object-linkage
+///
 /// A convenient typealias might make your code much more legible: `Many<ResourceObjectDescription>`
-public struct ToManyRelationship<Relatable: JSONAPI.Relatable, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
+///
+/// The `IdMetaType` (if not `NoIdMetadata`) will be parsed out of the Resource Identifier Object.
+/// (see https://jsonapi.org/format/#document-resource-identifier-objects)
+///
+/// The `MetaType` (if not `NoMetadata`) will be parsed out of the Relationship Object.
+/// (see https://jsonapi.org/format/#document-resource-object-relationships)
+public struct ToManyRelationship<Relatable: JSONAPI.Relatable, IdMetaType: JSONAPI.Meta, MetaType: JSONAPI.Meta, LinksType: JSONAPI.Links>: RelationshipType, Equatable {
+
+    public struct ID: Equatable {
+        public let id: Relatable.ID
+        public let meta: IdMetaType
+
+        public init(id: Relatable.ID, meta: IdMetaType) {
+            self.id = id
+            self.meta = meta
+        }
 
-    public let ids: [Relatable.ID]
+        internal init(_ idPair: (Relatable.ID, IdMetaType)) {
+            self.init(id: idPair.0, meta: idPair.1)
+        }
+    }
+
+    public let idsWithMeta: [ID]
+
+    public var ids: [Relatable.ID] {
+        idsWithMeta.map(\.id)
+    }
 
     public let meta: MetaType
     public let links: LinksType
 
-    public init(ids: [Relatable.ID], meta: MetaType, links: LinksType) {
-        self.ids = ids
+    public init(idsWithMetadata ids: [(Relatable.ID, IdMetaType)], meta: MetaType, links: LinksType) {
+        self.idsWithMeta = ids.map { ID.init($0) }
         self.meta = meta
         self.links = links
     }
 
-    public init<T: JSONAPIIdentifiable>(pointers: [ToOneRelationship<T, NoMetadata, NoLinks>], meta: MetaType, links: LinksType) where T.ID == Relatable.ID {
-        ids = pointers.map(\.id)
+    public init<T: JSONAPIIdentifiable>(pointers: [ToOneRelationship<T, NoIdMetadata, NoMetadata, NoLinks>], meta: MetaType, links: LinksType) where T.ID == Relatable.ID, IdMetaType == NoIdMetadata {
+        idsWithMeta = pointers.map { .init(id: $0.id, meta: .none) }
         self.meta = meta
         self.links = links
     }
 
-    public init<T: ResourceObjectType>(resourceObjects: [T], meta: MetaType, links: LinksType) where T.Id == Relatable.ID {
+    public init<T: ResourceObjectType>(resourceObjects: [T], meta: MetaType, links: LinksType) where T.Id == Relatable.ID, IdMetaType == NoIdMetadata {
         self.init(ids: resourceObjects.map(\.id), meta: meta, links: links)
     }
 
     private init(meta: MetaType, links: LinksType) {
-        self.init(ids: [], meta: meta, links: links)
+        self.init(idsWithMetadata: [], meta: meta, links: links)
     }
 
     public static func none(withMeta meta: MetaType, links: LinksType) -> ToManyRelationship {
         return ToManyRelationship(meta: meta, links: links)
     }
 }
 
+extension ToManyRelationship where IdMetaType == NoIdMetadata {
+    public init(ids: [Relatable.ID], meta: MetaType, links: LinksType) {
+        self.idsWithMeta = ids.map { .init(id: $0, meta: .none) }
+        self.meta = meta
+        self.links = links
+    }
+}
+
 extension ToManyRelationship where MetaType == NoMetadata, LinksType == NoLinks {
 
-    public init(ids: [Relatable.ID]) {
-        self.init(ids: ids, meta: .none, links: .none)
+    public init(idsWithMetadata ids: [(Relatable.ID, IdMetaType)]) {
+        self.init(idsWithMetadata: ids, meta: .none, links: .none)
     }
 
-    public init<T: JSONAPIIdentifiable>(pointers: [ToOneRelationship<T, NoMetadata, NoLinks>]) where T.ID == Relatable.ID {
+    public init<T: JSONAPIIdentifiable>(pointers: [ToOneRelationship<T, NoIdMetadata, NoMetadata, NoLinks>]) where T.ID == Relatable.ID, IdMetaType == NoIdMetadata {
         self.init(pointers: pointers, meta: .none, links: .none)
     }
 
     public static var none: ToManyRelationship {
         return .none(withMeta: .none, links: .none)
     }
 
-    public init<T: ResourceObjectType>(resourceObjects: [T]) where T.Id == Relatable.ID {
+    public init<T: ResourceObjectType>(resourceObjects: [T]) where T.Id == Relatable.ID, IdMetaType == NoIdMetadata {
         self.init(resourceObjects: resourceObjects, meta: .none, links: .none)
     }
 }
 
+extension ToManyRelationship where IdMetaType == NoIdMetadata, MetaType == NoMetadata, LinksType == NoLinks {
+    public init(ids: [Relatable.ID]) {
+        self.init(ids: ids, meta: .none, links: .none)
+    }
+}
+
 public protocol JSONAPIIdentifiable: JSONTyped {
     associatedtype ID: Equatable
 }
@@ -164,6 +230,7 @@ private enum ResourceLinkageCodingKeys: String, CodingKey {
 private enum ResourceIdentifierCodingKeys: String, CodingKey {
     case id = "id"
     case entityType = "type"
+    case metadata = "meta"
 }
 
 extension MetaRelationship: Codable {
@@ -196,6 +263,9 @@ extension MetaRelationship: Codable {
     }
 }
 
+fileprivate protocol _Optional {}
+extension Optional: _Optional {}
+
 extension ToOneRelationship: Codable where Identifiable.ID: OptionalId {
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: ResourceLinkageCodingKeys.self)
@@ -228,6 +298,23 @@ extension ToOneRelationship: Codable where Identifiable.ID: OptionalId {
                     )
                 )
             }
+            // if we know we aren't getting any Resource Identifer Object at all
+            // (which we do inside this block) then we better either be expecting
+            // no Id Metadata or optional Id Metadata or else we will report an
+            // error.
+            if let noIdMeta = NoIdMetadata() as? IdMetaType {
+                idMeta = noIdMeta
+            } else if let nilMeta = anyNil as? IdMetaType {
+                idMeta = nilMeta
+            } else {
+                throw DecodingError.valueNotFound(
+                    Self.self,
+                    DecodingError.Context(
+                        codingPath: decoder.codingPath,
+                        debugDescription: "Expected non-null relationship data with metadata inside."
+                    )
+                )
+            }
             id = val
             return
         }
@@ -256,6 +343,15 @@ extension ToOneRelationship: Codable where Identifiable.ID: OptionalId {
             )
         }
 
+        let idMeta: IdMetaType
+        let maybeNoIdMeta: IdMetaType? = NoIdMetadata() as? IdMetaType
+        if let noIdMeta = maybeNoIdMeta {
+            idMeta = noIdMeta
+        } else {
+            idMeta = try identifier.decode(IdMetaType.self, forKey: .metadata)
+        }
+        self.idMeta = idMeta
+
         id = Identifiable.ID(rawValue: try identifier.decode(Identifiable.ID.RawType.self, forKey: .id))
     }
 
@@ -282,6 +378,9 @@ extension ToOneRelationship: Codable where Identifiable.ID: OptionalId {
         var identifier = container.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self, forKey: .data)
 
         try identifier.encode(id.rawValue, forKey: .id)
+        if IdMetaType.self != NoMetadata.self {
+            try identifier.encode(idMeta, forKey: .metadata)
+        }
         try identifier.encode(Identifiable.jsonType, forKey: .entityType)
     }
 }
@@ -311,10 +410,10 @@ extension ToManyRelationship: Codable {
                     throw error
             }
             throw JSONAPICodingError.quantityMismatch(expected: .many,
-                                                  path: context.codingPath)
+                                                      path: context.codingPath)
         }
 
-        var newIds = [Relatable.ID]()
+        var newIds = [ID]()
         while !identifiers.isAtEnd {
             let identifier = try identifiers.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self)
 
@@ -324,9 +423,19 @@ extension ToManyRelationship: Codable {
                 throw JSONAPICodingError.typeMismatch(expected: Relatable.jsonType, found: type, path: decoder.codingPath)
             }
 
-            newIds.append(Relatable.ID(rawValue: try identifier.decode(Relatable.ID.RawType.self, forKey: .id)))
+            let id = try identifier.decode(Relatable.ID.RawType.self, forKey: .id)
+
+            let idMeta: IdMetaType
+            let maybeNoIdMeta: IdMetaType? = NoIdMetadata() as? IdMetaType
+            if let noIdMeta = maybeNoIdMeta {
+                idMeta = noIdMeta
+            } else {
+                idMeta = try identifier.decode(IdMetaType.self, forKey: .metadata)
+            }
+
+            newIds.append(.init(id: Relatable.ID(rawValue: id), meta: idMeta) )
         }
-        ids = newIds
+        idsWithMeta = newIds
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -342,10 +451,13 @@ extension ToManyRelationship: Codable {
 
         var identifiers = container.nestedUnkeyedContainer(forKey: .data)
 
-        for id in ids {
+        for id in idsWithMeta {
             var identifier = identifiers.nestedContainer(keyedBy: ResourceIdentifierCodingKeys.self)
 
-            try identifier.encode(id.rawValue, forKey: .id)
+            try identifier.encode(id.id.rawValue, forKey: .id)
+            if IdMetaType.self != NoMetadata.self {
+                try identifier.encode(id.meta, forKey: .metadata)
+            }
             try identifier.encode(Relatable.jsonType, forKey: .entityType)
         }
     }