Options
All
  • Public
  • Public/Protected
  • All
Menu

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

Hierarchy

  • Ditto

Index

Constructors

  • 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

    identity

    see

    path

    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 into the backing storage (in-memory at the moment, support for IndexedDB is in development). Defaults to "ditto".

    Returns Ditto

Properties

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

deviceName: string

Configure a custom identifier for the current device.

When using observePeers(), 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.

identity: Identity

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

isActivated: boolean

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

see

setOfflineOnlyLicenseToken()

isSyncActive: boolean

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

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

siteID: number | BigInt

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

store: Store

Provides access to the SDK's store functionality.

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.

see

setTransportConfig()

see

updateTransportConfig()

Accessors

  • get isSyncEnabled(): boolean
  • Returns true if sync has been started, returns false if it has been stopped. Returns false if sync has never been started for this instance.

    deprecated:

    use isSyncActive instead.

    Returns boolean

  • get sdkVersion(): string
  • Returns a string identifying the version of the Ditto SDK.

    Returns string

Methods

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

    Returns 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

    Returns Observer

  • runGarbageCollection(): void
  • 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

  • setAccessLicense(accessLicense: string): void
  • deprecated

    use setOfflineOnlyLicenseToken() instead. 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

    • accessLicense: string

    Returns void

  • setLicenseToken(licenseToken: string): 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.

    deprecated

    use setOfflineOnlyLicenseToken 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

  • setOfflineOnlyLicenseToken(licenseToken: string): 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

  • 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

    transportConfig

    see

    updateTransportConfig()

    Parameters

    Returns void

  • 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 Bluetooth, WiFi/LAN, and AWDL. The network configuration can be customized with setTransportConfig(). On the Web, only connecting via Websockets is supported.

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

    see

    isSyncActive

    see

    stopSync()

    Returns void

  • stopSync(): void
  • Stops all network transports.

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

    see

    isSyncActive

    see

    startSync()

    Returns void

  • tryStartSync(): void
  • Alias for startSync().

    This method and startSync() are semantically equivalent in the JS SDK while differing for languages like Swift or ObjC. Therefore the alias.

    Returns void

  • 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