@dittolive/ditto 4.4.1 → 4.4.2-alpha1

package/package.json

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

@@ -72,8 +72,8 @@ declare class ObserverManager {
 
 /** @internal */
 interface ObserverManaging {
-    hasObserver(token: ObserverToken): any;
-    removeObserver(token: ObserverToken): any;
+    hasObserver(token: ObserverToken): boolean;
+    removeObserver(token: ObserverToken): void;
 }
 /** @internal */
 type ObserverOptions = {
@@ -89,7 +89,7 @@ declare class Observer {
     /** @internal */
     readonly observerManager: ObserverManaging;
     /** @internal */
-    readonly token?: ObserverToken;
+    get token(): ObserverToken | undefined;
     /** @internal */
     readonly options?: ObserverOptions;
     /** @internal */
@@ -104,6 +104,7 @@ declare class Observer {
      */
     stop(): void;
     private static finalizationRegistry;
+    private _token?;
     private static finalize;
 }
 
@@ -139,6 +140,23 @@ type WriteStrategy = 'merge' | 'insertIfAbsent' | 'insertDefaultIfAbsent';
 type QueryArguments = {
     [key: string]: any;
 };
+/**
+ * Values to be incorporated into a query keyed by the placeholder used within
+ * that query.
+ *
+ * @internal
+ */
+type DQLQueryArguments = {
+    [key: string]: DQLQueryArgumentValue;
+};
+/**
+ * Value for an invidual key in a {@link DQLQueryArguments} object.
+ *
+ * @internal
+ */
+type DQLQueryArgumentValue = string | number | boolean | Uint8Array | undefined | null | DQLQueryArgumentValue[] | {
+    [key: string | number]: DQLQueryArgumentValue;
+};
 
 /** @internal */
 declare class Value {
@@ -153,15 +171,16 @@ declare class Value {
  */
 declare class Counter {
     /** The value of the counter. */
-    readonly value: number;
+    get value(): number;
     /**
      * Creates a new counter that can be used as part of a document's content.
      */
     constructor();
     /** @internal */
     static '@ditto.create'(mutDoc: any, path: any, value: any): any;
-    private mutDoc;
-    private path;
+    protected mutDoc: any;
+    protected path: any;
+    protected _value: number;
 }
 /**
  * Represents a mutable CRDT counter that can be incremented by a specific
@@ -181,7 +200,7 @@ declare class MutableCounter extends Counter {
      */
     increment(amount: number): void;
     /** @internal */
-    constructor();
+    protected constructor();
 }
 
 /**
@@ -301,7 +320,7 @@ declare class Logger {
      * Registers a file path where logs will be written to, whenever Ditto wants
      * to issue a log (on _top_ of emitting the log to the console).
      */
-    static readonly logFile?: string;
+    static get logFile(): string | undefined;
     /**
      * On Node, registers a file path where logs will be written to, whenever
      * Ditto wants to issue a log (on _top_ of emitting the log to the console).
@@ -350,7 +369,7 @@ declare class Logger {
      * {@link setCustomLogCallback | setCustomLogCallback()} for a detailed
      * description.
      */
-    static readonly customLogCallback?: CustomLogCallback;
+    static get customLogCallback(): CustomLogCallback | undefined;
     /**
      * Registers a custom callback that will be called to report each log entry.
      *
@@ -394,6 +413,8 @@ declare class Logger {
      * {@link LogLevel} `Verbose`.
      */
     static verbose(message: string): void;
+    private static _logFile?;
+    private static _customLogCallback?;
     private constructor();
 }
 
@@ -805,6 +826,9 @@ interface TransportConfigPeerToPeer {
 interface TransportConfigLan {
     isEnabled: boolean;
     isMdnsEnabled: boolean;
+    /**
+     * @deprecated Multicast is deprecated. Please use mDNS instead.
+     */
     isMulticastEnabled: boolean;
 }
 /**
@@ -915,7 +939,7 @@ declare class TransportConfig {
      * Returns `true` if the transport configuration is frozen, otherwise
      * returns `false`.
      */
-    readonly isFrozen: boolean;
+    get isFrozen(): boolean;
     /**
      * (Deep) freezes the receiver such that it can't be modified anymore.
      */
@@ -934,6 +958,7 @@ declare class TransportConfig {
      * returns `false`.
      */
     static areListenHTTPsEqual(left: TransportConfigListenHTTP, right: TransportConfigListenHTTP): boolean;
+    private _isFrozen;
 }
 
 /**
@@ -997,7 +1022,7 @@ declare class Authenticator {
     /**
      Returns the current authentication status.
      */
-    readonly status: AuthenticationStatus;
+    get status(): AuthenticationStatus;
     /**
      * Log in to Ditto with a third-party token. Throws if authentication is not
      * available, which can be checked with {@link loginSupported}.
@@ -1027,7 +1052,7 @@ declare class Authenticator {
      * [Ditto] instance as the sole argument that allows you to perform any
      * required cleanup of the store as part of the logout process.
      */
-    logout(cleanupFn?: (Ditto: any) => void): Promise<void>;
+    logout(cleanupFn?: (ditto: Ditto) => void): Promise<void>;
     observeStatus(callback: (authenticationStatus: AuthenticationStatus) => void): Observer;
     /** @internal */
     constructor(keepAlive: KeepAlive);
@@ -1041,12 +1066,15 @@ declare class Authenticator {
     protected keepAlive: KeepAlive;
     /** @internal */
     protected observerManager: ObserverManager;
+    /** @internal */
+    protected _status: AuthenticationStatus;
 }
 /** @internal */
 declare class OnlineAuthenticator extends Authenticator {
+    readonly loginSupported: boolean;
     loginWithToken(token: string, provider: string): Promise<void>;
     loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<void>;
-    logout(cleanupFn?: (Ditto: any) => void): Promise<void>;
+    logout(cleanupFn?: (ditto: Ditto) => void): Promise<void>;
     readonly authenticationHandler: AuthenticationHandler;
     private ditto;
     constructor(keepAlive: KeepAlive, ditto: Ditto, authenticationHandler: AuthenticationHandler);
@@ -1056,11 +1084,11 @@ declare class OnlineAuthenticator extends Authenticator {
 }
 /** @internal */
 declare class NotAvailableAuthenticator extends Authenticator {
-    loginWithToken(token: string, provider: string): Promise<void>;
-    loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<void>;
-    logout(cleanupFn?: (Ditto: any) => void): Promise<void>;
-    '@ditto.authenticationExpiring'(secondsRemaining: any): void;
-    '@ditto.authClientValidityChanged'(isWebValid: boolean, isX509Valid: boolean): void;
+    loginWithToken(token: string, provider: string): Promise<never>;
+    loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<never>;
+    logout(cleanupFn?: (ditto: Ditto) => void): Promise<never>;
+    '@ditto.authenticationExpiring'(secondsRemaining: number): never;
+    '@ditto.authClientValidityChanged'(isWebValid: boolean, isX509Valid: boolean): never;
 }
 
 /**
@@ -1400,7 +1428,7 @@ declare class Subscription {
      * Returns `true` if subscription has been explicitly cancelled, `false`
      * otherwise.
      */
-    readonly isCancelled = false;
+    get isCancelled(): boolean;
     /**
      * The name of the collection that the subscription is based on.
      */
@@ -1416,8 +1444,6 @@ declare class Subscription {
      * @internal Because not exposed in any of the other SDKs (yet?).
      */
     readonly collection: Collection;
-    /** @internal */
-    private readonly manager;
     /**
      * The corresponding named arguments for {@link query}, if any.
      * @internal Because not exposed in any of the other SDKs (yet?).
@@ -1425,6 +1451,8 @@ declare class Subscription {
     readonly queryArgsCBOR: Uint8Array | null;
     /** @internal */
     readonly contextInfo: SubscriptionContextInfo;
+    private readonly manager;
+    private _isCancelled;
 }
 
 /**
@@ -1711,14 +1739,19 @@ declare class LiveQuery {
     readonly collection: Collection;
     /** @internal */
     readonly handler: QueryObservationHandler;
-    /** @internal */
+    /**
+     * This field is only populated while a live query is active and set to null
+     * when the live query is stopped.
+     *
+     * @internal
+     */
     liveQueryManager: LiveQueryManager | null;
-    /** @internal */
-    readonly liveQueryID: number;
+    get liveQueryID(): number;
     /** @internal */
     constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number, collection: Collection, handler: QueryObservationHandler);
     /** @internal */
     signalNext(): Promise<void>;
+    private _liveQueryID;
 }
 
 /** @internal */
@@ -1942,18 +1975,18 @@ declare class Ditto {
      *
      * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
      */
-    readonly isActivated: boolean;
+    get isActivated(): boolean;
     /**
      * `true` once {@link close | Ditto.close()} has been called, otherwise
      * `false`.
      */
-    readonly isClosed: boolean;
+    get isClosed(): boolean;
     /**
      * Returns `true` if sync is active, otherwise returns `false`. Use
      * {@link startSync | startSync()} to activate and
      * {@link stopSync | stopSync()} to deactivate sync.
      */
-    readonly isSyncActive: boolean;
+    get isSyncActive(): boolean;
     /**
      * Application ID associated with the {@link Identity | identity} used by this
      * Ditto instance.
@@ -2054,7 +2087,7 @@ declare class Ditto {
      * @see {@link setTransportConfig | setTransportConfig()}
      * @see {@link updateTransportConfig | updateTransportConfig()}
      */
-    readonly transportConfig: TransportConfig;
+    get transportConfig(): TransportConfig;
     /**
      * Assigns a new transports configuration. By default peer-to-peer transports
      * (Bluetooth, WiFi, and AWDL) are enabled. You may use this method to alter
@@ -2201,6 +2234,10 @@ declare class Ditto {
     private isX509Valid;
     private presenceManager;
     private transportConditionsManager;
+    private _isActivated;
+    private _isSyncActive;
+    private _isClosed;
+    private _transportConfig;
     /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
     private pendingOperations;
     private authClientValidityChanged;
@@ -2216,7 +2253,7 @@ declare class Ditto {
  * @returns `true` iff all required APIs exist on `global`.
  * @internal
  */
-declare const checkAPIs: (_globalObject?: Window | typeof globalThis) => boolean;
+declare const checkAPIs: (_globalObject?: typeof globalThis) => boolean;
 /**
  * Disable deadlock timeout when Node.js is running with `--inspect` parameter.
  *
@@ -2741,9 +2778,9 @@ declare class ExperimentalChangeListener {
     /**
      * The arguments to this listener's query.
      */
-    readonly queryArgs?: QueryArguments;
+    readonly queryArgs?: DQLQueryArguments;
     /** @internal */
-    constructor(store: ExperimentalStore, query: string, queryArgs: QueryArguments | null, onChange: ChangeHandler | ChangeHandlerWithSignalNext, onError?: ErrorHandler, withSignalNext?: boolean);
+    constructor(store: ExperimentalStore, query: string, queryArgs: DQLQueryArguments | null, onChange: ChangeHandler | ChangeHandlerWithSignalNext, onError?: ErrorHandler, withSignalNext?: boolean);
     /**
      * A change listener starts out in the `active` state and can be stopped by
      * calling {@link ExperimentalChangeListener.stop | `stop()`} or letting it go
@@ -2908,7 +2945,7 @@ declare class ExperimentalReplicationSubscription {
      * `true` when {@link cancel | cancel()} has been called or the Ditto instance
      * managing this replication subscription has been closed.
      */
-    readonly isCancelled = false;
+    get isCancelled(): boolean;
     /**
      * Cancels a replication subscription and releases all associated resources.
      */
@@ -2923,10 +2960,55 @@ declare class ExperimentalReplicationSubscription {
      * @internal
      */
     readonly queryArgsCBOR: Uint8Array | null;
-    /** @internal */
+    private _isCancelled;
     private manager;
 }
 
+/**
+ * Represents single result object.
+ * This API needs to be completed to navigate in the result object.
+ * The result object is retrieved via FFI.dqlResultCBOR(Pointer<FFIDqlResult>).
+ *
+ * Currently experimental.
+ *
+ * @internal
+ */
+declare class ExperimentalDqlResult {
+    get value(): any;
+    /** @internal */
+    storedValue: any;
+    /**
+     * FIXME: warn users who try to instantiate this class themselves
+     *
+     * @internal
+     */
+    constructor();
+}
+
+/**
+ * Represents the response from executing DQL statements.
+ * Currently experimental.
+ *
+ * The memory management is quite complex. Every time when Rust is called
+ * it will clone the result object. Rust mirror of DqlResponse contains
+ * the collection of result objects. During the getting results call
+ * Rust will copy DqlResult obejcts, thus JS here gets complete control
+ * of their lifetimes.
+ *
+ * @internal
+ */
+declare class ExperimentalDqlResponse {
+    get results(): ExperimentalDqlResult[];
+    /** @internal */
+    storedResults: ExperimentalDqlResult[] | undefined;
+    /**
+     * FIXME: warn users who try to instantiate this class themselves
+     *
+     * @internal
+     */
+    constructor();
+}
+
 /**
  * An addon for the Ditto store that contains experimental features. Accessible
  * on `ditto.store.experimental`.
@@ -2964,7 +3046,7 @@ declare class ExperimentalStore {
      *
      * @internal
      */
-    addChangeListener(query: string, onChange: ChangeHandler, onError?: ErrorHandler, queryArgs?: QueryArguments): ExperimentalChangeListener;
+    addChangeListener(query: string, onChange: ChangeHandler, onError?: ErrorHandler, queryArgs?: DQLQueryArguments): ExperimentalChangeListener;
     /**
      * Register a handler to be called whenever a query's results change in the
      * local store and control when the next invocation of the change handler
@@ -2980,7 +3062,7 @@ declare class ExperimentalStore {
      *
      * @internal
      */
-    addChangeListenerWithSignalNext(query: string, onChange: ChangeHandlerWithSignalNext, onError?: ErrorHandler, queryArgs?: QueryArguments): ExperimentalChangeListener;
+    addChangeListenerWithSignalNext(query: string, onChange: ChangeHandlerWithSignalNext, onError?: ErrorHandler, queryArgs?: DQLQueryArguments): ExperimentalChangeListener;
     /**
      * Registers a URL to be called whenever the given query observes changes.
      *
@@ -2989,7 +3071,7 @@ declare class ExperimentalStore {
      * @internal
      * @returns a promise for a document id that acts as a webhook id
      */
-    addChangeListenerWebhook(query: string, url: string, queryArgs?: QueryArguments): Promise<DocumentID>;
+    addChangeListenerWebhook(query: string, url: string, queryArgs?: DQLQueryArguments): Promise<DocumentID>;
     /**
      * Run the provided query on the device of connected peers and send the
      * results of the query back to the local peer's data store.
@@ -2997,29 +3079,44 @@ declare class ExperimentalStore {
      * The returned {@link ExperimentalReplicationSubscription} object must be kept in scope
      * for as long as you want to keep receiving updates.
      *
+     * Use placeholders to incorporate values from the optional `queryArguments`
+     * parameter into the query. The keys of the `queryArguments` object must
+     * match the placeholders used within the query. You can not use placeholders
+     * in the `FROM` clause.
+     *
      * @internal
      * @param query a Ditto Query Language query string of the form SELECT * FROM
      * collection WHERE expression
+     * @param queryArguments an object with values to be incorporated into a
+     * query. The keys of the object must match the placeholders used within the
+     * query.
      * @returns {@link ExperimentalReplicationSubscription} object
      */
-    addReplicationSubscription(query: string): ExperimentalReplicationSubscription;
+    addReplicationSubscription(query: string, queryArguments?: DQLQueryArguments): ExperimentalReplicationSubscription;
     /** @internal */
     close(): void;
     /**
      * Executes the given query in the local store and returns the result.
      *
+     * Use placeholders to incorporate values from the optional `queryArguments`
+     * parameter into the query. The keys of the `queryArguments` object must
+     * match the placeholders used within the query. You can not use placeholders
+     * in the `FROM` clause.
+     *
      * Limitations:
      *
      * - 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
+     * @param queryArguments an object with values to be incorporated into a
+     * query. The keys of the object must match the placeholders used within the
+     * query.
      * @returns a promise for an array of Ditto documents matching the query
      */
-    execute(query: string): Promise<Document[]>;
+    execute(query: string, queryArguments?: DQLQueryArguments): Promise<ExperimentalDqlResponse>;
     private replicationSubscriptionManager;
 }
 
@@ -3421,5 +3518,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, ChangeHandler, ChangeHandlerWithSignalNext, Collection, CollectionInterface, CollectionsEvent, CollectionsEventParams, CollectionsObservationHandler, ConditionSource, Connection, ConnectionType, Counter, CustomLogCallback, Ditto, Document, DocumentID, DocumentIDValue, DocumentPath, DocumentValue, ErrorHandler, ExperimentalChangeListener, ExperimentalChangeListenerManager, ExperimentalChangeListenerStatus, ExperimentalReplicationSubscription, ExperimentalReplicationSubscriptionContextInfo, ExperimentalReplicationSubscriptionManager, 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, transportConfigFromDeserializable, transportConfigToSerializable, validateDocumentIDCBOR, validateDocumentIDValue };
+export { Address, Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, BasePendingCursorOperation, BasePendingIDSpecificOperation, CBOR, ChangeHandler, ChangeHandlerWithSignalNext, Collection, CollectionInterface, CollectionsEvent, CollectionsEventParams, CollectionsObservationHandler, ConditionSource, Connection, ConnectionType, Counter, CustomLogCallback, DQLQueryArgumentValue, DQLQueryArguments, Ditto, Document, DocumentID, DocumentIDValue, DocumentPath, DocumentValue, ErrorHandler, ExperimentalChangeListener, ExperimentalChangeListenerManager, ExperimentalChangeListenerStatus, ExperimentalReplicationSubscription, ExperimentalReplicationSubscriptionContextInfo, ExperimentalReplicationSubscriptionManager, 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, transportConfigFromDeserializable, transportConfigToSerializable, validateDocumentIDCBOR, validateDocumentIDValue };
 //# sourceMappingURL=ditto.d.ts.map