@dittolive/ditto 4.1.1 → 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.1**
+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.1/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) }
@@ -406,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) {
     {
@@ -643,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, 
@@ -729,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();
@@ -1140,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) {
@@ -1452,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.1';
+const fullBuildVersionString = '4.2.0';
 
 //
 /**
@@ -5221,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
@@ -5232,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 () => {
@@ -5261,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);
     }
 }
 
@@ -6031,8 +6187,6 @@ class Sync {
         this.ditto = ditto;
         this.parameters = parameters;
         this.state = stateFrom(parameters);
-        this.staticTCPClientsByAddress = {};
-        this.websocketClientsByURL = {};
     }
     update(parameters) {
         this['parameters'] = { ...parameters };
@@ -6216,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) {
@@ -6381,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.
@@ -6406,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.
@@ -6429,7 +6530,7 @@ class SubscriptionManager {
      * registry.
      *
      * @internal */
-    removeWithContextinfo(contextInfo) {
+    removeWithContextInfo(contextInfo) {
         const ditto = this.ditto;
         const dittoHandle = Bridge.ditto.handleFor(ditto);
         ditto.deferClose(() => {
@@ -6732,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);
@@ -7244,7 +7350,8 @@ const disableDeadlockTimeoutWhenDebugging = () => {
  *
  * 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 = {};
@@ -7300,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittolive/ditto",
-  "version": "4.1.1",
+  "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",

package/types/ditto.d.ts

@@ -1348,7 +1348,7 @@ declare class SubscriptionManager {
      * registry.
      *
      * @internal */
-    private removeWithContextinfo;
+    private removeWithContextInfo;
 }
 
 /**
@@ -2638,6 +2638,94 @@ declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
     private readonly pendingCursorOperation;
 }
 
+/**
+ * Manages `ExperimentalSubscription` instances and removes them when Ditto is
+ * closed.
+ *
+ * @internal
+ */
+declare class ExperimentalSubscriptionManager {
+    constructor(ditto: Ditto);
+    /**
+     * Begin tracking a subscription instance and start it.
+     *
+     * @internal
+     */
+    addSubscription(subscription: ExperimentalSubscription): void;
+    /**
+     * Stop tracking a subscription instance and cancel it.
+     *
+     * @internal
+     */
+    removeSubscription(subscription: ExperimentalSubscription): void;
+    /**
+     * Stop tracking all subscriptions and cancel them.
+     *
+     * @internal
+     */
+    close(): void;
+    private readonly ditto;
+    private subscriptions;
+    private finalizationRegistry;
+    /**
+     * Remove tracked subscription without unregistering from finalization
+     * registry.
+     *
+     * @internal
+     */
+    private removeWithContextInfo;
+}
+
+/**
+ * Contains all information required to deregister a subscription
+ * in Ditto Core, even when the subscription instance itself has
+ * already been garbage collected.
+ *
+ * @internal
+ */
+type ExperimentalSubscriptionContextInfo = {
+    /** Unique ID per `ExperimentalSubscription` instance. */
+    id: string;
+    query: string;
+    queryArgsCBOR: Uint8Array | null;
+};
+/**
+ * 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
+ */
+declare class ExperimentalSubscription {
+    /**
+     * Documents matching this query will be included in the subscription.
+     */
+    readonly query: string;
+    /**
+     * `true` when {@link cancel | cancel()} has been called or the Ditto instance
+     * managing this subscription has been closed.
+     */
+    readonly isCancelled = false;
+    /**
+     * Cancels a subscription and releases all associated resources.
+     */
+    cancel(): void;
+    /** @internal */
+    constructor(manager: ExperimentalSubscriptionManager, query: string, queryArgsCBOR: Uint8Array | null);
+    /** @internal */
+    contextInfo: ExperimentalSubscriptionContextInfo;
+    /**
+     * The corresponding named arguments for {@link query}, if any.
+     *
+     * @internal
+     */
+    readonly queryArgsCBOR: Uint8Array | null;
+    /** @internal */
+    private manager;
+}
+
 /**
  * An addon for the Ditto store that contains experimental features. Accessible
  * on `ditto.store.experimental`.
@@ -2652,22 +2740,37 @@ declare class ExperimentalStore {
     readonly ditto: Ditto;
     /** @internal */
     constructor(ditto: Ditto);
+    /** @internal */
+    close(): void;
     /**
      * 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
-     **/
+     */
     execute(query: string): Promise<Document[]>;
-    /** @internal */
-    close(): void;
+    /**
+     * 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: string): ExperimentalSubscription;
+    private subscriptionManager;
 }
 
 /**
@@ -3048,7 +3151,8 @@ declare abstract class BasePendingCursorOperation implements PromiseLike<Documen
  *
  * 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.
  */
 declare function getBridgeLoad(): {
     [bridgeName: string]: number;
@@ -3062,5 +3166,5 @@ declare class CBOR {
     static decode(data: Uint8Array): any;
 }
 
-export { Address, Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, Collection, CollectionInterface, CollectionsEvent, CollectionsEventParams, CollectionsObservationHandler, ConditionSource, Connection, ConnectionType, Counter, CustomLogCallback, Ditto, Document, DocumentID, DocumentIDValue, DocumentPath, DocumentValue, ExperimentalStore, Identity, IdentityManual, IdentityOfflinePlayground, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, InitOptions, KeepAlive, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRegister, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, Peer, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, Presence, PresenceConnectionType, PresenceGraph, QueryArguments, QueryObservationHandler, Register, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, WriteTransaction, WriteTransactionCollection, WriteTransactionPendingCursorOperation, WriteTransactionPendingIDSpecificOperation, WriteTransactionResult, addressToString, checkAPIs, disableDeadlockTimeoutWhenDebugging, getBridgeLoad, init, validateDocumentIDCBOR, validateDocumentIDValue };
+export { Address, Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, Collection, CollectionInterface, CollectionsEvent, CollectionsEventParams, CollectionsObservationHandler, ConditionSource, Connection, ConnectionType, Counter, CustomLogCallback, Ditto, Document, DocumentID, DocumentIDValue, DocumentPath, DocumentValue, ExperimentalStore, ExperimentalSubscription, ExperimentalSubscriptionContextInfo, ExperimentalSubscriptionManager, Identity, IdentityManual, IdentityOfflinePlayground, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, InitOptions, KeepAlive, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRegister, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, Peer, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, Presence, PresenceConnectionType, PresenceGraph, QueryArguments, QueryObservationHandler, Register, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, WriteTransaction, WriteTransactionCollection, WriteTransactionPendingCursorOperation, WriteTransactionPendingIDSpecificOperation, WriteTransactionResult, addressToString, checkAPIs, disableDeadlockTimeoutWhenDebugging, getBridgeLoad, init, validateDocumentIDCBOR, validateDocumentIDValue };
 //# sourceMappingURL=ditto.d.ts.map