Classes

The AsynchronousDataTransaction provides an interface for DynamicObject creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from DataStack.perform(asynchronous:...).

The BaseDataTransaction is an abstract interface for NSManagedObject creates, updates, and deletes. All BaseDataTransaction subclasses manage a private NSManagedObjectContext which are direct children of the NSPersistentStoreCoordinator‘s root NSManagedObjectContext. This means that all updates are saved first to the persistent store, and then propagated up to the read-only NSManagedObjectContext.

The CoreStoreObject is an abstract class for creating CoreStore-managed objects that are more type-safe and more convenient than NSManagedObject subclasses. The model entities for CoreStoreObject subclasses are inferred from the Swift declaration themselves; no .xcdatamodeld files are needed. To declare persisted attributes and relationships for the CoreStoreObject subclass, declare properties of type Value.Required<T>, Value.Optional<T> for values, or Relationship.ToOne<T>, Relationship.ToManyOrdered<T>, Relationship.ToManyUnordered<T> for relationships.

class Animal: CoreStoreObject {
    let species = Value.Required<String>("species", initial: "")
    let nickname = Value.Optional<String>("nickname")
    let master = Relationship.ToOne<Person>("master")
}

class Person: CoreStoreObject {
    let name = Value.Required<String>("name", initial: "")
    let pet = Relationship.ToOne<Animal>("pet", inverse: { $0.master })
}

CoreStoreObject entities for a model version should be added to CoreStoreSchema instance.

CoreStoreDefaults.dataStack = DataStack(
    CoreStoreSchema(
        modelVersion: "V1",
        entities: [
            Entity<Animal>("Animal"),
            Entity<Person>("Person")
        ]
    )
)

The CoreStoreSchema describes models written for CoreStoreObject Swift class declarations for a particular model version. CoreStoreObject entities for a model version should be added to CoreStoreSchema instance.

class Animal: CoreStoreObject {
    let species = Value.Required<String>("species", initial: "")
    let nickname = Value.Optional<String>("nickname")
    let master = Relationship.ToOne<Person>("master")
}

class Person: CoreStoreObject {
    let name = Value.Required<String>("name", initial: "")
    let pet = Relationship.ToOne<Animal>("pet", inverse: { $0.master })
}

CoreStoreDefaults.dataStack = DataStack(
    CoreStoreSchema(
        modelVersion: "V1",
        entities: [
            Entity<Animal>("Animal"),
            Entity<Person>("Person")
        ],
        versionLock: [
            "Animal": [0x2698c812ebbc3b97, 0x751e3fa3f04cf9, 0x51fd460d3babc82, 0x92b4ba735b5a3053],
            "Person": [0xae4060a59f990ef0, 0x8ac83a6e1411c130, 0xa29fea58e2e38ab6, 0x2071bb7e33d77887]
        ]
    )
)

The DataStack encapsulates the data model for the Core Data stack. Each DataStack can have multiple data stores, usually specified as a “Configuration” in the model editor. Behind the scenes, the DataStack manages its own NSPersistentStoreCoordinator, a root NSManagedObjectContext for disk saves, and a shared NSManagedObjectContext designed as a read-only model interface for NSManagedObjects.

The Entity<O> contains NSEntityDescription metadata for CoreStoreObject subclasses. Pass the Entity instances to CoreStoreSchema initializer.

class Animal: CoreStoreObject {
    let species = Value.Required<String>("species", initial: "")
    let nickname = Value.Optional<String>("nickname")
    let master = Relationship.ToOne<Person>("master")
}

class Person: CoreStoreObject {
    let name = Value.Required<String>("name", initial: "")
    let pet = Relationship.ToOne<Animal>("pet", inverse: { $0.master })
}

CoreStoreDefaults.dataStack = DataStack(
    CoreStoreSchema(
        modelVersion: "V1",
        entities: [
            Entity<Animal>("Animal"),
            Entity<Person>("Person")
        ]
    )
)

A storage interface that is backed only in memory.

The UnsafeDataModelSchema describes models loaded directly from an existing NSManagedObjectModel. It is not advisable to continue using this model as its metadata are not available to CoreStore.

The ListMonitor monitors changes to a list of DynamicObject instances. Observers that implement the ListObserver protocol may then register themselves to the ListMonitor‘s addObserver(_:) method:

let monitor = dataStack.monitorList(
    From<Person>(),
    Where("title", isEqualTo: "Engineer"),
    OrderBy(.ascending("lastName"))
)
monitor.addObserver(self)

The ListMonitor instance needs to be held on (retained) for as long as the list needs to be observed. Observers registered via addObserver(_:) are not retained. ListMonitor only keeps a weak reference to all observers, thus keeping itself free from retain-cycles.

Lists created with monitorList(...) keep a single-section list of objects, where each object can be accessed by index:

let firstPerson: MyPersonEntity = monitor[0]

Accessing the list with an index above the valid range will raise an exception.

Creating a sectioned-list is also possible with the monitorSectionedList(...) method:

let monitor = dataStack.monitorSectionedList(
    From<Person>(),
    SectionBy("age") { "Age \($0)" },
    Where("title", isEqualTo: "Engineer"),
    OrderBy(.ascending("lastName"))
)
monitor.addObserver(self)

Objects from ListMonitors created this way can be accessed either by an IndexPath or a tuple:

let indexPath = IndexPath(forItem: 3, inSection: 2)
let person1 = monitor[indexPath]
let person2 = monitor[2, 3]

In the example above, both person1 and person2 will contain the object at section=2, index=3.

ListPublisher tracks a diffable list of DynamicObject instances. Unlike ListMonitors, ListPublisher are more lightweight and access objects lazily. Objects that need to be notified of ListPublisher changes may register themselves to its addObserver(_:_:) method:

let listPublisher = CoreStoreDefaults.dataStack.listPublisher(
    From<Person>()
        .where(\.title == "Engineer")
        .orderBy(.ascending(\.lastName))
)
listPublisher.addObserver(self) { (listPublisher) in
    // Handle changes
}

The ListPublisher instance needs to be held on (retained) for as long as the list needs to be observed. Observers registered via addObserver(_:_:) are not retained. ListPublisher only keeps a weak reference to all observers, thus keeping itself free from retain-cycles.

ListPublishers may optionally be created with sections:

let listPublisher = CoreStoreDefaults.dataStack.listPublisher(
    From<Person>()
        .sectionBy(\.age") { "Age \($0)" }
        .where(\.title == "Engineer")
        .orderBy(.ascending(\.lastName))
)

All access to the ListPublisher items should be done via its snapshot value, which is a struct of type ListSnapshot<O>. ListSnapshots are also designed to work well with DiffableDataSource.TableViewAdapters and DiffableDataSource.CollectionViewAdapters. For detailed examples, refer to the documentation for DiffableDataSource.TableViewAdapter and DiffableDataSource.CollectionViewAdapter.

The ObjectMonitor monitors changes to a single DynamicObject instance. Observers that implement the ObjectObserver protocol may then register themselves to the ObjectMonitor‘s addObserver(_:) method:

let monitor = dataStack.monitorObject(object)
monitor.addObserver(self)

The created ObjectMonitor instance needs to be held on (retained) for as long as the object needs to be observed.

Observers registered via addObserver(_:) are not retained. ObjectMonitor only keeps a weak reference to all observers, thus keeping itself free from retain-cycles.

The ObjectPublisher tracks changes to a single DynamicObject instance. Objects that need to be notified of ObjectPublisher changes may register themselves to its addObserver(_:_:) method:

let objectPublisher = CoreStoreDefaults.dataStack.objectPublisher(object)
objectPublisher.addObserver(self) { (objectPublisher) in
    // Handle changes
}

The created ObjectPublisher instance needs to be held on (retained) for as long as the object needs to be observed.

Observers registered via addObserver(_:_:) are not retained. ObjectPublisher only keeps a weak reference to all observers, thus keeping itself free from retain-cycles.

The ObjectPublisher‘s snapshot value is a lazy copy operation that extracts all property values at a specific point time. This cached copy is invalidated right before the ObjectPublisher broadcasts any changes to its observers.

The SchemaHistory encapsulates multiple DynamicSchema across multiple model versions. It contains all model history and is used by the DataStack to

A storage interface that is backed by an SQLite database.

The SynchronousDataTransaction provides an interface for DynamicObject creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from DataStack.beginSynchronous(_:).

The UnsafeDataTransaction provides an interface for non-contiguous NSManagedObject or CoreStoreObject creates, updates, and deletes. This is useful for making temporary changes, such as partially filled forms. An unsafe transaction object should typically be only used from the main queue.

The XcodeDataModelSchema describes a model version declared in a single *.xcdatamodeld file.

CoreStoreDefaults.dataStack = DataStack(
    XcodeDataModelSchema(modelName: "MyAppV1", bundle: .main)
)

The object containing the changeset for an observed ValueContainer.Required and ValueContainer.Optional property.

The object containing the changeset for an observed TransformableContainer.Required or TransformableContainer.Optional property.

The object containing the changeset for an observed RelationshipContainer.ToOne property.

The object containing the changeset for an observed RelationshipContainer.ToManyUnordered property.

The object containing the changeset for an observed RelationshipContainer.Ordered property.

A SchemaMappingProvider that accepts custom mappings for some entities. Mappings of entities with no CustomMapping provided will be automatically calculated if possible.

The DefaultLogger is a basic implementation of the CoreStoreLogger protocol.

Use concrete instances of Entity<O> in API that accept DynamicEntity arguments.

A SchemaMappingProvider that tries to infer model migration between two DynamicSchema versions by searching all xcmappingmodels from Bundle.allBundles or by relying on lightweight migration if possible. Throws an error if lightweight migration is impossible for the two DynamicSchema. This mapping is automatically used as a fallback mapping provider, even if no mapping providers are explicitly declared in the StorageInterface.

The UserInfo class is provided by several CoreStore types such as DataStack, ListMonitor, ObjectMonitor and transactions to allow external libraries or user apps to store their own custom data.

enum Static {
    static var myDataKey: Void?
}
CoreStoreDefaults.dataStack.userInfo[&Static.myDataKey] = myObject

A SchemaMappingProvider that tries to infer model migration between two DynamicSchema versions by loading an xcmappingmodel file from the specified Bundle. Throws CoreStoreError.mappingModelNotFound if the xcmappingmodel file cannot be found, or if the xcmappingmodel doesn’t resolve the source and destination DynamicSchema.