DittoStore

public class DittoStore

DittoStore provides access to DittoCollections and a write transaction API.

  • Returns a DittoCollection with the provided name.

    Declaration

    Swift

    public subscript(collectionName: DittoCollectionName) -> DittoCollection { get }

    Parameters

    collectionName

    The name of the collection.

    Return Value

    A DittoCollection.

  • Returns a DittoCollection with the provided name. A collection name is valid if:

    • its length is less than 100
    • it is not empty
    • it does not contain the char ‘\0’

    • it does not begin with “$TS_”

    Declaration

    Swift

    public func collection(_ name: DittoCollectionName) -> DittoCollection

    Parameters

    name

    The name of the collection.

    Return Value

    A DittoCollection.

  • Returns a list of the names of collections in the store.

    Declaration

    Swift

    public func collectionNames() -> [DittoCollectionName]

    Return Value

    A list of collection names found in the store.

  • Returns an object that lets you fetch or observe the collections in the store.

    Declaration

    Swift

    public func collections() -> DittoPendingCollectionsOperation

    Return Value

    An object that lets you fetch or observe the collections in the store.

  • Returns a hash representing the current version of the given queries. When a document matching such queries gets mutated, the hash will change as well.

    Please note that the hash depends on how queries are constructed, so you should make sure to always compare hashes generated with the same set of queries.

    Declaration

    Swift

    public func queriesHash(queries: [DittoLiveQuery]) -> UInt

    Parameters

    queries

    A list of DittoLiveQuery objects that you want to get the hash for.

    Return Value

    A hash representing the current version of the given queries.

  • Returns a sequence of English words representing the current version of the given queries. When a document matching such queries gets mutated, the words will change as well.

    Please note that the resulting sequence of words depends on how queries are constructed, so you should make sure to always compare hashes generated with the same set of queries.

    Declaration

    Swift

    public func queriesHashMnemonic(queries: [DittoLiveQuery]) -> String

    Parameters

    queries

    A list of DittoLiveQuery objects that you want to get the mnemonic hash for.

    Return Value

    A string representing the current version of the given queries.

  • Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.

    Declaration

    Swift

    @discardableResult
public func write(
    _ block: @escaping (DittoWriteTransaction) -> Void
) -> [DittoWriteTransactionResult]

    Parameters

    block

    A closure that provides access to a write transaction object that can be used to perform operations on the store.

    Return Value

    A list of DittoWriteTransactionResults. There is a result for each operation performed as part of the write transaction.

Executing DQL Queries

  • Executes a DQL query and returns matching items as a query result.

    Throws

    DittoSwiftError > .storeError(.queryInvalid) if query string is not valid DQL.

    Throws

    DittoSwiftError > .storeError(.queryArgumentsInvalid) if arguments dictionary is not valid (contains unsupported types).

    Throws

    May throw other DittoSwiftErrors.

    Declaration

    Swift

    @discardableResult
public func execute(query: String, arguments: Dictionary<String, Any?>? = [:]) async throws -> DittoQueryResult

    Return Value

    A DittoQueryResult containing a DittoQueryItem for each match.

Managing Store Observers

  • Returns all currently active store observers.

    Declaration

    Swift

    public private(set) var observers: Set<DittoStoreObserver> { get }

  • Convenience method, same as registerObserver(query:arguments:deliverOn:storeObservationHandlerWithSignalNext:) where signalNext is called automatically after the storeObservationHandler finishes.

    Declaration

    Swift

    @discardableResult
public func registerObserver(
    query: String,
    arguments: Dictionary<String, Any?>? = nil,
    deliverOn queue: DispatchQueue = .main,
    handler: @escaping DittoStoreObservationHandler
) throws -> DittoStoreObserver

  • Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local store change such that the result of the matching query changes. The passed in query must be a SELECT query, otherwise a store error with queryNotSupported reason is thrown.

    Throws

    DittoSwiftError > .storeError(.queryInvalid) if query string is not valid DQL.

    Throws

    DittoSwiftError > .storeError(.queryArgumentsInvalid) if arguments dictionary is not valid (contains unsupported types).

    Throws

    DittoSwiftError > .storeError(.queryNotSupported) if query is not a SELECT query.

    Throws

    May throw other DittoSwiftErrors.

    Declaration

    Swift

    @discardableResult
public func registerObserver(
    query: String,
    arguments: Dictionary<String, Any?>? = nil,
    deliverOn queue: DispatchQueue = .main,
    handlerWithSignalNext: @escaping DittoStoreObservationHandlerWithSignalNext
) throws -> DittoStoreObserver

    Return Value

    An active StoreObserver for the passed in query and arguments. You’ll have to keep it to be able to cancel the observation. Otherwise it will remain active until the owning Ditto object goes out of scope.