Ditto

public class Ditto

Ditto is the entry point for accessing Ditto-related functionality.

  • The default root directory used for Ditto data persistence.

    This property returns the Application Support directory on Apple platforms (iOS, macOS, tvOS, visionOS) where Ditto stores its data when a relative persistence directory path (or nil) is provided.

    See also

    absolutePersistenceDirectory

    See also

    persistenceDirectory

    Declaration

    Swift

    public static let defaultRootDirectory: URL

    Return Value

    A URL representing the default root directory.

  • open(config:) Asynchronous

    Asynchronously creates and returns a new Ditto instance using the provided configuration.

    This is the recommended way to initialize Ditto in async environments. The method will suspend until the instance is ready or an error is thrown.

    Important

    This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy init(identity:persistenceDirectory:) initializers.

    Important

    In Ditto version 4.x, this method is only partially async and blocks for a significant portion of the initialization process. It will become fully async starting with Ditto 5.0.

    Throws

    DittoSwiftError.storeError(_:) with .persistenceDirectoryLocked if the chosen persistence directory is already in use by another Ditto instance.

    Throws

    DittoSwiftError.validationError(_:) with .invalidDittoConfig if the passed in DittoConfig‘s contents do not meet the required validation criteria. For detailed information on the validation requirements, consult the documentation of the individual properties of DittoConfig.

    Throws

    May throw other DittoSwiftErrors for other initialization failures.

    See also

    openSync(config:) for a blocking, non-async alternative.

    Declaration

    Swift

    public class func open(config: DittoConfig = .default) async throws -> Ditto

    Parameters

    config

    The configuration to initialize the new Ditto instance with. Defaults to DittoConfig.default.

    Return Value

    The newly created Ditto instance.

  • Synchronously creates and returns a new Ditto instance using the provided configuration.

    This is a blocking convenience method for initializing Ditto, intended for use in non-async environments. The method will block the calling thread until the instance is ready or an error is thrown.

    Important

    This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy init(identity:persistenceDirectory:) initializers.

    Throws

    DittoSwiftError.storeError(_:) with .persistenceDirectoryLocked if the chosen persistence directory is already in use by another Ditto instance.

    Throws

    DittoSwiftError.validationError(_:) with .invalidDittoConfig if the passed in DittoConfig‘s contents do not meet the required validation criteria. For detailed information on the validation requirements, consult the documentation of the individual properties of DittoConfig.

    Throws

    May throw other DittoSwiftErrors for other initialization failures.

    See also

    open(config:) for an async alternative.

    Declaration

    Swift

    public class func openSync(config: DittoConfig = .default) throws -> Ditto

    Parameters

    config

    The configuration to initialize the new Ditto instance with. Defaults to DittoConfig.default.

    Return Value

    The newly created Ditto instance.

  • A string containing the semantic version of the Ditto SDK. Example: 4.4.3.

    Declaration

    Swift

    public class var version: String { get }

  • Controls whether deinit should wait for underlying Ditto cleanup to complete. Default is true for debug builds and false for release builds. Can be explicitly set to override the default behavior.

    This is useful for detecting memory leaks in tests or ensuring fully deterministic cleanup.

    Declaration

    Swift

    public static var shouldWaitForCleanupOnClose: Bool { get set }

  • Timeout in seconds for waiting on underlying Ditto cleanup during deinit. Default is 10 seconds. Set to 0 for indefinite waiting. Only used when shouldWaitForCleanupOnClose is true.

    Declaration

    Swift

    public static var deinitTimeoutSeconds: TimeInterval { get set }

  • Interval in seconds for logging periodic status updates while waiting for underlying Ditto cleanup during deinit. Default is 1 second. Only used when shouldWaitForCleanupOnClose is true.

    Declaration

    Swift

    public static var deinitLogIntervalSeconds: TimeInterval { get set }

  • Returns the configuration used to initialize this Ditto instance.

    Important

    This API is in preview and provides a read-only property to access the configuration used during initialization of a Ditto instance in v5.

    Note

    Sensitive data such as passphrases and private keys are redacted from the returned configuration and replaced with the string [REDACTED].

    If this instance was initialized using the deprecated parameter-based APIs, the returned configuration will be an incomplete approximation, since there is no exact 1:1 mapping between the old parameters and the new DittoConfig. In this case, a warning will be logged.

    Warning

    Accessing this property on a Ditto instance created with the deprecated parameter-based APIs may result in a partially filled configuration. Prefer using the new DittoConfig-based initialization methods whenever possible.

    Declaration

    Swift

    public var config: DittoConfig { get }

  • An optional delegate that will be called with SDK lifecycle information if defined.

    Declaration

    Swift

    public var delegate: DittoDelegate? { get set }

  • Configure a custom identifier for this peer.

    When using presence, each remote peer is represented by a short UTF-8 “device name”. By default this will be a truncated version of the device’s hostname.

    Changes to this property after sync.start() was called will only take effect after the next restart of sync. The value does not need to be unique among peers. Device names longer than 24 bytes will be truncated once sync.start() is called.

    Declaration

    Swift

    public var deviceName: String { get set }

  • The site ID that the instance of Ditto is using as part of its identity.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `peerKeyString` instead — accessible via `DittoPeer`, `DittoConnection`, and `DittoConnectionRequest`.")
public var siteID: UInt64 { get }

  • The persistence directory used by Ditto to persist data.

    It is not recommended to directly read or write to this directory as its structure and contents are managed by Ditto and may change in future versions.

    When DittoLogger is enabled, logs may be written to this directory even after a Ditto instance was deallocated. Please refer to the documentation of DittoLogger for more information.

    Declaration

    Swift

    @available(*, deprecated, renamed: "absolutePersistenceDirectory", message: "Please use `absolutePersistenceDirectory` instead.")
public var persistenceDirectory: URL { get }

  • The absolute path to the persistence directory used by Ditto to persist data.

    This property returns the final, resolved absolute file path where Ditto stores its data. The value depends on what was provided in persistenceDirectory:

    • If an absolute path was provided, it returns that path unchanged
    • If a relative path was provided, it returns the path resolved relative to Ditto.defaultRootDirectory
    • If nil was provided, it returns the default path using the pattern {default_root}/ditto-{database-id} where {default-root} corresponds to Ditto.defaultRootDirectory and {database-id} is the Ditto database ID in lowercase.

    This property always returns a consistent value throughout the lifetime of the Ditto instance and represents the actual directory being used for persistence.

    Note

    “Database ID” was previously referred to as “App ID” in older versions of the SDK.

    Note

    It is not recommended to directly read from or write to this directory as its structure and contents are managed by Ditto and may change in future versions.

    Note

    When DittoLogger is enabled, logs may be written to this directory even after a Ditto instance has been deallocated. Please refer to the documentation of DittoLogger for more information.

    See also

    persistenceDirectory

    Declaration

    Swift

    public var absolutePersistenceDirectory: URL { get }

  • The Ditto application ID.

    Phased out in 4.x — replaced by databaseID — now accessible via config. This API will be replaced by databaseID in v5.

    Declaration

    Swift

    public var appID: String { get }

  • A flag indicating whether or not the SDK has been activated with a valid license token.

    Declaration

    Swift

    public var activated: Bool { get }

  • A flag indicating whether or not sync is active. Use startSync() to active and stopSync() to deactivate sync.

    Declaration

    Swift

    @available(*, deprecated, message: "Use sync.isActive instead")
public var isSyncActive: Bool { get }

  • A flag indicating whether or not the Ditto data is encrypted.

    Declaration

    Swift

    public var isEncrypted: Bool { get }

  • Provides access to authentication information and methods for logging on to Ditto Cloud.

    Declaration

    Swift

    public internal(set) var auth: DittoAuthenticator? { get }

  • Provides visibility into to disk usage of this Ditto instance.

    Declaration

    Swift

    public let diskUsage: DiskUsage

  • Provides access to the SDK’s store functionality.

    Declaration

    Swift

    public let store: DittoStore

  • Provides access to the SDK’s sync functionality.

    Declaration

    Swift

    public let sync: DittoSync

  • Provides access to the SDK’s presence functionality.

    Declaration

    Swift

    public let presence: DittoPresence

  • Provides access to the SDK’s small peer info functionality.

    Declaration

    Swift

    public let smallPeerInfo: DittoSmallPeerInfo

  • Provides access to the SDK’s experimental functionality.

    Declaration

    Swift

    public let experimental: DittoExperimental

  • The DispatchQueue that will be used to deliver delegate events. Defaults to DispatchQueue.main.

    Declaration

    Swift

    public var delegateEventQueue: DispatchQueue { get set }

  • Assign a new transports configuration. By default peer-to-peer transports (Bluetooth, WiFi and AWDL) are enabled. You may use this property to alter the configuration at any time. Sync will not begin until sync.sync() is called.

    Declaration

    Swift

    public var transportConfig: DittoTransportConfig { get set }

  • Convenience method to update the current transport config of the receiver.

    Invokes the block with a copy of the current transport config which you can alter to your liking. The updated transport config is then set on the receiver.

    You may use this method to alter the configuration at any time. Sync will not begin until startSync is invoked.

    Declaration

    Swift

    public func updateTransportConfig(block: (inout DittoTransportConfig) -> Void)

  • Indicates whether or not history tracking is enabled. Default is false.

    Phased out in 4.x — support for (experimental) history tracking is being phased out. This API will be removed in v5.

    History tracking is experimental and shouldn’t be used in production.

    Declaration

    Swift

    public var isHistoryTrackingEnabled: Bool { get }

  • Activate an offline DITDitto instance by setting a license token. You cannot sync data across instances using an offline (Development, OfflinePlayground, Manual or SharedKey) identity before you have activated the associated Ditto instance.

    Throws

    DittoError.

    Declaration

    Swift

    public func setOfflineOnlyLicenseToken(_ licenseToken: String) throws

    Parameters

    licenseToken

    The license token to activate the Ditto instance with, which you can find on the Ditto portal (https://portal.ditto.live).

  • Starts the network transports. Ditto will connect to other devices.

    By default Ditto will enable all peer-to-peer transport types. On Apple devices, this means BluetoothLE, WiFi/LAN, and AWDL. The default network configuration can be modified with updateTransportConfig() or replaced via the transportConfig property.

    Performance of initial sync when bootstrapping a new peer can be improved by calling disableSyncWithV3() before calling startSync(). Only do this when all peers in the mesh are known to be running Ditto v4 or higher.

    Throws

    DittoSwiftError > .authenticationError(.expirationHandlerMissing) if the Ditto instance was initialized with connect set to .server(url:) while expirationHandler is nil. For sync to work with server connections, Ditto requires (a) a DittoAuthenticationExpirationHandler to be set via ditto.auth.expirationHandler, and (b) that handler to properly authenticate when requested.

    Throws

    DittoError.

    Declaration

    Swift

    @available(*, deprecated, message: "Use sync.start(﹚ instead")
public func startSync() throws

  • Stops all network transports.

    You may continue to use the Ditto store locally but no data will sync to or from other devices.

    Declaration

    Swift

    @available(*, deprecated, message: "Use sync.stop(﹚ instead")
public func stopSync()

  • Request bulk status information about the transports. This is mostly intended for statistical or debugging purposes.

    Throws

    DittoError.

    Declaration

    Swift

    public func transportDiagnostics() throws -> DittoTransportDiagnostics

    Return Value

    An instance of DittoTransportDiagnostics.

  • A string identifying the version of the DittoSwift SDK.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `version` instead.")
public var sdkVersion: String { get }

  • Removes all sync metadata for any remote peers which aren’t currently connected. This method shouldn’t usually be called. Manually running garbage collection often will result in slower sync times. Ditto automatically runs a garbage a collection process in the background at optimal times.

    Manually running garbage collection is typically only useful during testing if large amounts of data are being generated. Alternatively, if an entire data set is to be evicted and it’s clear that maintaining this metadata isn’t necessary, then garbage collection could be run after evicting the old data.

    Declaration

    Swift

    @available(*, deprecated, message: "Explicit trigger for garbage collection is being phased out.")
public func runGarbageCollection()

  • Disable sync with peers running version 3 or lower of the Ditto SDK.

    Required for the execution of mutating DQL statements.

    This setting spreads to other peers on connection. Those peers will in turn spread it further until all peers in the mesh take on the same setting. This is irreversible and will persist across restarts of the Ditto instance.

    Calling this method before startSync() is recommended whenever possible. This improves performance of initial sync when this peer has never before connected to a Ditto mesh for which sync with v3 peers is disabled.

    Throws

    DittoError if the operation fails.

    Declaration

    Swift

    public func disableSyncWithV3() throws

Deprecated

  • Request information about Ditto peers in range of this device.

    This method returns an observer which should be held as long as updates are required. A newly registered observer will have a peers update delivered to it immediately. Then it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `self.presence.observe(﹚` instead.")
public func observePeers(callback: @escaping (Array<DittoRemotePeer>) -> ()) -> DittoObserver

  • Request information about Ditto peers in range of this device.

    This method returns an observer which should be held as long as updates are required. A newly registered observer will have a peers update delivered to it immediately. From then on it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `self.presence.observe(﹚` instead.")
public func observePeersV2(callback: @escaping (String) -> ()) -> DittoObserver

  • Initializes a new Ditto.

    Phased out in 4.x — replaced by open(config:) and openSync(config:) factory methods. This API will be replaced by the new factory methods in v5.

    Declaration

    Swift

    public convenience init(
    identity: DittoIdentity = .offlinePlayground(),
    persistenceDirectory directory: URL? = nil
)

    Parameters

    identity

    Provide the identity of the entity that is interacting with Ditto.
    persistenceDirectory

    The directory that will be used to persist Ditto data.

  • Initializes a new Ditto.

    Phased out in 4.x — replaced by open(config:) and openSync(config:) factory methods. This API will be replaced by the new factory methods in v5.

    Declaration

    Swift

    public convenience init(
    identity: DittoIdentity = .offlinePlayground(),
    historyTrackingEnabled: Bool,
    persistenceDirectory: URL? = nil
)

    Parameters

    identity

    Provide the identity of the entity that is interacting with Ditto.
    historyTrackingEnabled

    Whether or not you want history tracking enabled.
    persistenceDirectory

    The directory that will be used to persist Ditto data.

  • A Combine publisher that shows all the remote connected peers.

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Replaced by `DittoPresence.GraphPublisher`.")
struct RemotePeersPublisher : Publisher

  • A Combine publisher that shows all the remote connected peers.

    Declaration

    Swift

    @available(*, deprecated, message: "Replaced by `self.presence.graphPublisher(﹚`.")
func remotePeersPublisher() -> RemotePeersPublisher

    Return Value

    A RemotePeersPublisher which has an output of [DittoRemotePeer]