Class Ditto

constructor

• new Ditto(identity?, persistenceDirectory?): Ditto

• Initializes a new Ditto instance.

  NOTE: The sharedKey identity is only supported for Node environments, using this to create a Ditto instance in the web browser will throw an exception.

  Parameters

  • Optionalidentity: Identity

    Identity for the new Ditto instance, defaults to offlinePlayground with appID being the empty string ''.
  • OptionalpersistenceDirectory: string

    optional string containing a directory path that Ditto will use for persistence. Defaults to "ditto". On Windows, the path will be automatically normalized.

  Returns Ditto

  See

  • Ditto.identity
  • Ditto.persistenceDirectory

  Throws

  when the current environment is not supported by this SDK.

  Throws

  for other failures during initialization of Ditto and validation of the provided identity.

ReadonlyappID

Readonlyauth

Readonlyidentity

ReadonlypersistenceDirectory

Readonlypresence

ReadonlysiteID

ReadonlysmallPeerInfo

Readonlystore

Readonlysync

deviceName

• get deviceName(): string

• Configure a custom identifier for this peer.

  When using presence.observe(), 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 startSync() 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 startSync() is called.

  Returns string
• set deviceName(value): void

• Parameters

  • value: string

  Returns void

isActivated

• get isActivated(): boolean

• Returns true if an offline license token has been set, otherwise returns false.

  Returns boolean

  See

  setOfflineOnlyLicenseToken()

isClosed

• get isClosed(): boolean

• true once Ditto.close() has been called, otherwise false.

  Returns boolean

isSyncActive

• get isSyncActive(): boolean

• Returns true if sync is active, otherwise returns false. Use startSync() to activate and stopSync() to deactivate sync.

  Returns boolean

path

• get path(): string

• The path this Ditto instance was initialized with, if no path was given at construction time, the default value is returned (see constructor).

  Returns string

  Deprecated

  Ditto.path is deprecated. Please update your code to use the new 'Ditto.persistenceDirectory' property instead.

sdkVersion

• get sdkVersion(): string

• Returns a string identifying the version of the Ditto SDK.

  Returns string

transportConfig

• get transportConfig(): TransportConfig

• Returns the current transport configuration, frozen. If you want to modify the transport config, make a copy first. Or use the updateTransportConfig() convenience method. By default peer-to-peer transports (Bluetooth, WiFi, and AWDL) are enabled if available in the current environment (Web, Node, OS, etc.).

  Returns TransportConfig

  See

  • setTransportConfig()
  • updateTransportConfig()

StaticVERSION

• get VERSION(): string

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

  Returns string

close

• close(): Promise<void>

• Shut down Ditto and release all resources.

  Must be called before recreating a Ditto instance that uses the same persistence directory.

  Returns Promise<void>

disableSyncWithV3

• disableSyncWithV3(): Promise<void>

• 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 starting sync 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.

  Returns Promise<void>

  Throws

  when called in a React Native environment where sync with v3 is always disabled.

observePeers

• observePeers(callback): Observer

• Registers an observer for info about Ditto peers in range of this device.

  Ditto will prevent the process from exiting as long as there are active peers observers (not relevant when running in the browser).

  Parameters

  • callback: ((peersData: RemotePeer[]) => void)

    called immediately with the current state of peers in range and whenever that state changes. Then it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

    • • (peersData): void

      • Parameters

        • peersData: RemotePeer[]

        Returns void

  Returns Observer

  Deprecated

  please use presence.observe() instead.

observeTransportConditions

• observeTransportConditions(callback): Observer

• Register observer for changes of underlying transport conditions.

  Ditto will prevent the process from exiting as long as there are active transport conditions observers (not relevant when running in the browser).

  Parameters

  • callback: ((condition: TransportCondition, source: ConditionSource) => void)

    called when underlying transport conditions change with the changed condition and its source.

    • • (condition, source): void

      • Parameters

        • condition: TransportCondition
        • source: ConditionSource

        Returns void

  Returns Observer

runGarbageCollection

• runGarbageCollection(): Promise<void>

• Removes all sync metadata for remote peers that 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.

  This method does not have any effect when running Ditto in a browser.

  Returns Promise<void>

setOfflineOnlyLicenseToken

• setOfflineOnlyLicenseToken(licenseToken): void

• Activate a Ditto instance by setting an offline only license token. You cannot initiate sync with Ditto before you have activated it. The offline license token is only valid for identities of type development, manual, offlinePlayground, and sharedKey.

  Parameters

  • licenseToken: string

    the license token to activate the Ditto instance with. You can find yours on the Ditto portal.

  Returns void

setTransportConfig

• setTransportConfig(transportConfig): void

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

  Parameters

  • transportConfig: TransportConfig

  Returns void

  See

  • transportConfig
  • updateTransportConfig()

startSync

• startSync(): void

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

  By default Ditto will enable all peer-to-peer transport types. On Node, this means BluetoothLE, WiFi/LAN, and AWDL. On the Web, only connecting via Websockets is supported. The default network configuration can be modified with updateTransportConfig() or replaced with setTransportConfig().

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

  Ditto will prevent the process from exiting until sync is stopped (not relevant when running in the browser).

  NOTE: the BluetoothLE transport on Linux is experimental, this method panics if no BluetoothLE hardware is available. Therefore, contrary to the above, the BluetoothLE transport is temporarily disabled by default on Linux.

  Returns void

  See

  • isSyncActive
  • stopSync()

stopSync

• stopSync(): void

• Stops all network transports.

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

  Returns void

  See

  • isSyncActive
  • startSync()

updateTransportConfig

• updateTransportConfig(update): Ditto

• Convenience method for updating the transport config. Creates a copy of the current transport config, passes that copy to the update closure, allowing it to mutate as needed, and sets that updated copy afterwards.

  Parameters

  • update: ((transportConfig: TransportConfig) => void)
    • • (transportConfig): void

      • Parameters

        • transportConfig: TransportConfig

        Returns void

  Returns Ditto

StaticdisableDeadlockDetection

• disableDeadlockDetection(): void

• Don't terminate the process when callbacks are pending for a long time.

  Some methods in the Ditto library accept asynchronous functions as callback parameters. If these asynchronous functions do not resolve within a certain period of time after having been invoked by Ditto, deadlock detection gets triggered, resulting in the termination of the process.

  When Ditto is executed in a Node.js environment with an interactive debugger attached, this deadlock detection might get activated upon encountering a breakpoint. Calling Ditto.disableDeadlockDetection() disables this behavior, thus allowing the use of an interactive debugger without triggering the deadlock detection.

  This feature is only available in Node.js environments.

  Returns void

StatichasDeadlockDetection

• hasDeadlockDetection(): boolean

• Returns true if deadlock detection is enabled.

  See Ditto.disableDeadlockDetection() for more information.

  When called outside of a Node.js environment, this method always returns false as deadlock detection is only available in Node.js.

  Returns boolean

  true if deadlock detection is enabled

StaticisEnvironmentSupported

• isEnvironmentSupported(): boolean

• Check if the current environment supports running Ditto.

  Required APIs include:

  • BigInt
  • FinalizationRegistry
  • WeakRef

  Internet Explorer is not supported.

  Returns boolean

  true if the environment is supported