Release 1.2.1

What's Changed

Documentation Improvements

• Added CloudKit Usage Recommendations: Important guidance for users working with NSPersistentCloudKitContainer
• Added Apple's 7-Day Cleanup Strategy: Documentation now includes Apple's recommended cleanup strategy for optimal performance/capacity balance
• Fixed Issue #7: Addressed concerns about aggressive cleanup causing NSPersistentHistoryTokenExpiredError in CloudKit scenarios

Key Recommendations

When using NSPersistentCloudKitContainer:

• Use .byDuration(seconds: 60 * 60 * 24 * 7) cleanup strategy (7 days)
• Do NOT set includingCloudKitMirroring: true in CloudKit scenarios
• This prevents CloudKit from losing tracking tokens and avoids local database purges

Previous Changes (since 1.2.0)

• Documentation improvements for CloudKit users

Full Changelog: 1.2.0...1.2.1

1.2.0

What's New in 1.2.0

Custom Transaction Merger Support

This release introduces support for custom transaction merger implementations, providing flexibility to handle specific use cases such as undo manager conflicts.

Key Features:

• Public TransactionMergerProtocol: The protocol is now public, allowing developers to create custom merger implementations
• Dependency Injection: Pass custom merger instances via optional merger parameter in initializers
• Crash Prevention: Solves critical crashes when NSManagedObjectContext instances have their undoManager property configured
• Full Backward Compatibility: Existing code continues to work without any changes - defaults to the standard Merger() implementation

Example Usage:

class CustomTransactionMerger: TransactionMergerProtocol {
    func callAsFunction(merge transactions: [NSPersistentHistoryTransaction],
                        into contexts: [NSManagedObjectContext]) {
        for transaction in transactions {
            let notification = transaction.objectIDNotification()
            for context in contexts {
                context.perform {
                    // Temporarily disable undo manager to prevent crashes
                    let undoManager = context.undoManager
                    context.undoManager = nil
                    context.mergeChanges(fromContextDidSave: notification)
                    context.undoManager = undoManager
                }
            }
        }
    }
}

// Use custom merger
let kit = PersistentHistoryTrackingKit(
    // ... other parameters
    merger: CustomTransactionMerger()
)

Credits

Special thanks to @yangyubo for this excellent contribution! This enhancement provides the flexibility needed to handle complex undo manager scenarios while maintaining the simplicity of the default behavior.

Technical Details

• Follows SOLID principles (Open/Closed Principle)
• Improves testability through dependency injection
• All changes are additive with no breaking changes to the public API

Full Changelog: 1.1.0...1.2.0

1.1.0

Change the original performAndWait to performAndWaitWithResult to solve the compatibility problem after Xcode 26 beta 5

1.0.9

typos fixed by @junping1

1.0.8

Slight performance improvement

1.0.7

Add a deduplicator protocol to avoid duplicate records

1.0.6

Add buffer and update Readme

1.0.5

Fixed a possible accidental deletion when deleting a transaction in a widget.

1.0.4

Added includingCloudKitMirroring parameter to add support for toggling Core Data sync state in real time

1.0.2

Optimized some codes