ListPublisher

public final class ListPublisher<O> : Hashable where O : DynamicObject
extension ListPublisher: CustomDebugStringConvertible, CoreStoreDebugStringConvertible

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.

Public (Accessors)

  • The DynamicObject type associated with this list

    Declaration

    Swift

    public typealias ObjectType = O

  • The type for the section IDs

    Declaration

    Swift

    public typealias SectionID = ListSnapshot<O>.SectionID

  • The type for the item IDs

    Declaration

    Swift

    public typealias ItemID = ListSnapshot<O>.ItemID

  • A snapshot of the latest state of this list

    Declaration

    Swift

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

Public (Observers)

  • 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

  • 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

  • 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)

  • Asks the ListPublisher to refetch its objects using the specified FetchChainableBuilderType. Unlike ListMonitors, 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.

  • Asks the ListPublisher to refetch its objects using the specified SectionMonitorBuilderType. Unlike ListMonitors, 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.

  • Used internally by CoreStore. Do not call directly.

    Declaration

    Swift

    public func cs_dataStack() -> DataStack?

Public (3rd Party Utilities)

  • 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

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

CustomDebugStringConvertible

  • Declaration

    Swift

    public var debugDescription: String { get }

Public

  • Combine utilities for the ListPublisher are exposed through this namespace

    Declaration

    Swift

    public var reactive: ListPublisher.ReactiveNamespace { get }

ReactiveNamespace

SnapshotPublisher