codexkit 1.0.0

package/.codex/skills/core-data-expert/references/model-configuration.md

@@ -0,0 +1,597 @@
+# Model Configuration
+
+Core Data's data model offers powerful configuration options beyond basic attributes and relationships. This guide covers constraints, derived attributes, transformables, validation, and lifecycle events.
+
+## Constraints
+
+Constraints ensure uniqueness of attribute values. When combined with the correct merge policy, Core Data automatically handles duplicates.
+
+### Setting Up Constraints
+
+In Xcode's Data Model Editor:
+1. Select your entity
+2. In the Data Model Inspector, find "Constraints"
+3. Click "+" and add attribute names
+
+**Example:** Make `name` unique in the `Category` entity.
+
+### Required Merge Policy
+
+```swift
+viewContext.mergePolicy = NSMergeByPropertyStoreTrumpMergePolicy
+```
+
+**Without this merge policy, constraint violations will crash your app.**
+
+### How Constraints Work
+
+```swift
+// First save
+let category1 = Category(context: context)
+category1.name = "Swift"
+try context.save() // Saves successfully
+
+// Duplicate attempt
+let category2 = Category(context: context)
+category2.name = "Swift" // Same name
+try context.save() // With correct merge policy: keeps first, discards second
+```
+
+### Multiple Constraints
+
+```swift
+// Constraints on multiple attributes
+// In model: constraints = ["email", "username"]
+
+// Both must be unique
+user1.email = "test@example.com"
+user1.username = "testuser"
+```
+
+### Compound Constraints
+
+```swift
+// Unique combination of attributes
+// In model: constraints = ["firstName,lastName"]
+
+// These are different (unique combinations)
+person1.firstName = "John"
+person1.lastName = "Doe"
+
+person2.firstName = "John"
+person2.lastName = "Smith" // Different combination, allowed
+```
+
+## Derived Attributes
+
+Derived attributes are computed from other attributes or relationships and stored in the database. They're calculated on save or refresh.
+
+### Benefits
+
+- No need to manually update computed values
+- Better performance than accessing relationships
+- Optimized for queries
+
+### Common Derivations
+
+#### 1. Count of Relationships
+
+```swift
+// In Data Model Editor:
+// Derived attribute: articlesCount
+// Derivation: articles.@count
+```
+
+**Why this is better than `articles.count`:**
+- Doesn't fire faults
+- Faster queries
+- Always up-to-date after save
+
+#### 2. Related Object Property
+
+```swift
+// Derived attribute: categoryName
+// Derivation: category.name
+```
+
+**Use case:** Avoid firing faults when displaying list views.
+
+#### 3. Current Timestamp
+
+```swift
+// Derived attribute: lastModified
+// Derivation: now()
+```
+
+**Automatically updates on every save.**
+
+#### 4. Canonical String (Search Optimization)
+
+```swift
+// Derived attribute: searchName
+// Derivation: canonical:(name)
+```
+
+**What it does:**
+- Converts to lowercase
+- Removes diacritics
+- Perfect for case-insensitive, diacritic-insensitive searches
+
+**Example:**
+```swift
+// name = "Café"
+// searchName = "cafe"
+
+// Search query
+fetchRequest.predicate = NSPredicate(format: "searchName CONTAINS %@", "cafe")
+// Matches "Café", "CAFE", "café", etc.
+```
+
+#### 5. Sum of Related Values
+
+```swift
+// Derived attribute: totalViews
+// Derivation: @sum.articles.views
+```
+
+### Important Notes
+
+- Derived attributes are calculated **on save** or **refresh**
+- In-memory changes don't update derived attributes until saved
+- Can't be set manually (they're computed)
+
+### Example Usage
+
+```swift
+class Article: NSManagedObject {
+    @NSManaged var name: String
+    @NSManaged var category: Category?
+    
+    // Derived from category.name
+    @NSManaged var categoryName: String?
+    
+    // Derived from canonical:(name)
+    @NSManaged var searchName: String?
+}
+
+// Usage
+article.name = "Core Data Best Practices"
+try context.save()
+
+// After save, derived attributes are updated
+print(article.searchName) // "core data best practices"
+print(article.categoryName) // "Swift"
+```
+
+## Transformables
+
+Transformables allow storing custom types that aren't natively supported by Core Data.
+
+### Creating a Value Transformer
+
+```swift
+import UIKit
+
+@objc(ColorTransformer)
+class ColorTransformer: ValueTransformer {
+    override class func transformedValueClass() -> AnyClass {
+        return NSData.self
+    }
+    
+    override class func allowsReverseTransformation() -> Bool {
+        return true
+    }
+    
+    override func transformedValue(_ value: Any?) -> Any? {
+        guard let color = value as? UIColor else { return nil }
+        
+        do {
+            let data = try NSKeyedArchiver.archivedData(
+                withRootObject: color,
+                requiringSecureCoding: true
+            )
+            return data
+        } catch {
+            print("Failed to transform color: \(error)")
+            return nil
+        }
+    }
+    
+    override func reverseTransformedValue(_ value: Any?) -> Any? {
+        guard let data = value as? Data else { return nil }
+        
+        do {
+            let color = try NSKeyedUnarchiver.unarchivedObject(
+                ofClass: UIColor.self,
+                from: data
+            )
+            return color
+        } catch {
+            print("Failed to reverse transform color: \(error)")
+            return nil
+        }
+    }
+}
+```
+
+### Registering the Transformer
+
+```swift
+// In your stack setup, before loading stores
+ValueTransformer.setValueTransformer(
+    ColorTransformer(),
+    forName: NSValueTransformerName("ColorTransformer")
+)
+```
+
+### Configuring in Data Model
+
+1. Select the attribute
+2. Set Type to "Transformable"
+3. Set "Custom Class" to your type (e.g., `UIColor`)
+4. Set "Transformer" to your transformer name (e.g., `ColorTransformer`)
+
+### Using Transformable Attributes
+
+```swift
+class Article: NSManagedObject {
+    @NSManaged var color: UIColor?
+}
+
+// Usage
+article.color = .systemBlue
+try context.save()
+
+// Retrieval
+let color = article.color // UIColor
+```
+
+### NSSecureCoding Requirement
+
+Modern Core Data requires secure coding:
+
+```swift
+// Make your custom type conform to NSSecureCoding
+extension CustomType: NSSecureCoding {
+    static var supportsSecureCoding: Bool { return true }
+    
+    func encode(with coder: NSCoder) {
+        // Encode properties
+    }
+    
+    required init?(coder: NSCoder) {
+        // Decode properties
+    }
+}
+```
+
+## Validation
+
+Core Data provides built-in validation that runs before saving.
+
+### Model-Level Validation
+
+Set in Data Model Editor:
+
+**String Validation:**
+- Minimum Length
+- Maximum Length
+- Regular Expression
+
+**Numeric Validation:**
+- Minimum Value
+- Maximum Value
+
+**Example:**
+```
+Attribute: name
+Type: String
+Min Length: 3
+Max Length: 100
+```
+
+### Code-Level Validation
+
+Override validation methods in your `NSManagedObject` subclass:
+
+```swift
+class Article: NSManagedObject {
+    @NSManaged var name: String?
+    
+    // Validate before insert
+    override func validateForInsert() throws {
+        try super.validateForInsert()
+        try validateName()
+    }
+    
+    // Validate before update
+    override func validateForUpdate() throws {
+        try super.validateForUpdate()
+        try validateName()
+    }
+    
+    // Validate before delete
+    override func validateForDelete() throws {
+        try super.validateForDelete()
+        
+        // Example: Can't delete if has related objects
+        if let attachments = attachments, !attachments.isEmpty {
+            throw NSError(
+                domain: "ArticleValidation",
+                code: 1001,
+                userInfo: [NSLocalizedDescriptionKey: "Cannot delete article with attachments"]
+            )
+        }
+    }
+    
+    // Custom validation
+    private func validateName() throws {
+        guard let name = name, !name.isEmpty else {
+            throw NSError(
+                domain: "ArticleValidation",
+                code: 1000,
+                userInfo: [NSLocalizedDescriptionKey: "Name cannot be empty"]
+            )
+        }
+        
+        // Check for protected names
+        let protectedNames = ["Admin", "System", "Root"]
+        if protectedNames.contains(name) {
+            throw NSError(
+                domain: "ArticleValidation",
+                code: 1002,
+                userInfo: [NSLocalizedDescriptionKey: "'\(name)' is a protected name"]
+            )
+        }
+    }
+}
+```
+
+### Property-Level Validation
+
+```swift
+class Article: NSManagedObject {
+    @NSManaged var name: String?
+    
+    override func validateName(_ value: AutoreleasingUnsafeMutablePointer<AnyObject?>) throws {
+        guard let name = value.pointee as? String, !name.isEmpty else {
+            throw NSError(
+                domain: "ArticleValidation",
+                code: 1000,
+                userInfo: [NSLocalizedDescriptionKey: "Name cannot be empty"]
+            )
+        }
+    }
+}
+```
+
+### Handling Validation Errors
+
+```swift
+do {
+    try context.save()
+} catch let error as NSError {
+    if error.domain == NSCocoaErrorDomain {
+        switch error.code {
+        case NSValidationStringTooShortError:
+            print("String too short")
+        case NSValidationStringTooLongError:
+            print("String too long")
+        case NSManagedObjectValidationError:
+            print("Validation failed")
+        default:
+            print("Other error: \(error.localizedDescription)")
+        }
+    }
+}
+```
+
+## Lifecycle Events
+
+Override lifecycle methods to perform actions at specific points in an object's life.
+
+### awakeFromInsert()
+
+Called once when object is first inserted into context.
+
+```swift
+override func awakeFromInsert() {
+    super.awakeFromInsert()
+    
+    // Set default values
+    setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
+    setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
+    setPrimitiveValue(0, forKey: #keyPath(Article.views))
+}
+```
+
+**Use `setPrimitiveValue` to avoid:**
+- KVO notifications
+- Marking object as changed
+- Infinite loops
+
+### willSave()
+
+Called before every save. Use for updating modification dates or cleaning up.
+
+```swift
+override func willSave() {
+    super.willSave()
+    
+    // Update modification date
+    setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
+    
+    // Delete local files if object is deleted
+    if isDeleted, let localResource = localResourceURL {
+        try? FileManager.default.removeItem(at: localResource)
+    }
+}
+```
+
+**Caution:** Don't call `save()` inside `willSave()` - infinite loop!
+
+### didSave()
+
+Called after save completes.
+
+```swift
+override func didSave() {
+    super.didSave()
+    
+    // Post notification, update cache, etc.
+    NotificationCenter.default.post(
+        name: .articleDidSave,
+        object: self
+    )
+}
+```
+
+### prepareForDeletion()
+
+Called when object is marked for deletion (before save).
+
+```swift
+override func prepareForDeletion() {
+    super.prepareForDeletion()
+    
+    // Cancel ongoing operations
+    downloadTask?.cancel()
+    
+    // Don't delete files here! Use willSave() instead
+    // (prepareForDeletion is called even if save is rolled back)
+}
+```
+
+**Important:** Don't delete files in `prepareForDeletion()`. The deletion might be rolled back, leaving your data inconsistent.
+
+### awakeFromFetch()
+
+Called when object is fetched from store.
+
+```swift
+override func awakeFromFetch() {
+    super.awakeFromFetch()
+    
+    // Initialize transient properties
+    setupObservers()
+}
+```
+
+### Complete Lifecycle Example
+
+```swift
+class Article: NSManagedObject {
+    @NSManaged var name: String?
+    @NSManaged var creationDate: Date?
+    @NSManaged var lastModified: Date?
+    @NSManaged var localResourceURL: URL?
+    
+    override func awakeFromInsert() {
+        super.awakeFromInsert()
+        
+        // Set creation date once
+        setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
+        setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
+    }
+    
+    override func willSave() {
+        super.willSave()
+        
+        // Update modification date on every save
+        if !isDeleted && changedValues().keys.contains("name") {
+            setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
+        }
+        
+        // Clean up files when deleted
+        if isDeleted, let url = localResourceURL {
+            try? FileManager.default.removeItem(at: url)
+        }
+    }
+    
+    override func prepareForDeletion() {
+        super.prepareForDeletion()
+        
+        // Cancel ongoing operations
+        // Don't delete files here!
+    }
+}
+```
+
+## Common Pitfalls
+
+### ❌ Not Setting Merge Policy with Constraints
+
+```swift
+// Constraint violation will crash
+let category = Category(context: context)
+category.name = "Duplicate"
+try context.save() // CRASH!
+```
+
+### ❌ Manually Setting Derived Attributes
+
+```swift
+// Derived attributes are read-only
+article.categoryName = "Swift" // Ignored!
+```
+
+### ❌ Using KVO Methods in Lifecycle Events
+
+```swift
+override func awakeFromInsert() {
+    super.awakeFromInsert()
+    
+    // ❌ Triggers KVO, marks as changed
+    self.creationDate = Date()
+    
+    // ✅ Use primitive values
+    setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
+}
+```
+
+### ❌ Deleting Files in prepareForDeletion
+
+```swift
+override func prepareForDeletion() {
+    super.prepareForDeletion()
+    
+    // ❌ Bad: Deletion might be rolled back
+    try? FileManager.default.removeItem(at: fileURL)
+}
+```
+
+### ✅ Correct Approaches
+
+```swift
+// Set merge policy
+viewContext.mergePolicy = NSMergeByPropertyStoreTrumpMergePolicy
+
+// Let derived attributes compute themselves
+article.name = "New Name"
+try context.save()
+print(article.searchName) // Automatically updated
+
+// Use primitive values in lifecycle events
+setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
+
+// Delete files in willSave when isDeleted
+override func willSave() {
+    super.willSave()
+    if isDeleted {
+        try? FileManager.default.removeItem(at: fileURL)
+    }
+}
+```
+
+## Summary
+
+1. **Use constraints for uniqueness** - Requires NSMergeByPropertyStoreTrumpMergePolicy
+2. **Use derived attributes** - Better performance than accessing relationships
+3. **Use canonical: for search** - Case and diacritic insensitive
+4. **Use transformables for custom types** - With NSSecureCoding
+5. **Validate in code** - For complex business rules
+6. **Use awakeFromInsert for defaults** - Called once on creation
+7. **Use willSave for updates** - Called before every save
+8. **Use setPrimitiveValue** - Avoid KVO in lifecycle events
+9. **Delete files in willSave** - When isDeleted is true
+10. **Don't save in willSave** - Causes infinite loop