Class Ditto

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

Hierarchy

  • Ditto

Constructors

constructor

Properties

auth deviceName identity isActivated isClosed isSyncActive path presence siteID store transportConfig

Accessors

sdkVersion

Methods

close disableSyncWithV3 observePeers observeTransportConditions runGarbageCollection setOfflineOnlyLicenseToken setTransportConfig startSync stopSync updateTransportConfig disableDeadlockDetection hasDeadlockDetection isEnvironmentSupported

Constructors

constructor

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

    See

    Parameters

    • Optional identity: Identity

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

    • Optional path: string

      On Node, path corresponds to a real directory on the file system (intermediate directories are created if needed). In the browser, path is used as an internal namespace for the in-memory storage. Defaults to "ditto".

    Returns Ditto

Properties

Readonly auth

auth: Authenticator

Provides access to authentication methods for logging on to Ditto Cloud.

deviceName

deviceName: string

Configure a custom identifier for the current device.

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. It does not need to be unique among peers. Configure the device name before calling startSync(). If it is too long it may be truncated.

Readonly identity

identity: Identity

The (validated) identity this Ditto instance was initialized with.

Readonly isActivated

isActivated: boolean

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

See

setOfflineOnlyLicenseToken()

Readonly isClosed

isClosed: boolean

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

Readonly isSyncActive

isSyncActive: boolean

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

Readonly path

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

Readonly presence

presence: Presence

Provides access to the SDK's presence functionality.

Readonly siteID

siteID: number | BigInt

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

Readonly store

store: Store

Provides access to the SDK's store functionality.

Readonly transportConfig

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

See

Accessors

sdkVersion

  • get sdkVersion(): string

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

    Returns string

Methods

close

  • 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

  • Explicitly opt-in to disabling the ability to sync with Ditto peers running any version of the SDK in the v3 (or lower) series of releases.

    Assuming this succeeds then this peer will only be able to sync with other peers using SDKs in the v4 (or higher) series of releases. Note that this disabling of sync spreads to peers that sync with a peer that has disabled, or has (transitively) had disabled, syncing with v3 SDK peers.

    Returns void

observePeers

  • 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).

    Deprecated

    please use presence.observe() instead.

    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.

    Returns Observer

observeTransportConditions

runGarbageCollection

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

    Only available in Node environments at the moment, no-op in the browser.

    Returns void

setOfflineOnlyLicenseToken

  • 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

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

    See

    Parameters

    Returns void

startSync

  • 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 network configuration can be customized with updateTransportConfig() or replaced entirely with setTransportConfig().

    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.

    See

    Returns void

stopSync

  • Stops all network transports.

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

    See

    Returns void

updateTransportConfig

  • 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

    Returns Ditto

Static disableDeadlockDetection

  • 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 not available in the browser.

    Returns void

Static hasDeadlockDetection

  • Returns true if deadlock detection is enabled.

    See Ditto.disableDeadlockDetection() for more information.

    This method always returns false in the browser where deadlock detection is not available.

    Returns

    true if deadlock detection is enabled

    Returns boolean

Static isEnvironmentSupported

  • Check if the current environment supports running Ditto.

    Required APIs include:

    • BigInt
    • FinalizationRegistry
    • WeakRef

    Internet Explorer is not supported.

    Returns

    true if the environment is supported

    Returns boolean

Settings

Member Visibility

Theme