@dittolive/ditto 1.1.0 → 1.1.3

package/types/ditto.d.ts

@@ -68,6 +68,25 @@ declare type InitOptions = {
  */
 declare function init(options?: InitOptions): Promise<void>;
 
+/** @internal */
+declare class KeepAlive {
+    /** @internal */
+    get isActive(): boolean;
+    /** @internal */
+    constructor();
+    /** @internal */
+    retain(id: string): void;
+    /** @internal */
+    release(id: string): void;
+    /** @internal */
+    currentIDs(): string[];
+    /** @internal */
+    countForID(id: string): number | null;
+    private static finalizationRegistry;
+    private intervalID;
+    private countsByID;
+}
+
 /**
  * Part of {@link TransportConfig} type, configuration for listening for TCP
  * connections.
@@ -315,6 +334,8 @@ interface IdentityManual {
     certificate: string;
 }
 /**
+ * Deprecated - use `IdentityOnlinePlaygroundV2` instead.
+ *
  * Test a Ditto Cloud app without authentication ("Playground mode"). This mode
  * offers no security and must only be used for development.
  */
@@ -327,6 +348,40 @@ interface IdentityOnlinePlayground {
     appID: string;
     /** If true, auto-configure sync with Ditto Cloud. Default is `true`. */
     enableDittoCloudSync?: boolean;
+    /**
+     * A custom Ditto Cloud URL.
+     * @internal
+     */
+    customDittoCloudURL?: string;
+}
+/**
+ * Test a Ditto Cloud app with weak shared token authentication ("Playground
+ * mode"). This mode is not secure and must only be used for development.
+ */
+interface IdentityOnlinePlaygroundV2 {
+    type: 'onlinePlaygroundV2';
+    /**
+     * An ID identifying this app registration on the Ditto portal, which can be
+     * found at https://portal.ditto.live.
+     */
+    appID: string;
+    /**
+     * A shared token used to set up the OnlinePlayground session. This token is
+     * provided by the Ditto Portal when setting up the application.
+     */
+    token: string;
+    /** If true, auto-configure sync with Ditto Cloud. Default is `true`. */
+    enableDittoCloudSync?: boolean;
+    /**
+     * If specified, use a custom authentication service instead of Ditto Cloud.
+     * @internal
+     */
+    customAuthURL?: string;
+    /**
+     * A custom Ditto Cloud URL.
+     * @internal
+     */
+    customDittoCloudURL?: string;
 }
 /**
  * Deprecated - use `IdentityOnlineWithAuthentication` instead.
@@ -372,6 +427,11 @@ interface IdentityOnline {
      * If specified, use a custom authentication service instead of Ditto Cloud.
      */
     customAuthURL?: string;
+    /**
+     * A custom Ditto Cloud URL.
+     * @internal
+     */
+    customDittoCloudURL?: string;
 }
 /**
  * Run Ditto in secure production mode, logging on to Ditto Cloud or an
@@ -412,17 +472,21 @@ interface IdentityOnlineWithAuthentication {
      * If specified, use a custom authentication service instead of Ditto Cloud.
      */
     customAuthURL?: string;
+    /**
+     * A custom Ditto Cloud URL.
+     * @internal
+     */
+    customDittoCloudURL?: string;
 }
 /**
  * The various identity configurations that you can use when initializing a
  * `Ditto` instance.
  */
-declare type Identity = IdentityDevelopment | IdentityOfflinePlayground | IdentitySharedKey | IdentityProduction | IdentityManual | IdentityOnlinePlayground | IdentityOnline | IdentityOnlineWithAuthentication;
+declare type Identity = IdentityDevelopment | IdentityOfflinePlayground | IdentitySharedKey | IdentityProduction | IdentityManual | IdentityOnlinePlayground | IdentityOnlinePlaygroundV2 | IdentityOnline | IdentityOnlineWithAuthentication;
+/** The list of identity types that require activation through an offlineLicenseToken */
+declare const IdentityTypesRequiringOfflineLicenseToken: string[];
 
-/**
- * TODO: document.
- * @internal
- */
+/** @internal */
 declare class Bridge<JSClass extends object, FFIType> {
     type: Function;
     release: (pointer: Pointer<FFIType>) => void;
@@ -431,18 +495,24 @@ declare class Bridge<JSClass extends object, FFIType> {
      * that is called whenever a registered object is garbage collected, passing
      * the associated `pointer` to it. The release function is then responsible
      * to free or drop the corresponding native object.
+     *
+     * @internal
      */
     constructor(type: Function, release: (pointer: Pointer<FFIType>) => void, options?: {});
     /**
      * Returns the FFI pointer for `object` if registered, otherwise returns
      * `undefined`. If `object` has been unregistered before, returns
      * `undefined`, too.
+     *
+     * @internal
      */
     pointerFor(object: JSClass): Pointer<FFIType> | undefined;
     /**
      * Convenience method, returns the object for the FFI `pointer` if registered,
      * otherwise returns `undefined`. If the object associated with the `pointer`
      * has been unregistered before, returns `undefined`, too.
+     *
+     * @internal
      */
     objectFor(pointer: Pointer<FFIType>): JSClass | undefined;
     /**
@@ -451,16 +521,20 @@ declare class Bridge<JSClass extends object, FFIType> {
      * returns after registering. If no `create` function is given, uses the
      * type of the bridge as a constructor and creates a new instance of it
      * without passing any parameters.
+     *
+     * @internal
      */
-    bridge(pointer: Pointer<FFIType>, create?: () => JSClass, options?: {}): JSClass;
-    /**
-     * TODO: document.
-     */
+    bridge(pointer: Pointer<FFIType>, objectOrCreate?: object | (() => JSClass), options?: {}): JSClass;
+    /** @internal */
     register(object: JSClass, pointer: Pointer<FFIType>): void;
-    /**
-     * TODO: document.
-     */
+    /** @internal */
     unregister(object: JSClass): void;
+    /** @internal */
+    unregisterAll(): void;
+    /** @internal */
+    get count(): number;
+    /** @internal */
+    static readonly all: any[];
     private metaByAddrMap;
     private finalizationRegistry;
     private finalize;
@@ -715,6 +789,10 @@ declare class Document {
      * represents the passed in document(s).
      */
     static hashMnemonic(documentOrMany: DocumentLike | DocumentLike[]): string;
+    /**
+     * Support for JSON-stringifying a document directly.
+     */
+    toJSON(): DocumentValue;
     /** @internal */
     constructor();
     /** @internal */
@@ -789,6 +867,10 @@ declare class MutableDocument {
      * Increments the counter of `mutableDocument` at the given `keyPath`.
      */
     static incrementCounterAt(mutableDocument: MutableDocumentLike, keyPath: string, amount: number, skipValidation?: boolean): void;
+    /**
+     * Support for JSON-stringifying a mutable document directly.
+     */
+    toJSON(): DocumentValue;
     /** @internal */
     constructor();
     /** @internal */
@@ -1017,6 +1099,9 @@ declare class UpdateResultsMap {
  * {@link PendingCursorOperation} object. It handles the logic for calling the
  * event handler that is provided to `observe` calls.
  *
+ * Ditto will prevent the process from exiting as long as there are
+ * active live queries (not relevant when running in the browser).
+ *
  * `LiveQuery` objects must be kept in scope for as long as you wish to have
  * your event handler be called when there is an update to a document matching
  * the query you provide. When you no longer want to receive updates about
@@ -1029,6 +1114,8 @@ declare class LiveQuery {
     readonly queryArgs: QueryArguments | null;
     /** The name of the collection that the live query is based on. */
     get collectionName(): string;
+    /** Returns true if the receiver has been stopped. */
+    get isStopped(): boolean;
     /**
      * Stop the live query from delivering updates.
      */
@@ -1686,8 +1773,8 @@ declare class Collection {
      * attachment into a document.
      *
      * ``` JavaScript
-     * const attachment = collection.newAttachment('/path/to/my/file.pdf')
-     * collection.insert({ _id: '123', attachment, other: 'some-string' })
+     * const attachment = await collection.newAttachment('/path/to/my/file.pdf')
+     * await collection.insert({ _id: '123', attachment, other: 'some-string' })
      * }
      * ```
      *
@@ -1698,7 +1785,7 @@ declare class Collection {
      */
     newAttachment(pathOrData: string | Uint8Array, metadata?: {
         [key: string]: string;
-    }): Attachment;
+    }): Promise<Attachment>;
     /**
      * Trigger an attachment to be downloaded locally to the device and observe
      * its progress as it does so.
@@ -1930,14 +2017,14 @@ declare class Store {
      * Returns the names of all available collections in the store of the
      * related {@link Ditto} instance.
      */
-    collectionNames(): string[];
+    collectionNames(): Promise<string[]>;
     /** @internal */
     constructor(ditto: Ditto);
     /**
      * Private method, used only by the Portal https://github.com/getditto/ditto/pull/3652
      * @internal
      */
-    registerLiveQueryWebhook(collectionName: string, query: string, url: string): DocumentIDValue;
+    registerLiveQueryWebhook(collectionName: string, query: string, url: string): Promise<DocumentIDValue>;
 }
 
 /** @internal */
@@ -1950,8 +2037,8 @@ declare type ObserverOptions = {
 };
 /**
  * Generic observer handle returned by various observation APIs. The observation
- * remains active until the {@link stop | stop()} method is called explicitly or the
- * observer instance is garbage collected. Therefore, to keep the observation
+ * remains active until the {@link stop | stop()} method is called explicitly or
+ * the observer instance is garbage collected. Therefore, to keep the observation
  * alive, you have to keep a reference to the corresponding observer.
  */
 declare class Observer {
@@ -2033,9 +2120,9 @@ declare class Ditto {
      */
     readonly siteID: number | BigInt;
     /**
-     * Returns `true` if a license token has been set, otherwise returns `false`.
+     * Returns `true` if an offline license token has been set, otherwise returns `false`.
      *
-     * @see {@link setLicenseToken | setLicenseToken()}
+     * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
      */
     readonly isActivated: boolean;
     /**
@@ -2057,7 +2144,9 @@ declare class Ditto {
      * using this to create a Ditto instance in the web browser will throw an
      * exception.
      *
-     * @param identity - Identity for the new Ditto instance.
+     * @param identity - Identity for the new Ditto instance, defaults to
+     * `offlinePlayground` with `appID` being the empty string `''`.
+     *
      * @param path - On Node, `path` corresponds to a real directory
      * on the file system (intermediate directories are created if needed). In the
      * browser, `path` is used as an internal namespace into the backing storage
@@ -2067,19 +2156,39 @@ declare class Ditto {
      * @see {@link identity}
      * @see {@link path}
      */
-    constructor(identity: Identity, path?: string);
+    constructor(identity?: Identity, path?: string);
     /**
-     * Activate a `Ditto` instance by setting a license token. You cannot sync
-     * with `Ditto` before you have activated it.
+     * @deprecated use {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()} instead.
+     * Activate a `Ditto` instance by setting an offline only license token. You cannot initiate sync
+     * with `Ditto` before you have activated it. The offline license token is only valid for identities
+     * of type `development`, `manual`, `offlinePlayground`, and `sharedKey`.
      *
      * @param licenseToken the license token to activate the `Ditto` instance
-     * with. You can find yours on the Ditto portal (https://portal.ditto.live).
+     * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
+     */
+    setAccessLicense(accessLicense: string): void;
+    /**
+     * Activate a `Ditto` instance by setting an offline only license token. You cannot initiate sync
+     * with `Ditto` before you have activated it. The offline license token is only valid for identities
+     * of type `development`, `manual`, `offlinePlayground`, and `sharedKey`.
+     *
+     * @deprecated use {@link setOfflineOnlyLicenseToken} for identities of type `development`, `manual`,
+     * `offlinePlayground`, and `sharedKey`.
+     *
+     *
+     * @param licenseToken the license token to activate the `Ditto` instance
+     * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
      */
     setLicenseToken(licenseToken: string): void;
     /**
-     * @deprecated use {@link setLicenseToken | setLicenseToken()} instead.
+     * Activate a `Ditto` instance by setting an offline only license token. You cannot initiate sync
+     * with `Ditto` before you have activated it. The offline license token is only valid for identities
+     * of type `development`, `manual`, `offlinePlayground`, and `sharedKey`.
+     *
+     * @param licenseToken the license token to activate the `Ditto` instance
+     * with. You can find yours on the [Ditto portal](https://portal.ditto.live).
      */
-    setAccessLicense(accessLicense: string): void;
+    setOfflineOnlyLicenseToken(licenseToken: string): void;
     /**
      * Returns the current transport configuration, frozen. If you want to modify
      * the transport config, make a {@link TransportConfig.copy | copy} first. Or
@@ -2122,6 +2231,9 @@ declare class Ditto {
      * customized with `setTransportConfig()`. On the **Web**, only connecting via
      * Websockets is supported.
      *
+     * Ditto will prevent the process from exiting until sync is stopped (not
+     * relevant when running in the browser).
+     *
      * @see {@link isSyncActive}
      * @see {@link stopSync | stopSync()}
      */
@@ -2139,6 +2251,9 @@ declare class Ditto {
     /**
      * Registers an observer for info about Ditto peers in range of this device.
      *
+     * Ditto will prevent the process from exiting as long as there are active
+     * peers observers (not relevant when running in the browser).
+     *
      * @param callback called immediately with the current state of peers
      * in range and whenever that state changes. Then it will be invoked
      * repeatedly when Ditto devices come and go, or the active connections to
@@ -2148,6 +2263,9 @@ declare class Ditto {
     /**
      * Register observer for changes of underlying transport conditions.
      *
+     * Ditto will prevent the process from exiting as long as there are active
+     * transport conditions observers (not relevant when running in the browser).
+     *
      * @param callback called when underlying transport conditions change with
      * the changed `condition` and it's `source`.
      */
@@ -2168,6 +2286,8 @@ declare class Ditto {
      * Only available in Node environments at the moment, no-op in the browser.
      */
     runGarbageCollection(): void;
+    /** @internal */
+    keepAlive: KeepAlive;
     private sync;
     private isWebValid;
     private isX509Valid;
@@ -2177,9 +2297,7 @@ declare class Ditto {
     private validateIdentity;
     private setSyncEnabled;
 }
-/**
- * @internal
- */
+/** @internal */
 declare const dittoBridge: Bridge<Ditto, "CDitto_t">;
 
 /** @internal */
@@ -2187,7 +2305,11 @@ declare type ObserverToken = string;
 /** @internal */
 declare class ObserverManager {
     /** @internal */
-    constructor();
+    readonly id: string;
+    /** @internal */
+    readonly keepAlive: KeepAlive | null;
+    /** @internal */
+    constructor(id: string, keepAlive?: KeepAlive | null);
     /** @internal */
     addObserver(callback: any): ObserverToken;
     /** @internal */
@@ -2322,11 +2444,14 @@ declare class Authenticator {
     logout(cleanupFn?: (Ditto: any) => void): Promise<void>;
     observeStatus(callback: (authenticationStatus: AuthenticationStatus) => void): Observer;
     /** @internal */
-    constructor();
+    constructor(keepAlive: KeepAlive);
     /** @internal */
     '@ditto.authenticationExpiring': (number: any) => void;
     /** @internal */
     '@ditto.authClientValidityChanged': (isWebValid: boolean, isX509Valid: boolean) => void;
+    /** @internal */
+    protected keepAlive: KeepAlive;
+    /** @internal */
     protected observerManager: ObserverManager;
 }
 /** @internal */
@@ -2337,7 +2462,7 @@ declare class OnlineAuthenticator extends Authenticator {
     readonly authClientPointer: Pointer<AuthClientType>;
     readonly authenticationHandler: AuthenticationHandler;
     private ditto;
-    constructor(authClientPointer: Pointer<AuthClientType>, ditto: Ditto, authenticationHandler: AuthenticationHandler);
+    constructor(keepAlive: KeepAlive, authClientPointer: Pointer<AuthClientType>, ditto: Ditto, authenticationHandler: AuthenticationHandler);
     '@ditto.authenticationExpiring': (secondsRemaining: number) => void;
     '@ditto.authClientValidityChanged': (isWebValid: boolean, isX509Valid: boolean) => void;
     private updateAndNotify;
@@ -2350,7 +2475,6 @@ declare class NotAvailableAuthenticator extends Authenticator {
     loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<void>;
     logout(cleanupFn?: (Ditto: any) => void): Promise<void>;
     '@ditto.authenticationExpiring': (secondsRemaining: any) => never;
-    /** @internal */
     '@ditto.authClientValidityChanged': (isWebValid: boolean, isX509Valid: boolean) => void;
 }
 
@@ -2562,5 +2686,5 @@ declare class CBOR {
     static decode(data: Uint8Array): any;
 }
 
-export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, CBOR, Collection, CollectionsEvent, CollectionsEventParams, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentIDValue, DocumentLike, DocumentPath, DocumentValue, Identity, IdentityDevelopment, IdentityManual, IdentityOfflinePlayground, IdentityOnline, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentityProduction, IdentitySharedKey, InitOptions, InsertOptions, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableDocument, MutableDocumentLike, MutableDocumentPath, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, __log, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge, validateDocumentIDCBOR, validateDocumentIDValue };
+export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, CBOR, Collection, CollectionsEvent, CollectionsEventParams, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentIDValue, DocumentLike, DocumentPath, DocumentValue, Identity, IdentityDevelopment, IdentityManual, IdentityOfflinePlayground, IdentityOnline, IdentityOnlinePlayground, IdentityOnlinePlaygroundV2, IdentityOnlineWithAuthentication, IdentityProduction, IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, InitOptions, InsertOptions, KeepAlive, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableDocument, MutableDocumentLike, MutableDocumentPath, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, __log, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge, validateDocumentIDCBOR, validateDocumentIDValue };
 //# sourceMappingURL=ditto.d.ts.map