@dittolive/ditto 4.1.0 → 4.2.0

package/types/ditto.d.ts

@@ -1348,7 +1348,7 @@ declare class SubscriptionManager {
      * registry.
      *
      * @internal */
-    private removeWithContextinfo;
+    private removeWithContextInfo;
 }
 
 /**
@@ -1919,6 +1919,36 @@ declare class Ditto {
      * @see {@link Ditto.path}
      */
     constructor(identity?: Identity, path?: string);
+    /**
+     * Don't terminate the process when callbacks are pending for a long time.
+     *
+     * Some methods in the Ditto library accept asynchronous functions as callback
+     * parameters. If these asynchronous functions do not resolve within a certain
+     * period of time after having been invoked by Ditto, deadlock detection gets
+     * triggered, resulting in the termination of the process.
+     *
+     * When Ditto is executed in a Node.js environment with an interactive
+     * debugger attached, this deadlock detection might get activated upon
+     * encountering a breakpoint. Calling `Ditto.disableDeadlockDetection()`
+     * disables this behavior, thus allowing the use of an interactive debugger
+     * without triggering the deadlock detection.
+     *
+     * This feature is not available in the browser.
+     */
+    static disableDeadlockDetection(): void;
+    /**
+     * Returns `true` if deadlock detection is enabled.
+     *
+     * See
+     * {@link Ditto.disableDeadlockDetection | Ditto.disableDeadlockDetection()}
+     * for more information.
+     *
+     * This method always returns `false` in the browser where deadlock detection
+     * is not available.
+     *
+     * @returns `true` if deadlock detection is enabled
+     */
+    static hasDeadlockDetection(): boolean;
     /**
      * Check if the current environment supports running Ditto.
      *
@@ -1930,7 +1960,7 @@ declare class Ditto {
      *
      *  Internet Explorer is not supported.
      *
-     * @returns true if the environment is supported
+     * @returns `true` if the environment is supported
      */
     static isEnvironmentSupported(): boolean;
     /**
@@ -2109,6 +2139,15 @@ declare class Ditto {
 }
 /** @internal */
 declare const checkAPIs: (_globalObject?: Window | typeof globalThis) => boolean;
+/**
+ * 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
+ */
+declare const disableDeadlockTimeoutWhenDebugging: () => void;
 
 /**
  * Represents an attachment and can be used to insert the associated attachment
@@ -2599,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`.
@@ -2613,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;
 }
 
 /**
@@ -3009,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;
@@ -3023,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, 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