Merge pull request #36 from PureSwift/feature/composite-attribute

Add Composite Attribute Support

Author: colemancda

Sources/CoreDataModel/CoreDataModelError.swift

@@ -0,0 +1,63 @@
+//
+//  CoreDataModelError.swift
+//  CoreDataModel
+//
+//  Created by Alsey Coleman Miller on 8/16/26.
+//
+
+#if canImport(CoreData)
+import Foundation
+import CoreModel
+
+/// An error building a CoreData model from a CoreModel ``Model``.
+public enum CoreDataModelError: Error {
+
+    /// The model declares a composite attribute, which requires
+    /// macOS 14, iOS 17, tvOS 17, or watchOS 10 or later.
+    case compositeAttributesUnavailable(EntityName, PropertyKey)
+
+    /// A composite attribute declared no elements.
+    ///
+    /// CoreData rejects a composite type with an empty element list.
+    case emptyCompositeAttribute(PropertyKey)
+
+    /// The stored value for a composite attribute did not match its element descriptions.
+    case invalidCompositeValue(PropertyKey)
+}
+
+// MARK: - CustomNSError
+
+extension CoreDataModelError: CustomNSError {
+
+    public static var errorDomain: String { "org.pureswift.CoreDataModel.CoreDataModelError" }
+
+    public var errorCode: Int {
+        switch self {
+        case .compositeAttributesUnavailable:   return 1
+        case .emptyCompositeAttribute:          return 2
+        case .invalidCompositeValue:            return 3
+        }
+    }
+
+    public var errorUserInfo: [String: Any] {
+        [NSLocalizedDescriptionKey: description]
+    }
+}
+
+// MARK: - CustomStringConvertible
+
+extension CoreDataModelError: CustomStringConvertible {
+
+    public var description: String {
+        switch self {
+        case let .compositeAttributesUnavailable(entity, key):
+            return "Composite attribute \(entity).\(key) requires macOS 14, iOS 17, tvOS 17, or watchOS 10 or later."
+        case let .emptyCompositeAttribute(key):
+            return "Composite attribute \(key) must declare at least one element."
+        case let .invalidCompositeValue(key):
+            return "Invalid value for composite attribute \(key)."
+        }
+    }
+}
+
+#endif

Sources/CoreDataModel/NSAttributeDescription.swift

@@ -1,6 +1,6 @@
 //
 //  NSAttributeDescription.swift
-//  
+//
 //
 //  Created by Alsey Coleman Miller on 8/17/23.
 //
@@ -11,16 +11,56 @@ import CoreData
 import CoreModel
 
 public extension NSAttributeDescription {
-    
+
+    /// - Warning: A composite attribute needs an `NSCompositeAttributeDescription`,
+    /// which this initializer cannot return. Use ``make(attribute:isOptional:)`` instead.
     convenience init(
         attribute: Attribute,
         isOptional: Bool = true
     ) {
         self.init()
         self.name = attribute.id.rawValue
         self.isOptional = isOptional
+        assert(attribute.type.isComposite == false, "Use NSAttributeDescription.make(attribute:) for composite attributes")
         self.attributeType = .init(attributeType: attribute.type)
     }
 }
 
+internal extension NSAttributeDescription {
+
+    /// Build the CoreData property description for a CoreModel attribute.
+    ///
+    /// A composite attribute produces an `NSCompositeAttributeDescription`, which is a
+    /// different class and so cannot come from a `convenience init` on this one.
+    ///
+    /// - Note: CoreData's two other constraints on elements hold by construction here:
+    /// an element can never be a relationship (``Attribute`` has no relationship type),
+    /// and the element tree is a finite value, so it cannot be recursive.
+    static func make(attribute: Attribute, isOptional: Bool = true) throws -> NSAttributeDescription {
+        guard case let .composite(elements) = attribute.type else {
+            return NSAttributeDescription(attribute: attribute, isOptional: isOptional)
+        }
+        guard elements.isEmpty == false else {
+            throw CoreDataModelError.emptyCompositeAttribute(attribute.id)
+        }
+        guard #available(macOS 14, iOS 17, tvOS 17, watchOS 10, *) else {
+            throw CoreDataModelError.compositeAttributesUnavailable("", attribute.id)
+        }
+        let description = NSCompositeAttributeDescription()
+        description.name = attribute.id.rawValue
+        description.isOptional = isOptional
+        description.attributeType = .composite
+        // - Note: Elements are always optional. CoreData raises a "missing mandatory
+        //   data" validation fault on save when a non-optional element is absent, and
+        //   `momc` does not diagnose it at build time.
+        var children = [NSAttributeDescription]()
+        children.reserveCapacity(elements.count)
+        for element in elements {
+            children.append(try make(attribute: element, isOptional: true))
+        }
+        description.elements = children
+        return description
+    }
+}
+
 #endif

Sources/CoreDataModel/NSAttributeType.swift

@@ -10,10 +10,22 @@ import Foundation
 import CoreData
 import CoreModel
 
+internal extension NSAttributeType {
+
+    /// `NSCompositeAttributeType` (2100).
+    ///
+    /// - Note: Spelled by raw value so that referencing it doesn't depend on the
+    /// availability annotations of the imported enum case. The
+    /// `NSCompositeAttributeDescription` *class* still requires macOS 14 / iOS 17.
+    static var composite: NSAttributeType { NSAttributeType(rawValue: 2100)! }
+}
+
 public extension NSAttributeType {
-    
+
     init(attributeType: AttributeType) {
         switch attributeType {
+        case .composite:
+            self = .composite
         case .bool:
             self = .booleanAttributeType
         case .int16:
@@ -43,7 +55,40 @@ public extension NSAttributeType {
 }
 
 public extension AttributeType {
-    
+
+    /// Reconstruct the CoreModel attribute type from a CoreData attribute description,
+    /// including composite attributes and their (possibly nested) elements.
+    ///
+    /// Prefer this over ``init(attributeType:)``, which cannot represent composites:
+    /// the elements live on the description, not on the `NSAttributeType`.
+    init?(attribute: NSAttributeDescription) {
+        guard attribute.attributeType == .composite else {
+            guard let type = AttributeType(attributeType: attribute.attributeType) else {
+                return nil
+            }
+            self = type
+            return
+        }
+        guard #available(macOS 14, iOS 17, tvOS 17, watchOS 10, *) else {
+            return nil
+        }
+        guard let composite = attribute as? NSCompositeAttributeDescription else {
+            return nil
+        }
+        var elements = [Attribute]()
+        elements.reserveCapacity(composite.elements.count)
+        for element in composite.elements {
+            // recursion handles nested composites
+            guard let type = AttributeType(attribute: element) else {
+                return nil
+            }
+            elements.append(Attribute(id: PropertyKey(rawValue: element.name), type: type))
+        }
+        self = .composite(elements)
+    }
+
+    /// - Note: Returns `nil` for `.compositeAttributeType`, whose elements cannot be
+    /// recovered from the type alone. Use ``init(attribute:)`` to round-trip composites.
     init?(attributeType: NSAttributeType) {
         switch attributeType {
         case .undefinedAttributeType:

Sources/CoreDataModel/NSEntityDescription.swift

@@ -12,7 +12,7 @@ import CoreModel
 
 internal extension NSEntityDescription {
 
-    convenience init(entity: EntityDescription) {
+    convenience init(entity: EntityDescription) throws {
         self.init()
         self.name = entity.id.rawValue
         // add id attribute
@@ -27,7 +27,15 @@ internal extension NSEntityDescription {
         var properties = [NSPropertyDescription]()
         properties.reserveCapacity(entity.attributes.count + entity.relationships.count + 1)
         properties.append(id)
-        properties += entity.attributes.map { NSAttributeDescription(attribute: $0) }
+        for attribute in entity.attributes {
+            do {
+                properties.append(try NSAttributeDescription.make(attribute: attribute))
+            }
+            catch CoreDataModelError.compositeAttributesUnavailable(_, let key) {
+                // re-throw with the entity name attached
+                throw CoreDataModelError.compositeAttributesUnavailable(entity.id, key)
+            }
+        }
         properties += entity.relationships.map { NSRelationshipDescription(relationship: $0) }
         self.properties = properties
         self.uniquenessConstraints = [[NSManagedObject.BuiltInProperty.id.rawValue as NSString]]