# ObjectPublisher

    @dynamicMemberLookup
    public final class ObjectPublisher<O> : ObjectRepresentation, Hashable where O : DynamicObject

    extension ObjectPublisher: CustomDebugStringConvertible, CoreStoreDebugStringConvertible

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.

### Public (Accessors)

- `snapshot`

  A snapshot of the latest state of this list. Returns `nil` if the object has been deleted.

  #### Declaration

  Swift

      public var snapshot: ObjectSnapshot<O>? { get }

- `object`

  The actual `DynamicObject` instance. Becomes `nil` if the object has been deleted.

  #### Declaration

  Swift

      public private(set) lazy var object: O? { get set }

### Public (Observers)

- `addObserver(_:notifyInitial:_:)`

  Registers an object as an observer to be notified when changes to the `ObjectPublisher`‘s snapshot occur.

  To prevent retain-cycles, `ObjectPublisher` only keeps `weak` references to its observers.

  For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

  Calling `addObserver(_:_:)` multiple times on the same observer is safe.

  #### Declaration

  Swift

      public func addObserver<T: AnyObject>(
          _ observer: T,
          notifyInitial: Bool = false,
          _ callback: @escaping (ObjectPublisher<O>) -> Void
      )

  #### Parameters

  `observer` | an object to become owner of the specified `callback`
  `notifyInitial` | if `true`, the callback is executed immediately with the current publisher state. Otherwise only succeeding updates will notify the observer. Default value is `false`.
  `callback` | the closure to execute when changes occur

- `addObserver(_:notifyInitial:initialSourceIdentifier:_:)`

  Registers an object as an observer to be notified when changes to the `ObjectPublisher`‘s snapshot occur.

  To prevent retain-cycles, `ObjectPublisher` only keeps `weak` references to its observers.

  For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

  Calling `addObserver(_:_:)` multiple times on the same observer is safe.

  #### Declaration

  Swift

      public func addObserver<T: AnyObject>(
          _ observer: T,
          notifyInitial: Bool = false,
          initialSourceIdentifier: Any? = nil,
          _ callback: @escaping (
              _ objectPublisher: ObjectPublisher<O>,
              _ sourceIdentifier: Any?
          ) -> Void
      )

  #### Parameters

  `observer` | an object to become owner of the specified `callback`
  `notifyInitial` | if `true`, the callback is executed immediately with the current publisher state. Otherwise only succeeding updates will notify the observer. Default value is `false`.
  `initialSourceIdentifier` | an optional value that identifies the initial callback invocation if `notifyInitial` is `true`.
  `callback` | the closure to execute when changes occur

- `removeObserver(_:)`

  Unregisters an object from receiving notifications for changes to the `ObjectPublisher`‘s snapshot.

  For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

  #### Declaration

  Swift

      public func removeObserver<T>(_ observer: T) where T : AnyObject

  #### Parameters

  `observer` | the object whose notifications will be unregistered

### AnyObjectRepresentation

- `objectID()`

  #### Declaration

  Swift

      public func objectID() -> O.ObjectID

- `cs_dataStack()`

  #### Declaration

  Swift

      public func cs_dataStack() -> DataStack?

### ObjectRepresentation

- `ObjectType`

  #### Declaration

  Swift

      public typealias ObjectType = O

- `asPublisher(in:)`

  #### Declaration

  Swift

      public func asPublisher(in dataStack: DataStack) -> ObjectPublisher<O>

- `asReadOnly(in:)`

  #### Declaration

  Swift

      public func asReadOnly(in dataStack: DataStack) -> O?

- `asEditable(in:)`

  #### Declaration

  Swift

      public func asEditable(in transaction: BaseDataTransaction) -> O?

- `asSnapshot(in:)`

  #### Declaration

  Swift

      public func asSnapshot(in dataStack: DataStack) -> ObjectSnapshot<O>?

- `asSnapshot(in:)`

  #### Declaration

  Swift

      public func asSnapshot(in transaction: BaseDataTransaction) -> ObjectSnapshot<O>?

### Equatable

- `==(_:_:)`

  #### Declaration

  Swift

      public static func == (lhs: ObjectPublisher, rhs: ObjectPublisher) -> Bool

### Hashable

- `hash(into:)`

  #### Declaration

  Swift

      public func hash(into hasher: inout Hasher)

### CustomDebugStringConvertible

- `debugDescription`

  #### Declaration

  Swift

      public var debugDescription: String { get }

### Public

- `reactive`

  Combine utilities for the `ObjectPublisher` are exposed through this namespace

  #### Declaration

  Swift

      public var reactive: ObjectPublisher.ReactiveNamespace { get }

### ReactiveNamespace

- `ReactiveNamespace`

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

  See more

  #### Declaration

  Swift

      @dynamicMemberLookup
      public struct ReactiveNamespace

### SnapshotPublisher

- `SnapshotPublisher`

  A `Publisher` that emits an `ObjectSnapshot?` whenever changes occur in the `ObjectPublisher`. The event emits `nil` if the object has been deletd.

  See also

  ObjectPublisher.reactive.snapshot(emitInitialValue:)
  See more

  #### Declaration

  Swift

      public struct SnapshotPublisher : Publisher

### Public

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<V>(dynamicMember member: KeyPath<O, V>) -> V! where V : AllowedObjectiveCKeyPathValue { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, FieldContainer<OBase>.Stored<V>>) -> V? where OBase : CoreStoreObject, V : FieldStorableType { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, FieldContainer<OBase>.Virtual<V>>) -> V? where OBase : CoreStoreObject { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, FieldContainer<OBase>.Coded<V>>) -> V? where OBase : CoreStoreObject { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, FieldContainer<OBase>.Relationship<V>>) -> V.PublishedType? where OBase : CoreStoreObject, V : FieldRelationshipType { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, ValueContainer<OBase>.Required<V>>) -> V? where OBase : CoreStoreObject, V : ImportableAttributeType { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, ValueContainer<OBase>.Optional<V>>) -> V? where OBase : CoreStoreObject, V : ImportableAttributeType { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, TransformableContainer<OBase>.Required<V>>) -> V? where OBase : CoreStoreObject, V : NSCoding, V : NSCopying { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, V>(dynamicMember member: KeyPath<O, TransformableContainer<OBase>.Optional<V>>) -> V? where OBase : CoreStoreObject, V : NSCoding, V : NSCopying { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, D>(dynamicMember member: KeyPath<O, RelationshipContainer<OBase>.ToOne<D>>) -> D? where OBase : CoreStoreObject, D : CoreStoreObject { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, D>(dynamicMember member: KeyPath<O, RelationshipContainer<OBase>.ToManyOrdered<D>>) -> [D]? where OBase : CoreStoreObject, D : CoreStoreObject { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<OBase, D>(dynamicMember member: KeyPath<O, RelationshipContainer<OBase>.ToManyUnordered<D>>) -> Set<D>? where OBase : CoreStoreObject, D : CoreStoreObject { get }

- `subscript(dynamicMember:)`

  Returns the value for the property identified by a given key.

  #### Declaration

  Swift

      public subscript<V>(dynamicMember member: KeyPath<O, V>) -> V? { get }