DittoStore

public class DittoStore

DittoStore provides access to DittoCollections and a write transaction API.


                    
                    
                    subscript(_:)

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.


                    
                    
                    collection(_:)

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.

collectionNames()
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.
collections()
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.


                    
                    
                    queriesHash(queries:)

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.


                    
                    
                    queriesHashMnemonic(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.


                    
                    
                    write(_:)

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

execute(query:arguments:)
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

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

A DittoQueryResult containing a DittoQueryItem for each match.

Managing Replication Subscriptions


                    
                    
                    replicationSubscriptions

Returns all currently active replication subscriptions.

Declaration

Swift

public private(set) var replicationSubscriptions: Set<DittoReplicationSubscription> { get }

registerReplicationSubscription(query:arguments:)
Installs and returns a replication subscription for a query, configuring Ditto to receive updates from other peers for documents matching that query. 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 registerReplicationSubscription( query: String, arguments: Dictionary<String, Any?>? = nil ) throws -> DittoReplicationSubscription
Return Value

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

Managing Change Observers


                    
                    
                    changeObservers

Returns all currently active change observers.

Declaration

Swift

public private(set) var changeObservers: Set<DittoChangeObserver> { get }


                    
                    
                    registerChangeObserver(query:arguments:deliverOn:changeHandler:)

Convenience method, same as registerChangeObserver(query:arguments:deliverOn:changeHandlerWithSignalNext:) where signal next is called automatically after the changeHandler finishes.

Declaration

Swift

@discardableResult
public func registerChangeObserver(
    query: String,
    arguments: Dictionary<String, Any?>? = nil,
    deliverOn queue: DispatchQueue = .main,
    changeHandler: @escaping DittoChangeHandler
) throws -> DittoChangeObserver

registerChangeObserver(query:arguments:deliverOn:changeHandlerWithSignalNext:)
Installs and returns a change 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 registerChangeObserver( query: String, arguments: Dictionary<String, Any?>? = nil, deliverOn queue: DispatchQueue = .main, changeHandlerWithSignalNext: @escaping DittoChangeHandlerWithSignalNext ) throws -> DittoChangeObserver
Return Value

An active ChangeObserver 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.