@dittolive/ditto 1.0.18 → 1.1.1

package/types/ditto.d.ts

@@ -5,6 +5,25 @@ declare type SortDirection = 'ascending' | 'descending';
 /**
  * Defines the various strategies available when inserting a document into a
  * collection.
+ *
+ * - `merge`: the existing document will be merged with the document being
+ *    inserted, if there is a pre-existing document.
+ *
+ * - `overwrite`: an existing document will be overwritten. This can be thought
+ *    of as first removing the existing document completely and then inserting
+ *    the new document in its place, if there is a pre-existing document.
+ *
+ * - `insertIfAbsent`: insert the document only if there is not already a
+ *    document with the same ID in the store. If there is already a document in
+ *    the store with the same ID then this will be a no-op.
+ *
+ * - `insertDefaultIfAbsent`: insert the document, with its contents treated as
+ *    default data, only if there is not already a document with the same ID in
+ *    the store. If there is already a document in the store with the same ID
+ *    then this will be a no-op. Use this strategy if you want to insert default
+ *    data for a given document ID, which you want to treat as common initial
+ *    data amongst all peers and that you expect to be mutated or overwritten in
+ *    due course.
  */
 declare type WriteStrategy = 'merge' | 'overwrite' | 'insertIfAbsent' | 'insertDefaultIfAbsent';
 /**
@@ -49,95 +68,173 @@ 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;
+}
+
 /**
- * Provides feedback to the developer about Ditto authentication status.
+ * Part of {@link TransportConfig} type, configuration for listening for TCP
+ * connections.
  */
-interface AuthenticationHandler {
-    /**
-     * There is no Ditto authentication token or it has expired. Sync will not
-     * work until there is a successful login using one of the login methods on
-     * {@link Authenticator}.
-     */
-    authenticationRequired(authenticator: Authenticator): any;
+interface TransportConfigListenTCP {
+    isEnabled: boolean;
+    interfaceIP: string;
+    port: number;
+}
+/**
+ * Part of {@link TransportConfig} type, configuration for listening for HTTP,
+ * including Websocket, connections.
+ */
+interface TransportConfigListenHTTP {
+    isEnabled: boolean;
+    interfaceIP: string;
+    port: number;
+    staticContentPath?: string;
+    websocketSync: boolean;
+    tlsKeyPath?: string;
+    tlsCertificatePath?: string;
+}
+/**
+ * Part of {@link TransportConfig} type, configuration for all P2P transports.
+ */
+interface TransportConfigPeerToPeer {
+    bluetoothLE: {
+        isEnabled: boolean;
+    };
+    awdl: {
+        isEnabled: boolean;
+    };
+    lan: TransportConfigLan;
+}
+/**
+ * Part of {@link TransportConfig} type, configuration for discovering and syncing with peers on LAN.
+ */
+interface TransportConfigLan {
+    isEnabled: boolean;
+    isMdnsEnabled: boolean;
+    isMulticastEnabled: boolean;
+}
+/**
+ * Part of {@link TransportConfig} type, configuration for connecting to TCP
+ * and Websocket servers.
+ */
+interface TransportConfigConnect {
+    tcpServers: string[];
+    websocketURLs: string[];
+}
+/**
+ * Part of {@link TransportConfig} type, configuration for listening for
+ * incoming TCP and HTTP connections.
+ */
+interface TransportConfigListen {
+    tcp: TransportConfigListenTCP;
+    http: TransportConfigListenHTTP;
+}
+/**
+ * Part of {@link TransportConfig} type, settings not associated with any specific type of transport.
+ */
+interface TransportConfigGlobal {
     /**
-     * Warns that the Ditto authentication token is getting old.
+     * The sync group for this device.
      *
-     * Ditto will attempt to refresh tokens periodically, starting from halfway
-     * through the token's validity period. This reduces the risk of
-     * authentication expiring while the user is offline.
+     * When peer-to-peer transports are enabled, all devices with the same App ID will
+     * normally form an interconnected mesh network. In some situations it may be
+     * desirable to have distinct groups of devices within the same app, so that
+     * connections will only be formed within each group. The `syncGroup` parameter
+     * changes that group membership. A device can only ever be in one sync group, which
+     * by default is group 0. Up to 2^32 distinct group numbers can be used in an app.
      *
-     * The refresh will happen automatically if Ditto has a suitable refresh
-     * token. If new credentials are required, such as a third-party token or a
-     * username/password, then Ditto does not cache that information and you must
-     * submit it again using one of the `login` methods on {@link Authenticator}.
+     * This is an optimization, not a security control. If a connection is created
+     * manually, such as by specifying a `connect` transport, then devices from
+     * different sync groups will still sync as normal. If two groups of devices are
+     * intended to have access to different data sets, this must be enforced using
+     * Ditto's permissions system.
      */
-    authenticationExpiringSoon(authenticator: Authenticator, secondsRemaining: number): any;
+    syncGroup: number;
 }
 /**
- * Log in to a remote authentication service, using an
- * `OnlineWithAuthentication` or an `Online` identity.
+ * A configuration object specifying which network transports Ditto should
+ * use to sync data.
+ *
+ * A Ditto object comes with a default transport configuration where all
+ * available peer-to-peer transports are enabled. You can customize this by
+ * copying that or initializing a new `TransportConfig`, adjusting its
+ * properties, and supplying it to `setTransportConfig()` on `Ditto`.
+ *
+ * When you initialize a new `TransportConfig` instance, all  transports are
+ * disabled. You must enable each one explicitly.
+ *
+ * Peer-to-peer transports will automatically discover peers in the vicinity
+ * and create connections without any configuration. These are configured via
+ * the `peerToPeer` property. To turn each one on, set its `isEnabled` property
+ * to `true`.
+ *
+ * To connect to a peer at a known location, such as a Ditto Big Peer, add its
+ * address inside the connect configuration. These are either "host:port"
+ * strings for raw TCP sync, or a "wss://…" URL for websockets.
+ *
+ * The listen configurations are for specific less common data sync scenarios.
+ * Please read the documentation on the Ditto website for examples. Incorrect
+ * use of listen can result in insecure configurations.
+ *
+ * **IMPORTANT**: when running in the browser, only the `connect.websocketURLs`
+ * part is considered, the rest of the configuration is ignored.
  */
-interface Authenticator {
+declare class TransportConfig {
+    /** Configuration for peer-to-peer connections. */
+    readonly peerToPeer: TransportConfigPeerToPeer;
+    /** Configuration for connecting to servers. */
+    readonly connect: TransportConfigConnect;
+    /** Configuration for listening for incomping connections. */
+    readonly listen: TransportConfigListen;
+    /** Settings not associated with any specific type of transport. */
+    readonly global: TransportConfigGlobal;
     /**
-     * Returns `true` if authentication is avaiable and the login methods can be
-     * used, otherwise returns `false`. Currently, authentication is only
-     * available if Ditto was initialized with an identity of type
-     * {@link IdentityOnlineWithAuthentication | 'onlineWithAuthentication'}.
+     * Create a new transport config initialized with the default settings.
      */
-    readonly loginSupported: boolean;
+    constructor();
     /**
-     * Log in to Ditto with a third-party token. Throws if authentication is not
-     * available, which can be checked with {@link loginSupported}.
-     *
-     * @param token the authentication token required to log in.
-     * @param options.provider the name of the authentication provider.
+     * Enables all peer-to-peer transports. Throws if receiver is frozen.
      */
-    loginWithToken(token: string, options?: any): Promise<void>;
+    setAllPeerToPeerEnabled(enabled: boolean): void;
     /**
-     * Log in to Ditto with a username and password. Throws if authentication is
-     * not available, which can be checked with {@link loginSupported}.
-     *
-     * @param username the username component of the credentials used for log in.
-     * @param password the password component of the credentials used for log in.
-     * @param options.provider the name of the authentication provider.
+     * Returns `true` if the transport configuration is frozen, otherwise
+     * returns `false`.
      */
-    loginWithUsernameAndPassword(username: string, password: string, options?: any): Promise<void>;
+    readonly isFrozen: boolean;
     /**
-     * Query whether Ditto has a valid authentication token.
-     *
-     * This will only be `true` when using an `OnlineWithAuthentication` or an
-     * `Online` identity, after a successful login. If the authentication token is
-     * allowed to expire then it will return `false` instead.
+     * (Deep) freezes the receiver such that it can't be modified anymore.
      */
-    isAuthenticated(): boolean;
+    freeze(): TransportConfig;
     /**
-     * Return the currently logged-in user ID.
-     *
-     * This will be `null` if there is no valid authentication or
-     * `OnlineWithAuthentication`/`Online` mode is not being used.
+     * Returns a (deep) copy of the receiver.
      */
-    readonly userID: string | null;
-}
-/** @internal */
-declare class OnlineWithAuthenticationAuthenticator implements Authenticator {
-    readonly loginSupported: boolean;
-    loginWithToken(token: string, provider: string): Promise<void>;
-    loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<void>;
-    isAuthenticated(): boolean;
-    readonly authClientPointer: Pointer<AuthClientType>;
-    constructor(authClientPointer: Pointer<AuthClientType>);
-    private static finalizationRegistry;
-    private static finalize;
-    get userID(): string | null;
-}
-/** @internal */
-declare class NotAvailableAuthenticator implements Authenticator {
-    readonly loginSupported: boolean;
-    loginWithToken(token: string, options?: any): Promise<void>;
-    loginWithUsernameAndPassword(username: string, password: string, options?: any): Promise<void>;
-    isAuthenticated(): boolean;
-    get userID(): string | null;
-    constructor();
+    copy(): TransportConfig;
+    /**
+     * Returns `true` if passed in TCP configurations are equal, otherwise
+     * returns `false`.
+     */
+    static areListenTCPsEqual(left: TransportConfigListenTCP, right: TransportConfigListenTCP): boolean;
+    /**
+     * Returns `true` if passed in HTTP configurations are equal, otherwise
+     * returns `false`.
+     */
+    static areListenHTTPsEqual(left: TransportConfigListenHTTP, right: TransportConfigListenHTTP): boolean;
 }
 
 /**
@@ -341,156 +438,6 @@ interface IdentityOnlineWithAuthentication {
  */
 declare type Identity = IdentityDevelopment | IdentityOfflinePlayground | IdentitySharedKey | IdentityProduction | IdentityManual | IdentityOnlinePlayground | IdentityOnline | IdentityOnlineWithAuthentication;
 
-/**
- * Part of {@link TransportConfig} type, configuration for listening for TCP
- * connections.
- */
-interface TransportConfigListenTCP {
-    isEnabled: boolean;
-    interfaceIP: string;
-    port: number;
-}
-/**
- * Part of {@link TransportConfig} type, configuration for listening for HTTP,
- * including Websocket, connections.
- */
-interface TransportConfigListenHTTP {
-    isEnabled: boolean;
-    interfaceIP: string;
-    port: number;
-    staticContentPath?: string;
-    websocketSync: boolean;
-    tlsKeyPath?: string;
-    tlsCertificatePath?: string;
-}
-/**
- * Part of {@link TransportConfig} type, configuration for all P2P transports.
- */
-interface TransportConfigPeerToPeer {
-    bluetoothLE: {
-        isEnabled: boolean;
-    };
-    awdl: {
-        isEnabled: boolean;
-    };
-    lan: TransportConfigLan;
-}
-/**
- * Part of {@link TransportConfig} type, configuration for discovering and syncing with peers on LAN.
- */
-interface TransportConfigLan {
-    isEnabled: boolean;
-    isMdnsEnabled: boolean;
-    isMulticastEnabled: boolean;
-}
-/**
- * Part of {@link TransportConfig} type, configuration for connecting to TCP
- * and Websocket servers.
- */
-interface TransportConfigConnect {
-    tcpServers: string[];
-    websocketURLs: string[];
-}
-/**
- * Part of {@link TransportConfig} type, configuration for listening for
- * incoming TCP and HTTP connections.
- */
-interface TransportConfigListen {
-    tcp: TransportConfigListenTCP;
-    http: TransportConfigListenHTTP;
-}
-/**
- * Part of {@link TransportConfig} type, settings not associated with any specific type of transport.
- */
-interface TransportConfigGlobal {
-    /**
-     * The sync group for this device.
-     *
-     * When peer-to-peer transports are enabled, all devices with the same App ID will
-     * normally form an interconnected mesh network. In some situations it may be
-     * desirable to have distinct groups of devices within the same app, so that
-     * connections will only be formed within each group. The `syncGroup` parameter
-     * changes that group membership. A device can only ever be in one sync group, which
-     * by default is group 0. Up to 2^32 distinct group numbers can be used in an app.
-     *
-     * This is an optimization, not a security control. If a connection is created
-     * manually, such as by specifying a `connect` transport, then devices from
-     * different sync groups will still sync as normal. If two groups of devices are
-     * intended to have access to different data sets, this must be enforced using
-     * Ditto's permissions system.
-     */
-    syncGroup: number;
-}
-/**
- * A configuration object specifying which network transports Ditto should
- * use to sync data.
- *
- * A Ditto object comes with a default transport configuration where all
- * available peer-to-peer transports are enabled. You can customize this by
- * copying that or initializing a new `TransportConfig`, adjusting its
- * properties, and supplying it to `setTransportConfig()` on `Ditto`.
- *
- * When you initialize a new `TransportConfig` instance, all  transports are
- * disabled. You must enable each one explicitly.
- *
- * Peer-to-peer transports will automatically discover peers in the vicinity
- * and create connections without any configuration. These are configured via
- * the `peerToPeer` property. To turn each one on, set its `isEnabled` property
- * to `true`.
- *
- * To connect to a peer at a known location, such as a Ditto Big Peer, add its
- * address inside the connect configuration. These are either "host:port"
- * strings for raw TCP sync, or a "wss://…" URL for websockets.
- *
- * The listen configurations are for specific less common data sync scenarios.
- * Please read the documentation on the Ditto website for examples. Incorrect
- * use of listen can result in insecure configurations.
- *
- * **IMPORTANT**: when running in the browser, only the `connect.websocketURLs`
- * part is considered, the rest of the configuration is ignored.
- */
-declare class TransportConfig {
-    /** Configuration for peer-to-peer connections. */
-    readonly peerToPeer: TransportConfigPeerToPeer;
-    /** Configuration for connecting to servers. */
-    readonly connect: TransportConfigConnect;
-    /** Configuration for listening for incomping connections. */
-    readonly listen: TransportConfigListen;
-    /** Settings not associated with any specific type of transport. */
-    readonly global: TransportConfigGlobal;
-    /**
-     * Create a new transport config initialized with the default settings.
-     */
-    constructor();
-    /**
-     * Enables all peer-to-peer transports. Throws if receiver is frozen.
-     */
-    setAllPeerToPeerEnabled(enabled: boolean): void;
-    /**
-     * Returns `true` if the transport configuration is frozen, otherwise
-     * returns `false`.
-     */
-    readonly isFrozen: boolean;
-    /**
-     * (Deep) freezes the receiver such that it can't be modified anymore.
-     */
-    freeze(): TransportConfig;
-    /**
-     * Returns a (deep) copy of the receiver.
-     */
-    copy(): TransportConfig;
-    /**
-     * Returns `true` if passed in TCP configurations are equal, otherwise
-     * returns `false`.
-     */
-    static areListenTCPsEqual(left: TransportConfigListenTCP, right: TransportConfigListenTCP): boolean;
-    /**
-     * Returns `true` if passed in HTTP configurations are equal, otherwise
-     * returns `false`.
-     */
-    static areListenHTTPsEqual(left: TransportConfigListenHTTP, right: TransportConfigListenHTTP): boolean;
-}
-
 /**
  * TODO: document.
  * @internal
@@ -787,8 +734,18 @@ 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 */
+    static idCBOR(document: DocumentLike): Uint8Array;
+    /** @internal */
+    static canonicalizedIDCBOR(idCBOR: Uint8Array): Uint8Array;
+    /** @internal */
+    static isIDCBORCanonical(idCBOR: Uint8Array): boolean;
 }
 /**
  * A representation of a {@link Document} that can be mutated via
@@ -855,12 +812,26 @@ 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 */
     readonly '@ditto.updateResults': UpdateResult[];
+    /** @internal */
+    static idCBOR(mutableDocument: MutableDocumentLike): Uint8Array;
+    /** @internal */
+    static canonicalizedIDCBOR: typeof Document.canonicalizedIDCBOR;
+    /** @internal */
+    static isIDCBORCanonical: typeof Document.isIDCBORCanonical;
 }
 /** @internal */
+declare function validateDocumentIDValue(id: DocumentIDValue): DocumentIDValue;
+/** @internal */
+declare function validateDocumentIDCBOR(idCBOR: Uint8Array): Uint8Array;
+/** @internal */
 declare const documentBridge: Bridge<Document, "CDocument_t">;
 /** @internal */
 declare const mutableDocumentBridge: Bridge<MutableDocument, "CDocument_t">;
@@ -1073,6 +1044,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
@@ -1085,6 +1059,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.
      */
@@ -1627,7 +1603,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<DocumentLike | u
      */
     update(closure: (document: MutableDocumentLike) => void): Promise<UpdateResult[]>;
     /** @internal */
-    constructor(documentID: DocumentIDValue, collection: Collection);
+    constructor(documentID: DocumentIDValue, collection: Collection, skipIDEncodingAndValidation?: boolean);
     /** @internal */
     then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
     private documentIDCBOR;
@@ -1640,6 +1616,9 @@ declare type InsertOptions = {
     isDefault?: boolean;
     writeStrategy?: WriteStrategy;
 };
+declare type UpsertOptions = {
+    writeStrategy?: WriteStrategy;
+};
 /**
  * Represents a collection of a Ditto store.
  *
@@ -1690,6 +1669,17 @@ declare class Collection {
      * @param id The ID of the document to find.
      */
     findByID(id: DocumentIDValue): PendingIDSpecificOperation;
+    /**
+     * Inserts a new document into the collection and returns its ID. If the
+     * document already exists, the contents of both are merged by default. You
+     * can change this by providing a different `writeStrategy` via `options`.
+     *
+     * @param value The content for the new document to insert or update.
+     *
+     * @param options.writeStrategy Specifies the desired strategy for inserting a
+     * document, defaults to `'merge'`.
+     */
+    upsert(value: DocumentValue, options?: UpsertOptions): Promise<DocumentIDValue>;
     /**
      * Inserts a new document into the collection and returns its ID.
      *
@@ -1708,6 +1698,8 @@ declare class Collection {
      *
      * @param options.writeStrategy Specifies the desired strategy for inserting a
      * document. The default value is `'overwrite'`.
+     *
+     * @deprecated: use `upsert()` instead.
      */
     insert(value: DocumentValue, options?: InsertOptions): Promise<DocumentIDValue>;
     /**
@@ -1762,6 +1754,10 @@ declare class Collection {
     fetchAttachment(token: AttachmentToken, eventHandler?: (AttachmentFetchEvent: any) => void): AttachmentFetcher;
     /** @internal */
     constructor(name: string, store: Store);
+    /** @internal */
+    findByIDCBOR(idCBOR: Uint8Array): PendingIDSpecificOperation;
+    /** @private */
+    private _insert;
 }
 
 /** @internal */
@@ -1980,10 +1976,14 @@ declare class Store {
 interface ObserverRemoving {
     removeObserver(token: any): any;
 }
+/** @internal */
+declare type ObserverOptions = {
+    stopsWhenFinalized?: boolean;
+};
 /**
  * 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 {
@@ -1992,7 +1992,9 @@ declare class Observer {
     /** @internal */
     readonly token?: any;
     /** @internal */
-    constructor(observerManager: ObserverRemoving, token: any);
+    readonly options?: ObserverOptions;
+    /** @internal */
+    constructor(observerManager: ObserverRemoving, token: any, options?: ObserverOptions);
     /**
      * Returns `true` if the observer has been explicitly stopped via the `stop()`
      * method. Otherwise returns `false`.
@@ -2068,12 +2070,18 @@ declare class Ditto {
      * @see {@link setLicenseToken | setLicenseToken()}
      */
     readonly isActivated: boolean;
+    /**
+     * Returns `true` if sync active, otherwise returns `false`. Use
+     * tryStartSync() to active and `stopSync()` to deactivate sync.
+     */
+    readonly isSyncActive: boolean;
     /**
      * Returns `true` if sync has been started, returns `false` if it has
      * been stopped. Returns `false` if sync has never been started for this
      * instance.
+     * @deprecated: use isSyncActive instead.
      */
-    readonly isSyncEnabled: boolean;
+    get isSyncEnabled(): boolean;
     /**
      * Initializes a new `Ditto` instance.
      *
@@ -2081,7 +2089,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
@@ -2091,7 +2101,7 @@ 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.
@@ -2146,7 +2156,10 @@ declare class Ditto {
      * customized with `setTransportConfig()`. On the **Web**, only connecting via
      * Websockets is supported.
      *
-     * @see {@link isSyncEnabled}
+     * 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()}
      */
     startSync(): void;
@@ -2156,13 +2169,16 @@ declare class Ditto {
      * You may continue to use the database locally but no data will sync to or
      * from other devices.
      *
-     * @see {@link isSyncEnabled}
+     * @see {@link isSyncActive}
      * @see {@link startSync | startSync()}
      */
     stopSync(): void;
     /**
      * 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
@@ -2172,6 +2188,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`.
      */
@@ -2192,12 +2211,13 @@ 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;
     private presenceManager;
     private transportConditionsManager;
-    private authenticationExpiring;
     private authClientValidityChanged;
     private validateIdentity;
     private setSyncEnabled;
@@ -2207,6 +2227,185 @@ declare class Ditto {
  */
 declare const dittoBridge: Bridge<Ditto, "CDitto_t">;
 
+/** @internal */
+declare type ObserverToken = string;
+/** @internal */
+declare class ObserverManager {
+    /** @internal */
+    readonly id: string;
+    /** @internal */
+    readonly keepAlive: KeepAlive | null;
+    /** @internal */
+    constructor(id: string, keepAlive?: KeepAlive | null);
+    /** @internal */
+    addObserver(callback: any): ObserverToken;
+    /** @internal */
+    removeObserver(token: ObserverToken): void;
+    /** @internal */
+    notify(...args: any[]): void;
+    /** @abstract */
+    protected register(callback: (...args: any[]) => void): void;
+    /** @abstract */
+    protected unregister(): void;
+    /** @abstract */
+    protected processCallback(...args: any[]): any[];
+    private isRegistered;
+    private callbacksByToken;
+    private hasObservers;
+    private registerIfNeeded;
+    private unregisterIfNeeded;
+    private generateToken;
+    private finalize;
+}
+
+/**
+ * Provides info about the authentication status.
+ */
+declare type AuthenticationStatus = {
+    /**
+     * Returns `true` if authenticated, otherwise returns `false`.
+     */
+    isAuthenticated: boolean;
+    /**
+     * If authenticated, returns the `userID` if one was provided by the
+     * authentication service. Otherwise returns `null`.
+     */
+    userID: string | null;
+};
+/**
+ * Provides feedback to the developer about Ditto authentication status.
+ */
+interface AuthenticationHandler {
+    /**
+     * There is no Ditto authentication token or it has expired. Sync will not
+     * work until there is a successful login using one of the login methods on
+     * {@link Authenticator}.
+     */
+    authenticationRequired: (authenticator: Authenticator) => void;
+    /**
+     * Warns that the Ditto authentication token is getting old.
+     *
+     * Ditto will attempt to refresh tokens periodically, starting from halfway
+     * through the token's validity period. This reduces the risk of
+     * authentication expiring while the user is offline.
+     *
+     * The refresh will happen automatically if Ditto has a suitable refresh
+     * token. If new credentials are required, such as a third-party token or a
+     * username/password, then Ditto does not cache that information and you must
+     * submit it again using one of the `login` methods on {@link Authenticator}.
+     */
+    authenticationExpiringSoon: (authenticator: Authenticator, secondsRemaining: number) => void;
+    /**
+     * Notifies the authentication handler that the authentication status did
+     * change. Use the `authenticator`s property `status` to query for the current
+     * authentication status.
+     *
+     * This method is **optional**.
+     */
+    authenticationStatusDidChange?: (authenticator: Authenticator) => void;
+}
+/**
+ * Log in to a remote authentication service, using an
+ * `OnlineWithAuthentication` or an `Online` identity.
+ */
+declare class Authenticator {
+    /**
+     * Returns `true` if authentication is avaiable and the login methods can be
+     * used, otherwise returns `false`. Currently, authentication is only
+     * available if Ditto was initialized with an identity of type
+     * {@link IdentityOnlineWithAuthentication | 'onlineWithAuthentication'}.
+     */
+    readonly loginSupported: boolean;
+    /**
+     Returns the current authentication status.
+     */
+    readonly status: AuthenticationStatus;
+    /**
+     * Query whether Ditto has a valid authentication token.
+     *
+     * This will only be `true` when using an `OnlineWithAuthentication` or an
+     * `Online` identity, after a successful login. If the authentication token is
+     * allowed to expire then it will return `false` instead.
+     *
+     * @deprecated: use `status.isAuthenticated` property instead.
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Return the currently logged-in user ID.
+     *
+     * This will be `null` if there is no valid authentication or
+     * `OnlineWithAuthentication`/`Online` mode is not being used.
+     *
+     * @deprecated: use `status.userID` property instead.
+     */
+    get userID(): string | null;
+    /**
+     * Log in to Ditto with a third-party token. Throws if authentication is not
+     * available, which can be checked with {@link loginSupported}.
+     *
+     * @param token the authentication token required to log in.
+     * @param provider the name of the authentication provider.
+     */
+    loginWithToken(token: string, provider: string): Promise<void>;
+    /**
+     * Log in to Ditto with a username and password. Throws if authentication is
+     * not available, which can be checked with {@link loginSupported}.
+     *
+     * @param username the username component of the credentials used for log in.
+     * @param password the password component of the credentials used for log in.
+     * @param provider the name of the authentication provider.
+     */
+    loginWithUsernameAndPassword(username: string, password: string, provider: string): Promise<void>;
+    /**
+     * Log out of Ditto.
+     *
+     * This will stop sync, shut down all replication sessions, and remove any
+     * cached authentication credentials. Note that this does not remove any data
+     * from the store. If you wish to delete data from the store then use the
+     * optional `cleanupFn` parameter to perform any required cleanup.
+     *
+     * @param cleanupFn An optional function that will be called with the relevant
+     * [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>;
+    observeStatus(callback: (authenticationStatus: AuthenticationStatus) => void): Observer;
+    /** @internal */
+    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 */
+declare class OnlineAuthenticator 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>;
+    readonly authClientPointer: Pointer<AuthClientType>;
+    readonly authenticationHandler: AuthenticationHandler;
+    private ditto;
+    constructor(keepAlive: KeepAlive, authClientPointer: Pointer<AuthClientType>, ditto: Ditto, authenticationHandler: AuthenticationHandler);
+    '@ditto.authenticationExpiring': (secondsRemaining: number) => void;
+    '@ditto.authClientValidityChanged': (isWebValid: boolean, isX509Valid: boolean) => void;
+    private updateAndNotify;
+    private static finalizationRegistry;
+    private static finalize;
+}
+/** @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) => never;
+    /** @internal */
+    '@ditto.authClientValidityChanged': (isWebValid: boolean, isX509Valid: boolean) => void;
+}
+
 /** @internal */
 declare class Value {
     readonly value: unknown;
@@ -2407,5 +2606,13 @@ declare class Logger {
     private constructor();
 }
 
-export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, Authenticator, 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, OnlineWithAuthenticationAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, Value, WebAssemblyModule, WriteStrategy, __log, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge };
+/** @internal */
+declare class CBOR {
+    /** @internal */
+    static encode(data: any): Uint8Array;
+    /** @internal */
+    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, 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