@dittolive/ditto 4.1.0 → 4.2.0

package/README.md

@@ -3,10 +3,10 @@
 *Ditto is a cross platform SDK that allows mobile, web, and IoT apps to sync
 with and even without connectivity.*
 
-Version: **4.1.0**
+Version: **4.2.0**
 
 Please visit [ditto.live](https://ditto.live) for more info as well as the
-[API Reference](https://software.ditto.live/js/Ditto/4.1.0/api-reference/) for this particular version.
+[API Reference](https://software.ditto.live/js/Ditto/4.2.0/api-reference/) for this particular version.
 
 --------------------------------------------------------------------------------
 

package/node/ditto.cjs.js

@@ -289,9 +289,7 @@ function ditto_add_internal_ble_server_transport(...args) { return ditto.ditto_a
 function ditto_add_internal_mdns_client_transport(...args) { return ditto.ditto_add_internal_mdns_client_transport(...args) }
 function ditto_add_internal_mdns_server_transport(...args) { return ditto.ditto_add_internal_mdns_server_transport(...args) }
 function ditto_add_multicast_transport(...args) { return ditto.ditto_add_multicast_transport(...args) }
-function ditto_add_static_tcp_client(...args) { return ditto.ditto_add_static_tcp_client(...args) }
 function ditto_add_subscription(...args) { return ditto.ditto_add_subscription(...args) }
-function ditto_add_websocket_client(...args) { return ditto.ditto_add_websocket_client(...args) }
 function ditto_auth_client_get_site_id(...args) { return ditto.ditto_auth_client_get_site_id(...args) }
 function ditto_auth_client_is_web_valid(...args) { return ditto.ditto_auth_client_is_web_valid(...args) }
 function ditto_auth_client_is_x509_valid(...args) { return ditto.ditto_auth_client_is_x509_valid(...args) }
@@ -326,7 +324,9 @@ function ditto_document_set_cbor_with_timestamp(...args) { return ditto.ditto_do
 function ditto_documents_hash(...args) { return ditto.ditto_documents_hash(...args) }
 function ditto_documents_hash_mnemonic(...args) { return ditto.ditto_documents_hash_mnemonic(...args) }
 function ditto_error_message(...args) { return ditto.ditto_error_message(...args) }
+function ditto_experimental_add_dql_subscription(...args) { return ditto.ditto_experimental_add_dql_subscription(...args) }
 function ditto_experimental_exec_query_str(...args) { return ditto.ditto_experimental_exec_query_str(...args) }
+function ditto_experimental_remove_dql_subscription(...args) { return ditto.ditto_experimental_remove_dql_subscription(...args) }
 function ditto_free(...args) { return ditto.ditto_free(...args) }
 function ditto_free_attachment_handle(...args) { return ditto.ditto_free_attachment_handle(...args) }
 function ditto_get_collection_names(...args) { return ditto.ditto_get_collection_names(...args) }
@@ -369,6 +369,8 @@ function ditto_resolve_attachment(...args) { return ditto.ditto_resolve_attachme
 function ditto_run_garbage_collection(...args) { return ditto.ditto_run_garbage_collection(...args) }
 function ditto_set_connect_retry_interval(...args) { return ditto.ditto_set_connect_retry_interval(...args) }
 function ditto_set_device_name(...args) { return ditto.ditto_set_device_name(...args) }
+function ditto_set_static_tcp_clients(...args) { return ditto.ditto_set_static_tcp_clients(...args) }
+function ditto_set_static_websocket_clients(...args) { return ditto.ditto_set_static_websocket_clients(...args) }
 function ditto_set_sync_group(...args) { return ditto.ditto_set_sync_group(...args) }
 function ditto_shutdown(...args) { return ditto.ditto_shutdown(...args) }
 function ditto_start_http_server(...args) { return ditto.ditto_start_http_server(...args) }
@@ -379,10 +381,12 @@ function ditto_validate_document_id(...args) { return ditto.ditto_validate_docum
 function ditto_write_transaction(...args) { return ditto.ditto_write_transaction(...args) }
 function ditto_write_transaction_commit(...args) { return ditto.ditto_write_transaction_commit(...args) }
 function ditto_write_transaction_rollback(...args) { return ditto.ditto_write_transaction_rollback(...args) }
+function getDeadlockTimeout$1(...args) { return ditto.getDeadlockTimeout(...args) }
 function jsDocsToCDocs(...args) { return ditto.jsDocsToCDocs(...args) }
 function mdns_client_free_handle(...args) { return ditto.mdns_client_free_handle(...args) }
 function mdns_server_free_handle(...args) { return ditto.mdns_server_free_handle(...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 uninitialized_ditto_make(...args) { return ditto.uninitialized_ditto_make(...args) }
 function verify_license(...args) { return ditto.verify_license(...args) }
@@ -404,9 +408,9 @@ var DittoCRDTType;
     DittoCRDTType[DittoCRDTType["rga"] = 3] = "rga";
     DittoCRDTType[DittoCRDTType["rwMap"] = 4] = "rwMap";
 })(DittoCRDTType || (DittoCRDTType = {}));
-// ------------------------------------------------------- Linux BLE Hack ------
+// -------------------------------------- Linux & Windows Transports Hack ------
 // HACK: quick and dirty, wrap the internal BLE functions which
-// are currently only used by the Node Linux build. See comment
+// are currently only used by the Node Linux & Windows build. See comment
 // in `sync.ts` -> `Ditto.applyPeerToPeerBluetoothLE()` for details.
 function dittoAddInternalBLEClientTransport(ditto) {
     {
@@ -641,6 +645,22 @@ function removeSubscription(ditto, collectionName, query, queryArgsCBOR, orderBy
     const queryX = bytesFromString(query);
     return ditto_remove_subscription(ditto, collectionNameX, queryX, queryArgsCBOR, orderBy, limit, offset);
 }
+/** @internal */
+function experimentalAddDqlSubscription(ditto, query, queryArgsCBOR) {
+    ensureInitialized();
+    const queryBuffer = bytesFromString(query);
+    const statusCode = ditto_experimental_add_dql_subscription(ditto, queryBuffer, queryArgsCBOR);
+    if (statusCode !== 0)
+        throw new Error(errorMessage() || `ditto_experimental_add_dql_subscription() failed with error code: ${statusCode}`);
+}
+/** @internal */
+function experimentalRemoveDqlSubscription(ditto, query, queryArgsCBOR) {
+    ensureInitialized();
+    const queryBuffer = bytesFromString(query);
+    const statusCode = ditto_experimental_remove_dql_subscription(ditto, queryBuffer, queryArgsCBOR);
+    if (statusCode !== 0)
+        throw new Error(errorMessage() || `ditto_experimental_remove_dql_subscription() failed with error code: ${statusCode}`);
+}
 // ------------------------------------------------------------ LiveQuery ------
 /** @internal */
 function liveQueryRegister(ditto, collectionName, query, queryArgsCBOR, orderBy, limit, offset, eventHandler, 
@@ -650,9 +670,10 @@ onError) {
     ensureInitialized();
     const collectionNameBuffer = bytesFromString(collectionName);
     const queryBuffer = bytesFromString(query);
-    // Note(Daniel): the callback is now registered to be called in a detached manner:
-    // if the FFI / Rust does `cb()`, then when that call returns, the js callback itself may not
-    // have completed. This is fine, since `signalNext()` shall be the proper way to achieve this.
+    // Note(Daniel): the callback is now registered to be called in a detached
+    // manner: if the FFI / Rust does `cb()`, then when that call returns, the js
+    // callback itself may not have completed. This is fine, since `signalNext()`
+    // shall be the proper way to achieve this.
     const { status_code: errorCode, i64: id } = ditto_live_query_register_str_detached(ditto, collectionNameBuffer, queryBuffer, queryArgsCBOR, orderBy, limit, offset, wrapBackgroundCbForFFI(onError, eventHandler));
     if (errorCode !== 0)
         throw new Error(errorMessage() || `\`ditto_live_query_register_str()\` failed with error code: ${errorCode}`);
@@ -726,24 +747,10 @@ async function writeTransactionRollback(ditto, transaction) {
     if (errorCode !== 0)
         throw new Error(errorMessage() || `ditto_write_transaction_rollback() failed with error code: ${errorCode}`);
 }
-// ------------------------------------------------------ StaticTCPClient ------
-/** @internal */
-function addStaticTCPClient(ditto, address) {
-    ensureInitialized();
-    const addressBuffer = bytesFromString(address);
-    return ditto_add_static_tcp_client(ditto, addressBuffer);
-}
 /** @internal */
 function staticTCPClientFreeHandle(self) {
     static_tcp_client_free_handle(self);
 }
-// ------------------------------------------------------ WebsocketClient ------
-/** @internal */
-function addWebsocketClient(ditto, address, routingHint) {
-    ensureInitialized();
-    const addressBuffer = bytesFromString(address);
-    return ditto_add_websocket_client(ditto, addressBuffer, routingHint);
-}
 /** @internal */
 function websocketClientFreeHandle(self) {
     ensureInitialized();
@@ -948,6 +955,16 @@ function dittoFree(self) {
     return ditto_free(self);
 }
 /** @internal */
+function getDeadlockTimeout() {
+    ensureInitialized();
+    return getDeadlockTimeout$1();
+}
+/** @internal */
+function setDeadlockTimeout(duration) {
+    ensureInitialized();
+    setDeadlockTimeout$1(duration);
+}
+/** @internal */
 async function dittoRegisterPresenceV1Callback(self, cb) {
     ensureInitialized();
     ditto_register_presence_v1_callback(self, wrapBackgroundCbForFFI((err) => console.error(`The registered presence callback v1 errored with ${err}`), (cJsonStr) => {
@@ -1127,6 +1144,20 @@ async function dittoDisableSyncWithV3(dittoPointer) {
     if (errorCode !== 0)
         throw new Error(errorMessage() || `ditto_disable_sync_with_v3() failed with error code: ${errorCode}`);
 }
+function dittoSetStaticTCPClients(ditto, listOfServers) {
+    ensureInitialized();
+    // TODO(Vincent): add error handling.
+    {
+        const listOfServersBytes = listOfServers.map((server) => bytesFromString(server));
+        ditto_set_static_tcp_clients(ditto, listOfServersBytes);
+    }
+}
+function dittoSetStaticWebsocketClients(ditto, listOfServers, routingHint) {
+    ensureInitialized();
+    // TODO(Vincent): add error handling.
+    const listOfServersBytes = listOfServers.map((server) => bytesFromString(server));
+    ditto_set_static_websocket_clients(ditto, listOfServersBytes, routingHint);
+}
 // ------------------------------------------------------ Hash & Mnemonic ------
 /** @internal */
 function documentsHash(documents) {
@@ -1439,7 +1470,7 @@ function awdlDestroy(awdl) {
 
 // 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.1.0';
+const fullBuildVersionString = '4.2.0';
 
 //
 /**
@@ -2749,6 +2780,11 @@ function augmentJSONValue(json, mutDoc, workingPath) {
         return json;
     }
 }
+/**
+ * Converts objects that may contain instances of classes of this SDK, i.e.
+ * `DocumentID`, `Counter`, `Register` and `Attachment`, into plain JS objects
+ * that can be passed to the FFI layer.
+ */
 function desugarJSObject(jsObj, atRoot = false) {
     if (jsObj && typeof jsObj === 'object') {
         if (Array.isArray(jsObj)) {
@@ -2786,8 +2822,25 @@ function desugarJSObject(jsObj, atRoot = false) {
         }
     }
     else {
+        checkForUnsupportedValues(jsObj);
         return jsObj;
     }
+}
+/**
+ * Throws an error if input is a non-finite float value.
+ *
+ * Workaround while we don't have a reliable way of receiving error messages
+ * from `dittoCore.ditto_collection_insert_value()`.
+ *
+ * See https://github.com/getditto/ditto/issues/8657 for details.
+ *
+ * @param jsObj The object to check.
+ * @throws {Error} If `jsObj` is a non-finite float value.
+ */
+function checkForUnsupportedValues(jsObj) {
+    if (Number.isNaN(jsObj) || jsObj === Infinity || jsObj === -Infinity) {
+        throw new Error('Non-finite float values are not supported');
+    }
 }
 
 //
@@ -5186,6 +5239,125 @@ function collectionsFromDocuments(documents, store) {
     return collections;
 }
 
+//
+/**
+ * Manages `ExperimentalSubscription` instances and removes them when Ditto is
+ * closed.
+ *
+ * @internal
+ */
+class ExperimentalSubscriptionManager {
+    constructor(ditto) {
+        this.subscriptions = {};
+        this.finalizationRegistry = new FinalizationRegistry(this.removeWithContextInfo.bind(this));
+        this.ditto = ditto;
+    }
+    /**
+     * Begin tracking a subscription instance and start it.
+     *
+     * @internal
+     */
+    addSubscription(subscription) {
+        if (this.subscriptions[subscription.contextInfo.id] != null) {
+            throw new Error(`Internal inconsistency, tried to add a subscription that is already tracked: ${subscription.contextInfo.id}`);
+        }
+        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
+        this.ditto.deferClose(() => {
+            experimentalAddDqlSubscription(dittoHandle.deref(), subscription.query, subscription.queryArgsCBOR);
+        });
+        // Only track the subscription after it has been successfully added to Ditto
+        // to avoid tracking a subscription that failed to start.
+        this.subscriptions[subscription.contextInfo.id] = new WeakRef(subscription);
+        this.finalizationRegistry.register(subscription, subscription.contextInfo, subscription);
+    }
+    /**
+     * Stop tracking a subscription instance and cancel it.
+     *
+     * @internal
+     */
+    removeSubscription(subscription) {
+        if (this.subscriptions[subscription.contextInfo.id] == null) {
+            throw new Error(`Internal inconsistency, tried to remove a subscription that is not tracked: ${subscription.contextInfo.id}`);
+        }
+        this.finalizationRegistry.unregister(subscription);
+        delete this.subscriptions[subscription.contextInfo.id];
+        this.removeWithContextInfo(subscription.contextInfo);
+    }
+    /**
+     * Stop tracking all subscriptions and cancel them.
+     *
+     * @internal
+     */
+    close() {
+        Logger.debug(`ExperimentalSubscriptionManager.close() with ${this.subscriptions.length} queries`);
+        this.ditto.deferClose(() => {
+            var _a;
+            for (const subscriptionWeakRef of Object.values(this.subscriptions)) {
+                // If this deref fails, the garbage collector has already removed the
+                // subscription and will issue a finalization callback to
+                // `removeWithContextInfo()`.
+                (_a = subscriptionWeakRef.deref()) === null || _a === void 0 ? void 0 : _a.cancel();
+            }
+        });
+    }
+    /**
+     * Remove tracked subscription without unregistering from finalization
+     * registry.
+     *
+     * @internal
+     */
+    removeWithContextInfo(contextInfo) {
+        const dittoHandle = Bridge.ditto.handleFor(this.ditto);
+        this.ditto.deferClose(() => {
+            experimentalRemoveDqlSubscription(dittoHandle.deref(), contextInfo.query, contextInfo.queryArgsCBOR);
+            delete this.subscriptions[contextInfo.id];
+        });
+    }
+}
+
+//
+/**
+ * Create a subscription to receive updates from remote peers about documents
+ * matching the subscription's query.
+ *
+ * The subscription will remain active until {@link cancel | cancel()} is called
+ * or the subscription object goes out of scope and is garbage collected.
+ *
+ * @internal
+ */
+class ExperimentalSubscription {
+    /**
+     * Cancels a subscription and releases all associated resources.
+     */
+    cancel() {
+        if (!this.isCancelled) {
+            this['isCancelled'] = true;
+            this.manager.removeSubscription(this);
+        }
+    }
+    // --------------------------- Internal --------------------------------------
+    /** @internal */
+    constructor(manager, query, queryArgsCBOR) {
+        /**
+         * `true` when {@link cancel | cancel()} has been called or the Ditto instance
+         * managing this subscription has been closed.
+         */
+        // Recording this information on the subscription instance itself allows
+        // working with it even after Ditto has been closed and the subscription
+        // manager can not be accessed anymore.
+        this.isCancelled = false;
+        this.query = query;
+        this.queryArgsCBOR = queryArgsCBOR;
+        this.contextInfo = {
+            id: generateEphemeralToken(),
+            query,
+            queryArgsCBOR,
+        };
+        this.manager = manager;
+        manager.addSubscription(this);
+    }
+}
+
 //
 /**
  * An addon for the Ditto store that contains experimental features. Accessible
@@ -5197,21 +5369,28 @@ class ExperimentalStore {
     /** @internal */
     constructor(ditto) {
         this.ditto = ditto;
+        this.subscriptionManager = new ExperimentalSubscriptionManager(this.ditto);
+    }
+    /** @internal */
+    close() {
+        this.subscriptionManager.close();
     }
     /**
      * Executes the given query in the local store and returns the result.
      *
      * Limitations:
      *
-     * - Only supports `SELECT * FROM <collection name>`
-     * - No query parameters
+     * - Supports `SELECT * FROM <collection name>` with optional `WHERE
+     *   <expression>`
+     * - No query parameters as function arguments yet
      * - No transactions
      *
      * @internal
      * @param query a Ditto Query Language query string
      * @returns a promise for an array of Ditto documents matching the query
-     **/
+     */
     async execute(query) {
+        Logger.debug(`ExperimentalStore.execute(query = ${query})`);
         const ditto = this.ditto;
         const dittoHandle = Bridge.ditto.handleFor(ditto);
         return ditto.deferCloseAsync(async () => {
@@ -5226,9 +5405,21 @@ class ExperimentalStore {
             return documentPointers.map((documentPointer) => Bridge.document.bridge(documentPointer));
         });
     }
-    /** @internal */
-    close() {
-        // Nothing to do yet.
+    /**
+     * Subscribes the device to updates specified by a DQL query to collections
+     * that other devices know about.
+     *
+     * The returned {@link ExperimentalSubscription} object must be kept in scope
+     * for as long as you want to keep receiving updates.
+     *
+     * @internal
+     * @param query a Ditto Query Language query string of the form SELECT * FROM
+     * collection WHERE expression
+     * @returns {@link ExperimentalSubscription} object
+     */
+    subscribe(query) {
+        Logger.debug(`ExperimentalStore.subscribe(query = ${query})`);
+        return new ExperimentalSubscription(this.subscriptionManager, query, null);
     }
 }
 
@@ -5996,8 +6187,6 @@ class Sync {
         this.ditto = ditto;
         this.parameters = parameters;
         this.state = stateFrom(parameters);
-        this.staticTCPClientsByAddress = {};
-        this.websocketClientsByURL = {};
     }
     update(parameters) {
         this['parameters'] = { ...parameters };
@@ -6181,70 +6370,17 @@ class Sync {
         const ditto = this.ditto;
         const dittoHandle = Bridge.ditto.handleFor(ditto);
         ditto.deferClose(() => {
-            // REFACTOR: same "algorithm" as for Websockets below, DRY up.
-            const currentTCPServers = Object.getOwnPropertyNames(this.staticTCPClientsByAddress);
-            const desiredTCPServers = stateNew.effectiveTransportConfig.connect.tcpServers;
-            const tcpServersToConnectToSet = new Set(desiredTCPServers);
-            for (const tcpServer of currentTCPServers)
-                tcpServersToConnectToSet.delete(tcpServer);
-            const tcpServersToDisconnectFromSet = new Set(currentTCPServers);
-            for (const tcpServer of desiredTCPServers)
-                tcpServersToDisconnectFromSet.delete(tcpServer);
-            const tcpServersToConnectTo = tcpServersToConnectToSet.values();
-            const tcpServersToDisconnectFrom = tcpServersToDisconnectFromSet.values();
-            for (const tcpServer of tcpServersToConnectTo) {
-                const staticTCPClientPointer = addStaticTCPClient(dittoHandle.deref(), tcpServer);
-                const staticTCPClient = Bridge.staticTCPClient.bridge(staticTCPClientPointer);
-                this.staticTCPClientsByAddress[tcpServer] = staticTCPClient;
-            }
-            for (const tcpServer of tcpServersToDisconnectFrom) {
-                // REFACTOR: we have to make sure freeing the tcpServer handle is done
-                // BEFORE the Ditto instance itself is freed.
-                const staticTCPClient = this.staticTCPClientsByAddress[tcpServer];
-                if (!staticTCPClient)
-                    throw new Error(`Internal inconsistency, can't disconnect from TCP address '${tcpServer}', no staticTCPClient found.`);
-                const staticTCPClientPointer = Bridge.staticTCPClient.handleFor(staticTCPClient).deref();
-                // Unregister to avoid double-free for this pointer, then free manually:
-                Bridge.staticTCPClient.unregister(staticTCPClient);
-                staticTCPClientFreeHandle(staticTCPClientPointer);
-                delete this.staticTCPClientsByAddress[tcpServer];
-            }
+            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(() => {
-            // REFACTOR: same "algorithm" as for TCP servers above, DRY up.
-            // IDEA: normalize URLs so that we don't connect to the same URL twice?
-            const currentWebsocketURLs = Object.getOwnPropertyNames(this.websocketClientsByURL);
-            const desiredWebsocketURLs = stateNew.effectiveTransportConfig.connect.websocketURLs.slice();
-            const websocketURLsToConnectToSet = new Set(desiredWebsocketURLs);
-            for (const websocketURL of currentWebsocketURLs)
-                websocketURLsToConnectToSet.delete(websocketURL);
-            const websocketURLsToDisconnectFromSet = new Set(currentWebsocketURLs);
-            for (const websocketURL of desiredWebsocketURLs)
-                websocketURLsToDisconnectFromSet.delete(websocketURL);
-            const websocketURLsToConnectTo = websocketURLsToConnectToSet.values();
-            const websocketURLsToDisconnectFrom = websocketURLsToDisconnectFromSet.values();
+            const websocketURLs = stateNew.effectiveTransportConfig.connect.websocketURLs;
             const routingHint = stateNew.effectiveTransportConfig.global.routingHint;
-            for (const websocketURL of websocketURLsToConnectTo) {
-                const websocketClientPointer = addWebsocketClient(dittoHandle.deref(), websocketURL, routingHint);
-                const websocketClient = Bridge.websocketClient.bridge(websocketClientPointer);
-                this.websocketClientsByURL[websocketURL] = websocketClient;
-            }
-            for (const websocketURL of websocketURLsToDisconnectFrom) {
-                // REFACTOR: we have to make sure freeing the websocket handle is done
-                // BEFORE the Ditto instance itself is freed.
-                const websocketClient = this.websocketClientsByURL[websocketURL];
-                if (!websocketClient)
-                    throw new Error(`Internal inconsistency, can't disconnect from websocket URL '${websocketURL}', no websocketClient found.`);
-                const websocketClientPointer = Bridge.websocketClient.handleFor(websocketClient).deref();
-                // Unregister to avoid double-free for this pointer, then free manually:
-                Bridge.websocketClient.unregister(websocketClient);
-                websocketClientFreeHandle(websocketClientPointer);
-                delete this.websocketClientsByURL[websocketURL];
-            }
+            dittoSetStaticWebsocketClients(dittoHandle.deref(), websocketURLs, routingHint);
         });
     }
     updateGlobal(stateOld, stateNew) {
@@ -6346,7 +6482,7 @@ class SubscriptionManager {
     constructor(ditto) {
         this.ditto = ditto;
         this.subscriptions = {};
-        this.finalizationRegistry = new FinalizationRegistry(this.removeWithContextinfo.bind(this));
+        this.finalizationRegistry = new FinalizationRegistry(this.removeWithContextInfo.bind(this));
     }
     /**
      * Begin tracking a subscription instance and start it.
@@ -6371,7 +6507,7 @@ class SubscriptionManager {
             throw new Error(`Internal inconsistency, tried to remove a subscription that is not tracked: ${subscription.contextInfo.id}`);
         }
         this.finalizationRegistry.unregister(subscription);
-        this.removeWithContextinfo(subscription.contextInfo);
+        this.removeWithContextInfo(subscription.contextInfo);
     }
     /**
      * Stop tracking all subscriptions and cancel them.
@@ -6394,7 +6530,7 @@ class SubscriptionManager {
      * registry.
      *
      * @internal */
-    removeWithContextinfo(contextInfo) {
+    removeWithContextInfo(contextInfo) {
         const ditto = this.ditto;
         const dittoHandle = Bridge.ditto.handleFor(ditto);
         ditto.deferClose(() => {
@@ -6697,8 +6833,13 @@ class Ditto {
         })();
         const dittoPointer = dittoMake(uninitializedDittoX, identityConfig);
         dittoAuthClientSetValidityListener(dittoPointer, function (...args) {
-            var _a;
-            (_a = weakThis.deref()) === null || _a === void 0 ? void 0 : _a.authClientValidityChanged(...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 = dittoAuthClientIsWebValid(dittoPointer);
         const isX509Valid = dittoAuthClientIsX509Valid(dittoPointer);
@@ -6762,12 +6903,59 @@ class Ditto {
         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() {
+        {
+            const current = getDeadlockTimeout();
+            if (current !== 0) {
+                try {
+                    setDeadlockTimeout(0);
+                }
+                catch (e) {
+                    throw new Error(`Failed to disable deadlock detection: ${e === null || e === void 0 ? void 0 : 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() {
+        {
+            return getDeadlockTimeout() !== 0;
+        }
+    }
     /**
      * Check if the current environment supports running Ditto.
      *
@@ -6779,7 +6967,7 @@ class Ditto {
      *
      *  Internet Explorer is not supported.
      *
-     * @returns true if the environment is supported
+     * @returns `true` if the environment is supported
      */
     static isEnvironmentSupported() {
         // From https://stackoverflow.com/questions/21825157/internet-explorer-11-detection
@@ -7130,6 +7318,31 @@ const checkAPIs = (_globalObject) => {
     const requiredBrowserAPIs = ['BigInt', 'WeakRef', 'FinalizationRegistry'];
     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
+ */
+const disableDeadlockTimeoutWhenDebugging = () => {
+    var _a, _b;
+    {
+        const hasInspector = process && ((_a = process === null || process === void 0 ? void 0 : process.execArgv) === null || _a === void 0 ? void 0 : _a.some((arg) => arg.includes('--inspect') || arg.includes('--debug')));
+        // @ts-ignore - v8debug may be undefined
+        const hasLegacyDebugMode = (process && ((_b = process === null || process === void 0 ? void 0 : process.execArgv) === null || _b === void 0 ? void 0 : _b.some((arg) => arg.includes('--debug')))) || typeof v8debug === 'object';
+        if (hasInspector || hasLegacyDebugMode) {
+            try {
+                setDeadlockTimeout(0);
+                Logger.warning('Detected Node running with inspector enabled, disabling deadlock timeout.');
+            }
+            catch (e) {
+                Logger.error(`Detected Node running with inspector enabled but failed to disable deadlock timeout: ${e === null || e === void 0 ? void 0 : e.message}`);
+            }
+        }
+    }
 };
 
 /**
@@ -7137,7 +7350,8 @@ const checkAPIs = (_globalObject) => {
  *
  * Use this in testing to ensure that all objects are properly garbage collected at the end of tests.
  *
- * @returns an object with a key per bridge type, containing the number of registered objects.
+ * @returns an object with a key per bridge type, set to the count of registered
+ * objects.
  */
 function getBridgeLoad() {
     const countsByType = {};
@@ -7193,6 +7407,8 @@ exports.Document = Document;
 exports.DocumentID = DocumentID;
 exports.DocumentPath = DocumentPath;
 exports.ExperimentalStore = ExperimentalStore;
+exports.ExperimentalSubscription = ExperimentalSubscription;
+exports.ExperimentalSubscriptionManager = ExperimentalSubscriptionManager;
 exports.IdentityTypesRequiringOfflineLicenseToken = IdentityTypesRequiringOfflineLicenseToken;
 exports.KeepAlive = KeepAlive;
 exports.LiveQuery = LiveQuery;
@@ -7224,6 +7440,7 @@ exports.WriteTransactionPendingCursorOperation = WriteTransactionPendingCursorOp
 exports.WriteTransactionPendingIDSpecificOperation = WriteTransactionPendingIDSpecificOperation;
 exports.addressToString = addressToString;
 exports.checkAPIs = checkAPIs;
+exports.disableDeadlockTimeoutWhenDebugging = disableDeadlockTimeoutWhenDebugging;
 exports.getBridgeLoad = getBridgeLoad;
 exports.init = init;
 exports.validateDocumentIDCBOR = validateDocumentIDCBOR;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittolive/ditto",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Ditto is a cross-platform embeddable NoSQL database that can sync with or without an internet connection.",
   "homepage": "https://ditto.live",
   "license": "SEE LICENSE IN LICENSE.md",