@dittolive/ditto 4.0.2-experimental.shutdown-support.2.darwin-arm64 → 4.0.2-experimental.shutdown-support.3.darwin-arm64

package/types/ditto.d.ts

@@ -68,7 +68,6 @@ declare class ObserverManager {
     private hasObservers;
     private registerIfNeeded;
     private unregisterIfNeeded;
-    private finalize;
 }
 
 /** @internal */
@@ -1313,724 +1312,746 @@ declare class Presence {
     private observerManager;
 }
 
-/** Types of connections that can be established between two peers. */
-type TransportCondition = 'Unknown' | 'OK' | 'GenericFailure' | 'AppInBackground' | 'MDNSFailure' | 'TCPListenFailure' | 'NoBLECentralPermission' | 'NoBLEPeripheralPermission' | 'CannotEstablishConnection' | 'BLEDisabled' | 'NoBLEHardware' | 'WiFiDisabled' | 'TemporarilyUnavailable';
-/** The source for a transport condition. */
-type ConditionSource = 'BLE' | 'TCP' | 'AWDL' | 'MDNS';
-/**
- * Types of connections that can be established between two peers.
- * @deprecated replaced by {@link ConnectionType}.
- */
-type PresenceConnectionType = 'WiFi' | 'WebSocket' | 'AWDL' | 'BLE';
-/**
- * A peer object with information about an observed peer.
- * @deprecated replaced by {@link Peer}.
- */
-type RemotePeer = {
-    networkID: string;
-    deviceName: string;
-    rssi?: number;
-    approximateDistanceInMeters?: number;
-    connections: PresenceConnectionType[];
-};
 /**
- * Ditto is the entry point for accessing Ditto-related functionality.
+ * Used to subscribe to receive updates from remote peers about matching
+ * documents.
+ *
+ * While {@link Subscription} objects remain in scope they ensure that
+ * documents in the collection specified and that match the query provided will
+ * try to be kept up-to-date with the latest changes from remote peers.
  */
-declare class Ditto {
-    /**
-     * Configure a custom identifier for the current device.
-     *
-     * When using {@link Presence.observe | presence.observe()}, each remote peer is
-     * represented by a short UTF-8 "device name". By default this will be a
-     * truncated version of the device's hostname. It does not need to be unique
-     * among peers. Configure the device name before calling
-     * {@link startSync | startSync()}. If it is too long it may be truncated.
-     */
-    deviceName: string;
-    /** Returns a string identifying the version of the Ditto SDK. */
-    get sdkVersion(): string;
+declare class Subscription {
     /**
-     * The (validated) identity this Ditto instance was initialized with.
+     * The query that the subscription is based on.
      */
-    readonly identity: Identity;
+    readonly query: string;
     /**
-     * The path this Ditto instance was initialized with, if no path was given at
-     * construction time, the default value is returned (see constructor).
+     * Returns `true` if subscription has been explicitly cancelled, `false`
+     * otherwise.
      */
-    readonly path: string;
+    readonly isCancelled = false;
     /**
-     * Provides access to the SDK's store functionality.
+     * The name of the collection that the subscription is based on.
      */
-    readonly store: Store;
+    get collectionName(): string;
     /**
-     * Provides access to the SDK's presence functionality.
+     * Cancels a subscription and releases all associated resources.
      */
-    readonly presence: Presence;
+    cancel(): void;
+    /** @internal */
+    constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number);
     /**
-     * Provides access to authentication methods for logging on to Ditto Cloud.
+     * The collection this subscription belongs to.
+     * @internal Because not exposed in any of the other SDKs (yet?).
      */
-    readonly auth: Authenticator;
+    readonly collection: Collection;
     /**
-     * The site ID that the instance of `Ditto` is using as part of its identity.
+     * The corresponding named arguments for {@link query}, if any.
+     * @internal Because not exposed in any of the other SDKs (yet?).
      */
-    readonly siteID: number | BigInt;
+    readonly queryArgsCBOR: Uint8Array | null;
+    private static finalizationRegistry;
+    private static add;
+    private static remove;
+    private contextInfo;
+}
+
+/**
+ * An object that describes how a document's position in a live query's list of
+ * matching documents has changed since the previous live query event.
+ */
+interface LiveQueryMove {
     /**
-     * Returns `true` if an offline license token has been set, otherwise returns `false`.
-     *
-     * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
+     * The index of the document in the list of matching documents from the
+     * previous live query event.
      */
-    readonly isActivated: boolean;
+    readonly from: number;
     /**
-     * `true` once {@link close | Ditto.close()} has been called, otherwise
-     * `false`.
+     * The index of the document in the list of matching documents from the new
+     * live query event.
      */
-    get isClosed(): boolean;
+    readonly to: number;
+}
+/** @internal */
+interface LiveQueryEventUpdateParams {
+    oldDocuments: Document[];
+    insertions: number[];
+    deletions: number[];
+    updates: number[];
+    moves: LiveQueryMove[];
+}
+/**
+ * First event fired immediately after registering a live query without any
+ * mutations. All subsequent events are of type {@link LiveQueryEventUpdate}.
+ */
+declare class LiveQueryEventInitial {
     /**
-     * Returns `true` if sync is active, otherwise returns `false`. Use
-     * {@link startSync | startSync()} to activate and {@link stopSync | stopSync()}
-     * to deactivate sync.
+     * Whether or not this is the initial event being delivered. Always `true`
+     * for `LiveQueryEventInitial`.
      */
-    readonly isSyncActive: boolean;
+    readonly isInitial = true;
     /**
-     * Initializes a new `Ditto` instance.
-     *
-     * **NOTE**: The `sharedKey` identity is only supported for Node environments,
-     * using this to create a Ditto instance in the web browser will throw an
-     * exception.
-     *
-     * @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 for the in-memory storage.
-     * Defaults to `"ditto"`.
-     *
-     * @see {@link Ditto.identity}
-     * @see {@link Ditto.path}
+     * Returns a hash that represents the set of matching documents.
      */
-    constructor(identity?: Identity, path?: string);
+    hash(documents: Document[]): BigInt;
     /**
-     * Check if the current environment supports running Ditto.
-     *
-     * Required APIs include:
-     *
-     * - `BigInt`
-     * - `FinalizationRegistry`
-     * - `WeakRef`
-     *
-     *  Internet Explorer is not supported.
-     *
-     * @returns true if the environment is supported
+     * Returns a pattern of words that together create a mnemonic, which
+     * represents the set of matching documents.
      */
-    static isEnvironmentSupported(): boolean;
+    hashMnemonic(documents: Document[]): string;
+}
+/**
+ * Represents an update event describing all changes that occured for documents
+ * covered by a (live) query.
+ */
+declare class LiveQueryEventUpdate {
     /**
-     * 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).
+     * Whether or not this is the initial event being delivered. Always `false`
+     * for `LiveQueryEventUpdate`.
      */
-    setOfflineOnlyLicenseToken(licenseToken: string): void;
+    readonly isInitial = false;
     /**
-     * Returns the current transport configuration, frozen. If you want to modify
-     * the transport config, make a {@link TransportConfig.copy | copy} first. Or
-     * use the {@link updateTransportConfig | updateTransportConfig()}
-     * convenience method. By default peer-to-peer transports (Bluetooth, WiFi,
-     * and AWDL) are enabled if available in the current environment
-     * (Web, Node, OS, etc.).
-     *
-     * @see {@link setTransportConfig | setTransportConfig()}
-     * @see {@link updateTransportConfig | updateTransportConfig()}
+     * The documents that previously matched the query, before the latest event.
      */
-    readonly transportConfig: TransportConfig;
+    readonly oldDocuments: Document[];
     /**
-     * Assigns a new transports configuration. By default peer-to-peer transports
-     * (Bluetooth, WiFi, and AWDL) are enabled. You may use this method to alter
-     * the configuration at any time, however sync will not begin until
-     * {@link startSync | startSync()} is called.
-     *
-     * @see {@link transportConfig}
-     * @see {@link updateTransportConfig | updateTransportConfig()}
+     * The indexes in the array of matching documents that accompany this event,
+     * which relate to a document that was not in the previous most recent list of
+     * matching documents.
      */
-    setTransportConfig(transportConfig: TransportConfig): void;
+    readonly insertions: number[];
     /**
-     * Convenience method for updating the transport config. Creates a copy of the
-     * current transport config, passes that copy to the `update` closure,
-     * allowing it to mutate as needed, and sets that updated copy afterwards.
+     * The indexes into the array {@link oldDocuments}, which relate to a document
+     * that was in the previous most recent list of matching documents but is no
+     * longer a matching document.
      */
-    updateTransportConfig(update: (transportConfig: TransportConfig) => void): Ditto;
+    readonly deletions: number[];
     /**
-     * Starts the network transports. Ditto will connect to other devices.
-     *
-     * By default Ditto will enable all peer-to-peer transport types. On **Node**,
-     * this means BluetoothLE, WiFi/LAN, and AWDL. On the **Web**, only connecting
-     * via  Websockets is supported. The network configuration can be
-     * customized with {@link updateTransportConfig | updateTransportConfig()}
-     * or replaced entirely with {@link setTransportConfig | setTransportConfig()}.
-     *
-     *
-     * Ditto will prevent the process from exiting until sync is stopped (not
-     * relevant when running in the browser).
-     *
-     * **NOTE**: the BluetoothLE transport on Linux is experimental, this
-     * method panics if no BluetoothLE hardware is available. Therefore, contrary
-     * to the above, the BluetoothLE transport is temporarily disabled by default
-     * on Linux.
-     *
-     * @see {@link isSyncActive}
-     * @see {@link stopSync | stopSync()}
+     * The indexes in the array of matching documents that accompany this event,
+     * which relate to a document that has been updated since the previous live
+     * query event.
      */
-    startSync(): void;
+    readonly updates: number[];
     /**
-     * Stops all network transports.
-     *
-     * You may continue to use the database locally but no data will sync to or
-     * from other devices.
-     *
-     * @see {@link isSyncActive}
-     * @see {@link startSync | startSync()}
+     * Objects that describe how documents' positions in the list of matching
+     * documents have changed since the previous live query event.
      */
-    stopSync(): void;
+    readonly moves: LiveQueryMove[];
     /**
-     * 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
-     * them change.
-     *
-     * @deprecated please use {@link Presence.observe | presence.observe()} instead.
+     * Returns a hash that represents the set of matching documents.
      */
-    observePeers(callback: (peersData: RemotePeer[]) => void): Observer;
+    hash(documents: Document[]): BigInt;
     /**
-     * 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`.
+     * Returns a pattern of words that together create a mnemonic, which
+     * represents the set of matching documents.
      */
-    observeTransportConditions(callback: (condition: TransportCondition, source: ConditionSource) => void): Observer;
+    hashMnemonic(documents: Document[]): string;
+    /** @internal */
+    constructor(params: LiveQueryEventUpdateParams);
+}
+/**
+ * Represents events delivered by a {@link LiveQuery}, which can be initial
+ * (fired immediately upon registration) or an update (all subsequent events).
+ */
+type LiveQueryEvent = LiveQueryEventInitial | LiveQueryEventUpdate;
+/**
+ * Provides information about a live query event relating to a single document
+ * live query.
+ */
+declare class SingleDocumentLiveQueryEvent {
     /**
-     * Removes all sync metadata for any remote peers which aren't currently
-     * connected. This method shouldn't usually be called. Manually running
-     * garbage collection often will result in slower sync times. Ditto
-     * automatically runs a garbage a collection process in the background at
-     * optimal times.
-     *
-     * Manually running garbage collection is typically only useful during testing
-     * if large amounts of data are being generated. Alternatively, if an entire
-     * data set is to be evicted and it's clear that maintaining this metadata
-     * isn't necessary, then garbage collection could be run after evicting the
-     * old data.
-     *
-     * Only available in Node environments at the moment, no-op in the browser.
+     * Whether or not this is the initial event being delivered.
      */
-    runGarbageCollection(): void;
+    readonly isInitial: boolean;
+    /** The old representation of the document with the relveant document ID. */
+    readonly oldDocument?: Document;
     /**
-     * Explicitly opt-in to disabling the ability to sync with Ditto peers running
-     * any version of the SDK in the v3 (or lower) series of releases.
-     *
-     * Assuming this succeeds then this peer will only be able to sync with other
-     * peers using SDKs in the v4 (or higher) series of releases. Note that this
-     * disabling of sync spreads to peers that sync with a peer that has disabled,
-     * or has (transitively) had disabled, syncing with v3 SDK peers.
+     * Returns a hash that represents the set of matching documents.
      */
-    disableSyncWithV3(): void;
+    hash(document: Document | null): BigInt;
     /**
-     * Shut down Ditto and release all resources.
-     *
-     * Must be called before recreating a Ditto instance that uses the same
-     * persistence directory.
+     * Returns a pattern of words that together create a mnemonic, which
+     * represents the set of matching documents.
      */
-    close(): Promise<void>;
+    hashMnemonic(document: Document | null): string;
     /** @internal */
-    keepAlive: KeepAlive;
+    constructor(isInitial: boolean, oldDocument?: Document);
+}
+
+/**
+ * The closure that is called whenever the documents covered by a live query
+ * change.
+ */
+type QueryObservationHandler = (documents: Document[], event: LiveQueryEvent, signalNext?: () => void) => void | Promise<void>;
+/**
+ * These objects are returned when using `find`-like functionality on
+ * {@link Collection}.
+ *
+ * They allow chaining of further query-related functions to do things like add
+ * a limit to the number of documents you want returned or specify how you want
+ * the documents to be sorted and ordered.
+ *
+ * You can either call {@link exec | exec()} on the object to get an array of
+ * {@link Document | documents} as an immediate return value, or you can
+ * establish either a live query or a subscription, which both work over time.
+ *
+ * A live query, established by calling
+ * {@link PendingCursorOperation.observeLocal | observeLocal()}, will notify you
+ * every time there's an update to a document that matches the query you
+ * provided in the preceding `find`-like call.
+ *
+ * A subscription, established by calling
+ * {@link PendingCursorOperation.subscribe | subscribe()}, will act as a signal
+ * to other peers that the device connects to that you would like to receive
+ * updates from them about documents that match the query you provided in the
+ * preceding `find`-like call.
+ *
+ * Update and remove functionality is also exposed through this object.
+ */
+declare class PendingCursorOperation extends BasePendingCursorOperation {
+    sort(propertyPath: string, direction?: SortDirection): PendingCursorOperation;
+    offset(offset: number): PendingCursorOperation;
+    limit(limit: number): PendingCursorOperation;
+    remove(): Promise<DocumentID[]>;
+    evict(): Promise<DocumentID[]>;
+    update(closure: (documents: MutableDocument[]) => void): Promise<UpdateResultsMap>;
     /**
-     * The number of operations pending before the Ditto instance can be closed.
+     * Enables you to subscribe to changes that occur in a collection remotely.
      *
-     * For testing purposes only.
-     * @internal */
-    get numPendingOperations(): number;
-    /**
-     * Makes sure that the closure is executed only if the Ditto instance hasn't
-     * been closed yet.
+     * Having a subscription acts as a signal to other peers that you are
+     * interested in receiving updates when local or remote changes are made to
+     * documents that match the query generated by the chain of operations that
+     * precedes the call to {@link subscribe | subscribe()}.
      *
-     * @param closure the synchronous closure to execute.
-     * @returns the result of the closure.
-     * @throws if the Ditto instance was closed before calling this method.
-     * @internal */
-    deferClose<T>(closure: () => T): T;
+     * The returned {@link Subscription} object must be kept in scope for as long
+     * as you want to keep receiving updates.
+     *
+     * @returns A {@link Subscription} object that must be kept in scope for as
+     * long as you want to keep receiving updates for documents that match the
+     * query specified in the preceding chain.
+     */
+    subscribe(): Subscription;
     /**
-     * Makes sure that the closure is executed to completion before the Ditto
-     * instance is closed.
+     * Enables you to listen for changes that occur in a collection locally.
      *
-     * Any calls to {@link close | `Ditto.close()`} will wait until the closure
-     * has completed before closing the Ditto instance.
+     * The `handler` block will be called when local changes are
+     * made to documents that match the query generated by the chain of operations
+     * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}.
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
      *
-     * @param closure the asynchronous closure to execute.
-     * @returns the result of the closure.
-     * @throws if the Ditto instance was closed before calling this method.
-     * @internal */
-    deferCloseAsync<T>(closure: () => Promise<T>): Promise<T>;
-    private sync;
-    private _isClosed;
-    private deferCloseAllowed;
-    private isWebValid;
-    private isX509Valid;
-    private presenceManager;
-    private transportConditionsManager;
-    /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
-    private pendingOperations;
-    private authClientValidityChanged;
-    private validateIdentity;
-    private setSyncActive;
-    private makeDefaultTransportConfig;
-}
-/** @internal */
-declare const checkAPIs: (_globalObject?: Window | typeof globalThis) => boolean;
-
-/**
- * Represents an attachment and can be used to insert the associated attachment
- * into a document at a specific key-path. You can't instantiate an attachment
- * directly, please use the {@link Collection.newAttachment | newAttachment()}
- * method of {@link Collection} instead.
- */
-declare class Attachment {
-    /** @internal */
-    readonly ditto: Ditto;
-    /** @internal */
-    readonly token: AttachmentToken;
-    /** The attachment's metadata. */
-    get metadata(): {
-        [key: string]: string;
-    };
-    /**
-     * Returns the attachment's data.
+     * This won't subscribe to receive changes made remotely by others and so it
+     * will only fire updates when a local change is made. If you want to receive
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+     * relevant query. The returned {@link LiveQuery} object must be kept in scope
+     * for as long as you want the provided `eventHandler` to be called when an
+     * update occurs.
+     *
+     * @param handler A closure that will be called every time there is a
+     * transaction committed to the store that involves modifications to documents
+     * matching the query in the collection this method was called on.
+     *
+     * @return A {@link LiveQuery} object that must be kept in scope for as long
+     * as you want to keep receiving updates.
      */
-    getData(): Promise<Uint8Array>;
+    observeLocal(handler: QueryObservationHandler): LiveQuery;
     /**
-     * Copies the attachment to the specified file path. Node-only,
-     * throws in the browser.
+     * Enables you to listen for changes that occur in a collection locally and
+     * to signal when you are ready for the live query to deliver the next event.
      *
-     * @param path The path that the attachment should be copied to.
+     * The `handler` block will be called when local changes are
+     * made to documents that match the query generated by the chain of operations
+     * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}.
+     * The returned {@link LiveQuery} object must be kept in scope for as long as
+     * you want the provided `handler` to be called when an update occurs.
+     *
+     * This won't subscribe to receive changes made remotely by others and so it
+     * will only fire updates when a local change is made. If you want to receive
+     * remotely performed updates as well, you'll have to create a subscription
+     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+     * relevant query. The returned {@link LiveQuery} object must be kept in scope
+     * for as long as you want the provided `eventHandler` to be called when an
+     * update occurs.
+     *
+     * @param handler A closure that will be called every time there is a
+     * transaction committed to the store that involves modifications to
+     * documents matching the query in the collection that this method was called
+     * on.
+     *
+     * @return A {@link LiveQuery} object that must be kept in scope for as long
+     * as you want to keep receiving updates.
      */
-    copyToPath(path: string): Promise<void>;
+    observeLocalWithNextSignal(handler: QueryObservationHandler): LiveQuery;
     /** @internal */
-    constructor(ditto: Ditto, token: AttachmentToken);
+    constructor(query: string, queryArgs: QueryArguments | null, collection: Collection);
+    /** @internal */
+    _observe(handler: QueryObservationHandler, waitForNextSignal: boolean): LiveQuery;
 }
 
 /**
- * The types of attachment fetch events that can be delivered to an attachment
- * fetcher's `callback`.
- */
-type AttachmentFetchEventType = 'Completed' | 'Progress' | 'Deleted';
-/**
- * An attachment fetch event used when the attachment's download has completed.
- */
-type AttachmentFetchEventCompleted = {
-    type: 'Completed';
-    attachment: Attachment;
-};
-/**
- * An attachment fetch event used when the attachment's download progressed but
- * is not yet complete.
- */
-type AttachmentFetchEventProgress = {
-    type: 'Progress';
-    totalBytes: number | BigInt;
-    downloadedBytes: number | BigInt;
-};
-/**
- * An attachment fetch event used when the attachment is deleted.
- */
-type AttachmentFetchEventDeleted = {
-    type: 'Deleted';
-};
-/**
- * A representation of the events that can occur in relation to an attachment
- * fetch.
- *
- * There are three different attachment fetch events: `Completed`, `Progress`,
- * or `Deleted`.
+ * The type that is returned when calling
+ * {@link PendingCursorOperation.observeLocal | observeLocal()} on a
+ * {@link PendingCursorOperation} object. It handles the logic for calling the
+ * event handler that is provided to `observeLocal()` calls.
  *
- * There will be at most one `Completed` or `Deleted` event per attachment
- * fetch. There can be many `Progress` events delivered for each attachment
- * fetch.
+ * Ditto will prevent the process from exiting as long as there are active live
+ * queries (not relevant when running in the browser).
  *
- * Updates relating to an attachment fetch are delivered by registering an
- * {@link AttachmentFetcher} through a call to
- * {@link Collection.fetchAttachment | fetchAttachment()} on a
- * {@link Collection} instance.
- */
-type AttachmentFetchEvent = AttachmentFetchEventCompleted | AttachmentFetchEventProgress | AttachmentFetchEventDeleted;
-
-/**
- * These objects are returned by calls to
- * {@link Collection.fetchAttachment | fetchAttachment()} on {@link Collection}
- * and allow you to stop an in-flight attachment fetch.
+ * `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
+ * documents matching a query then you must call {@link stop | stop()}.
  */
-declare class AttachmentFetcher implements PromiseLike<Attachment | null> {
-    /**
-     * Returns a promise for the attachment that you can `await`. The promise
-     * resolves to either an attachment or `null` if the attachment has been
-     * deleted meanwhile. The promise is rejected if an error occurs during
-     * the fetch. Note that the `AttachmentFetcher` itself implementes
-     * `PromiseLike`, so you can `await` it directly.
-     */
-    readonly attachment: Promise<Attachment | null>;
+declare class LiveQuery {
+    /** The query that the live query is based on. */
+    readonly query: string;
+    /** The arguments belonging to {@link query}. */
+    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;
     /**
-     * Stops fetching the associated attachment and cleans up any associated
-     * resources.
-     *
-     * Note that you are not required to call `stop()` once your attachment fetch
-     * operation has finished. The method primarily exists to allow you to cancel
-     * an attachment fetch request while it is ongoing if you no longer wish for
-     * the attachment to be made available locally to the device.
+     * Stop the live query from delivering updates.
      */
     stop(): void;
     /** @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>;
+    orderBys: OrderBy[];
+    /** @internal */
+    queryArgsCBOR: Uint8Array | null;
+    /** @internal */
+    readonly limit: number;
+    /** @internal */
+    readonly offset: number;
     /** @internal */
+    readonly collection: Collection;
+    /** @internal */
+    readonly handler: QueryObservationHandler;
+    /** @internal */
+    liveQueryManager: LiveQueryManager | null;
+    /** @internal */
+    readonly 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>;
+}
+
+/** @internal */
+declare class LiveQueryManager {
     readonly ditto: Ditto;
+    readonly keepAlive: KeepAlive;
     /** @internal */
-    readonly token: AttachmentToken;
+    constructor(ditto: Ditto, keepAlive: KeepAlive);
     /** @internal */
-    readonly eventHandler: (attachmentFetchEvent: AttachmentFetchEvent) => void | null;
+    startLiveQuery(liveQuery: LiveQuery): void;
     /** @internal */
-    constructor(ditto: Ditto, token: AttachmentToken, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void);
-    private cancelTokenPromise;
-    private static finalizationRegistry;
-    private static stopWithContextInfo;
+    stopLiveQuery(liveQuery: LiveQuery): void;
+    /** @internal */
+    close(): void;
+    private liveQueriesByID;
+    private finalizationRegistry;
+    private stopLiveQueryWithID;
+    private finalize;
 }
 
+/** Types of connections that can be established between two peers. */
+type TransportCondition = 'Unknown' | 'OK' | 'GenericFailure' | 'AppInBackground' | 'MDNSFailure' | 'TCPListenFailure' | 'NoBLECentralPermission' | 'NoBLEPeripheralPermission' | 'CannotEstablishConnection' | 'BLEDisabled' | 'NoBLEHardware' | 'WiFiDisabled' | 'TemporarilyUnavailable';
+/** The source for a transport condition. */
+type ConditionSource = 'BLE' | 'TCP' | 'AWDL' | 'MDNS';
 /**
- * Used to subscribe to receive updates from remote peers about matching
- * documents.
- *
- * While {@link Subscription} objects remain in scope they ensure that
- * documents in the collection specified and that match the query provided will
- * try to be kept up-to-date with the latest changes from remote peers.
+ * Types of connections that can be established between two peers.
+ * @deprecated replaced by {@link ConnectionType}.
  */
-declare class Subscription {
+type PresenceConnectionType = 'WiFi' | 'WebSocket' | 'AWDL' | 'BLE';
+/**
+ * A peer object with information about an observed peer.
+ * @deprecated replaced by {@link Peer}.
+ */
+type RemotePeer = {
+    networkID: string;
+    deviceName: string;
+    rssi?: number;
+    approximateDistanceInMeters?: number;
+    connections: PresenceConnectionType[];
+};
+/**
+ * Ditto is the entry point for accessing Ditto-related functionality.
+ */
+declare class Ditto {
     /**
-     * The query that the subscription is based on.
+     * Configure a custom identifier for the current device.
+     *
+     * When using {@link Presence.observe | presence.observe()}, each remote peer is
+     * represented by a short UTF-8 "device name". By default this will be a
+     * truncated version of the device's hostname. It does not need to be unique
+     * among peers. Configure the device name before calling
+     * {@link startSync | startSync()}. If it is too long it may be truncated.
      */
-    readonly query: string;
+    deviceName: string;
+    /** Returns a string identifying the version of the Ditto SDK. */
+    get sdkVersion(): string;
     /**
-     * Returns `true` if subscription has been explicitly cancelled, `false`
-     * otherwise.
+     * The (validated) identity this Ditto instance was initialized with.
      */
-    readonly isCancelled = false;
+    readonly identity: Identity;
     /**
-     * The name of the collection that the subscription is based on.
+     * The path this Ditto instance was initialized with, if no path was given at
+     * construction time, the default value is returned (see constructor).
      */
-    get collectionName(): string;
+    readonly path: string;
+    /**
+     * Provides access to the SDK's store functionality.
+     */
+    readonly store: Store;
+    /**
+     * Provides access to the SDK's presence functionality.
+     */
+    readonly presence: Presence;
+    /**
+     * Provides access to authentication methods for logging on to Ditto Cloud.
+     */
+    readonly auth: Authenticator;
     /**
-     * Cancels a subscription and releases all associated resources.
+     * The site ID that the instance of `Ditto` is using as part of its identity.
      */
-    cancel(): void;
-    /** @internal */
-    constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number);
+    readonly siteID: number | BigInt;
     /**
-     * The collection this subscription belongs to.
-     * @internal Because not exposed in any of the other SDKs (yet?).
+     * Returns `true` if an offline license token has been set, otherwise returns `false`.
+     *
+     * @see {@link setOfflineOnlyLicenseToken | setOfflineOnlyLicenseToken()}
      */
-    readonly collection: Collection;
+    readonly isActivated: boolean;
     /**
-     * The corresponding named arguments for {@link query}, if any.
-     * @internal Because not exposed in any of the other SDKs (yet?).
+     * `true` once {@link close | Ditto.close()} has been called, otherwise
+     * `false`.
      */
-    readonly queryArgsCBOR: Uint8Array | null;
-    private static finalizationRegistry;
-    private static add;
-    private static remove;
-    private contextInfo;
-}
-
-/**
- * The type that is returned when calling
- * {@link PendingCursorOperation.observeLocal | observeLocal()} on a
- * {@link PendingCursorOperation} object. It handles the logic for calling the
- * event handler that is provided to `observeLocal()` 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
- * documents matching a query then you must call {@link stop | stop()}.
- */
-declare class LiveQuery {
-    /** The query that the live query is based on. */
-    readonly query: string;
-    /** The arguments belonging to {@link query}. */
-    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;
+    readonly isClosed: boolean;
     /**
-     * Stop the live query from delivering updates.
+     * Returns `true` if sync is active, otherwise returns `false`. Use
+     * {@link startSync | startSync()} to activate and {@link stopSync | stopSync()}
+     * to deactivate sync.
      */
-    stop(): void;
-    /** @internal */
-    readonly limit: number;
-    /** @internal */
-    readonly offset: number;
-    /** @internal */
-    readonly collection: Collection;
-    /** @internal */
-    readonly subscription?: Subscription;
-    /** @internal */
-    readonly handler: QueryObservationHandler;
-    /** @internal */
-    constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number, collection: Collection, subscription: Subscription | null, handler: QueryObservationHandler);
-    /** @internal */
-    signalNext(): Promise<void>;
-    private orderBys;
-    private queryArgsCBOR;
-    private liveQueryID;
-}
-
-/**
- * An object that describes how a document's position in a live query's list of
- * matching documents has changed since the previous live query event.
- */
-interface LiveQueryMove {
+    readonly isSyncActive: boolean;
     /**
-     * The index of the document in the list of matching documents from the
-     * previous live query event.
+     * Initializes a new `Ditto` instance.
+     *
+     * **NOTE**: The `sharedKey` identity is only supported for Node environments,
+     * using this to create a Ditto instance in the web browser will throw an
+     * exception.
+     *
+     * @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 for the in-memory storage.
+     * Defaults to `"ditto"`.
+     *
+     * @see {@link Ditto.identity}
+     * @see {@link Ditto.path}
      */
-    readonly from: number;
+    constructor(identity?: Identity, path?: string);
     /**
-     * The index of the document in the list of matching documents from the new
-     * live query event.
+     * Check if the current environment supports running Ditto.
+     *
+     * Required APIs include:
+     *
+     * - `BigInt`
+     * - `FinalizationRegistry`
+     * - `WeakRef`
+     *
+     *  Internet Explorer is not supported.
+     *
+     * @returns true if the environment is supported
      */
-    readonly to: number;
-}
-/** @internal */
-interface LiveQueryEventUpdateParams {
-    oldDocuments: Document[];
-    insertions: number[];
-    deletions: number[];
-    updates: number[];
-    moves: LiveQueryMove[];
-}
-/**
- * First event fired immediately after registering a live query without any
- * mutations. All subsequent events are of type {@link LiveQueryEventUpdate}.
- */
-declare class LiveQueryEventInitial {
+    static isEnvironmentSupported(): boolean;
     /**
-     * Whether or not this is the initial event being delivered. Always `true`
-     * for `LiveQueryEventInitial`.
+     * 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).
      */
-    readonly isInitial = true;
+    setOfflineOnlyLicenseToken(licenseToken: string): void;
     /**
-     * Returns a hash that represents the set of matching documents.
+     * Returns the current transport configuration, frozen. If you want to modify
+     * the transport config, make a {@link TransportConfig.copy | copy} first. Or
+     * use the {@link updateTransportConfig | updateTransportConfig()}
+     * convenience method. By default peer-to-peer transports (Bluetooth, WiFi,
+     * and AWDL) are enabled if available in the current environment
+     * (Web, Node, OS, etc.).
+     *
+     * @see {@link setTransportConfig | setTransportConfig()}
+     * @see {@link updateTransportConfig | updateTransportConfig()}
      */
-    hash(documents: Document[]): BigInt;
+    readonly transportConfig: TransportConfig;
     /**
-     * Returns a pattern of words that together create a mnemonic, which
-     * represents the set of matching documents.
+     * Assigns a new transports configuration. By default peer-to-peer transports
+     * (Bluetooth, WiFi, and AWDL) are enabled. You may use this method to alter
+     * the configuration at any time, however sync will not begin until
+     * {@link startSync | startSync()} is called.
+     *
+     * @see {@link transportConfig}
+     * @see {@link updateTransportConfig | updateTransportConfig()}
      */
-    hashMnemonic(documents: Document[]): string;
-}
-/**
- * Represents an update event describing all changes that occured for documents
- * covered by a (live) query.
- */
-declare class LiveQueryEventUpdate {
+    setTransportConfig(transportConfig: TransportConfig): void;
     /**
-     * Whether or not this is the initial event being delivered. Always `false`
-     * for `LiveQueryEventUpdate`.
+     * Convenience method for updating the transport config. Creates a copy of the
+     * current transport config, passes that copy to the `update` closure,
+     * allowing it to mutate as needed, and sets that updated copy afterwards.
      */
-    readonly isInitial = false;
+    updateTransportConfig(update: (transportConfig: TransportConfig) => void): Ditto;
     /**
-     * The documents that previously matched the query, before the latest event.
+     * Starts the network transports. Ditto will connect to other devices.
+     *
+     * By default Ditto will enable all peer-to-peer transport types. On **Node**,
+     * this means BluetoothLE, WiFi/LAN, and AWDL. On the **Web**, only connecting
+     * via  Websockets is supported. The network configuration can be
+     * customized with {@link updateTransportConfig | updateTransportConfig()}
+     * or replaced entirely with {@link setTransportConfig | setTransportConfig()}.
+     *
+     *
+     * Ditto will prevent the process from exiting until sync is stopped (not
+     * relevant when running in the browser).
+     *
+     * **NOTE**: the BluetoothLE transport on Linux is experimental, this
+     * method panics if no BluetoothLE hardware is available. Therefore, contrary
+     * to the above, the BluetoothLE transport is temporarily disabled by default
+     * on Linux.
+     *
+     * @see {@link isSyncActive}
+     * @see {@link stopSync | stopSync()}
      */
-    readonly oldDocuments: Document[];
+    startSync(): void;
     /**
-     * The indexes in the array of matching documents that accompany this event,
-     * which relate to a document that was not in the previous most recent list of
-     * matching documents.
+     * Stops all network transports.
+     *
+     * You may continue to use the database locally but no data will sync to or
+     * from other devices.
+     *
+     * @see {@link isSyncActive}
+     * @see {@link startSync | startSync()}
      */
-    readonly insertions: number[];
+    stopSync(): void;
     /**
-     * The indexes into the array {@link oldDocuments}, which relate to a document
-     * that was in the previous most recent list of matching documents but is no
-     * longer a matching document.
+     * 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
+     * them change.
+     *
+     * @deprecated please use {@link Presence.observe | presence.observe()} instead.
      */
-    readonly deletions: number[];
+    observePeers(callback: (peersData: RemotePeer[]) => void): Observer;
     /**
-     * The indexes in the array of matching documents that accompany this event,
-     * which relate to a document that has been updated since the previous live
-     * query event.
+     * 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`.
      */
-    readonly updates: number[];
+    observeTransportConditions(callback: (condition: TransportCondition, source: ConditionSource) => void): Observer;
     /**
-     * Objects that describe how documents' positions in the list of matching
-     * documents have changed since the previous live query event.
+     * Removes all sync metadata for any remote peers which aren't currently
+     * connected. This method shouldn't usually be called. Manually running
+     * garbage collection often will result in slower sync times. Ditto
+     * automatically runs a garbage a collection process in the background at
+     * optimal times.
+     *
+     * Manually running garbage collection is typically only useful during testing
+     * if large amounts of data are being generated. Alternatively, if an entire
+     * data set is to be evicted and it's clear that maintaining this metadata
+     * isn't necessary, then garbage collection could be run after evicting the
+     * old data.
+     *
+     * Only available in Node environments at the moment, no-op in the browser.
      */
-    readonly moves: LiveQueryMove[];
+    runGarbageCollection(): void;
     /**
-     * Returns a hash that represents the set of matching documents.
+     * Explicitly opt-in to disabling the ability to sync with Ditto peers running
+     * any version of the SDK in the v3 (or lower) series of releases.
+     *
+     * Assuming this succeeds then this peer will only be able to sync with other
+     * peers using SDKs in the v4 (or higher) series of releases. Note that this
+     * disabling of sync spreads to peers that sync with a peer that has disabled,
+     * or has (transitively) had disabled, syncing with v3 SDK peers.
      */
-    hash(documents: Document[]): BigInt;
+    disableSyncWithV3(): void;
     /**
-     * Returns a pattern of words that together create a mnemonic, which
-     * represents the set of matching documents.
+     * Shut down Ditto and release all resources.
+     *
+     * Must be called before recreating a Ditto instance that uses the same
+     * persistence directory.
      */
-    hashMnemonic(documents: Document[]): string;
+    close(): Promise<void>;
     /** @internal */
-    constructor(params: LiveQueryEventUpdateParams);
+    keepAlive: KeepAlive;
+    /** @internal */
+    liveQueryManager: LiveQueryManager;
+    /**
+     * The number of operations pending before the Ditto instance can be closed.
+     *
+     * For testing purposes only.
+     * @internal */
+    get numPendingOperations(): number;
+    /**
+     * Makes sure that the closure is executed only if the Ditto instance hasn't
+     * been closed yet.
+     *
+     * @param closure the synchronous closure to execute.
+     * @returns the result of the closure.
+     * @throws if the Ditto instance was closed before calling this method.
+     * @internal */
+    deferClose<T>(closure: () => T): T;
+    /**
+     * Makes sure that the closure is executed to completion before the Ditto
+     * instance is closed.
+     *
+     * Any calls to {@link close | `Ditto.close()`} will wait until the closure
+     * has completed before closing the Ditto instance.
+     *
+     * @param closure the asynchronous closure to execute.
+     * @returns the result of the closure.
+     * @throws if the Ditto instance was closed before calling this method.
+     * @internal */
+    deferCloseAsync<T>(closure: () => Promise<T>): Promise<T>;
+    private sync;
+    private deferCloseAllowed;
+    private isWebValid;
+    private isX509Valid;
+    private presenceManager;
+    private transportConditionsManager;
+    /** Set of pending operations that need to complete before the Ditto instance can be closed in a safe manner. */
+    private pendingOperations;
+    private authClientValidityChanged;
+    private validateIdentity;
+    private setSyncActive;
+    private makeDefaultTransportConfig;
 }
+/** @internal */
+declare const checkAPIs: (_globalObject?: Window | typeof globalThis) => boolean;
+
 /**
- * Represents events delivered by a {@link LiveQuery}, which can be initial
- * (fired immediately upon registration) or an update (all subsequent events).
- */
-type LiveQueryEvent = LiveQueryEventInitial | LiveQueryEventUpdate;
-/**
- * Provides information about a live query event relating to a single document
- * live query.
+ * Represents an attachment and can be used to insert the associated attachment
+ * into a document at a specific key-path. You can't instantiate an attachment
+ * directly, please use the {@link Collection.newAttachment | newAttachment()}
+ * method of {@link Collection} instead.
  */
-declare class SingleDocumentLiveQueryEvent {
-    /**
-     * Whether or not this is the initial event being delivered.
-     */
-    readonly isInitial: boolean;
-    /** The old representation of the document with the relveant document ID. */
-    readonly oldDocument?: Document;
+declare class Attachment {
+    /** @internal */
+    readonly ditto: Ditto;
+    /** @internal */
+    readonly token: AttachmentToken;
+    /** The attachment's metadata. */
+    get metadata(): {
+        [key: string]: string;
+    };
     /**
-     * Returns a hash that represents the set of matching documents.
+     * Returns the attachment's data.
      */
-    hash(document: Document | null): BigInt;
+    getData(): Promise<Uint8Array>;
     /**
-     * Returns a pattern of words that together create a mnemonic, which
-     * represents the set of matching documents.
+     * Copies the attachment to the specified file path. Node-only,
+     * throws in the browser.
+     *
+     * @param path The path that the attachment should be copied to.
      */
-    hashMnemonic(document: Document | null): string;
+    copyToPath(path: string): Promise<void>;
     /** @internal */
-    constructor(isInitial: boolean, oldDocument?: Document);
+    constructor(ditto: Ditto, token: AttachmentToken);
 }
 
 /**
- * The closure that is called whenever the documents covered by a live query
- * change.
+ * The types of attachment fetch events that can be delivered to an attachment
+ * fetcher's `callback`.
  */
-type QueryObservationHandler = (documents: Document[], event: LiveQueryEvent, signalNext?: () => void) => void | Promise<void>;
+type AttachmentFetchEventType = 'Completed' | 'Progress' | 'Deleted';
 /**
- * These objects are returned when using `find`-like functionality on
- * {@link Collection}.
- *
- * They allow chaining of further query-related functions to do things like add
- * a limit to the number of documents you want returned or specify how you want
- * the documents to be sorted and ordered.
- *
- * You can either call {@link exec | exec()} on the object to get an array of
- * {@link Document | documents} as an immediate return value, or you can
- * establish either a live query or a subscription, which both work over time.
+ * An attachment fetch event used when the attachment's download has completed.
+ */
+type AttachmentFetchEventCompleted = {
+    type: 'Completed';
+    attachment: Attachment;
+};
+/**
+ * An attachment fetch event used when the attachment's download progressed but
+ * is not yet complete.
+ */
+type AttachmentFetchEventProgress = {
+    type: 'Progress';
+    totalBytes: number | BigInt;
+    downloadedBytes: number | BigInt;
+};
+/**
+ * An attachment fetch event used when the attachment is deleted.
+ */
+type AttachmentFetchEventDeleted = {
+    type: 'Deleted';
+};
+/**
+ * A representation of the events that can occur in relation to an attachment
+ * fetch.
  *
- * A live query, established by calling
- * {@link PendingCursorOperation.observeLocal | observeLocal()}, will notify you
- * every time there's an update to a document that matches the query you
- * provided in the preceding `find`-like call.
+ * There are three different attachment fetch events: `Completed`, `Progress`,
+ * or `Deleted`.
  *
- * A subscription, established by calling
- * {@link PendingCursorOperation.subscribe | subscribe()}, will act as a signal
- * to other peers that the device connects to that you would like to receive
- * updates from them about documents that match the query you provided in the
- * preceding `find`-like call.
+ * There will be at most one `Completed` or `Deleted` event per attachment
+ * fetch. There can be many `Progress` events delivered for each attachment
+ * fetch.
  *
- * Update and remove functionality is also exposed through this object.
+ * Updates relating to an attachment fetch are delivered by registering an
+ * {@link AttachmentFetcher} through a call to
+ * {@link Collection.fetchAttachment | fetchAttachment()} on a
+ * {@link Collection} instance.
  */
-declare class PendingCursorOperation extends BasePendingCursorOperation {
-    sort(propertyPath: string, direction?: SortDirection): PendingCursorOperation;
-    offset(offset: number): PendingCursorOperation;
-    limit(limit: number): PendingCursorOperation;
-    remove(): Promise<DocumentID[]>;
-    evict(): Promise<DocumentID[]>;
-    update(closure: (documents: MutableDocument[]) => void): Promise<UpdateResultsMap>;
-    /**
-     * Enables you to subscribe to changes that occur in a collection remotely.
-     *
-     * Having a subscription acts as a signal to other peers that you are
-     * interested in receiving updates when local or remote changes are made to
-     * documents that match the query generated by the chain of operations that
-     * precedes the call to {@link subscribe | subscribe()}.
-     *
-     * The returned {@link Subscription} object must be kept in scope for as long
-     * as you want to keep receiving updates.
-     *
-     * @returns A {@link Subscription} object that must be kept in scope for as
-     * long as you want to keep receiving updates for documents that match the
-     * query specified in the preceding chain.
-     */
-    subscribe(): Subscription;
+type AttachmentFetchEvent = AttachmentFetchEventCompleted | AttachmentFetchEventProgress | AttachmentFetchEventDeleted;
+
+/**
+ * These objects are returned by calls to
+ * {@link Collection.fetchAttachment | fetchAttachment()} on {@link Collection}
+ * and allow you to stop an in-flight attachment fetch.
+ */
+declare class AttachmentFetcher implements PromiseLike<Attachment | null> {
     /**
-     * Enables you to listen for changes that occur in a collection locally.
-     *
-     * The `handler` block will be called when local changes are
-     * made to documents that match the query generated by the chain of operations
-     * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}.
-     * The returned {@link LiveQuery} object must be kept in scope for as long as
-     * you want the provided `handler` to be called when an update occurs.
-     *
-     * This won't subscribe to receive changes made remotely by others and so it
-     * will only fire updates when a local change is made. If you want to receive
-     * remotely performed updates as well, you'll have to create a subscription
-     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
-     * relevant query. The returned {@link LiveQuery} object must be kept in scope
-     * for as long as you want the provided `eventHandler` to be called when an
-     * update occurs.
-     *
-     * @param handler A closure that will be called every time there is a
-     * transaction committed to the store that involves modifications to documents
-     * matching the query in the collection this method was called on.
-     *
-     * @return A {@link LiveQuery} object that must be kept in scope for as long
-     * as you want to keep receiving updates.
+     * Returns a promise for the attachment that you can `await`. The promise
+     * resolves to either an attachment or `null` if the attachment has been
+     * deleted meanwhile. The promise is rejected if an error occurs during
+     * the fetch. Note that the `AttachmentFetcher` itself implementes
+     * `PromiseLike`, so you can `await` it directly.
      */
-    observeLocal(handler: QueryObservationHandler): LiveQuery;
+    readonly attachment: Promise<Attachment | null>;
     /**
-     * Enables you to listen for changes that occur in a collection locally and
-     * to signal when you are ready for the live query to deliver the next event.
-     *
-     * The `handler` block will be called when local changes are
-     * made to documents that match the query generated by the chain of operations
-     * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}.
-     * The returned {@link LiveQuery} object must be kept in scope for as long as
-     * you want the provided `handler` to be called when an update occurs.
-     *
-     * This won't subscribe to receive changes made remotely by others and so it
-     * will only fire updates when a local change is made. If you want to receive
-     * remotely performed updates as well, you'll have to create a subscription
-     * via {@link PendingCursorOperation.subscribe | subscribe()} with the
-     * relevant query. The returned {@link LiveQuery} object must be kept in scope
-     * for as long as you want the provided `eventHandler` to be called when an
-     * update occurs.
-     *
-     * @param handler A closure that will be called every time there is a
-     * transaction committed to the store that involves modifications to
-     * documents matching the query in the collection that this method was called
-     * on.
+     * Stops fetching the associated attachment and cleans up any associated
+     * resources.
      *
-     * @return A {@link LiveQuery} object that must be kept in scope for as long
-     * as you want to keep receiving updates.
+     * Note that you are not required to call `stop()` once your attachment fetch
+     * operation has finished. The method primarily exists to allow you to cancel
+     * an attachment fetch request while it is ongoing if you no longer wish for
+     * the attachment to be made available locally to the device.
      */
-    observeLocalWithNextSignal(handler: QueryObservationHandler): LiveQuery;
+    stop(): void;
     /** @internal */
-    constructor(query: string, queryArgs: QueryArguments | null, collection: Collection);
+    then<TResult1 = any, TResult2 = never>(onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): PromiseLike<TResult1 | TResult2>;
+    /** @internal */
+    readonly ditto: Ditto;
     /** @internal */
-    _observe(handler: QueryObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
+    readonly token: AttachmentToken;
+    /** @internal */
+    readonly eventHandler: (attachmentFetchEvent: AttachmentFetchEvent) => void | null;
+    /** @internal */
+    constructor(ditto: Ditto, token: AttachmentToken, eventHandler?: (attachmentFetchEvent: AttachmentFetchEvent) => void);
+    private cancelTokenPromise;
+    private static finalizationRegistry;
+    private static stopWithContextInfo;
 }
 
 /**
@@ -2185,7 +2206,7 @@ declare class PendingIDSpecificOperation extends BasePendingIDSpecificOperation
     /** @internal */
     constructor(documentID: DocumentID, collection: Collection);
     /** @internal */
-    _observe(handler: SingleObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
+    _observe(handler: SingleObservationHandler, waitForNextSignal: boolean): LiveQuery;
 }
 
 /**
@@ -2488,7 +2509,7 @@ declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
     /** @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>;
     /** @internal */
-    _observe(handler: CollectionsObservationHandler, createSubscription: boolean, waitForNextSignal: boolean): LiveQuery;
+    _observe(handler: CollectionsObservationHandler, waitForNextSignal: boolean): LiveQuery;
     private readonly pendingCursorOperation;
 }