List

public class List<ModelType> : Collection, Codable, ExpressibleByArrayLiteral, ModelListMarker where ModelType : Model

List<ModelType> is a custom Collection that is capable of loading records from a data source. This is especially useful when dealing with Model associations that need to be lazy loaded. Lazy loading is performed when you access the Collection methods by retrieving the data from the underlying data source and then stored into this object, before returning the data to you. Consumers must be aware that multiple calls to the data source and then stored into this object will happen simultaneously if the object is used from different threads, thus not thread safe. Lazy loading is idempotent and will return the stored results on subsequent access.

  • Declaration

    Swift

    public typealias Index = Int
  • Declaration

    Swift

    public typealias Element = ModelType
  • The array of Element that backs the custom collection implementation.

    Attempting to access the list object will attempt to retrieve the elements in memory or retrieve it from the provider’s data source. This is not thread safe as it can be performed from multiple threads, however the provider’s call to load should be idempotent and should result in the final loaded state. An attempt to set this again will result in no-op and will not overwrite the existing loaded data.

    Declaration

    Swift

    public internal(set) var elements: [Element] { get set }

Initializers

ExpressibleByArrayLiteral

Collection conformance

  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public var startIndex: Index { get }
  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public var endIndex: Index { get }
  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public func index(after index: Index) -> Index
  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public subscript(position: Int) -> Element { get }
  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public  func makeIterator() -> IndexingIterator<[Element]>
  • Accessing the elements on a list that has not been loaded yet will operate slower than O(1) as the data will be retrieved synchronously as part of this call.

    Declaration

    Swift

    public var count: Int { get }

Persistent Operations

  • Declaration

    Swift

    public var totalCount: Int { get }
  • limit is currently not a supported API.

    Declaration

    Swift

    @available(*, deprecated, message: "Not supported.")
    public func limit(_ limit: Int) -> Self

Codable

  • The decoding logic uses ModelListDecoderRegistry to find available decoders to decode to plugin specific implementations of a ModelListProvider for List<Model>. The decoders should be added to the registry by the plugin as part of its configuration steps. By delegating responsibility to the ModelListDecoder, it is up to the plugin to successfully return an instance of ModelListProvider.

    Declaration

    Swift

    required convenience public init(from decoder: Decoder) throws
  • Declaration

    Swift

    public func encode(to encoder: Encoder) throws
  • Declaration

    Swift

    public typealias LazyListPublisher = AnyPublisher<[Element], DataStoreError>
  • This method has been deprecated, Use load(completion:) instead.

    Lazy load the collection and expose the loaded Elements as a Combine Publisher. The List will retrieve the data from the underlying data source before the publisher is returned. This is useful for integrating the List<ModelType> with existing Combine code and/or SwiftUI. This method has been deprecated and is currently not a supported API.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `load(completion:﹚` instead.")
    public func loadAsPublisher() -> LazyListPublisher

    Return Value

    a type-erased Combine publisher

Asynchronous API

  • Call this to initialize the collection if you have retrieved the list by traversing from your model objects to its associated children objects. For example, a Post model may contain a list of Comments. By retrieving the post object and traversing to the comments, the comments are not retrieved from the data source until this method is called. Data will be retrieved based on the plugin’s data source and may have different failure conditions–for example, a data source that requires network connectivity may fail if the network is unavailable. Alternately, you can trigger an implicit fetch by invoking the Collection methods (such as using map, or iterating in a for/in loop) on the List, which will retrieve data if it hasn’t already been retrieved. In such cases, the time to perform that operation will include the time required to request data from the underlying data source.

    If you have directly created this list object (for example, by calling List(elements:)) then the collection has already been initialized and calling this method will have no effect.

    Declaration

    Swift

    public func fetch(_ completion: @escaping (Result<Void, CoreError>) -> Void)
  • Call this to initialize the collection if you have retrieved the list by traversing from your model objects to its associated children objects. For example, a Post model may contain a list of Comments. By retrieving the post object and traversing to the comments, the comments are not retrieved from the data source until this method is called. Data will be retrieved based on the plugin’s data source and may have different failure conditions–for example, a data source that requires network connectivity may fail if the network is unavailable. Alternately, you can trigger an implicit load by invoking the Collection methods (such as using map, or iterating in a for/in loop) on the List, which will retrieve data if it hasn’t already been retrieved. In such cases, the time to perform that operation will include the time required to request data from the underlying data source.

    If you have directly created this list object (for example, by calling List(elements:)) then the collection has already been initialized and calling this method will have no effect.

    Declaration

    Swift

    @available(*, deprecated, message: "Use fetch(completion:﹚ instead.")
    public func load(_ completion: DataStoreCallback<[Element]>)

Synchronous API

  • This method has been deprecated, Use load(completion:) instead.

    Load data into the collection from the data source. Consumers must be aware of the internal behavior which relies on DispatchSemaphore and will block the current DispatchQueue until data is ready. When operating on large result sets, prefer using the asynchronous load(completion:) instead.

    Seealso

    load(completion:)

    Declaration

    Swift

    @available(*, deprecated, message: "Use fetch(completion:﹚ instead.")
    public func load() -> Self

    Return Value

    the current instance after data was loaded.

  • Check if there is subsequent data to retrieve. If true, the next page can be retrieved using getNextPage(completion:). Calling hasNextPage() will load the underlying elements from the data source if not yet loaded before.

    Declaration

    Swift

    public func hasNextPage() -> Bool
  • Retrieve the next page as a new in-memory List object. Calling getNextPage(completion:) will load the underlying elements of the receiver from the data source if not yet loaded before

    Declaration

    Swift

    public func getNextPage(completion: @escaping (Result<List<Element>, CoreError>) -> Void)