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.

    NOTE: only returns results from the local store without waiting for any DittoSyncSubscription to have caught up with the latest changes. Only use this method if your program must proceed with immediate results. Use a DittoStoreObserver to receive updates to query results as soon as they have been synced to this peer.

    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 DittoStoreObserver 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.

Working with Attachments

  • Creates a new attachment, which can then be inserted into a document.

    The file residing at the provided path will be copied into Ditto’s store. The DittoAttachment object that is returned is what you can then use to insert an attachment into a document.

    You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.

    Below is a snippet to show how you can use the newAttachment() functionality to insert an attachment into a document.

    if let attachment = try await store.newAttachment("/path/to/my/file.zip") {
    let document: [String: Any] = ["some": "string", "myAttachment": attachment]
    let insertQueryResult = try await store.execute(
        query: "INSERT INTO COLLECTION myCollection (myAttachment ATTACHMENT) DOCUMENTS (:document1)",
        arguments: ["document1": document]
    )
}

    Throws

    DittoSwiftError > .storeError(.attachmentFileNotFound) if the corresponding file couldn’t be found.

    Throws

    DittoSwiftError > .storeError(.attachmentFilePermissionDenied) if permission to access the file has been denied.

    Throws

    DittoSwiftError > .storeError(.failedToFetchAttachment) if an unknown error occured while trying to fetch an attachment.

    Declaration

    Swift

    public func newAttachment(path: String, metadata: [String : String] = [:]) async throws -> DittoAttachment

    Parameters

    path

    Path to the file on disk that will be used as the attachment.
    metadata

    Optional metadata relating to the attachment.

    Return Value

    A DittoAttachment object, which can be used to insert the attachment into a document.

  • Returns all currently active attachment fetchers.

    Declaration

    Swift

    public private(set) var attachmentFetchers: Set<DittoAttachmentFetcher> { get }

  • Fetch the attachment corresponding to the provided attachment token.

    Throws

    DittoSwiftError > .storeError(.attachmentNotFound) if the corresponding attachment couldn’t be found.

    Throws

    DittoSwiftError > .storeError(.failedToFetchAttachment) if an unknown error occured while trying to fetch an attachment.

    Declaration

    Swift

    @discardableResult
public func fetchAttachment(
    token: DittoAttachmentToken,
    deliverOn deliveryQueue: DispatchQueue = .main,
    onFetchEvent: @escaping (DittoAttachmentFetchEvent) -> Void
) throws -> DittoAttachmentFetcher

    Parameters

    token

    The token for the attachment that you want to fetch.
    dispatchQueue

    The dispatch queue that will be used to deliver attachment fetch updates. Defaults to the main queue.
    onFetchEvent

    A closure that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

    Return Value

    An active DittoAttachmentFetcher for the passed in token. You’ll have to keep it to be able to cancel the fetching. Otherwise the fetch will remain active until it either completes, the attachment is deleted, or the owning Ditto object goes out of scope.

  • Fetch the attachment corresponding to the provided attachment token. Expects a dictionary representation of the token as returned in a DittoQueryResultItem.

    Throws

    DittoSwiftError > .storeError(.failedToFetchAttachment) if the corresponding attachment couldn’t be found.

    Declaration

    Swift

    @discardableResult
public func fetchAttachment(
    token: [String: Any],
    deliverOn queue: DispatchQueue = .main,
    onFetchEvent: @escaping (DittoAttachmentFetchEvent) -> Void
) throws -> DittoAttachmentFetcher

    Parameters

    token

    Dictionary representation of the token for the attachment that you want to fetch.
    dispatchQueue

    The dispatch queue that will be used to deliver attachment fetch updates. Defaults to the main queue.
    onFetchEvent

    A closure that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

    Return Value

    A DittoAttachmentFetcher object.

  • A Combine publisher that fetches an attachement. Can also be used to monitor progress as a large attachment is downloaded across the network.

    See more

    Declaration

    Swift

    struct FetchAttachmentPublisher : Publisher

  • A Combine publisher that fetches an attachement.

    Declaration

    Swift

    func fetchAttachmentPublisher(attachmentToken: DittoAttachmentToken) -> FetchAttachmentPublisher

    Parameters

    attachmentToken

    The DittoAttachmentToken for the attachment to fetch.

    Return Value

    A FetchAttachmentPublisher which has an output of DittoAttachmentFetchEvent

  • A Combine publisher that fetches an attachement given the attachment token as dictionary representation.

    Declaration

    Swift

    func fetchAttachmentPublisher(attachmentToken: [String : Any]) -> FetchAttachmentPublisher

    Parameters

    attachmentToken

    The DittoAttachmentToken for the attachment to fetch as dictionary representation.

    Return Value

    A FetchAttachmentPublisher which has an output of DittoAttachmentFetchEvent