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.
Phased out in 4.x — replaced by Ditto.open() and Ditto.openSync() factory methods. This API will be replaced by the new factory methods in v5.
Optionalidentity: IdentityIdentity for the new Ditto instance, defaults to
offlinePlayground with appID being the empty string ''.
OptionalpersistenceDirectory: stringoptional string containing a directory path
that Ditto will use for persistence. Defaults to "ditto". On Windows, the
path will be automatically normalized.
ReadonlyappIDApplication ID associated with the identity used by this Ditto instance.
Phased out in 4.x. This API will be replaced by ditto.config.databaseID in v5.
ReadonlyauthProvides access to authentication methods for logging on to Ditto Cloud.
ReadonlypresenceProvides access to the SDK's presence functionality.
ReadonlysiteIDThe site ID that the instance of Ditto is using as part of its identity.
use peerKeyString instead, accessible via Peer,
Connection, and ConnectionRequest.
ReadonlysmallProvides access to the SDK's small peer info functionality.
ReadonlystoreProvides access to the SDK's store functionality.
ReadonlysyncProvides access to the SDK's sync functionality.
The persistence directory used by Ditto to persist data, represented by an absolute path.
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 Logger is enabled, logs may be written to this directory even after a Ditto instance was deallocated. Please refer to the documentation of Logger for more information.
In browsers, this string acts as a namespace for the in-memory data store and does not correspond to a file system directory.
The configuration used to initialize this Ditto instance.
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.
Ditto instance created with the
deprecated parameter-based APIs may result in a partially filled
configuration. Prefer using the new DittoConfig-based initialization
methods Ditto.open() and
Ditto.openSync() whenever possible.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.
The (validated) identity this Ditto instance was initialized with.
Phased out in 4.x. This API will be replaced by DittoConfig in v5.
Returns true if an offline license token has been set, otherwise returns false.
true once Ditto.close() has been called, otherwise
false.
Returns true if sync is active, otherwise returns false. Use
startSync() to activate and
stopSync() to deactivate sync.
use ditto.sync.isActive instead.
The path this Ditto instance was initialized with, if no path was given at construction time, the default value is returned (see constructor).
Path to the local directory used for persistent data storage.
Defaults to 'ditto'. In environments without file system access, such as browsers, this is used as a namespace for the internal data store.
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 Logger is enabled, logs may be written to this directory even after a Ditto instance was closed. Please refer to the documentation of Logger for more information.
replaced by absolutePersistenceDirectory, which guarantees an absolute path.
Returns a string identifying the version of the Ditto SDK. *
This property is deprecated, use Ditto.VERSION instead.
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.).
StaticDEFAULT_The default root directory used for Ditto data persistence.
This property returns the platform-dependent directory where Ditto stores
its data when a relative persistence directory path (or null) is
provided.
Node.js
~/Library/Application Support/ditto directory.~/AppData/Roaming/ditto directory.~/.local/share/ditto directory.Note that sandboxed environments, such as Electron apps running under Apple's App Sandbox, can require setting a custom persistence directory as these default directories may not be accessible.
React Native
Browsers
In browsers, this returns an empty string as there is no file system access.
A string representing the default root directory.
DittoConfig.persistenceDirectory for more information on configuring the persistence directory.
StaticVERSIONA string containing the semantic version of the Ditto SDK. Example: 4.4.3
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.
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).
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.
please use presence.observe() instead.
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).
called when underlying transport conditions change with
the changed condition and its source.
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.
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.
the license token to activate the Ditto instance
with. You can find yours on the Ditto portal.
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.
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.
use ditto.sync.start() instead.
Stops all network transports.
You may continue to use the Ditto store locally but no data will sync to or from other devices.
use ditto.sync.stop() instead.
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.
StaticdisableDon'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.
StatichasReturns 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.
true if deadlock detection is enabled
StaticisStaticopenAsynchronously creates and returns a new Ditto instance using the
provided configuration.
This is the recommended way to initialize Ditto in async environments.
This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy Ditto constructor.
In Ditto 4.x, this method is only partially async and blocks for a
significant portion of the initialization process. It will become fully
async in Ditto 5.x.
Optionalconfig: DittoConfigThe configuration to initialize the new Ditto instance with. Defaults to DittoConfig.default.
The newly created Ditto instance.
DittoError with code persistenceDirectoryLocked if the
chosen persistence directory is already in use by another Ditto instance.
DittoError with code 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.
May throw other DittoErrors for other initialization failures.
Ditto.openSync() for a blocking, non-async alternative.
StaticopenSynchronously 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.
This API is in preview and will become the standard way to initialize Ditto instances in v5, replacing the legacy Ditto constructor.
Optionalconfig: DittoConfigThe configuration to initialize the new Ditto instance with. Defaults to DittoConfig.default.
The newly created Ditto instance.
DittoError with code persistenceDirectoryLocked if the
chosen persistence directory is already in use by another Ditto instance.
DittoError with code 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.
May throw other DittoErrors for other initialization failures.
Ditto.open() for an async alternative.
Ditto is the entry point for accessing Ditto-related functionality.