@dittolive/ditto 4.7.4 → 4.8.0-rc.2

package/node/ditto.cjs.js

@@ -278,18 +278,6 @@ const ditto = (function () {
 
   throw new Error("No native module 'ditto." + target + ".node' found. Please check the Ditto documentation for supported platforms.")
 })();
-
-// Kept in a block scope to avoid leaking the target variable. The native
-// module registers its functions in global scope.
-{
-  const target = process.platform + '-' + process.arch;
-  try {
-    if (target === 'darwin-x64') require('./transports.darwin-x64.node');
-    if (target === 'darwin-arm64') require('./transports.darwin-arm64.node');
-  } catch (error) {
-    console.warn("Couldn't load native module 'transports." + target + ".node' due to error:" + error.toString());
-  }
-}
 function ble_client_free_handle(...args) { return ditto.ble_client_free_handle(...args) }
 function ble_server_free_handle(...args) { return ditto.ble_server_free_handle(...args) }
 function boxCBytesIntoBuffer(...args) { return ditto.boxCBytesIntoBuffer(...args) }
@@ -417,10 +405,12 @@ function dittoffi_connection_request_free(...args) { return ditto.dittoffi_conne
 function dittoffi_connection_request_identity_service_metadata_json(...args) { return ditto.dittoffi_connection_request_identity_service_metadata_json(...args) }
 function dittoffi_connection_request_peer_key_string(...args) { return ditto.dittoffi_connection_request_peer_key_string(...args) }
 function dittoffi_connection_request_peer_metadata_json(...args) { return ditto.dittoffi_connection_request_peer_metadata_json(...args) }
+function dittoffi_crypto_generate_secure_random_token(...args) { return ditto.dittoffi_crypto_generate_secure_random_token(...args) }
 function dittoffi_error_code(...args) { return ditto.dittoffi_error_code(...args) }
 function dittoffi_error_description(...args) { return ditto.dittoffi_error_description(...args) }
 function dittoffi_error_free(...args) { return ditto.dittoffi_error_free(...args) }
 function dittoffi_get_sdk_semver(...args) { return ditto.dittoffi_get_sdk_semver(...args) }
+function dittoffi_logger_try_export_to_file_async(...args) { return ditto.dittoffi_logger_try_export_to_file_async(...args) }
 function dittoffi_presence_peer_metadata_json(...args) { return ditto.dittoffi_presence_peer_metadata_json(...args) }
 function dittoffi_presence_set_connection_request_handler(...args) { return ditto.dittoffi_presence_set_connection_request_handler(...args) }
 function dittoffi_presence_try_set_peer_metadata_json(...args) { return ditto.dittoffi_presence_try_set_peer_metadata_json(...args) }
@@ -446,8 +436,6 @@ function mdns_server_free_handle(...args) { return ditto.mdns_server_free_handle
 function refCBytesIntoBuffer(...args) { return ditto.refCBytesIntoBuffer(...args) }
 function refCStringToString(...args) { return ditto.refCStringToString(...args) }
 function setDeadlockTimeout$1(...args) { return ditto.setDeadlockTimeout(...args) }
-function static_tcp_client_free_handle(...args) { return ditto.static_tcp_client_free_handle(...args) }
-function websocket_client_free_handle(...args) { return ditto.websocket_client_free_handle(...args) }
 function withOutBoxCBytes(...args) { return ditto.withOutBoxCBytes(...args) }
 
 const isWebBuild = false;
@@ -821,7 +809,6 @@ function tryAddSyncSubscription(dittoPointer, query, queryArgsCBOR) {
     const queryBuffer = bytesFromString(query);
     const result = dittoffi_try_add_sync_subscription(dittoPointer, queryBuffer, queryArgsCBOR);
     throwOnErrorResult(result.error, 'dittoffi_try_add_sync_subscription');
-    return;
 }
 /** @internal */
 function tryRemoveSyncSubscription(dittoPointer, query, queryArgsCBOR) {
@@ -829,7 +816,6 @@ function tryRemoveSyncSubscription(dittoPointer, query, queryArgsCBOR) {
     const queryBuffer = bytesFromString(query);
     const result = dittoffi_try_remove_sync_subscription(dittoPointer, queryBuffer, queryArgsCBOR);
     throwOnErrorResult(result.error, 'dittoffi_try_remove_sync_subscription');
-    return;
 }
 // ----------------------------------------------------------- QueryResult ------
 /**
@@ -1017,15 +1003,6 @@ async function writeTransactionRollback(ditto, transaction) {
     if (errorCode !== 0)
         throw new Error(errorMessage() || `ditto_write_transaction_rollback() failed with error code: ${errorCode}`);
 }
-/** @internal */
-function staticTCPClientFreeHandle(self) {
-    static_tcp_client_free_handle(self);
-}
-/** @internal */
-function websocketClientFreeHandle(self) {
-    ensureInitialized();
-    websocket_client_free_handle(self);
-}
 // --------------------------------------------------------------- Logger ------
 /** @internal */
 function loggerInit() {
@@ -1088,11 +1065,22 @@ function loggerSetLogFile(path) {
     const pathBytesOrNull = path ? bytesFromString(path) : null;
     const errorCode = ditto_logger_set_log_file(pathBytesOrNull);
     if (errorCode !== 0) {
-        errorMessage();
-        throw new Error(`Can't set log file, due to error: ${errorMessage}`);
+        const message = errorMessage();
+        throw new Error(`Can't set log file, due to error: ${message}`);
     }
 }
 /** @internal */
+async function loggerTryExportToFileAsync(path) {
+    ensureInitialized();
+    const pathBytes = bytesFromString(path);
+    const result = await new Promise((resolve, reject) => {
+        const wrappedCallback = wrapBackgroundCbForFFI(reject, resolve);
+        dittoffi_logger_try_export_to_file_async(pathBytes, wrappedCallback);
+    });
+    throwOnErrorResult(result.error, 'dittoffi_logger_try_export_to_file_async');
+    return result.success;
+}
+/** @internal */
 function log(level, message) {
     ensureInitialized();
     const messageBuffer = bytesFromString(message);
@@ -1236,6 +1224,12 @@ function setDeadlockTimeout(duration) {
     setDeadlockTimeout$1(duration);
 }
 /** @internal */
+function cryptoGenerateSecureRandomToken() {
+    ensureInitialized();
+    const docIDString = dittoffi_crypto_generate_secure_random_token();
+    return boxCStringIntoString(docIDString);
+}
+/** @internal */
 function dittoRegisterPresenceV1Callback(self, cb) {
     ensureInitialized();
     ditto_register_presence_v1_callback(self, wrapBackgroundCbForFFI((err) => log('Error', `The registered presence callback v1 errored with ${err}`), (cJsonStr) => {
@@ -1531,9 +1525,11 @@ function dittoStopHTTPServer(dittoPointer) {
     return ditto_stop_http_server(dittoPointer);
 }
 /** @internal */
-function dittoRunGarbageCollection(dittoPointer) {
+async function dittoRunGarbageCollection(dittoPointer) {
     ensureInitialized();
-    return ditto_run_garbage_collection(dittoPointer);
+    const statusCode = await ditto_run_garbage_collection(dittoPointer);
+    if (statusCode !== 0)
+        throw new Error(errorMessage() || `ditto_run_garbage_collection() failed with error code: ${statusCode}`);
 }
 /** @internal */
 async function dittoDisableSyncWithV3(dittoPointer) {
@@ -1613,14 +1609,7 @@ onError) {
     return ditto_auth_client_set_validity_listener(ditto, validityUpdateRawCb);
 }
 // ----------------------------------------------------------- Transports ------
-/**
- * We currently don't initialize transports through this function but rather in
- * the NAPI module registration in `transports.c` due to an issue with importing
- * the functions required by this function.
- * See https://github.com/getditto/ditto/issues/10723
- *
- * @internal
- */
+/** @internal */
 function transportsInit() {
     ensureInitialized();
     const { output: wasInitialized, errorType } = withTransportsError(ditto_sdk_transports_init);
@@ -1871,13 +1860,26 @@ const ERROR_CODES = {
     /** Internal error for unexpected system states */
     internal: 'An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.',
     /** Internal error with an unknown error cause */
+    // REFACTOR: May be replaced by `unknown` in v5. Tracked in #12755.
     'internal/unknown-error': 'An unexpected internal error occurred. Please get in touch with Ditto customer service to report this incident.',
     //
     // Errors originating in the SDK
     //
     /** Error when using a feature not supported by the current environment */
+    // REFACTOR: May be replaced by `unsupported` in v5. Tracked in #12755.
     'sdk/unsupported': 'The feature is not supported by the current environment.',
     //
+    // IO errors
+    //
+    /** Error when a file or directory already exists */
+    'io/already-exists': 'A file or directory already exists.',
+    /** Error when a file or directory could not be found */
+    'io/not-found': 'A file or directory could not be found.',
+    /** Error when permission is denied for a file operation */
+    'io/permission-denied': 'The operation failed due to insufficient permissions.',
+    /** Error when an IO operation failed for an unspecified reason. See error message for details. */
+    'io/operation-failed': 'The operation failed.',
+    //
     // Query errors
     //
     /** Error for invalid DQL query arguments. */
@@ -1949,6 +1951,13 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     ActivationLicenseUnsupportedFutureVersion: ['activation/license-token-unsupported-future-version'],
     ActivationNotActivated: ['activation/not-activated'],
     //
+    // Input/output errors
+    //
+    IoAlreadyExists: ['io/already-exists'],
+    IoNotFound: ['io/not-found'],
+    IoPermissionDenied: ['io/permission-denied'],
+    IoOperationFailed: ['io/operation-failed'],
+    //
     // SDK-specific errors
     //
     JsFloatingStoreOperation: ['internal', 'Internal inconsistency, an outstanding store operation was not awaited.'],
@@ -1977,6 +1986,8 @@ const DEFAULT_STATUS_CODE_MAPPING = {
     ValidationInvalidJson: ['validation/invalid-json'],
     ValidationNotAMap: ['validation/not-an-object'],
     ValidationSizeLimitExceeded: ['validation/size-limit-exceeded'],
+    Unsupported: ['sdk/unsupported'],
+    Unknown: ['internal/unknown-error'], // May be updated in v5, c.f. #12755
     default: ['internal/unknown-error'],
 };
 /**
@@ -2222,7 +2233,7 @@ class AttachmentToken {
 
 // NOTE: this is patched up with the actual build version by Jake task
 // build:package and has to be a valid semantic version as defined here: https://semver.org.
-const fullBuildVersionString = '4.7.4';
+const fullBuildVersionString = '4.8.0-rc.2';
 
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
@@ -2253,7 +2264,6 @@ async function init(options = {}) {
             initSDKVersion('Unknown', 'JavaScript', fullBuildVersionString);
             break;
     }
-    loggerInit();
 }
 
 //
@@ -2262,6 +2272,16 @@ async function init(options = {}) {
 /**
  * Class with static methods to customize the logging behavior from Ditto and
  * log messages with the Ditto logging infrastructure.
+ *
+ * Currently, Ditto uses the persistence directory of the Ditto instance that
+ * was most recently created to store a limited amount of logs. Ditto may
+ * continue writing logs to a persistence directory even after the associated
+ * Ditto instance is {@link Ditto.close | closed}. If this is a concern,
+ * consider either disabling logging by setting {@link Logger.enabled} to
+ * `false`, or instantiating a new Ditto instance. After either of these
+ * actions, it is safe to remove the persistence directory. Please refer to
+ * {@link Logger.exportToFile | `exportToFile()`} for further details on locally
+ * collected logs.
  */
 class Logger {
     /**
@@ -2298,7 +2318,13 @@ class Logger {
         var _a;
         this.setLogFile((_a = url === null || url === void 0 ? void 0 : url.pathname) !== null && _a !== void 0 ? _a : null);
     }
-    /** Whether the logger is currently enabled. */
+    /**
+     * Whether the logger is currently enabled.
+     *
+     * Logs exported through {@link exportToFile | exportToFile()} are not
+     * affected by this setting and will also include logs emitted while
+     * {@link enabled} is `false`.
+     */
     static get enabled() {
         return loggerEnabledGet();
     }
@@ -2325,6 +2351,9 @@ class Logger {
      *
      * For example if this is set to `Warning`, then only logs that are logged
      * with the `Warning` or `Error` log levels will be shown.
+     *
+     * Logs exported through {@link exportToFile | exportToFile()} are not
+     * affected by this setting and include all logs at `Debug` level and above.
      */
     static get minimumLogLevel() {
         return loggerMinimumLogLevelGet();
@@ -2353,10 +2382,14 @@ class Logger {
      * unregister any previous callback and stop reporting log entries through
      * callbacks.
      *
+     * @throws {TypeError} if `callback` is not a function or `undefined`.
      * @throws {Error} if called in a React Native environment.
      */
     static async setCustomLogCallback(callback) {
-        if (callback) {
+        if (callback != null && typeof callback !== 'function') {
+            throw new TypeError(`Expected parameter 'callback' to be a function or undefined, but got ${typeof callback}.`);
+        }
+        if (callback != null) {
             await loggerSetCustomLogCb(callback);
             this._customLogCallback = callback;
         }
@@ -2365,6 +2398,65 @@ class Logger {
             delete this._customLogCallback;
         }
     }
+    /**
+     * Exports collected logs to a compressed and JSON-encoded file on the local
+     * file system.
+     *
+     * Ditto's logger locally collects a limited amount of logs at `Debug` level
+     * and above, periodically discarding older logs. This internal logger is
+     * always enabled and works independently of the {@link Logger.enabled}
+     * setting and the configured {@link Logger.minimumLogLevel}. Its logs can be
+     * requested and downloaded from any peer that is active in a Ditto app using
+     * the portal's device dashboard. This method provides an alternative way of
+     * accessing those logs by exporting them to the local file system.
+     *
+     * The logs will be written as a gzip compressed file at the path specified by
+     * the `path` parameter. When uncompressed, the file contains one JSON value
+     * per line with the oldest entry on the first line (JSON lines format).
+     *
+     * Ditto limits the amount of logs it retains on disk to 15 MB and a maximum
+     * age of three days. Older logs are periodically discarded once one of these
+     * limits is reached.
+     *
+     * This method currently only exports logs from the most recently created
+     * Ditto instance, even when multiple instances are running in the same
+     * process.
+     *
+     * Not supported in browser environments.
+     *
+     * @param path The path of the file to write the logs to. The file must not
+     * already exist, and the containing directory must exist. It is recommended
+     * for the `path` to have the `.jsonl.gz` file extension but Ditto won't
+     * enforce it, nor correct it.
+     *
+     * @returns The number of bytes written to the file.
+     *
+     * @throws `TypeError` if `path` is not a string.
+     *
+     * @throws {@link DittoError} `io/*` when the file cannot be written to disk.
+     * Prevent this by ensuring that no file exists at the provided `path`, all
+     * parent directories exists, sufficient permissions are granted, and that the
+     * disk is not full.
+     *
+     * @throws {@link DittoError} `sdk/unsupported` when called in a browser
+     * environment.
+     */
+    static async exportToFile(path) {
+        if (typeof path !== 'string') {
+            throw new TypeError(`Expected parameter 'path' to be a string, but got ${typeof path}.`);
+        }
+        let normalizedPath = path;
+        if (process.platform === 'win32' && !path.startsWith('\\\\?\\')) {
+            if (path.length === 0) {
+                throw new DittoError('io/not-found', 'The path must not be empty.');
+            }
+            // Normalize the path on Windows to prevent issues with long paths.
+            // Windows has a hard limit of 260 characters for paths.
+            // c.f. httpes://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#maximum-path-length-limitation
+            normalizedPath = `\\\\?\\${path}`;
+        }
+        return mapFFIErrorsAsync(() => loggerTryExportToFileAsync(normalizedPath));
+    }
     /**
      * Logs the message for the given `level`.
      *
@@ -3416,8 +3508,8 @@ const CBOR$1 = {
 /** @internal */
 class CBOR {
     /** @internal */
-    static encode(data, replacer) {
-        const arrayBuffer = CBOR$1.encode(data, replacer);
+    static encode(data) {
+        const arrayBuffer = CBOR$1.encode(data);
         return new Uint8Array(arrayBuffer);
     }
     /** @internal */
@@ -3727,8 +3819,6 @@ class Handles {
  * - {@link Ditto}: `Bridge.ditto`
  * - {@link Document}: `Bridge.document`
  * - {@link MutableDocument}: `Bridge.mutableDocument`
- * - {@link StaticTCPClient}: `Bridge.staticTCPClient`
- * - {@link WebsocketClient}: `Bridge.websocketClient`
  *
  * Use `Bridge.<type>.handleFor()` to obtain a handle, which is a wrapper around
  * the raw pointer, and `Bridge.<type>.bridge()` to get or create the matching
@@ -4013,10 +4103,6 @@ Bridge.queryResult = new _a(queryResultFree);
 /** @internal */
 Bridge.queryResultItem = new _a(queryResultItemFree);
 /** @internal */
-Bridge.staticTCPClient = new _a(staticTCPClientFreeHandle);
-/** @internal */
-Bridge.websocketClient = new _a(websocketClientFreeHandle);
-/** @internal */
 Bridge.ditto = new _a(async (dittoPointer) => {
     // HACK: quick and dirty, clear all presence callbacks. This covers presence
     // v1 and v2 callbacks. v3 should be cleared properly by the `Presence`
@@ -4052,9 +4138,7 @@ class Attachment {
      * Returns the attachment's data.
      */
     data() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             {
                 const attachmentHandle = Bridge.attachment.handleFor(this);
                 const attachmentPath = dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref());
@@ -4078,16 +4162,14 @@ class Attachment {
      * @param path The path that the attachment should be copied to.
      */
     copyToPath(path) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             {
                 const attachmentHandle = Bridge.attachment.handleFor(this);
                 const attachmentPath = dittoGetCompleteAttachmentPath(dittoHandle.deref(), attachmentHandle.deref());
                 const fs = require('fs').promises;
                 // If the file already exists, we fail. This is the same behavior as
                 // for the Swift/ObjC SDK.
-                return await fs.copyFile(attachmentPath, path, fs.COPYFILE_EXCL);
+                await fs.copyFile(attachmentPath, path, fs.COPYFILE_EXCL);
             }
         });
     }
@@ -4331,21 +4413,6 @@ function validateQuery(query, options = {}) {
     return validatedQuery;
 }
 // -------------------------------------------------------------- Helpers ------
-/**
- * Generate a random hex-encoded token using the WebCrypto API.
- *
- * @internal */
-function generateEphemeralToken() {
-    let webcrypto = undefined;
-    let data = new Uint16Array(16);
-    // Note: Replacing conditional with polymorphism. (#10731)
-    {
-        webcrypto = require('crypto').webcrypto;
-        webcrypto.getRandomValues(data);
-    }
-    const doublets = Array.from(data);
-    return doublets.map((doublet) => doublet.toString(16)).join('');
-}
 /**
  * Can be used to implement a custom Node.js `inspect` representation for
  * objects that have a `value` property.
@@ -5123,8 +5190,7 @@ class BasePendingCursorOperation {
      */
     async exec() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const query = this.query;
             const documentPointers = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 return await collectionExecQueryStr(dittoHandle.deref(), this.collection.name, null, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset);
@@ -5151,8 +5217,7 @@ class BasePendingCursorOperation {
      */
     async updateWithTransaction(closure, writeTransactionX) {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const query = this.query;
                 const documentsX = await collectionExecQueryStr(dittoHandle.deref(), this.collection.name, writeTransactionX, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset);
@@ -5234,8 +5299,7 @@ class BasePendingIDSpecificOperation {
      */
     async exec() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const readTransactionX = await readTransaction(dittoHandle.deref());
                 const documentX = await collectionGet(dittoHandle.deref(), this.collection.name, this.documentIDCBOR, readTransactionX);
@@ -5286,9 +5350,7 @@ class ConnectionRequest {
     /**
      * Metadata associated with the remote peer.
      *
-     * This is an empty object if the remote peer has not set any metadata, or
-     * when this request is for a WebSocket connection (which does not currently
-     * support peer metadata).
+     * This is an empty object if the remote peer has not set any metadata.
      *
      * Set peer metadata for the local peer using {@link Presence.peerMetadata} or
      * {@link Presence.peerMetadataJSONString}.
@@ -5303,8 +5365,7 @@ class ConnectionRequest {
      * JSON-encoded metadata associated with the remote peer.
      *
      * This is a JSON string representing an empty dictionary if the remote peer
-     * has not set any metadata or when this request is for a WebSocket
-     * connection.
+     * has not set any metadata.
      *
      * Set peer metadata for the local peer using {@link Presence.peerMetadata} or
      * {@link Presence.peerMetadataJSONString}.
@@ -5403,7 +5464,7 @@ class ObserverManager {
             throw new Error(`Internal inconsistency, can't add '${this.id}' observer, observer mananger close()-ed.`);
         }
         this.registerIfNeeded();
-        const token = generateEphemeralToken();
+        const token = cryptoGenerateSecureRandomToken();
         this.callbacksByToken[token] = callback;
         (_a = this.keepAlive) === null || _a === void 0 ? void 0 : _a.retain(`${this.id}.${token}`);
         return token;
@@ -5590,44 +5651,26 @@ class Authenticator {
 class OnlineAuthenticator extends Authenticator {
     async loginWithToken(token, provider) {
         const ditto = this.ditto.deref();
-        if (!ditto) {
-            return;
-        }
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        const dittoPointer = dittoHandle.derefOrNull();
-        if (!dittoPointer) {
+        if (!ditto || ditto.isClosed)
             return;
-        }
-        return ditto.deferCloseAsync(async () => {
-            await dittoAuthClientLoginWithToken(dittoPointer, token, provider);
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLoginWithToken(dittoHandle.deref(), token, provider);
         });
     }
     async loginWithUsernameAndPassword(username, password, provider) {
         const ditto = this.ditto.deref();
-        if (!ditto) {
-            return;
-        }
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        const dittoPointer = dittoHandle.derefOrNull();
-        if (!dittoPointer) {
+        if (!ditto || ditto.isClosed)
             return;
-        }
-        return ditto.deferCloseAsync(async () => {
-            await dittoAuthClientLoginWithUsernameAndPassword(dittoPointer, username, password, provider);
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLoginWithUsernameAndPassword(dittoHandle.deref(), username, password, provider);
         });
     }
     async logout(cleanupFn) {
         const ditto = this.ditto.deref();
-        if (!ditto) {
-            return;
-        }
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        const dittoPointer = dittoHandle.derefOrNull();
-        if (!dittoPointer) {
+        if (!ditto || ditto.isClosed)
             return;
-        }
-        return ditto.deferCloseAsync(async () => {
-            await dittoAuthClientLogout(dittoPointer);
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            await dittoAuthClientLogout(dittoHandle.deref());
             ditto.stopSync();
             cleanupFn === null || cleanupFn === void 0 ? void 0 : cleanupFn(ditto);
         });
@@ -6044,7 +6087,7 @@ class AttachmentFetcher {
         this.ditto = ditto;
         this.token = token;
         this.manager = manager;
-        this.id = generateEphemeralToken();
+        this.id = cryptoGenerateSecureRandomToken();
         const eventHandlerOrNoOp = eventHandler || function () { };
         const dittoHandle = Bridge.ditto.handleFor(ditto);
         this.attachment = new Promise((resolve, reject) => {
@@ -6210,7 +6253,7 @@ class Subscription {
         this.queryArgsCBOR = queryArgsCBOR;
         this.collection = collection;
         this.contextInfo = {
-            id: generateEphemeralToken(),
+            id: cryptoGenerateSecureRandomToken(),
             collectionName: collection.name,
             query,
             queryArgsCBOR,
@@ -6390,19 +6433,14 @@ class LiveQuery {
         let liveQueryID = undefined;
         const signalNext = async () => {
             const ditto = weakDitto.deref();
-            if (!ditto)
-                return;
-            const dittoHandle = Bridge.ditto.handleFor(ditto);
-            const dittoPointer = dittoHandle.derefOrNull();
-            if (!dittoPointer)
+            if (!ditto || ditto.isClosed)
                 return;
-            return ditto.deferCloseAsync(async () => {
-                await liveQuerySignalAvailableNext(dittoPointer, liveQueryID);
+            return ditto.deferCloseAsync(async (dittoHandle) => {
+                await liveQuerySignalAvailableNext(dittoHandle.deref(), liveQueryID);
             });
         };
         const ditto = collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        ditto.deferClose((dittoHandle) => {
             liveQueryID = liveQueryRegister(dittoHandle.deref(), collectionName, query, queryArgsCBOR, this.orderBys, limit, offset, (cCBParams) => {
                 const documents = cCBParams.documents.map((ptr) => Bridge.document.bridge(ptr));
                 let event;
@@ -6427,18 +6465,6 @@ class LiveQuery {
         }
         this._liveQueryID = liveQueryID;
     }
-    /** @internal */
-    async signalNext() {
-        // IDEA: make this public?
-        const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        const dittoPointer = dittoHandle.derefOrNull();
-        if (!dittoPointer)
-            return;
-        return ditto.deferCloseAsync(async () => {
-            await liveQuerySignalAvailableNext(dittoHandle.deref(), this.liveQueryID);
-        });
-    }
 }
 
 //
@@ -6482,8 +6508,7 @@ class PendingCursorOperation extends BasePendingCursorOperation {
     }
     async remove() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const query = this.query;
             const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const writeTransactionX = await writeTransaction(dittoHandle.deref());
@@ -6498,8 +6523,7 @@ class PendingCursorOperation extends BasePendingCursorOperation {
     }
     async evict() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const query = this.query;
             const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const writeTransactionX = await writeTransaction(dittoHandle.deref());
@@ -6514,8 +6538,7 @@ class PendingCursorOperation extends BasePendingCursorOperation {
     }
     async update(closure) {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const writeTransactionX = await writeTransaction(dittoHandle.deref());
                 const results = await super.updateWithTransaction(closure, writeTransactionX);
@@ -6649,8 +6672,7 @@ class PendingCursorOperation extends BasePendingCursorOperation {
 class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     async remove() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const writeTransactionX = await writeTransaction(dittoHandle.deref());
                 const didRemove = await collectionRemove(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR);
@@ -6661,8 +6683,7 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     }
     async evict() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
                 const writeTransactionX = await writeTransaction(dittoHandle.deref());
                 const didEvict = await collectionEvict(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR);
@@ -6673,8 +6694,7 @@ class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     }
     async update(closure) {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const readTransactionX = await readTransaction(dittoHandle.deref());
             const documentX = await collectionGet(dittoHandle.deref(), this.collection.name, this.documentIDCBOR, readTransactionX);
             readTransactionFree(readTransactionX);
@@ -6864,9 +6884,7 @@ class Collection {
         return new PendingIDSpecificOperation(documentID, this);
     }
     async upsert(value, options = {}) {
-        const ditto = this.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return this.store.ditto.deferCloseAsync(async (dittoHandle) => {
             var _a;
             const writeStrategy = (_a = options.writeStrategy) !== null && _a !== void 0 ? _a : 'merge';
             const documentValueJSON = desugarJSObject(value);
@@ -6908,8 +6926,7 @@ class Collection {
      */
     async newAttachment(pathOrData, metadata = {}) {
         const ditto = this.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const { id, len, handle } = await (async () => {
                 if (typeof pathOrData === 'string') {
                     {
@@ -6984,6 +7001,8 @@ class Collection {
  * {@link QueryResultItem} for each match.
  *
  * More info, such as metrics, will be provided in the near future.
+ *
+ * @template T The type of items in the query result.
  */
 class QueryResult {
     /**
@@ -7029,6 +7048,11 @@ class QueryResult {
  *
  * Create a store observer by calling
  * {@link Store.registerObserver | `ditto.store.registerObserver()`}.
+ *
+ * @template T The type of items in query results. This is a convenience type
+ * that is neither inferred from the store observer's
+ * {@link StoreObserver.queryString | query} nor validated against it.
+ * @template S The type of query arguments.
  */
 class StoreObserver {
     /**
@@ -7073,8 +7097,7 @@ class StoreObserver {
             }
         }
         let storeObserverID;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        this.ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const weakThis = new WeakRef(this);
             function wrappedObservationHandler(cCBParams) {
                 const strongThis = weakThis.deref();
@@ -7100,20 +7123,16 @@ class StoreObserver {
     /**
      * Signals to Ditto Core that the observer is ready for the next event.
      */
-    signalNext() {
+    async signalNext() {
         const ditto = this.ditto;
         if (!ditto || ditto.isClosed)
             return;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        const dittoPointer = dittoHandle.derefOrNull();
-        if (!dittoPointer)
-            return;
         if (this.liveQueryID == null) {
             throw new Error('live query ID is null while signaling ready for next event');
         }
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             Logger.debug(`Signaling availability for live query ${this.liveQueryID}`);
-            await liveQuerySignalAvailableNext(dittoPointer, this.liveQueryID);
+            await liveQuerySignalAvailableNext(dittoHandle.deref(), this.liveQueryID);
         });
     }
 }
@@ -7386,8 +7405,7 @@ class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation
     }
     async remove() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const query = this.query;
             const transaction = this.collection.writeTransaction;
             const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => collectionRemoveQueryStr(dittoHandle.deref(), this.collection.name, transaction.writeTransactionPointer, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset));
@@ -7402,8 +7420,7 @@ class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation
     }
     async evict() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const query = this.query;
             const transaction = this.collection.writeTransaction;
             const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => collectionEvictQueryStr(dittoHandle.deref(), this.collection.name, transaction.writeTransactionPointer, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset));
@@ -7437,8 +7454,7 @@ class WriteTransactionPendingCursorOperation extends BasePendingCursorOperation
 class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOperation {
     async remove() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const transaction = this.collection.writeTransaction;
             const result = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => collectionRemove(dittoHandle.deref(), this.collection.name, transaction.writeTransactionPointer, this.documentIDCBOR));
             transaction.addResult('removed', this.documentID, this.collection.name);
@@ -7447,8 +7463,7 @@ class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOp
     }
     async evict() {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const transaction = this.collection.writeTransaction;
             const result = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => await collectionEvict(dittoHandle.deref(), this.collection.name, transaction.writeTransactionPointer, this.documentIDCBOR));
             transaction.addResult('evicted', this.documentID, this.collection.name);
@@ -7457,8 +7472,7 @@ class WriteTransactionPendingIDSpecificOperation extends BasePendingIDSpecificOp
     }
     async update(closure) {
         const ditto = this.collection.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             const transaction = this.collection.writeTransaction;
             const readTransactionX = await readTransaction(dittoHandle.deref());
             const documentX = await collectionGet(dittoHandle.deref(), this.collection.name, this.documentIDCBOR, readTransactionX);
@@ -7531,8 +7545,7 @@ class WriteTransactionCollection {
     }
     async upsert(value, options = {}) {
         const ditto = this.store.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
             var _a;
             const writeStrategy = (_a = options.writeStrategy) !== null && _a !== void 0 ? _a : 'merge';
             const documentValueJSON = desugarJSObject(value);
@@ -7574,22 +7587,6 @@ class WriteTransactionCollection {
  * Create a write transaction using {@link Store.write | ditto.store.write}.
  */
 class WriteTransaction {
-    /**
-     * Initialise a write transaction given a Ditto instance.
-     *
-     * This is not implemented as a constructor in order to be able to use FFI
-     * async functions. Users start transactions through {@link Store.write}.
-     *
-     * @param ditto an instance of Ditto
-     * @internal
-     */
-    static async init(ditto) {
-        return ditto.deferCloseAsync(async () => {
-            const dittoHandle = Bridge.ditto.handleFor(ditto);
-            const writeTransactionPointer = await writeTransaction(dittoHandle.deref());
-            return new WriteTransaction(ditto, writeTransactionPointer);
-        });
-    }
     /**
      * Creates a transaction-specific
      * {@link WriteTransactionCollection | collection} object that will ensure
@@ -7604,20 +7601,36 @@ class WriteTransaction {
         }
         return new WriteTransactionCollection(toCollectionNamed, this.ditto.store, this);
     }
-    // ----------------------------------------------------------- Internal ------
+    /** @internal */
+    constructor(ditto, cTransaction) {
+        this.writeTransactionPointer = cTransaction;
+        this.ditto = ditto;
+        this.results = [];
+    }
+    /**
+     * Initialise a write transaction given a Ditto instance.
+     *
+     * This is not implemented as a constructor in order to be able to use FFI
+     * async functions. Users start transactions through {@link Store.write}.
+     *
+     * @param ditto an instance of Ditto
+     * @internal
+     */
+    static async init(ditto) {
+        return ditto.deferCloseAsync(async (dittoHandle) => {
+            const writeTransactionPointer = await writeTransaction(dittoHandle.deref());
+            return new WriteTransaction(ditto, writeTransactionPointer);
+        });
+    }
     /** @internal */
     async commit() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             return writeTransactionCommit(dittoHandle.deref(), this.writeTransactionPointer);
         });
     }
     /** @internal */
     async rollback() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             return writeTransactionRollback(dittoHandle.deref(), this.writeTransactionPointer);
         });
     }
@@ -7625,7 +7638,8 @@ class WriteTransaction {
      * Adds an entry to the list of results that is returned at the end of a
      * transaction.
      *
-     * @internal */
+     * @internal
+     */
     addResult(type, docID, collectionName) {
         this.results.push({
             type,
@@ -7633,12 +7647,6 @@ class WriteTransaction {
             collectionName,
         });
     }
-    /** @internal */
-    constructor(ditto, cTransaction) {
-        this.writeTransactionPointer = cTransaction;
-        this.ditto = ditto;
-        this.results = [];
-    }
 }
 
 //
@@ -7662,14 +7670,18 @@ class Store {
      * triggered automatically instead of having to call the passed in
      * `signalNext` function.
      *
-     * @param query a string containing a valid query expressed in DQL.
-     * @param observationHandler a function that is called whenever the query's results
-     * change. The function is passed a {@link QueryResult} containing a
+     * @param query A string containing a valid query expressed in DQL.
+     * @param observationHandler A function that is called whenever the query's
+     * results change. The function is passed a {@link QueryResult} containing a
      * {@link QueryResultItem} for each match.
-     * @param queryArguments an object of values keyed by the placeholder name
+     * @param queryArguments An object of values keyed by the placeholder name
      * without the leading `:`. Example: `{ "name": "Joanna" }` for a query like
      * `SELECT * FROM people WHERE name = :name`.
-     * @returns a {@link StoreObserver} that can be used to cancel the
+     * @template T The type of items returned by the query. This is a convenience
+     * type that is neither inferred from the `query` parameter nor validated
+     * against it.
+     * @template U The type of the query arguments.
+     * @returns A {@link StoreObserver} that can be used to cancel the
      * observation.
      * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
      * string or not valid DQL.
@@ -7706,14 +7718,18 @@ class Store {
      * The first invocation of `observationHandler` will always happen after this
      * method has returned.
      *
-     * @param query a string containing a valid query expressed in DQL.
-     * @param observationHandler an observation handler function that is called
+     * @param query A string containing a valid query expressed in DQL.
+     * @param observationHandler An observation handler function that is called
      * whenever the query's results change. The function is passed a
      * {@link QueryResult} containing a {@link QueryResultItem} for each match.
-     * @param queryArguments an object of values keyed by the placeholder name
+     * @param queryArguments An object of values keyed by the placeholder name
      * without the leading `:`. Example: `{ "name": "Joanna" }` for a query like
      * `SELECT * FROM people WHERE name = :name`.
-     * @returns a {@link StoreObserver} that can be used to cancel the
+     * @template T The type of items returned by the query. This is a convenience
+     * type that is neither inferred from the `query` parameter nor validated
+     * against it.
+     * @template U The type of the query arguments
+     * @returns A {@link StoreObserver} that can be used to cancel the
      * observation.
      * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
      * string or not valid DQL.
@@ -7736,8 +7752,7 @@ class Store {
         // If we would await the call here, we could end up in a situation where
         // the first callback to the event handler is emitted before we return from
         // the method call that started the observer.
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        void this.ditto.deferCloseAsync(async () => {
+        void this.ditto.deferCloseAsync(async (dittoHandle) => {
             return new Promise((resolve) => {
                 void step(async () => {
                     try {
@@ -7783,20 +7798,28 @@ class Store {
      * related {@link Ditto} instance.
      */
     collectionNames() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return mapFFIErrors(() => dittoGetCollectionNames(dittoHandle.deref()));
         });
     }
     /**
      * Executes a DQL query and returns matching items as a query result.
      *
-     * @param query a string containing a valid query expressed in DQL.
-     * @param queryArguments an object of values keyed by the placeholder name
+     * **Note:** only returns results from the local store without waiting for any
+     * {@link SyncSubscription | sync subscriptions} to have caught up with the
+     * latest changes. Only use this method if your program must proceed with
+     * immediate results. Use a {@link StoreObserver | store observer} to receive
+     * updates to query results as soon as they have been synced to this peer.
+     *
+     * @param query A string containing a valid query expressed in DQL.
+     * @param queryArguments An object of values keyed by the placeholder name
      * without the leading `:`. Example: `{ "name": "John" }` for a query like
      * `SELECT * FROM people WHERE name = :name`.
-     * @returns a promise for a {@link QueryResult} containing a
+     * @template T The type of items returned by the query. This is a convenience
+     * type that is neither inferred from the `query` parameter nor validated
+     * against it.
+     * @template U The type of the query arguments
+     * @returns A promise for a {@link QueryResult} containing a
      * {@link QueryResultItem} for each match.
      * @throws {@link DittoError} `query/invalid`: if `query` argument is not a
      * string or not valid DQL.
@@ -7808,8 +7831,7 @@ class Store {
         if (typeof query !== 'string') {
             throw new DittoError('query/invalid', `Expected parameter 'query' to be of type 'string', found: ${typeof query}`);
         }
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             // A one-off query execution uses a transaction internally but a
             // transaction API is not implemented yet.
             const writeTransaction = null;
@@ -7914,12 +7936,10 @@ class Store {
      * attachment from a file path in a web browser.
      */
     async newAttachment(pathOrData, metadata) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
         if (metadata != null) {
             validateAttachmentMetadata(metadata);
         }
-        return ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             //
             // Create inputs for the attachment token from either a file path or raw data.
             //
@@ -7942,7 +7962,8 @@ class Store {
             })();
             const attachmentTokenJSON = { _id: id, _len: len, _meta: { ...metadata }, [DittoCRDTTypeKey]: DittoCRDTType.attachment };
             const attachmentToken = new AttachmentToken(attachmentTokenJSON);
-            const attachment = new Attachment(ditto, attachmentToken);
+            // this.ditto is safe to use because we are inside a deferCloseAsync block
+            const attachment = new Attachment(this.ditto, attachmentToken);
             return Bridge.attachment.bridge(handle, () => attachment);
         });
     }
@@ -8015,9 +8036,8 @@ class Store {
         else {
             attachmentToken = new AttachmentToken(token);
         }
-        const ditto = this.ditto;
-        return ditto.deferClose(() => {
-            const attachmentFetcher = new AttachmentFetcher(ditto, attachmentToken, null, eventHandler);
+        return this.ditto.deferClose(() => {
+            const attachmentFetcher = new AttachmentFetcher(this.ditto, attachmentToken, null, eventHandler);
             // @ts-expect-error modifying readonly property
             // eslint-disable-next-line @typescript-eslint/no-floating-promises
             this.attachmentFetchers = Object.freeze([...this.attachmentFetchers, attachmentFetcher]);
@@ -8035,6 +8055,7 @@ class Store {
          * observer and {@link StoreObserver.cancel | StoreObserver.cancel()} to
          * remove an existing store observer.
          */
+        // The type parameters are defined as `any` to avoid recursive type inference.
         this.observers = Object.freeze([]);
         /**
          * All currently active attachment fetchers.
@@ -8074,9 +8095,8 @@ class Store {
                 throw new DittoError('query/arguments-invalid', `Invalid query arguments: ${error.message}`);
             }
         }
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
         // prettier-ignore
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             const webhookIDCBOR = await mapFFIErrorsAsync(async () => await tryRegisterStoreObserverWebhook(dittoHandle.deref(), query, queryArgumentsCBOR, url));
             return new DocumentID(webhookIDCBOR, true);
         });
@@ -8169,9 +8189,7 @@ class Store {
      * @internal
      */
     async registerLiveQueryWebhook(collectionName, query, url) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             const validatedQuery = validateQuery(query);
             const idCBOR = await liveQueryWebhookRegister(dittoHandle.deref(), collectionName, validatedQuery, [], 0, 0, url);
             return new DocumentID(idCBOR, true);
@@ -8260,9 +8278,7 @@ class Presence {
      * connections between them.
      */
     get graph() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             const graphJSONString = dittoPresenceV3(dittoHandle.deref());
             return JSON.parse(graphJSONString);
         });
@@ -8273,16 +8289,13 @@ class Presence {
      * and when evaluating connection requests using
      * {@link connectionRequestHandler | connectionRequestHandler()}.
      *
-     * This is not made available to peers only connected via WebSocket.
-     *
      * Uses UTF-8 encoding.
      *
      * @see {@link peerMetadata | peerMetadata()} for a convenience property that
      * provides access to parsed metadata.
      */
     get peerMetadataJSONString() {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return mapFFIErrors(() => {
                 return presencePeerMetadataJSON(dittoHandle.deref());
             });
@@ -8293,7 +8306,7 @@ class Presence {
      *
      * The metadata must not exceed 4 KB in size when JSON-encoded.
      *
-     * @param {string} jsonString: JSON-encoded metadata.
+     * @param {string} jsonString JSON-encoded metadata.
      *
      * @throws {@link DittoError} `validation/invalid-json`: if `jsonString` does
      * not contain valid JSON.
@@ -8308,8 +8321,7 @@ class Presence {
      * on usage of metadata.
      */
     async setPeerMetadataJSONString(jsonString) {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        await this.ditto.deferCloseAsync(async () => {
+        await this.ditto.deferCloseAsync(async (dittoHandle) => {
             return mapFFIErrorsAsync(async () => {
                 return presenceTrySetPeerMetadataJSON(dittoHandle.deref(), jsonString);
             });
@@ -8377,16 +8389,12 @@ class Presence {
         this.observerManager = new ObserverManager('PresenceObservation', {
             keepAlive: ditto.keepAlive,
             register: (callback) => {
-                const ditto = this.ditto;
-                const dittoHandle = Bridge.ditto.handleFor(ditto);
-                ditto.deferClose(() => {
+                this.ditto.deferClose((dittoHandle) => {
                     dittoRegisterPresenceV3Callback(dittoHandle.deref(), callback);
                 });
             },
             unregister: () => {
-                const ditto = this.ditto;
-                const dittoHandle = Bridge.ditto.handleFor(ditto);
-                void ditto.deferCloseAsync(async () => {
+                void ditto.deferCloseAsync(async (dittoHandle) => {
                     return dittoClearPresenceV3Callback(dittoHandle.deref());
                 });
             },
@@ -8416,8 +8424,6 @@ class LiveQueryManager {
     }
     /** @internal */
     startLiveQuery(liveQuery) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
         // REFACTOR: the starting closure runs detached from here which is a smell.
         // Can we make this whole starting mechanism non-async? The culprit is
         // the workaround for a zalgo with `ditto_live_query_start()` FFI function:
@@ -8426,7 +8432,7 @@ class LiveQueryManager {
         // (by definition). This is a classic zalgo case. Fix by making
         // `ditto_live_query_start()` trigger the first live query callback `async`,
         // just like the subsequent ones.
-        void this.ditto.deferCloseAsync(async () => {
+        void this.ditto.deferCloseAsync(async (dittoHandle) => {
             const liveQueryID = liveQuery.liveQueryID;
             if (!liveQueryID) {
                 throw new Error("Internal inconsistency, tried to add a live query that doesn't have a live query ID (probably stopped).");
@@ -8439,7 +8445,7 @@ class LiveQueryManager {
             this.liveQueriesByID[liveQueryID] = weakLiveQuery;
             this.finalizationRegistry.register(liveQuery, liveQueryID, this.finalize);
             liveQuery.liveQueryManager = this;
-            ditto.keepAlive.retain(`LiveQuery.${liveQueryID}`);
+            this.ditto.keepAlive.retain(`LiveQuery.${liveQueryID}`);
             return new Promise((resolve, reject) => {
                 // not awaited on purpose; let the invocation of the initial observation
                 // happen in a "fire-and-forget" / detached / escaping fashion, to be
@@ -8472,9 +8478,7 @@ class LiveQueryManager {
         }
     }
     stopLiveQueryWithID(liveQueryID) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             liveQueryStop(dittoHandle.deref(), liveQueryID);
             this.keepAlive.release(`LiveQuery.${liveQueryID}`);
             delete this.liveQueriesByID[liveQueryID];
@@ -8508,7 +8512,7 @@ class PresenceManager {
             throw new Error(`Internal inconsistency, can't add presence observer, observer mananger close()-ed.`);
         }
         this.registerIfNeeded();
-        const token = generateEphemeralToken();
+        const token = cryptoGenerateSecureRandomToken();
         this.callbacksByPresenceToken[token] = callback;
         this.ditto.keepAlive.retain(`PresenceObservation.${token}`);
         // REFACTOR: make the initial callback call async, too (othewise we'd be
@@ -8553,9 +8557,7 @@ class PresenceManager {
         return Object.keys(this.callbacksByPresenceToken).length > 0;
     }
     registerIfNeeded() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const needsToRegister = !this.isRegistered;
             if (needsToRegister) {
                 this.isRegistered = true;
@@ -8566,9 +8568,7 @@ class PresenceManager {
         });
     }
     unregisterIfNeeded() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             const needsToUnregister = !this.hasObservers() && this.isRegistered;
             if (needsToUnregister) {
                 this.isRegistered = false;
@@ -8631,16 +8631,12 @@ class TransportConditionsManager extends ObserverManager {
         this.ditto = ditto;
     }
     register(callback) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoRegisterTransportConditionChangedCallback(dittoHandle.deref(), callback);
         });
     }
     unregister() {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        return ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoRegisterTransportConditionChangedCallback(dittoHandle.deref(), null);
         });
     }
@@ -8723,6 +8719,8 @@ class TransportConditionsManager extends ObserverManager {
  *
  * Create a sync subscription by calling
  * {@link Sync.registerSubscription | `ditto.sync.registerSubscription()`}.
+ *
+ * @template T The type of query arguments passed to the sync subscription.
  */
 class SyncSubscription {
     /**
@@ -8782,6 +8780,7 @@ class Sync {
      * @param query a string containing a valid query expressed in DQL.
      * @param queryArguments an object containing the arguments for the query.
      * Example: `{mileage: 123}` for a query with `:mileage` placeholder.
+     * @template T The type of the query arguments.
      * @returns An active `SyncSubscription` for the passed in query and
      * arguments. It will remain active until it is
      * {@link SyncSubscription.cancel | cancelled} or the {@link Ditto} instance
@@ -8808,8 +8807,7 @@ class Sync {
                 throw new DittoError('query/arguments-invalid', `Unable to encode query arguments: ${error.message}`);
             }
         }
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        this.ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             mapFFIErrors(() => tryAddSyncSubscription(dittoHandle.deref(), query, queryArgumentsCBOR));
         });
         const subscription = new SyncSubscription(this.ditto, query, queryArguments || null, queryArgumentsCBOR);
@@ -8877,8 +8875,7 @@ class Sync {
         newSyncSubscriptions.splice(indexToDelete, 1);
         // @ts-expect-error modifying readonly property
         this.subscriptions = Object.freeze(newSyncSubscriptions);
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        this.ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             // prettier-ignore
             mapFFIErrors(() => tryRemoveSyncSubscription(dittoHandle.deref(), syncSubscription.queryString, syncSubscription.queryArgumentsCBOR));
         });
@@ -8917,9 +8914,7 @@ class Sync {
         // already be cleaned up properly.
     }
     updatePeerToPeerBluetoothLE(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const bluetoothLEOld = stateOld.effectiveTransportConfig.peerToPeer.bluetoothLE;
             const bluetoothLENew = stateNew.effectiveTransportConfig.peerToPeer.bluetoothLE;
             const shouldStart = !bluetoothLEOld.isEnabled && bluetoothLENew.isEnabled;
@@ -8958,9 +8953,7 @@ class Sync {
         });
     }
     updatePeerToPeerAWDL(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const awdlOld = stateOld.effectiveTransportConfig.peerToPeer.awdl;
             const awdlNew = stateNew.effectiveTransportConfig.peerToPeer.awdl;
             const shouldStart = !awdlOld.isEnabled && awdlNew.isEnabled;
@@ -8980,9 +8973,7 @@ class Sync {
         });
     }
     updatePeerToPeerLAN(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const lanOld = stateOld.effectiveTransportConfig.peerToPeer.lan;
             const lanNew = stateNew.effectiveTransportConfig.peerToPeer.lan;
             // HACK: quick & dirty Linux & Windows hack. A proper implementation
@@ -9041,9 +9032,7 @@ class Sync {
         });
     }
     updateListenTCP(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const tcpOld = stateOld.effectiveTransportConfig.listen.tcp;
             const tcpNew = stateNew.effectiveTransportConfig.listen.tcp;
             if (TransportConfig.areListenTCPsEqual(tcpNew, tcpOld))
@@ -9055,9 +9044,7 @@ class Sync {
         });
     }
     updateListenHTTP(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const httpOld = stateOld.effectiveTransportConfig.listen.http;
             const httpNew = stateNew.effectiveTransportConfig.listen.http;
             if (TransportConfig.areListenHTTPsEqual(httpOld, httpNew))
@@ -9072,35 +9059,27 @@ class Sync {
         });
     }
     updateConnectTCPServers(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const tcpServers = stateNew.effectiveTransportConfig.connect.tcpServers;
             dittoSetStaticTCPClients(dittoHandle.deref(), tcpServers);
         });
     }
     updateConnectWebsocketURLs(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             const websocketURLs = stateNew.effectiveTransportConfig.connect.websocketURLs;
             const routingHint = stateNew.effectiveTransportConfig.global.routingHint;
             dittoSetStaticWebsocketClients(dittoHandle.deref(), websocketURLs, routingHint);
         });
     }
     updateGlobal(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             if (stateOld.effectiveTransportConfig.global.syncGroup !== stateNew.effectiveTransportConfig.global.syncGroup) {
                 dittoSetSyncGroup(dittoHandle.deref(), stateNew.effectiveTransportConfig.global.syncGroup);
             }
         });
     }
     updateConnectRetryInterval(stateOld, stateNew) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             dittoSetConnectRetryInterval(dittoHandle.deref(), stateNew.effectiveTransportConfig.connect.retryInterval);
         });
     }
@@ -9173,8 +9152,7 @@ function stateFrom(parameters) {
  * @private
  */
 function validateEnabledTransportsAvailable(ditto, transportConfig) {
-    const dittoHandle = Bridge.ditto.handleFor(ditto);
-    return ditto.deferClose(() => {
+    return ditto.deferClose((dittoHandle) => {
         // - BLE
         // - AWDL
         // - LAN / mDNS
@@ -9230,10 +9208,8 @@ class SubscriptionManager {
      * @internal
      */
     add(subscription) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
         const contextInfo = subscription.contextInfo;
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             this.subscriptions[contextInfo.id] = new WeakRef(subscription);
             this.finalizationRegistry.register(subscription, subscription.contextInfo, subscription);
             addSubscription(dittoHandle.deref(), contextInfo.collectionName, contextInfo.query, contextInfo.queryArgsCBOR, contextInfo.orderBys, contextInfo.limit, contextInfo.offset);
@@ -9271,9 +9247,7 @@ class SubscriptionManager {
      * @internal
      */
     removeWithContextInfo(contextInfo) {
-        const ditto = this.ditto;
-        const dittoHandle = Bridge.ditto.handleFor(ditto);
-        ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             delete this.subscriptions[contextInfo.id];
             removeSubscription(dittoHandle.deref(), contextInfo.collectionName, contextInfo.query, contextInfo.queryArgsCBOR, contextInfo.orderBys, contextInfo.limit, contextInfo.offset);
         });
@@ -9373,8 +9347,7 @@ class AttachmentFetcherManager {
      * registry.
      */
     stopWithContextInfo(contextInfo) {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             // Remove the manager's own record of the context info.
             if (this.contextInfoByID[contextInfo.id] == null) {
                 throw new Error(`Internal inconsistency: attachment fetcher ${contextInfo.id} not found in active attachment fetchers.`);
@@ -9407,7 +9380,7 @@ class AttachmentFetcherManager {
 class SmallPeerInfo {
     /**
      * Indicates whether small peer info collection is currently enabled, defaults
-     * to `false`.
+     * to `true`.
      *
      * **Note**: whether the background ingestion process is enabled or not is a
      * separate decision to whether this information is allowed to sync to other
@@ -9416,8 +9389,7 @@ class SmallPeerInfo {
      * {@link setSyncScope | setSyncScope()}.
      */
     get isEnabled() {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoSmallPeerInfoGetIsEnabled(dittoHandle.deref());
         });
     }
@@ -9430,8 +9402,7 @@ class SmallPeerInfo {
         if (typeof newValue !== 'boolean') {
             throw new TypeError(`Expected boolean, got ${typeof newValue}`);
         }
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        void this.ditto.deferCloseAsync(async () => {
+        void this.ditto.deferCloseAsync(async (dittoHandle) => {
             return dittoSmallPeerInfoSetEnabled(dittoHandle.deref(), newValue);
         });
     }
@@ -9473,8 +9444,7 @@ class SmallPeerInfo {
      * The metadata associated with the small peer info, as a JSON string.
      */
     get metadataJSONString() {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferClose(() => {
+        return this.ditto.deferClose((dittoHandle) => {
             return dittoSmallPeerInfoGetMetadata(dittoHandle.deref());
         });
     }
@@ -9490,8 +9460,7 @@ class SmallPeerInfo {
         if (typeof metadata !== 'string') {
             throw new TypeError(`Expected string, got ${typeof metadata}`);
         }
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        this.ditto.deferClose(() => {
+        this.ditto.deferClose((dittoHandle) => {
             // throws if any validation errors occur
             dittoSmallPeerInfoSetMetadata(dittoHandle.deref(), metadata);
         });
@@ -9504,8 +9473,7 @@ class SmallPeerInfo {
      * `BigPeerOnly` to replicate collected info to the Big Peer.
      */
     async getSyncScope() {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             return dittoSmallPeerInfoGetSyncScope(dittoHandle.deref());
         });
     }
@@ -9518,8 +9486,7 @@ class SmallPeerInfo {
      * @throws when set to a value other than `BigPeerOnly` or `LocalPeerOnly`.
      */
     async setSyncScope(syncScope) {
-        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
-        return this.ditto.deferCloseAsync(async () => {
+        return this.ditto.deferCloseAsync(async (dittoHandle) => {
             return dittoSmallPeerInfoSetSyncScope(dittoHandle.deref(), syncScope);
         });
     }
@@ -9570,8 +9537,7 @@ class Ditto {
     }
     /** Returns a string identifying the version of the Ditto SDK. */
     get sdkVersion() {
-        const dittoHandle = Bridge.ditto.handleFor(this);
-        return this.deferClose(() => {
+        return this.deferClose((dittoHandle) => {
             return dittoGetSDKVersion(dittoHandle.deref());
         });
     }
@@ -9644,6 +9610,7 @@ class Ditto {
         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.');
         }
+        loggerInit();
         this.persistenceDirectory = Ditto.initPersistenceDirectory(persistenceDirectory);
         const identityOrDefault = identity !== null && identity !== void 0 ? identity : { type: 'offlinePlayground', appID: '' };
         const validIdentity = Object.freeze(this.validateIdentity(identityOrDefault));
@@ -9957,8 +9924,7 @@ class Ditto {
         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(() => {
+        this.deferClose((dittoHandle) => {
             dittoSmallPeerInfoCollectionSetTransportConfigData(dittoHandle.deref(), configCBOR);
         });
     }
@@ -9982,6 +9948,10 @@ class Ditto {
      * customized with {@link updateTransportConfig | updateTransportConfig()}
      * or replaced entirely with {@link setTransportConfig | setTransportConfig()}.
      *
+     * Performance of initial sync when bootstrapping new peers can be improved by
+     * calling {@link disableSyncWithV3 | disableSyncWithV3()} before
+     * {@link startSync | 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).
@@ -10041,11 +10011,11 @@ class Ditto {
         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.
+     * 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
@@ -10053,28 +10023,31 @@ class Ditto {
      * 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.
+     * This method does not have any effect when running Ditto in a browser.
      */
-    runGarbageCollection() {
-        const dittoHandle = Bridge.ditto.handleFor(this);
-        return this.deferClose(() => {
-            dittoRunGarbageCollection(dittoHandle.deref());
+    async runGarbageCollection() {
+        return this.deferCloseAsync(async (dittoHandle) => {
+            return 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.
+     * 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.
      *
-     * 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.
+     * 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.
      *
      * @throws {Error} if called in a React Native environment.
      */
     async disableSyncWithV3() {
-        const dittoHandle = Bridge.ditto.handleFor(this);
-        return this.deferCloseAsync(async () => {
+        return this.deferCloseAsync(async (dittoHandle) => {
             await dittoDisableSyncWithV3(dittoHandle.deref());
         });
     }
@@ -10127,15 +10100,20 @@ class Ditto {
      * Makes sure that the closure is executed only if the Ditto instance hasn't
      * been closed yet.
      *
+     * The closure is given a {@link Handle | handle} to the Ditto instance that
+     * is valid while the closure is executing.
+     *
      * @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 */
+     * @internal
+     */
     deferClose(closure) {
         if (!this.deferCloseAllowed) {
             throw new Error(`Can't perform operation using a Ditto instance that has been closed.`);
         }
-        return closure();
+        const dittoHandle = Bridge.ditto.handleFor(this);
+        return closure(dittoHandle);
     }
     /**
      * Makes sure that the closure is executed to completion before the Ditto
@@ -10144,15 +10122,20 @@ class Ditto {
      * Any calls to {@link close | `Ditto.close()`} will wait until the closure
      * has completed before closing the Ditto instance.
      *
+     * The closure is given a {@link Handle | handle} to the Ditto instance that
+     * is valid while the closure is executing.
+     *
      * @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 */
+     * @internal
+     */
     async deferCloseAsync(closure) {
         if (!this.deferCloseAllowed) {
             throw new Error(`Can't perform operation using a Ditto instance that has been closed.`);
         }
-        const pendingOperation = closure();
+        const dittoHandle = Bridge.ditto.handleFor(this);
+        const pendingOperation = closure(dittoHandle);
         this.pendingOperations.add(pendingOperation);
         let result;
         try {
@@ -10214,8 +10197,7 @@ class Ditto {
         return validIdentity;
     }
     setSyncActive(flag) {
-        const dittoHandle = Bridge.ditto.handleFor(this);
-        this.deferClose(() => {
+        this.deferClose((dittoHandle) => {
             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.');
             }
@@ -10235,8 +10217,7 @@ class Ditto {
         });
     }
     makeDefaultTransportConfig() {
-        const dittoHandle = Bridge.ditto.handleFor(this);
-        return this.deferClose(() => {
+        return this.deferClose((dittoHandle) => {
             const transportConfig = new TransportConfig();
             if (transportsBLEIsAvailable(dittoHandle.deref())) {
                 transportConfig.peerToPeer.bluetoothLE.isEnabled = true;
@@ -10349,12 +10330,14 @@ const CUSTOM_INSPECT_SYMBOL = Symbol.for('nodejs.util.inspect.custom');
  * It’s a reference type serving as a “cursor”, allowing for efficient access of
  * the underlying data in various formats.
  *
- * The {@link QueryResultItem.value | value } property is lazily
- * materialized and kept in memory until it goes out of scope. To reduce the
- * memory footprint, structure your code such that items can be processed as a
- * stream, i.e. one by one (or in batches) and
- * {@link QueryResultItem.dematerialize | dematerialize() } them
- * right after use.
+ * The {@link QueryResultItem.value | value } property is lazily materialized
+ * and kept in memory until it goes out of scope. To reduce the memory
+ * footprint, structure your code such that items can be processed as a stream,
+ * i.e. one by one (or in batches) and
+ * {@link QueryResultItem.dematerialize | dematerialize() } them right after
+ * use.
+ *
+ * @template T The type of the item's {@link QueryResultItem.value | value }.
  */
 class QueryResultItem {
     /**
@@ -10474,22 +10457,6 @@ function getBridgeLoad() {
     return countsByType;
 }
 
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-// HACK: don't export these publicly, only needed internally.
-/** @internal */
-class StaticTCPClient {
-}
-
-//
-// Copyright © 2021 DittoLive Incorporated. All rights reserved.
-//
-// HACK: don't export these publicly, only needed internally.
-/** @internal */
-class WebsocketClient {
-}
-
 //
 // Copyright © 2021 DittoLive Incorporated. All rights reserved.
 //
@@ -10505,8 +10472,6 @@ Bridge.document.registerType(Document);
 Bridge.queryResultItem.registerType(QueryResultItem);
 Bridge.queryResult.registerType(QueryResult);
 Bridge.mutableDocument.registerType(MutableDocument);
-Bridge.staticTCPClient.registerType(StaticTCPClient);
-Bridge.websocketClient.registerType(WebsocketClient);
 Bridge.ditto.registerType(Ditto);
 
 exports.Attachment = Attachment;