# ListPublisher

    public final class ListPublisher<O> : Hashable where O : DynamicObject

    extension ListPublisher: CustomDebugStringConvertible, CoreStoreDebugStringConvertible

`ListPublisher` tracks a diffable list of `DynamicObject` instances. Unlike `ListMonitor`s, `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.

`ListPublisher`s 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>`. `ListSnapshot`s are also designed to work well with `DiffableDataSource.TableViewAdapter`s and `DiffableDataSource.CollectionViewAdapter`s. For detailed examples, refer to the documentation for `DiffableDataSource.TableViewAdapter` and `DiffableDataSource.CollectionViewAdapter`.

### Public (Accessors)

- `ObjectType`

  The `DynamicObject` type associated with this list

  #### Declaration

  Swift

      public typealias ObjectType = O

- `SectionID`

  The type for the section IDs

  #### Declaration

  Swift

      public typealias SectionID = ListSnapshot<O>.SectionID

- `ItemID`

  The type for the item IDs

  #### Declaration

  Swift

      public typealias ItemID = ListSnapshot<O>.ItemID

- `snapshot`

  A snapshot of the latest state of this list

  #### Declaration

  Swift

      public private(set) var snapshot: ListSnapshot<O> { get }

### Public (Observers)

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

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

  To prevent retain-cycles, `ListPublisher` 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 (ListPublisher<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 `ListPublisher`‘s snapshot occur.

  To prevent retain-cycles, `ListPublisher` 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 (
              _ listPublisher: ListPublisher<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 `ListPublisher`‘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

### Public (Refetching)

- `refetch(_:sourceIdentifier:)`

  Asks the `ListPublisher` to refetch its objects using the specified `FetchChainableBuilderType`. Unlike `ListMonitor`s, a `ListPublisher`‘s `refetch(...)` executes immediately.

      try listPublisher.refetch(
          From<MyPersonEntity>()
              .where(\.age > 18)
              .orderBy(.ascending(\.age))
      )

  #### Declaration

  Swift

      public func refetch<B: FetchChainableBuilderType>(
          _ clauseChain: B,
          sourceIdentifier: Any? = nil
      ) throws where B.ObjectType == O

  #### Parameters

  `clauseChain` | a `FetchChainableBuilderType` built from a chain of clauses
  `sourceIdentifier` | an optional value that identifies the source of this transaction. This identifier will be passed to the change notifications and callers can use it for custom handling that depends on the source.

- `refetch(_:sourceIdentifier:)`

  Asks the `ListPublisher` to refetch its objects using the specified `SectionMonitorBuilderType`. Unlike `ListMonitor`s, a `ListPublisher`‘s `refetch(...)` executes immediately.

       try listPublisher.refetch(
           From<MyPersonEntity>()
               .sectionBy(\.age, { "\($0!) years old" })
               .where(\.age > 18)
               .orderBy(.ascending(\.age))
       )

  #### Declaration

  Swift

      public func refetch<B: SectionMonitorBuilderType>(
          _ clauseChain: B,
          sourceIdentifier: Any? = nil
      ) throws where B.ObjectType == O

  #### Parameters

  `clauseChain` | a `SectionMonitorBuilderType` built from a chain of clauses
  `sourceIdentifier` | an optional value that identifies the source of this transaction. This identifier will be passed to the change notifications and callers can use it for custom handling that depends on the source.

- `cs_dataStack()`

  Used internally by CoreStore. Do not call directly.

  #### Declaration

  Swift

      public func cs_dataStack() -> DataStack?

### Public (3rd Party Utilities)

- `userInfo`

  Allow external libraries to store custom data in the `ListPublisher`. App code should rarely have a need for this.

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

  Important

  Do not use this method to store thread-sensitive data.

  #### Declaration

  Swift

      public let userInfo: UserInfo

### Equatable

- `==(_:_:)`

  #### Declaration

  Swift

      public static func == (lhs: ListPublisher, rhs: ListPublisher) -> 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 `ListPublisher` are exposed through this namespace

  #### Declaration

  Swift

      public var reactive: ListPublisher.ReactiveNamespace { get }

### ReactiveNamespace

- `ReactiveNamespace`

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

  See more

  #### Declaration

  Swift

      public struct ReactiveNamespace

### SnapshotPublisher

- `SnapshotPublisher`

  A `Publisher` that emits a `ListSnapshot` whenever changes occur in the `ListPublisher`.

  See also

  ListPublisher.reactive.snapshot(emitInitialValue:)
  See more

  #### Declaration

  Swift

      public struct SnapshotPublisher : Publisher