@dittolive/ditto 4.7.3 → 4.7.4-rc.2

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

@@ -1,991 +0,0 @@
-//
-// 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'
-import { DittoError, mapFFIErrors } from './error'
-// -----------------------------------------------------------------------------
-
-/** 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 this peer.
-   *
-   * 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.
-   *
-   * Changes to this property after {@link startSync | 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 {@link startSync | startSync()} is called.
-   */
-  get deviceName(): string {
-    return this._deviceName
-  }
-
-  set deviceName(value: string) {
-    if (this.isSyncActive) {
-      Logger.warning('Changes to the device name take effect when sync is restarted.')
-    }
-    this._deviceName = value
-  }
-
-  /** 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.isReactNativeBuild) {
-      this._deviceName = FFI.defaultDeviceName() as string
-    }
-
-    this.keepAlive = new KeepAlive()
-
-    // WORKAROUND: the login provider triggers the registered callback right
-    // when the auth client is being constructed. At this point, we don't have
-    // the auth client, which would be needed to perform a login, nor did we
-    // have a chance to create an authenticator. Therefore catch that first
-    // callback, store the seconds remaining and proceed with propagating
-    // it after all pieces are in place.
-    let secondsRemainingUntilAuthenticationExpires: number | null = null
-
-    const weakThis = new WeakRef(this)
-    const identityConfig = (() => {
-      if (validIdentity.type === 'offlinePlayground') {
-        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') {
-        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}`)
-    })()
-
-    // History tracking is an experimental feature that is not supported in the JS SDK.
-    const historyTracking = 'Disabled'
-
-    const dittoPointer = FFI.dittoMake(this.persistenceDirectory, identityConfig, historyTracking)
-
-    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)
-
-    if (Environment.isReactNativeBuild) {
-      // FIXME: disabling sync needs to be awaited but that is not possible in
-      // the constructor
-      this.disableSyncWithV3().catch((error: any) => {
-        Logger.error(`Failed to disable sync with V3: ${error?.message}`)
-      })
-    }
-
-    // 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 {
-          // WORKAROUND: see description above where the
-          // secondsRemainingUntilAuthenticationExpires variable is declared.
-          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
-      void 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()
-
-    // WORKAROUND: see description above where the
-    // secondsRemainingUntilAuthenticationExpires variable is declared.
-    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).
-   */
-  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 (IdentityTypesRequiringOfflineLicenseToken.includes(this.identity.type)) {
-      this._isActivated = false
-
-      mapFFIErrors(() => FFI.tryVerifyLicense(licenseToken))
-
-      this._isActivated = true
-    } else {
-      Logger.error(`The identity type '${this.identity.type}' does not require an offline license token.`)
-    }
-  }
-
-  /**
-   * 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.
-   */
-  async disableSyncWithV3(): Promise<void> {
-    const dittoHandle = Bridge.ditto.handleFor(this)
-    return this.deferCloseAsync(async () => {
-      await 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()
-    await 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)
-      // REFACTOR: in theory, we could end up in an endless loop here if for
-      // some reason a resolved or rejected promise isn't removed from
-      // `pendingOperations`. AFAICS, this is not possible atm due to the
-      // way `deferClose` and `deferCloseAsync` is implemented. Would be
-      // great to rework this and make it more solid if possible.
-    } 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
-  private _deviceName: string
-
-  /** 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
-
-      this._deviceName = 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
-}