# CSCoreStore Class Reference

# CSCoreStore

    @objc
    public final class CSCoreStore : NSObject

The `CSCoreStore` serves as the Objective-C bridging type for `CoreStore`.

See also

`CoreStore`

- `defaultStack`

  The default `CSDataStack` instance to be used. If `defaultStack` is not set before the first time accessed, a default-configured `CSDataStack` will be created.

  See also

  `CSDataStack`

  Note

  Changing the `defaultStack` is thread safe, but it is recommended to setup `CSDataStacks` on a common queue (e.g. the main queue).

  #### Declaration

  Swift

      @objc
      public static var defaultStack: CSDataStack { get set }

### CSCoreStore

- `addInMemoryStorage(_:completion:)`

  Asynchronously adds a `CSInMemoryStore` to the `defaultStack`. Migrations are also initiated by default.

      NSError *error;
      NSProgress *migrationProgress = [dataStack
          addInMemoryStorage:[CSInMemoryStore new]
          completion:^(CSSetupResult *result) {
              if (result.isSuccess) {
                  // ...
              }
          }
          error: &error];

  #### Declaration

  Swift

      public static func addInMemoryStorage(_ storage: CSInMemoryStore, completion: @escaping (CSSetupResult) -> Void)

  #### Parameters

  `storage` | the `CSInMemoryStore` instance
  `completion` | the closure to be executed on the main queue when the process completes, either due to success or failure. The closure’s `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.

- `addSQLiteStorage(_:completion:error:)`

  Asynchronously adds a `CSSQLiteStore` to the `defaultStack`. Migrations are also initiated by default.

      NSError *error;
      NSProgress *migrationProgress = [dataStack
          addInMemoryStorage:[[CSSQLiteStore alloc]
          initWithFileName:@"core_data.sqlite"
          configuration:@"Config1"]
          completion:^(CSSetupResult *result) {
              if (result.isSuccess) {
                  // ...
              }
          }
          error: &error];

  #### Declaration

  Swift

      public static func addSQLiteStorage(_ storage: CSSQLiteStore, completion: @escaping (CSSetupResult) -> Void, error: NSErrorPointer) -> Progress?

  #### Parameters

  `storage` | the `CSSQLiteStore` instance

  `completion`

  the closure to be executed on the main queue when the process completes, either due to success or failure. The closure’s `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously. Note that the `CSLocalStorage` associated to the `-[CSSetupResult storage]` may not always be the same instance as the parameter argument if a previous `CSLocalStorage` was already added at the same URL and with the same configuration.

  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.

- `upgradeStorageIfNeeded(_:completion:error:)`

  Migrates a `CSSQLiteStore` to match the `defaultStack`‘s managed object model version. This method does NOT add the migrated store to the data stack.

  #### Declaration

  Swift

      @objc
      public static func upgradeStorageIfNeeded(_ storage: CSSQLiteStore, completion: @escaping (CSMigrationResult) -> Void, error: NSErrorPointer) -> Progress?

  #### Parameters

  `storage` | the `CSSQLiteStore` instance
  `completion` | the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure’s `CSMigrationResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.
  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.

- `requiredMigrationsForSQLiteStore(_:error:)`

  Checks the migration steps required for the `CSSQLiteStore` to match the `defaultStack`‘s managed object model version.

  #### Declaration

  Swift

      @objc
      public static func requiredMigrationsForSQLiteStore(_ storage: CSSQLiteStore, error: NSErrorPointer) -> [CSMigrationType]?

  #### Parameters

  `storage` | the `CSSQLiteStore` instance
  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  a `CSMigrationType` array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, `nil` is returned and the `error` argument is set if either inspection of the store failed, or if no mapping model was found/inferred.

### CSCoreStore

- `monitorObject(_:)`

  Using the `defaultStack`, creates an `CSObjectMonitor` for the specified `NSManagedObject`. Multiple `CSObjectObserver`s may then register themselves to be notified when changes are made to the `NSManagedObject`.

  #### Declaration

  Swift

      @objc
      public static func monitorObject(_ object: NSManagedObject) -> CSObjectMonitor

  #### Parameters

  `object` | the `NSManagedObject` to observe changes from

  #### Return Value

  a `CSObjectMonitor` that monitors changes to `object`

- `monitorListFrom(_:fetchClauses:)`

  Using the `defaultStack`, creates a `CSListMonitor` for a list of `NSManagedObject`s that satisfy the specified fetch clauses. Multiple `CSListObserver`s may then register themselves to be notified when changes are made to the list.

  #### Declaration

  Swift

      @objc
      public static func monitorListFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> CSListMonitor

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  a `CSListMonitor` instance that monitors changes to the list

- `monitorListByCreatingAsynchronously(_:from:fetchClauses:)`

  Using the `defaultStack`, asynchronously creates a `CSListMonitor` for a list of `NSManagedObject`s that satisfy the specified fetch clauses. Multiple `CSListObserver`s may then register themselves to be notified when changes are made to the list. Since `NSFetchedResultsController` greedily locks the persistent store on initial fetch, you may prefer this method instead of the synchronous counterpart to avoid deadlocks while background updates/saves are being executed.

  #### Declaration

  Swift

      @objc
      public static func monitorListByCreatingAsynchronously(_ createAsynchronously: @escaping (CSListMonitor) -> Void, from: CSFrom, fetchClauses: [CSFetchClause])

  #### Parameters

  `createAsynchronously` | the closure that receives the created `CSListMonitor` instance
  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

- `monitorSectionedListFrom(_:sectionBy:fetchClauses:)`

  Using the `defaultStack`, creates a `CSListMonitor` for a sectioned list of `NSManagedObject`s that satisfy the specified fetch clauses. Multiple `CSListObserver`s may then register themselves to be notified when changes are made to the list.

  #### Declaration

  Swift

      @objc
      public static func monitorSectionedListFrom(_ from: CSFrom, sectionBy: CSSectionBy, fetchClauses: [CSFetchClause]) -> CSListMonitor

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `sectionBy` | a `CSSectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections.
  `fetchClauses` | a series of `CSFetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  a `CSListMonitor` instance that monitors changes to the list

- `monitorSectionedListByCreatingAsynchronously(_:from:sectionBy:fetchClauses:)`

  Using the `defaultStack`, asynchronously creates a `CSListMonitor` for a sectioned list of `NSManagedObject`s that satisfy the specified fetch clauses. Multiple `CSListObserver`s may then register themselves to be notified when changes are made to the list. Since `NSFetchedResultsController` greedily locks the persistent store on initial fetch, you may prefer this method instead of the synchronous counterpart to avoid deadlocks while background updates/saves are being executed.

  #### Declaration

  Swift

      @objc
      public static func monitorSectionedListByCreatingAsynchronously(_ createAsynchronously: @escaping (CSListMonitor) -> Void, from: CSFrom, sectionBy: CSSectionBy, fetchClauses: [CSFetchClause])

  #### Parameters

  `createAsynchronously` | the closure that receives the created `CSListMonitor` instance
  `from` | a `CSFrom` clause indicating the entity type
  `sectionBy` | a `CSSectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections.
  `fetchClauses` | a series of `CSFetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

### CSCoreStore

- `fetchExistingObject(_:)`

  Using the `defaultStack`, fetches the `NSManagedObject` instance in the transaction’s context from a reference created from a transaction or from a different managed object context.

  #### Declaration

  Swift

      @objc
      public static func fetchExistingObject(_ object: NSManagedObject) -> Any?

  #### Parameters

  `object` | a reference to the object created/fetched outside the transaction

  #### Return Value

  the `NSManagedObject` instance if the object exists in the transaction, or `nil` if not found.

- `fetchExistingObjectWithID(_:)`

  Using the `defaultStack`, fetches the `NSManagedObject` instance in the transaction’s context from an `NSManagedObjectID`.

  #### Declaration

  Swift

      @objc
      public static func fetchExistingObjectWithID(_ objectID: NSManagedObjectID) -> Any?

  #### Parameters

  `objectID` | the `NSManagedObjectID` for the object

  #### Return Value

  the `NSManagedObject` instance if the object exists in the transaction, or `nil` if not found.

- `fetchExistingObjects(_:)`

  Using the `defaultStack`, fetches the `NSManagedObject` instances in the transaction’s context from references created from a transaction or from a different managed object context.

  #### Declaration

  Swift

      @objc
      public static func fetchExistingObjects(_ objects: [NSManagedObject]) -> [Any]

  #### Parameters

  `objects` | an array of `NSManagedObject`s created/fetched outside the transaction

  #### Return Value

  the `NSManagedObject` array for objects that exists in the transaction

- `fetchExistingObjectsWithIDs(_:)`

  Using the `defaultStack`, fetches the `NSManagedObject` instances in the transaction’s context from a list of `NSManagedObjectID`.

  #### Declaration

  Swift

      @objc
      public static func fetchExistingObjectsWithIDs(_ objectIDs: [NSManagedObjectID]) -> [Any]

  #### Parameters

  `objectIDs` | the `NSManagedObjectID` array for the objects

  #### Return Value

  the `NSManagedObject` array for objects that exists in the transaction

- `fetchOneFrom(_:fetchClauses:)`

  Using the `defaultStack`, fetches the first `NSManagedObject` instance that satisfies the specified `CSFetchClause`s. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Declaration

  Swift

      @objc
      public static func fetchOneFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> Any?

  #### Parameters

  `from` | a `From` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for the fetch request. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  the first `NSManagedObject` instance that satisfies the specified `CSFetchClause`s

- `fetchAllFrom(_:fetchClauses:)`

  Using the `defaultStack`, fetches all `NSManagedObject` instances that satisfy the specified `CSFetchClause`s. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Declaration

  Swift

      @objc
      public static func fetchAllFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> [Any]?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for the fetch request. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  all `NSManagedObject` instances that satisfy the specified `CSFetchClause`s

- `fetchCountFrom(_:fetchClauses:)`

  Using the `defaultStack`, fetches the number of `NSManagedObject`s that satisfy the specified `CSFetchClause`s. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Declaration

  Swift

      @objc
      public static func fetchCountFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> NSNumber?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for the fetch request. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  the number `NSManagedObject`s that satisfy the specified `CSFetchClause`s

- `fetchObjectIDFrom(_:fetchClauses:)`

  Using the `defaultStack`, fetches the `NSManagedObjectID` for the first `NSManagedObject` that satisfies the specified `CSFetchClause`s. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Declaration

  Swift

      @objc
      public static func fetchObjectIDFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> NSManagedObjectID?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `CSFetchClause` instances for the fetch request. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  the `NSManagedObjectID` for the first `NSManagedObject` that satisfies the specified `CSFetchClause`s

- `fetchObjectIDsFrom(_:fetchClauses:)`

  Using the `defaultStack`, fetches the `NSManagedObjectID` for all `NSManagedObject`s that satisfy the specified `CSFetchClause`s. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Declaration

  Swift

      @objc
      public static func fetchObjectIDsFrom(_ from: CSFrom, fetchClauses: [CSFetchClause]) -> [NSManagedObjectID]?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `fetchClauses` | a series of `FetchClause` instances for the fetch request. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.

  #### Return Value

  the `NSManagedObjectID` for all `NSManagedObject`s that satisfy the specified `CSFetchClause`s

- `queryValueFrom(_:selectClause:queryClauses:)`

  Using the `defaultStack`, queries aggregate values as specified by the `CSQueryClause`s. Requires at least a `CSSelect` clause, and optional `CSWhere`, `CSOrderBy`, `CSGroupBy`, and `CSTweak` clauses.

  A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

  #### Declaration

  Swift

      @objc
      public static func queryValueFrom(_ from: CSFrom, selectClause: CSSelect, queryClauses: [CSQueryClause]) -> Any?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `selectClause` | a `CSSelect` clause indicating the properties to fetch, and with the generic type indicating the return type.
  `queryClauses` | a series of `CSQueryClause` instances for the query request. Accepts `CSWhere`, `CSOrderBy`, `CSGroupBy`, and `CSTweak` clauses.

  #### Return Value

  the result of the the query. The type of the return value is specified by the generic type of the `CSSelect` parameter.

- `queryAttributesFrom(_:selectClause:queryClauses:)`

  Using the `defaultStack`, queries a dictionary of attribute values as specified by the `CSQueryClause`s. Requires at least a `CSSelect` clause, and optional `CSWhere`, `CSOrderBy`, `CSGroupBy`, and `CSTweak` clauses.

  A query differs from a fetch in that it only retrieves values already stored in the persistent store. As such, values from unsaved transactions or contexts will not be incorporated in the query result.

  #### Declaration

  Swift

      @objc
      public static func queryAttributesFrom(_ from: CSFrom, selectClause: CSSelect, queryClauses: [CSQueryClause]) -> [[String : Any]]?

  #### Parameters

  `from` | a `CSFrom` clause indicating the entity type
  `selectClause` | a `CSSelect` clause indicating the properties to fetch, and with the generic type indicating the return type.
  `queryClauses` | a series of `CSQueryClause` instances for the query request. Accepts `CSWhere`, `CSOrderBy`, `CSGroupBy`, and `CSTweak` clauses.

  #### Return Value

  the result of the the query. The type of the return value is specified by the generic type of the `CSSelect` parameter.

### CSCoreStore

- `modelVersion`

  Returns the `defaultStack`‘s model version. The version string is the same as the name of the version-specific .xcdatamodeld file.

  #### Declaration

  Swift

      @objc
      public static var modelVersion: String { get }

- `entityTypesByNameForType(_:)`

  Returns the entity name-to-class type mapping from the `defaultStack`‘s model.

  #### Declaration

  Swift

      @objc
      public static func entityTypesByNameForType(_ type: NSManagedObject.Type) -> [EntityName : NSManagedObject.Type]

- `entityDescriptionForClass(_:)`

  Returns the `NSEntityDescription` for the specified `NSManagedObject` subclass from `defaultStack`‘s model.

  #### Declaration

  Swift

      @objc
      public static func entityDescriptionForClass(_ type: NSManagedObject.Type) -> NSEntityDescription?

- `addInMemoryStorageAndWaitAndReturnError(_:)`

  Creates an `CSInMemoryStore` with default parameters and adds it to the `defaultStack`. This method blocks until completion.

      CSSQLiteStore *storage = [CSCoreStore addInMemoryStorageAndWaitAndReturnError:&error];

  #### Declaration

  Swift

      @discardableResult
      @objc
      public static func addInMemoryStorageAndWaitAndReturnError(_ error: NSErrorPointer) -> CSInMemoryStore?

  #### Parameters

  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  the `CSInMemoryStore` added to the `defaultStack`

- `addSQLiteStorageAndWaitAndReturnError(_:)`

  Creates an `CSSQLiteStore` with default parameters and adds it to the `defaultStack`. This method blocks until completion.

      CSSQLiteStore *storage = [CSCoreStore addSQLiteStorageAndWaitAndReturnError:&error];

  #### Declaration

  Swift

      @discardableResult
      @objc
      public static func addSQLiteStorageAndWaitAndReturnError(_ error: NSErrorPointer) -> CSSQLiteStore?

  #### Parameters

  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  the `CSSQLiteStore` added to the `defaultStack`

- `addInMemoryStorageAndWait(_:error:)`

  Adds a `CSInMemoryStore` to the `defaultStack` and blocks until completion.

      NSError *error;
      CSInMemoryStore *storage = [CSCoreStore
          addStorageAndWait: [[CSInMemoryStore alloc] initWithConfiguration: @"Config1"]
          error: &error];

  #### Declaration

  Swift

      @discardableResult
      @objc
      public static func addInMemoryStorageAndWait(_ storage: CSInMemoryStore, error: NSErrorPointer) -> CSInMemoryStore?

  #### Parameters

  `storage` | the `CSInMemoryStore`
  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  the `CSInMemoryStore` added to the `defaultStack`

- `addSQLiteStorageAndWait(_:error:)`

  Adds a `CSSQLiteStore` to the `defaultStack` and blocks until completion.

      NSError *error;
      CSSQLiteStore *storage = [CSCoreStore
          addStorageAndWait: [[CSSQLiteStore alloc] initWithConfiguration: @"Config1"]
          error: &error];

  #### Declaration

  Swift

      @discardableResult
      @objc
      public static func addSQLiteStorageAndWait(_ storage: CSSQLiteStore, error: NSErrorPointer) -> CSSQLiteStore?

  #### Parameters

  `storage` | the `CSSQLiteStore`
  `error` | the `NSError` pointer that indicates the reason in case of an failure

  #### Return Value

  the `CSSQLiteStore` added to the `defaultStack`

### CSCoreStore

- `beginAsynchronous(_:)`

  Using the `defaultStack`, begins a transaction asynchronously where `NSManagedObject` creates, updates, and deletes can be made.

  #### Declaration

  Swift

      @objc
      public static func beginAsynchronous(_ closure: @escaping (_ transaction: CSAsynchronousDataTransaction) -> Void)

  #### Parameters

  `closure` | the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`.

- `beginSynchronous(_:error:)`

  Using the `defaultStack`, begins a transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made.

  #### Declaration

  Swift

      @objc
      public static func beginSynchronous(_ closure: @escaping (_ transaction: CSSynchronousDataTransaction) -> Void, error: NSErrorPointer) -> Bool

  #### Parameters

  `closure` | the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`.

  #### Return Value

  a `CSSaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously

- `beginUnsafe()`

  Using the `defaultStack`, begins a child transaction where `NSManagedObject` creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms.

  To support undo methods such as `-undo`, `-redo`, and `-rollback`, use the `-beginSafeWithSupportsUndo:` method passing `YES` to the argument. Without undo support, calling those methods will raise an exception.

  #### Declaration

  Swift

      @objc
      public static func beginUnsafe() -> CSUnsafeDataTransaction

  #### Return Value

  a `CSUnsafeDataTransaction` instance where creates, updates, and deletes can be made.

- `beginUnsafeWithSupportsUndo(_:)`

  Using the `defaultStack`, begins a child transaction where `NSManagedObject` creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms.

  - prameter supportsUndo: `-undo`, `-redo`, and `-rollback` methods are only available when this parameter is `YES`, otherwise those method will raise an exception. Note that turning on Undo support may heavily impact performance especially on iOS or watchOS where memory is limited.

  #### Declaration

  Swift

      @objc
      public static func beginUnsafeWithSupportsUndo(_ supportsUndo: Bool) -> CSUnsafeDataTransaction

  #### Return Value

  a `CSUnsafeDataTransaction` instance where creates, updates, and deletes can be made.

- `refreshAndMergeAllObjects()`

  Refreshes all registered objects `NSManagedObject`s in the `defaultStack`.

  #### Declaration

  Swift

      @objc
      public static func refreshAndMergeAllObjects()