# ReactiveNamespace

    public struct ReactiveNamespace

Combine utilities for the `DataStack` are exposed through this namespace. Extend this type if you need to add other Combine Publisher utilities for `DataStack`.

### Public

- `base`

  The `DataStack` instance

  #### Declaration

  Swift

      public let base: DataStack

- `addStorage(_:)`

  Reactive extension for `CoreStore.DataStack`‘s `addStorage(...)` API. Asynchronously adds a `StorageInterface` to the stack.

      dataStack.reactive
          .addStorage(
              InMemoryStore(configuration: "Config1")
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { storage in
                  // ...
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func addStorage<T: StorageInterface>(
          _ storage: T
      ) -> Future<T, CoreStoreError>

  #### Parameters

  `storage` | the storage

  #### Return Value

  A `Future` that emits a `StorageInterface` instance added to the `DataStack`. Note that the `StorageInterface` event value may not always be the same instance as the parameter argument if a previous `StorageInterface` was already added at the same URL and with the same configuration.

- `addStorage(_:)`

  Reactive extension for `CoreStore.DataStack`‘s `addStorage(...)` API. Asynchronously adds a `LocalStorage` to the stack. Migrations are also initiated by default. The event emits `MigrationProgress` `enum` values.

      dataStack.reactive
          .addStorage(
              SQLiteStore(
                  fileName: "core_data.sqlite",
                  configuration: "Config1"
              )
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { (progress) in
                  print("\(round(progress.fractionCompleted * 100)) %") // 0.0 ~ 1.0
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func addStorage<T>(_ storage: T) -> DataStack.AddStoragePublisher<T> where T : LocalStorage

  #### Parameters

  `storage` | the local storage

  #### Return Value

  A `DataStack.AddStoragePublisher` that emits a `MigrationProgress` value with metadata for migration progress. Note that the `LocalStorage` event value may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.

- `importObject(_:source:)`

  Reactive extension for `CoreStore.DataStack`‘s `importObject(...)` API. Creates an `ImportableObject` by importing from the specified import source. The event value will be the object instance correctly associated for the `DataStack`.

      dataStack.reactive
          .importObject(
              Into<Person>(),
              source: ["name": "John"]
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { (person) in
                  XCTAssertNotNil(person)
                  // ...
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func importObject<O: DynamicObject & ImportableObject>(
          _ into: Into<O>,
          source: O.ImportSource
      ) -> Future<O?, CoreStoreError>

  #### Parameters

  `into` | an `Into` clause specifying the entity type
  `source` | the object to import values from

  #### Return Value

  A `Future` that publishes the imported object. The event value, if not `nil`, will be the object instance correctly associated for the `DataStack`.

- `importObject(_:source:)`

  Reactive extension for `CoreStore.DataStack`‘s `importObject(...)` API. Updates an existing `ImportableObject` by importing values from the specified import source. The event value will be the object instance correctly associated for the `DataStack`.

      let existingPerson: Person = // ...
      dataStack.reactive
          .importObject(
              existingPerson,
              source: ["name": "John", "age": 30]
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { (person) in
                  XCTAssertEqual(person?.age, 30)
                  // ...
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func importObject<O: DynamicObject & ImportableObject>(
          _ object: O,
          source: O.ImportSource
      ) -> Future<O?, CoreStoreError>

  #### Parameters

  `object` | the object to update
  `source` | the object to import values from

  #### Return Value

  A `Future` that publishes the imported object. The event value, if not `nil`, will be the object instance correctly associated for the `DataStack`.

- `importUniqueObject(_:source:)`

  Reactive extension for `CoreStore.DataStack`‘s `importUniqueObject(...)` API. Updates an existing `ImportableUniqueObject` or creates a new instance by importing from the specified import source. The event value will be the object instance correctly associated for the `DataStack`.

      dataStack.reactive
          .importUniqueObject(
              Into<Person>(),
              source: ["name": "John", "age": 30]
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { (person) in
                  XCTAssertEqual(person?.age, 30)
                  // ...
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func importUniqueObject<O: DynamicObject & ImportableUniqueObject>(
          _ into: Into<O>,
          source: O.ImportSource
      ) -> Future<O?, CoreStoreError>

  #### Parameters

  `into` | an `Into` clause specifying the entity type
  `source` | the object to import values from

  #### Return Value

  A `Future` for the imported object. The event value, if not `nil`, will be the object instance correctly associated for the `DataStack`.

- `importUniqueObjects(_:sourceArray:preProcess:)`

  Reactive extension for `CoreStore.DataStack`‘s `importUniqueObjects(...)` API. Updates existing `ImportableUniqueObject`s or creates them by importing from the specified array of import sources. `ImportableUniqueObject` methods are called on the objects in the same order as they are in the `sourceArray`, and are returned in an array with that same order. The event values will be object instances correctly associated for the `DataStack`.

      dataStack.reactive
          .importUniqueObjects(
              Into<Person>(),
              sourceArray: [
                  ["name": "John"],
                  ["name": "Bob"],
                  ["name": "Joe"]
              ]
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { (people) in
                  XCTAssertEqual(people?.count, 3)
                  // ...
              }
          )
          .store(in: &cancellables)

  Warning

  If `sourceArray` contains multiple import sources with same ID, no merging will occur and ONLY THE LAST duplicate will be imported.

  #### Declaration

  Swift

      public func importUniqueObjects<O: DynamicObject & ImportableUniqueObject, S: Sequence>(
          _ into: Into<O>,
          sourceArray: S,
          preProcess: @escaping (_ mapping: [O.UniqueIDType: O.ImportSource]) throws -> [O.UniqueIDType: O.ImportSource] = { $0 }
      ) -> Future<[O], CoreStoreError> where S.Iterator.Element == O.ImportSource

  #### Parameters

  `into` | an `Into` clause specifying the entity type
  `sourceArray` | the array of objects to import values from
  `preProcess` | a closure that lets the caller tweak the internal `UniqueIDType`-to-`ImportSource` mapping to be used for importing. Callers can remove from/add to/update `mapping` and return the updated array from the closure.

  #### Return Value

  A `Future` for the imported objects. The event values will be the object instances correctly associated for the `DataStack`.

- `perform(_:)`

  Reactive extension for `CoreStore.DataStack`‘s `perform(asynchronous:...)` API. Performs a transaction asynchronously where `NSManagedObject` creates, updates, and deletes can be made. The changes are commited automatically after the `task` closure returns. The event value will be the value returned from the `task` closure. Any errors thrown from inside the `task` will be wrapped in a `CoreStoreError` and reported to the completion `.failure`. To cancel/rollback changes, call `transaction.cancel()`, which throws a `CoreStoreError.userCancelled`.

      dataStack.reactive
          .perform(
              asynchronous: { (transaction) -> (inserted: Set<NSManagedObject>, deleted: Set<NSManagedObject>) in

                  // ...
                  return (
                      transaction.insertedObjects(),
                      transaction.deletedObjects()
                  )
              }
          )
          .sink(
              receiveCompletion: { result in
                  // ...
              },
              receiveValue: { value in
                  let inserted = dataStack.fetchExisting(value0.inserted)
                  let deleted = dataStack.fetchExisting(value0.deleted)
                  // ...
              }
          )
          .store(in: &cancellables)

  #### Declaration

  Swift

      public func perform<Output>(
          _ asynchronous: @escaping (AsynchronousDataTransaction) throws -> Output
      ) -> Future<Output, CoreStoreError>

  #### Parameters

  `task` | the asynchronous closure 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 `Future` whose event value be the value returned from the `task` closure.