@dittolive/ditto 4.5.1-experimental.aarch64-linux.1.aarch64 → 4.5.2-rc.2

package/react-native/src/sources/ditto.ts

@@ -0,0 +1,979 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import * as Environment from './@environment'
+
+import { TransportConfig, transportConfigToSerializable } from './transport-config'
+
+import { Authenticator, OnlineAuthenticator, NotAvailableAuthenticator } from './authenticator'
+import { IdentityTypesRequiringOfflineLicenseToken } from './identity'
+import { Bridge } from './bridge'
+import { CBOR } from './cbor'
+import { Store } from './store'
+import { Logger } from './logger'
+import { KeepAlive } from './keep-alive'
+
+import { Observer } from './observer'
+import { ObserverManager } from './observer-manager'
+
+import { Presence } from './presence'
+import { LiveQueryManager } from './live-query-manager'
+import { PresenceManager } from './presence-manager'
+import { TransportConditionsManager } from './transport-conditions-manager'
+import { Sync } from './sync'
+
+import { defaultAuthURL } from './internal'
+import { SubscriptionManager } from './subscription-manager'
+import { AttachmentFetcherManager } from './attachment-fetcher-manager'
+import { SmallPeerInfo } from './small-peer-info'
+
+import type { Identity } from './identity'
+// -----------------------------------------------------------------------------
+
+/** Types of connections that can be established between two peers. */
+export type TransportCondition = 'Unknown' | 'OK' | 'GenericFailure' | 'AppInBackground' | 'MDNSFailure' | 'TCPListenFailure' | 'NoBLECentralPermission' | 'NoBLEPeripheralPermission' | 'CannotEstablishConnection' | 'BLEDisabled' | 'NoBLEHardware' | 'WiFiDisabled' | 'TemporarilyUnavailable'
+
+/** The source for a transport condition. */
+export type ConditionSource = 'BLE' | 'TCP' | 'AWDL' | 'MDNS'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Types of connections that can be established between two peers.
+ * @deprecated replaced by {@link ConnectionType}.
+ */
+export type PresenceConnectionType = 'WiFi' | 'WebSocket' | 'AWDL' | 'BLE'
+
+/**
+ * A peer object with information about an observed peer.
+ * @deprecated replaced by {@link Peer}.
+ */
+export type RemotePeer = {
+  networkID: string
+  deviceName: string
+  rssi?: number
+  approximateDistanceInMeters?: number
+  connections: PresenceConnectionType[]
+}
+
+// -----------------------------------------------------------------------------
+
+// The name of the directory, relative to cwd, that will be used for persistence
+// if no other directory is specified.
+const DEFAULT_PERSISTENCE_DIRECTORY = 'ditto'
+
+/**
+ * Ditto is the entry point for accessing Ditto-related functionality.
+ */
+export class Ditto {
+  /**
+   * A string containing the semantic version of the Ditto SDK. Example: 4.4.3
+   */
+  static get VERSION(): string {
+    // Requires having called FFI.initSDKVersion() first.
+    return FFI.dittoGetSDKSemver()
+  }
+
+  /**
+   * Configure a custom identifier for the current device.
+   *
+   * When using {@link Presence.observe | 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
+   * {@link startSync | startSync()}. If it is too long it may be truncated.
+   */
+  deviceName: string
+
+  /** Returns a string identifying the version of the Ditto SDK. */
+  get sdkVersion() {
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    return this.deferClose(() => {
+      return FFI.dittoGetSDKVersion(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * The (validated) identity this Ditto instance was initialized with.
+   */
+  readonly identity: Identity
+
+  /**
+   * The path this Ditto instance was initialized with, if no path was given at
+   * construction time, the default value is returned (see constructor).
+   *
+   * @deprecated `Ditto.path` is deprecated. Please update your code to use the
+   * new 'Ditto.persistenceDirectory' property instead.
+   */
+  get path(): string {
+    Logger.warning("⚠️ Deprecation Warning: The 'Ditto.path' property is deprecated. Please update your code to use the new 'Ditto.persistenceDirectory' property instead.")
+    return this.persistenceDirectory
+  }
+
+  /**
+   * 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.
+   */
+  readonly persistenceDirectory: string
+
+  /**
+   * Provides access to the SDK's store functionality.
+   */
+  readonly store: Store
+
+  /**
+   * Provides access to the SDK's sync functionality.
+   */
+  readonly sync: Sync
+
+  /**
+   * Provides access to the SDK's presence functionality.
+   */
+  readonly presence: Presence
+
+  /**
+   * Provides access to authentication methods for logging on to Ditto Cloud.
+   */
+  readonly auth: Authenticator
+
+  /**
+   * The site ID that the instance of `Ditto` is using as part of its identity.
+   */
+  readonly siteID: number | BigInt
+
+  /**
+   * Provides access to the SDK's small peer info functionality.
+   */
+  readonly smallPeerInfo: SmallPeerInfo
+
+  /**
+   * Returns `true` if an offline license token has been set, otherwise returns `false`.
+   *
+   * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
+   */
+  get isActivated() {
+    return this._isActivated ?? false
+  }
+
+  /**
+   * `true` once {@link close | Ditto.close()} has been called, otherwise
+   * `false`.
+   */
+  get isClosed() {
+    return this._isClosed ?? false
+  }
+
+  /**
+   * Returns `true` if sync is active, otherwise returns `false`. Use
+   * {@link startSync | startSync()} to activate and
+   * {@link stopSync | stopSync()} to deactivate sync.
+   */
+  get isSyncActive() {
+    return this._isSyncActive ?? false
+  }
+
+  /**
+   * Application ID associated with the {@link Identity | identity} used by this
+   * Ditto instance.
+   * */
+  readonly appID: string
+
+  /**
+   * 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.
+   *
+   * @param identity - Identity for the new Ditto instance, defaults to
+   * `offlinePlayground` with `appID` being the empty string `''`.
+   *
+   * @param persistenceDirectory optional string containing a directory path
+   * that Ditto will use for persistence. Defaults to `"ditto"`. On Windows,
+   * the path will be automatically normalized.
+   *
+   * @see {@link Ditto.identity}
+   * @see {@link Ditto.persistenceDirectory}
+   * @throws {Error} when the current environment is not supported by this SDK.
+   * @throws {Error} for other failures during initialization of Ditto and
+   * validation of the provided identity.
+   */
+  constructor(identity?: Identity, persistenceDirectory?: string) {
+    if (!Ditto.isEnvironmentSupported()) {
+      throw new Error('Ditto does not support this JavaScript environment. Please consult the Ditto JavaScript documentation for a list of supported environments and browsers. You can use `Ditto.isEnvironmentSupported()` to run this check anytime.')
+    }
+
+    this.persistenceDirectory = Ditto.initPersistenceDirectory(persistenceDirectory)
+
+    const identityOrDefault = identity ?? { type: 'offlinePlayground', appID: '' }
+
+    const validIdentity = Object.freeze(this.validateIdentity(identityOrDefault))
+
+    this.identity = Object.freeze(validIdentity)
+
+    // Check if device name stays the same on sdk and core levels (#10729).
+
+    if (Environment.isWebBuild) {
+      this.deviceName = navigator.userAgent
+    }
+
+    if (Environment.isReactNativeBuild) {
+      this.deviceName = FFI.getDeviceName() as string
+    }
+
+    this.keepAlive = new KeepAlive()
+
+    // NOTE: some behavior not implemented yet as compared to the ObjC/Swift
+    // version:
+    //
+    // 1. Optional `identity` parameter falling back to a default one.
+    //
+    // 2. Optional siteID of the identity, falling back to a random one if
+    //    newly created or to the stored one if already persisted.
+
+    const uninitializedDittoX = FFI.uninitializedDittoMake(this.persistenceDirectory)
+
+    let secondsRemainingUntilAuthenticationExpires: number | null = null
+
+    const weakThis = new WeakRef(this)
+    const identityConfig = (() => {
+      if (validIdentity.type === 'offlinePlayground') {
+        if (Environment.isReactNativeBuild) {
+          throw new Error('OfflinePlayground Identity is currently not implemented for React Native.')
+        }
+        return FFI.dittoIdentityConfigMakeOfflinePlayground(validIdentity.appID, validIdentity.siteID ?? 0)
+      }
+
+      if (validIdentity.type === 'manual') {
+        if (Environment.isReactNativeBuild) {
+          throw new Error('Manual Identify is currently not implemented for React Native.')
+        }
+        return FFI.dittoIdentityConfigMakeManual(validIdentity.certificate)
+      }
+
+      if (validIdentity.type === 'sharedKey') {
+        if (Environment.isReactNativeBuild) {
+          throw new Error('Shared Key Identity is currently not implemented for React Native.')
+        }
+        return FFI.dittoIdentityConfigMakeSharedKey(validIdentity.appID, validIdentity.sharedKey, validIdentity.siteID)
+      }
+
+      if (validIdentity.type === 'onlinePlayground') {
+        const authURL = validIdentity.customAuthURL ?? defaultAuthURL(validIdentity.appID)
+        return FFI.dittoIdentityConfigMakeOnlinePlayground(validIdentity.appID, validIdentity.token, authURL)
+      }
+
+      if (validIdentity.type === 'onlineWithAuthentication') {
+        const authURL = validIdentity.customAuthURL ?? defaultAuthURL(validIdentity.appID)
+        return FFI.dittoIdentityConfigMakeOnlineWithAuthentication(validIdentity.appID, authURL)
+      }
+
+      throw new Error(`Can't create Ditto, unsupported identity type: ${validIdentity}`)
+    })()
+
+    const dittoPointer = FFI.dittoMake(uninitializedDittoX, identityConfig)
+
+    FFI.dittoAuthClientSetValidityListener(dittoPointer, function (...args) {
+      const ditto = weakThis.deref()
+      if (ditto == null || ditto.isClosed) {
+        Logger.info('Ditto is closed, ignoring auth client validity change')
+      } else {
+        ditto.authClientValidityChanged(...args)
+      }
+    })
+
+    const isWebValid = FFI.dittoAuthClientIsWebValid(dittoPointer)
+    const isX509Valid = FFI.dittoAuthClientIsX509Valid(dittoPointer)
+
+    const appID = FFI.dittoAuthClientGetAppID(dittoPointer)
+    const siteID = FFI.dittoAuthClientGetSiteID(dittoPointer)
+
+    Bridge.ditto.bridge(dittoPointer, this)
+
+    // IMPORTANT: Keeping the auth client around accumulates run-times and
+    // resources which becomes a problem specifically in tests (where we use one
+    // Ditto instance per test). We therefore keep it only if needed, i.e.
+    // _only_ for the onlineWithAuthentication and online identities and
+    // transfer ownership of it to the authenticator.
+    if (validIdentity.type === 'onlineWithAuthentication') {
+      this.auth = new OnlineAuthenticator(this.keepAlive, this, validIdentity.authHandler)
+
+      const loginProviderX = FFI.dittoAuthClientMakeLoginProvider(function (secondsRemaining) {
+        const strongThis = weakThis.deref()
+        if (!strongThis) {
+          Logger.warning(`Internal inconsistency, LoginProvider callback fired after the corresponding Ditto instance has been deallocated.`)
+          return
+        }
+
+        if (strongThis.auth) {
+          strongThis.auth['@ditto.authenticationExpiring'](secondsRemaining)
+        } else {
+          secondsRemainingUntilAuthenticationExpires = secondsRemaining
+        }
+      })
+      // We don't need to worry about awaiting the result of this call because
+      // auth all happens in the background and so there are no guarantees we
+      // need to uphold by making sure things are in a certain state before the
+      // constructor finishes
+      FFI.dittoAuthSetLoginProvider(dittoPointer, loginProviderX)
+    } else if (validIdentity.type === 'onlinePlayground') {
+      this.auth = new OnlineAuthenticator(this.keepAlive, this, {
+        authenticationRequired: function (authenticator: Authenticator) {
+          // No-op.
+        },
+
+        authenticationExpiringSoon: function (authenticator: Authenticator, secondsRemaining: number) {
+          // No-op.
+        },
+      })
+    } else {
+      this.auth = new NotAvailableAuthenticator(this.keepAlive)
+    }
+
+    const transportConfig = this.makeDefaultTransportConfig().freeze()
+
+    //
+    // Assign instance properties.
+    //
+
+    this.appID = appID
+    this.siteID = siteID
+
+    this.isX509Valid = isX509Valid
+    this.isWebValid = isWebValid
+
+    this.sync = new Sync(this)
+    this.sync.update({ isSyncActive: false, isX509Valid, isWebValid, identity: validIdentity, ditto: this, transportConfig })
+
+    // We don't need a license when running in the browser, so we
+    // mark the instance as activated from the get-go in that case.
+    this._isActivated = Environment.isWebBuild || !IdentityTypesRequiringOfflineLicenseToken.includes(validIdentity.type)
+
+    this.store = new Store(this)
+    this.smallPeerInfo = new SmallPeerInfo(this)
+    this.presence = new Presence(this)
+    this.presenceManager = new PresenceManager(this)
+    this.liveQueryManager = new LiveQueryManager(this, this.keepAlive)
+    this.attachmentFetcherManager = new AttachmentFetcherManager(this)
+    this.transportConditionsManager = new TransportConditionsManager(this)
+    this.subscriptionManager = new SubscriptionManager(this)
+
+    disableDeadlockTimeoutWhenDebugging()
+
+    if (secondsRemainingUntilAuthenticationExpires != null) {
+      this.auth['@ditto.authenticationExpiring'](secondsRemainingUntilAuthenticationExpires)
+    }
+  }
+
+  /**
+   * 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.
+   */
+  static disableDeadlockDetection(): void {
+    if (Environment.isNodeBuild) {
+      const current = FFI.getDeadlockTimeout()
+      if (current !== 0) {
+        try {
+          FFI.setDeadlockTimeout(0)
+        } catch (e: any) {
+          throw new Error(`Failed to disable deadlock detection: ${e?.message}`)
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns `true` if deadlock detection is enabled.
+   *
+   * See
+   * {@link Ditto.disableDeadlockDetection | 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
+   */
+  static hasDeadlockDetection(): boolean {
+    if (Environment.isNodeBuild) {
+      return FFI.getDeadlockTimeout() !== 0
+    }
+    return false
+  }
+
+  /**
+   * 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
+   */
+  static isEnvironmentSupported(): boolean {
+    // From https://stackoverflow.com/questions/21825157/internet-explorer-11-detection
+    let isIE = false
+    if (typeof window !== 'undefined' && window.navigator && window.navigator.userAgent && window.navigator.appVersion) {
+      isIE = window.navigator.userAgent.indexOf('MSIE') !== -1 || window.navigator.appVersion.indexOf('Trident/') > -1
+    }
+
+    let hasRequiredAPIs: boolean
+    try {
+      hasRequiredAPIs = checkAPIs()
+    } catch (error) {
+      throw new Error(`Error checking environment support: ${error}`)
+    }
+
+    return !isIE && hasRequiredAPIs
+  }
+
+  /**
+   * Validates and creates the given directory and returns its path.
+   *
+   * Any string containing non-whitespace characters is considered valid.
+   * Defaults to `ditto` if no path or an invalid path is given. In web
+   * environments, the given path is returned as-is if it is valid.
+   *
+   * @param path optional string containing a writable directory path
+   * @returns validated path
+   * @internal
+   */
+  static initPersistenceDirectory(path?: string): string {
+    let validatedPath: string
+    if (path == null) {
+      validatedPath = DEFAULT_PERSISTENCE_DIRECTORY
+    } else if (path.trim().length === 0) {
+      throw new Error(`Invalid argument for path parameter: '${path}'`)
+    } else {
+      validatedPath = path
+    }
+
+    if (Environment.isReactNativeBuild) {
+      validatedPath = FFI.createDirectory(validatedPath) as string
+    }
+    return validatedPath
+  }
+
+  /**
+   * 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`.
+   *
+   * @param licenseToken the license token to activate the `Ditto` instance
+   * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
+   *
+   * @throws {Error} if called in a React Native environment.
+   */
+  setOfflineOnlyLicenseToken(licenseToken: string) {
+    if (Environment.isWebBuild) {
+      // We don't need a license when running in the browser. Web builds mark the instance as activated
+      // inside the constructor.
+      Logger.info('Offline license token are ignored on web builds. Token validation will be skipped.')
+    }
+    if (Environment.isReactNativeBuild) {
+      throw new Error('Offline license tokens are currently not implemented for the React Native SDK.')
+    } else {
+      if (IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type)) {
+        const { result, errorMessage } = FFI.verifyLicense(licenseToken)
+        if (result !== 'LicenseOk') {
+          this._isActivated = false
+          throw new Error(errorMessage)
+        } else {
+          this._isActivated = true
+        }
+      } else {
+        throw new Error('Offline license tokens should only be used for manual, sharedKey or offlinePlayground identities')
+      }
+    }
+  }
+
+  /**
+   * Returns the current transport configuration, frozen. If you want to modify
+   * the transport config, make a {@link TransportConfig.copy | copy} first. Or
+   * use the {@link updateTransportConfig | 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 {@link setTransportConfig | setTransportConfig()}
+   * @see {@link updateTransportConfig | updateTransportConfig()}
+   */
+  get transportConfig(): TransportConfig {
+    return this.sync.parameters.transportConfig
+  }
+
+  /**
+   * 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
+   * {@link startSync | startSync()} is called.
+   *
+   * @see {@link transportConfig}
+   * @see {@link updateTransportConfig | updateTransportConfig()}
+   */
+  setTransportConfig(transportConfig: TransportConfig) {
+    const transportConfigNew = transportConfig.copy().freeze()
+
+    const identity = this.identity
+    const isWebValid = this.isWebValid
+    const isX509Valid = this.isX509Valid
+
+    this.sync.update({ transportConfig: transportConfigNew, identity, isWebValid, isX509Valid, isSyncActive: this.isSyncActive, ditto: this })
+
+    const configSerializeReady = transportConfigToSerializable(transportConfigNew)
+    const configCBOR = CBOR.encode(configSerializeReady)
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    this.deferClose(() => {
+      FFI.dittoSmallPeerInfoCollectionSetTransportConfigData(dittoHandle.deref(), configCBOR)
+    })
+  }
+
+  /**
+   * 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.
+   */
+  updateTransportConfig(update: (transportConfig: TransportConfig) => void): Ditto {
+    const transportConfig = this.transportConfig.copy()
+    update(transportConfig)
+    this.setTransportConfig(transportConfig)
+    return this
+  }
+
+  /**
+   * 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 {@link updateTransportConfig | updateTransportConfig()}
+   * or replaced entirely with {@link setTransportConfig | 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 {@link isSyncActive}
+   * @see {@link stopSync | stopSync()}
+   */
+  startSync() {
+    this.setSyncActive(true)
+  }
+
+  /**
+   * Stops all network transports.
+   *
+   * You may continue to use the database locally but no data will sync to or
+   * from other devices.
+   *
+   * @see {@link isSyncActive}
+   * @see {@link startSync | startSync()}
+   */
+  stopSync() {
+    this.setSyncActive(false)
+  }
+
+  /**
+   * 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).
+   *
+   * @param callback 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.
+   *
+   * @deprecated please use {@link Presence.observe | presence.observe()} instead.
+   */
+  observePeers(callback: (peersData: RemotePeer[]) => void): Observer {
+    Logger.warning('`ditto.observePeers()` is deprecated, please use `ditto.presence.observe()` instead.')
+    const token = this.presenceManager.addObserver(callback)
+    return new Observer(this.presenceManager, token, { stopsWhenFinalized: true })
+  }
+
+  /**
+   * 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).
+   *
+   * @param callback called when underlying transport conditions change with
+   * the changed `condition` and its `source`.
+   */
+  observeTransportConditions(callback: (condition: TransportCondition, source: ConditionSource) => void): Observer {
+    const token = this.transportConditionsManager.addObserver(callback)
+    return new Observer(this.transportConditionsManager, token, { stopsWhenFinalized: true })
+  }
+
+  /**
+   * 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.
+   */
+  runGarbageCollection() {
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    return this.deferClose(() => {
+      FFI.dittoRunGarbageCollection(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * 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.
+   *
+   * @throws {Error} if called in a React Native environment.
+   */
+  disableSyncWithV3() {
+    if (Environment.isReactNativeBuild) {
+      throw new Error('Disabling sync with V3 is not supported in a React Native environment.')
+    }
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    return this.deferClose(() => {
+      FFI.dittoDisableSyncWithV3(dittoHandle.deref())
+    })
+  }
+
+  /**
+   * Shut down Ditto and release all resources.
+   *
+   * Must be called before recreating a Ditto instance that uses the same
+   * persistence directory.
+   */
+  async close() {
+    if (this.isClosed) {
+      return
+    }
+
+    this._isClosed = true
+
+    this.stopSync()
+
+    this.store.close()
+    this.presence.close()
+    this.auth.close()
+    this.sync.close()
+    this.presenceManager.close()
+    this.liveQueryManager.close()
+    this.attachmentFetcherManager.close()
+    this.transportConditionsManager.close()
+    this.subscriptionManager.close()
+
+    if (this.keepAlive.isActive) {
+      throw new Error('Internal inconsistency, still kept alive after the Ditto object has been close()-ed. ')
+    }
+
+    // Await all pending operations before closing. Rejected promises are
+    // ignored because they are handled at the original call site.
+    do {
+      await Promise.allSettled(this.pendingOperations)
+
+    } while (this.pendingOperations.size > 0)
+    this.deferCloseAllowed = false
+
+    await Bridge.ditto.close(this)
+  }
+
+  // ------------------------------------------------------------ Internal -----
+
+  /** @internal */
+  keepAlive: KeepAlive
+
+  /** @internal */
+  liveQueryManager: LiveQueryManager
+
+  /** @internal */
+  subscriptionManager: SubscriptionManager
+
+  /** @internal */
+  attachmentFetcherManager: AttachmentFetcherManager
+
+  /**
+   * The number of operations pending before the Ditto instance can be closed.
+   *
+   * For testing purposes only.
+   * @internal */
+  get numPendingOperations(): number {
+    return this.pendingOperations.size
+  }
+
+  /**
+   * Makes sure that the closure is executed only if the Ditto instance hasn't
+   * been closed yet.
+   *
+   * @param closure the synchronous closure to execute.
+   * @returns the result of the closure.
+   * @throws if the Ditto instance was closed before calling this method.
+   * @internal */
+  deferClose<T>(closure: () => T): T {
+    if (!this.deferCloseAllowed) {
+      throw new Error(`Can't perform operation using a Ditto instance that has been closed.`)
+    }
+
+    return closure()
+  }
+
+  /**
+   * Makes sure that the closure is executed to completion before the Ditto
+   * instance is closed.
+   *
+   * Any calls to {@link close | `Ditto.close()`} will wait until the closure
+   * has completed before closing the Ditto instance.
+   *
+   * @param closure the asynchronous closure to execute.
+   * @returns the result of the closure.
+   * @throws if the Ditto instance was closed before calling this method.
+   * @internal */
+  async deferCloseAsync<T>(closure: () => Promise<T>): Promise<T> {
+    if (!this.deferCloseAllowed) {
+      throw new Error(`Can't perform operation using a Ditto instance that has been closed.`)
+    }
+
+    const pendingOperation = closure()
+    this.pendingOperations.add(pendingOperation)
+
+    let result: T
+    try {
+      result = await pendingOperation
+    } finally {
+      // Remove the promise from the set of pending operations even if it
+      // rejected.
+      this.pendingOperations.delete(pendingOperation)
+    }
+
+    return result
+  }
+
+  // ------------------------------------------------------------ Private ------
+
+  private deferCloseAllowed: boolean = true
+  private isWebValid: boolean = false
+  private isX509Valid: boolean = false
+
+  private presenceManager: PresenceManager
+  private transportConditionsManager: ObserverManager
+
+  private _isActivated: boolean
+  private _isSyncActive: boolean = false
+  private _isClosed: boolean = false
+
+  /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
+  private pendingOperations = new Set<Promise<any>>()
+
+  private authClientValidityChanged(isWebValid: boolean, isX509Valid: boolean) {
+    const transportConfig = this.transportConfig
+    const identity = this.identity
+
+    const isSyncActive = this.isSyncActive
+    const wasX509Valid = this.isX509Valid
+    const wasWebValid = this.isWebValid
+
+    this.isX509Valid = isX509Valid
+    this.isWebValid = isWebValid
+
+    this.auth['@ditto.authClientValidityChanged'](isWebValid, isX509Valid)
+    this.sync.update({ transportConfig, identity, isWebValid, isX509Valid, isSyncActive, ditto: this })
+  }
+
+  private validateIdentity(identity: Identity): Identity {
+    const validIdentity = { ...identity }
+
+    // @ts-expect-error we validate the existence of the value below.
+    const appID = identity.appID
+
+    if (!['offlinePlayground', 'sharedKey', 'manual', 'onlinePlayground', 'onlineWithAuthentication'].includes(identity.type)) {
+      throw new Error(`Can't create Ditto instance, unknown identity type: ${identity.type}`)
+    }
+
+    if ((identity.type === 'offlinePlayground' || identity.type === 'sharedKey' || identity.type === 'onlinePlayground' || identity.type === 'onlineWithAuthentication') && typeof appID === 'undefined') {
+      throw new Error(`Property .appID must be given for identity, but isn't.`)
+    }
+
+    if (typeof appID !== 'undefined' && typeof appID !== 'string') {
+      throw new Error(`Property .appID must be be of type string, but is of type '${typeof appID}': ${appID}`)
+    }
+
+    if ((identity.type === 'offlinePlayground' || identity.type === 'sharedKey') && typeof identity.siteID !== 'undefined') {
+      const siteID = identity.siteID
+      const isSiteIDNumberOrBigInt = typeof siteID === 'number' || typeof siteID === 'bigint'
+
+      if (!isSiteIDNumberOrBigInt) throw new Error("Can't create Ditto instance, siteID must be a number or BigInt")
+      if (siteID < 0) throw new Error("Can't create Ditto instance, siteID must be >= 0")
+      if (siteID > BigInt('0xffffffffffffffff')) throw new Error("Can't create Ditto instance, siteID must be < 2^64")
+    }
+
+    if (identity.type === 'sharedKey') {
+      // No validations yet.
+    }
+
+    if (identity.type === 'manual') {
+      // No validations yet.
+    }
+
+    if (identity.type === 'onlinePlayground') {
+      const token = identity.token
+
+      if (typeof token === 'undefined') {
+        throw new Error(`Property .token must be given for identity but isn't. You can find the corresponding token on the Ditto Portal.`)
+      }
+
+      if (typeof token !== 'undefined' && typeof token !== 'string') {
+        throw new Error(`Property .token of identity must be be of type string, but is of type '${typeof token}': ${token}`)
+      }
+    }
+
+    if (identity.type === 'onlineWithAuthentication') {
+      // No validations yet.
+    }
+
+    return validIdentity
+  }
+
+  private setSyncActive(flag: boolean) {
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    this.deferClose(() => {
+      if (flag && IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type) && !this.isActivated) {
+        throw new Error('Sync could not be started because Ditto has not yet been activated. This can be achieved with a successful call to `setOfflineOnlyLicenseToken`. If you need to obtain a license token then please visit https://portal.ditto.live.')
+      }
+
+      if (!this.isSyncActive && flag) {
+        this.keepAlive.retain('sync')
+      }
+
+      if (this.isSyncActive && !flag) {
+        this.keepAlive.release('sync')
+      }
+
+      this._isSyncActive = flag
+
+      const isWebValid = this.isWebValid
+      const isX509Valid = this.isX509Valid
+
+      const identity = this.identity
+      const transportConfig = this.transportConfig
+
+      FFI.dittoSetDeviceName(dittoHandle.deref(), this.deviceName)
+      this.sync.update({ identity, transportConfig, isWebValid, isX509Valid, isSyncActive: !!flag, ditto: this })
+    })
+  }
+
+  private makeDefaultTransportConfig(): TransportConfig {
+    const dittoHandle = Bridge.ditto.handleFor(this)
+    return this.deferClose(() => {
+      const transportConfig = new TransportConfig()
+
+      if (FFI.transportsBLEIsAvailable(dittoHandle.deref())) {
+        transportConfig.peerToPeer.bluetoothLE.isEnabled = true
+      }
+
+      if (FFI.transportsAWDLIsAvailable(dittoHandle.deref())) {
+        transportConfig.peerToPeer.awdl.isEnabled = true
+      }
+
+      if (FFI.transportsLANIsAvailable(dittoHandle.deref())) {
+        transportConfig.peerToPeer.lan.isEnabled = true
+      }
+
+      return transportConfig.freeze()
+    })
+  }
+}
+
+/**
+ * Returns true if the current JS environment supports all required APIs.
+ *
+ * @param _globalObject optional global object to test this function without
+ * having to mock `global`.
+ * @returns `true` iff all required APIs exist on `global`.
+ * @internal
+ */
+export const checkAPIs = (_globalObject?: typeof globalThis): boolean => {
+  const requiredBrowserAPIs = ['BigInt', 'WeakRef', 'FinalizationRegistry'] as const
+  const globalObject = _globalObject || globalThis || global || window
+  return requiredBrowserAPIs.every((apiName) => !!globalObject[apiName])
+}
+
+/**
+ * Disable deadlock timeout when Node.js is running with `--inspect` parameter.
+ *
+ * This heuristic is not failsafe as debugging mode can also be enabled by
+ * sending a `SIGUSR1` signal to the process.
+ *
+ * @internal
+ */
+export const disableDeadlockTimeoutWhenDebugging = () => {
+  if (Environment.isNodeBuild) {
+    const hasInspector = process && process?.execArgv?.some((arg) => arg.includes('--inspect') || arg.includes('--debug'))
+
+    // @ts-ignore - v8debug may be undefined
+    const hasLegacyDebugMode = (process && process?.execArgv?.some((arg) => arg.includes('--debug'))) || typeof v8debug === 'object'
+
+    if (hasInspector || hasLegacyDebugMode) {
+      try {
+        FFI.setDeadlockTimeout(0)
+        Logger.warning('Detected Node running with inspector enabled, disabling deadlock timeout.')
+      } catch (e: any) {
+        Logger.error(`Detected Node running with inspector enabled but failed to disable deadlock timeout: ${e?.message}`)
+      }
+    }
+  }
+}
+
+/**
+ * Return true if we have read and write permissions for the given directory.
+ *
+ * Always returns `true` in the browser.
+ *
+ * Uses `fs.accessSync()` on all platforms except Windows, where ACLs are not
+ * checked by that method [1]. On Windows, we try writing and removing a temp
+ * file to the given path instead.
+ *
+ * [1]:
+ * https://nodejs.org/docs/latest-v18.x/api/fs.html#fsaccesspath-mode-callback
+ *
+ * @internal
+ */
+const isDirectoryWritable = (directoryPath: string): boolean => {
+  return true
+}