A Swift package that processes Core Data persistent history so apps and extensions can observe, merge, and clean transactions consistently.
English | 中文
Core Data persistent history records changes made by an app, its extensions, background contexts, and optional CloudKit synchronization. Turning those records into a reliable merge and cleanup flow requires coordinating authors, contexts, and lifecycle events.
PersistentHistoryTrackingKit provides that coordination with an actor-based processing pipeline and hooks for app-specific observation or merge behavior. For the underlying Core Data model, read Using Persistent History Tracking in Core Data.
- Processes persistent-history transactions from configured authors and merges them into chosen contexts.
- Provides Observer Hooks for monitoring entity operations and Merge Hooks for custom merge pipelines.
- Supports automatic, manual, or disabled history cleanup and optional CloudKit mirroring authors.
- Uses Swift concurrency throughout and exposes explicit start/stop lifecycle control.
Add PersistentHistoryTrackingKit with Swift Package Manager:
dependencies: [
.package(url: "https://github.com/fatbobman/PersistentHistoryTrackingKit.git", from: "2.1.0")
]Enable persistent history and create the kit with the authors that share the store:
import CoreData
import PersistentHistoryTrackingKit
let container = NSPersistentContainer(name: "Model")
let description = container.persistentStoreDescriptions.first!
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
container.loadPersistentStores { _, error in
if let error { fatalError("Failed to load store: \(error)") }
}
container.viewContext.transactionAuthor = "MainApp"
let kit = PersistentHistoryTrackingKit(
container: container,
currentAuthor: "MainApp",
allAuthors: ["MainApp", "WidgetExtension"],
userDefaults: .standard
)- Want to understand Observer Hooks, Merge Hooks, and their execution constraints? Read the Hook Mechanism Guide.
- Want to move an existing V1 integration to V2? Read the Migration Guide.
- Want to look up initializer parameters, hook methods, cleanup options, and public types? Read the API Reference.
- Want to learn the Core Data fundamentals behind this package? Read Using Persistent History Tracking in Core Data.
Contributions are welcome through pull requests. Run the full suite with ./test.sh; it enables Core Data concurrency assertions and parallel execution.
PersistentHistoryTrackingKit is available under the MIT license. See the LICENSE file for more info.
Fatbobman (肘子) — Blog: fatbobman.com · X: @fatbobman
If this project helps you, please consider supporting my work:
- 📮 Subscribe to Fatbobman's Swift Weekly — fresh Swift and Apple-ecosystem insights every week
- ☕️ Buy Me a Coffee