@dittolive/ditto 2.0.0-alpha1 → 2.0.0

package/types/ditto.d.ts

@@ -425,6 +425,80 @@ declare class Bridge<JSClass extends object, FFIType> {
     private finalize;
 }
 
+/** Represents a unique identifier for a {@link Document}. */
+declare type DocumentIDValue = any;
+/** Represents a unique identifier for a {@link Document}. */
+declare class DocumentID {
+    /**
+     * Returns the value of the receiver, lazily decoded from its CBOR
+     * representation if needed.
+     */
+    get value(): any;
+    /**
+     * Returns `false` if validation has been skipped at construction time,
+     * otherwise returns `true`. This is mostly for internal use only, you
+     * shouldn't need this in client code.
+     */
+    readonly isValidated: boolean;
+    /**
+     * Creates a new `DocumentID`.
+     *
+     * A document ID can be created from any of the following:
+     *
+     * - `string`
+     * - `number` (integer)
+     * - `boolean`
+     * - `null`
+     * - raw data in the form of a JS [Typed Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays)
+     * - `Array` (containing any of the items in this list)
+     * - Map (a raw JS `object`, where the keys must be strings and the values
+     *   can be made up of any of the items in this list)
+     *
+     * Note that you cannot use floats or other custom types to create a document
+     * ID.
+     *
+     * Document IDs are also limited in size, based on their serialized
+     * representation, to 256 bytes. You will receive an error if you try to
+     * create a document ID that exceeds the size limit.
+     *
+     * @param value The value that represents the document identifier.
+     * @param skipCBOREncoding If `true, skips CBOR encoding and assumes
+     * the passed in `value` is already CBOR encoded. You shouldn't need to ever
+     * pass this parameter, it's only used internally for certain edge cases.
+     * @param skipValidation If `true, skips validation of the passed in value or
+     * CBOR. You shouldn't need to ever pass this parameter, it's only used
+     * internally for certain edge cases.
+     */
+    constructor(value: any, skipCBOREncoding?: boolean, skipValidation?: boolean);
+    /**
+     * Returns `true` if passed in `documentID` is equal to the receiver,
+     * otherwise returns `false`.
+     */
+    equals(documentID: DocumentID): boolean;
+    /**
+     * Returns a string representation of the receiver.
+     *
+     * The returned string can be used directly in queries that you use with
+     * other Ditto functions. For example you could create a query that was like
+     * this:
+     *
+     *  ``` TypeScript
+     *  collection.find(`_id == ${documentID.toString()}`)
+     *  ```
+     */
+    toString(): string;
+    /**
+     * Returns a byte representation of the document ID value as base64 string.
+     */
+    toBase64String(): string;
+    /** @internal */
+    toCBOR(): Uint8Array;
+}
+/** @internal */
+declare function validateDocumentIDValue(id: DocumentIDValue): DocumentIDValue;
+/** @internal */
+declare function validateDocumentIDCBOR(idCBOR: Uint8Array): Uint8Array;
+
 /**
  * The types of an {@link UpdateResult}.
  */
@@ -433,7 +507,7 @@ declare class UpdateResult {
     /** The update result's type. */
     readonly type: UpdateResultType;
     /** The ID of the document that was updated. */
-    readonly docID: DocumentIDValue;
+    readonly docID: DocumentID;
     /** The path to the key in the document that was updated. */
     readonly path: string;
     /**
@@ -453,19 +527,19 @@ declare class UpdateResult {
     /** The associated amount, only set if {@link type} is `incremented`. */
     readonly amount?: number;
     /** @internal */
-    static set(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
+    static set(docID: DocumentID, path: string, value?: any): UpdateResult;
     /** @internal */
-    static replacedWithCounter(docID: DocumentIDValue, path: string): UpdateResult;
+    static replacedWithCounter(docID: DocumentID, path: string): UpdateResult;
     /** @internal */
-    static incremented(docID: DocumentIDValue, path: string, amount: number): UpdateResult;
+    static incremented(docID: DocumentID, path: string, amount: number): UpdateResult;
     /** @internal */
-    static inserted(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
+    static inserted(docID: DocumentID, path: string, value?: any): UpdateResult;
     /** @internal */
-    static removed(docID: DocumentIDValue, path: string): UpdateResult;
+    static removed(docID: DocumentID, path: string): UpdateResult;
     /** @internal */
-    static pushed(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
+    static pushed(docID: DocumentID, path: string, value?: any): UpdateResult;
     /** @internal */
-    static popped(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
+    static popped(docID: DocumentID, path: string, value?: any): UpdateResult;
     /** @internal */
     private constructor();
 }
@@ -494,13 +568,17 @@ declare class Counter {
  * any counter property within an update block via {@link MutableDocumentPath.counter}.
  */
 declare class MutableCounter extends Counter {
-    constructor();
     /**
-     * Increments the counter by `amount`, which can be any valid number. Only
-     * valid within the closure of {@link Collection}'s {@link Collection.update | update()}
-     * method, otherwise an exception is thrown.
+     * Increments the counter by `amount`, which can be any valid number.
+     *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
      */
     increment(amount: number): void;
+    /** @internal */
+    constructor();
 }
 
 /**
@@ -531,16 +609,23 @@ declare class Register {
  * any register property of a document within an update block via {@link MutableDocumentPath.register}.
  */
 declare class MutableRegister extends Register {
-    constructor(value: any);
     /** Returns the value of the register. */
     get value(): any;
     /**
-     * Sets the register to the provided value. Only valid within the closure of
-     * {@link Collection}'s {@link Collection.update | update()}
-     * method, otherwise an exception is thrown.
+     * Convenience setter, equivalent to {@link set | set()}.
      */
     set value(value: any);
+    /**
+     * Sets the register to the provided value.
+     *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
+     */
     set(value: any): void;
+    /** @internal */
+    constructor(value: any);
 }
 
 /**
@@ -567,48 +652,89 @@ declare class RGA {
     protected '@ditto.value': any;
 }
 /**
- * Represents a mutable CRDT RGA that can be set to a specific value when
- * updating a document.
+ * Represents a mutable CRDT Replicated Growable Array (RGA) that can be
+ * mutated as part of updating a document.
  *
  * This class can't be instantiated directly, it's returned automatically for
  * any `rga` property of a document within an update block via {@link MutableDocumentPath.rga}.
  */
 declare class MutableRGA extends RGA {
-    constructor(value: any);
     /** Returns the value of the RGA. */
     get value(): any[];
     /**
      * Set a value at the specified index.
      *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
+     *
      * @param value - The value to set at the specified index.
      * @param index - The index at which to set the provided value.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     setAt(value: any, index: number): void;
     /**
      * Remove a value at the specified index.
      *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
+     *
      * @param index - The index of the element to remove.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     removeAt(index: number): void;
     /**
      * Push a value on to the end of the RGA.
      *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
+     *
      * @param value - The value to push on to the RGA.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     push(value: any): void;
     /**
      * Pop a value off the end of the RGA.
      *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
+     *
      * @return The value popped off from the end of the RGA.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     pop(): any | null;
     /**
-     * Inserts a value into an the RGA at the index specified.
+     * Inserts a value into the RGA at the index specified.
+     *
+     * Only valid within the `update` closure of
+     * {@link PendingCursorOperation.update | PendingCursorOperation.update()} and
+     * {@link PendingIDSpecificOperation.update | PendingIDSpecificOperation.update()},
+     * otherwise an exception is thrown.
      *
      * @param value - The value to insert into the RGA.
      * @param index - The index at which to insert the provided value.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     insertAt(value: any, index: number): void;
+    /** @internal */
+    constructor(value: any);
 }
 
 /**
@@ -630,9 +756,12 @@ declare class AttachmentToken {
 }
 
 /**
+ * Represents a portion of the document at a specific key-path.
+ *
  * Provides an interface to specify a path to a key in a document that you can
  * then call a function on to get the value at the specified key as a specific
- * type. You don't create a `DocumentPath` directly but obtain one via the `at()`
+ * type. You don't create a `DocumentPath` directly but obtain one via the
+ * {@link Document.path | path} property or the {@link Document.at | at()}
  * method of {@link Document}.
  */
 declare class DocumentPath {
@@ -646,9 +775,9 @@ declare class DocumentPath {
      *
      * A key-path can be a single property name or multiple property names
      * separated by a dot. Indexes can also be specified as part of the key
-     * path using square brackets syntax. The empty string returns a document path
-     * representing the same portion of the document as the receiver. If a key
-     * path starts with a property name and is prefixed by a dot, the dot is
+     * path using the square bracket syntax. The empty string returns a document
+     * path representing the same portion of the document as the receiver. If a
+     * key-path starts with a property name and is prefixed by a dot, the dot is
      * ignored.
      *
      * Examples:
@@ -661,28 +790,31 @@ declare class DocumentPath {
      */
     at(keyPathOrIndex: string | number): DocumentPath;
     /**
-     * Traverses the document with the key path represented by the receiver and
+     * Traverses the document with the key-path represented by the receiver and
      * returns the corresponding object or value.
      */
     get value(): any | undefined;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `Counter` if possible, otherwise returns `null`.
+     * {@link Counter} if possible, otherwise returns `null`.
      */
     get counter(): Counter | null;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `Register` if possible, otherwise returns `null`.
+     * {@link Register} if possible, otherwise returns `null`.
      */
     get register(): Register | null;
     /**
-     * Returns the value at the previously specified key in the document as a
-     * `RGA` if possible, otherwise returns `null`.
+     * Returns the value at the previously specified key in the document as an
+     * {@link RGA} if possible, otherwise returns `null`.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     get rga(): RGA | null;
     /**
-     * Returns the value at the previously specified key in the document as a
-     * `AttachmentToken` if possible, otherwise returns `null`.
+     * Returns the value at the previously specified key in the document as an
+     * {@link AttachmentToken} if possible, otherwise returns `null`.
      */
     get attachmentToken(): AttachmentToken | null;
     /** @internal */
@@ -692,8 +824,9 @@ declare class DocumentPath {
 }
 /**
  * Mutable version of {@link DocumentPath} allowing you to mutate a document at
- * a specific key path. You don't create a `MutableDocumentPath` directly
- * but obtain one via the `at()` method of {@link MutableDocument}.
+ * a specific key-path. You don't create a `MutableDocumentPath` directly but
+ * obtain one via the {@link MutableDocument.path | path} property or the
+ * {@link MutableDocument.at | at()} method of {@link MutableDocument}.
  */
 declare class MutableDocumentPath {
     /** The (mutable) document this path belongs to. */
@@ -721,32 +854,35 @@ declare class MutableDocumentPath {
      */
     at(keyPathOrIndex: string | number): MutableDocumentPath;
     /**
-     * Traverses the document with the key path represented by the receiver and
+     * Traverses the document with the key-path represented by the receiver and
      * returns the corresponding object or value.
      */
     get value(): any | undefined;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `MutableCounter` if possible, otherwise returns `null`.
+     * {@link MutableCounter} if possible, otherwise returns `null`.
      */
     get counter(): MutableCounter | null;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `MutableRegister` if possible, otherwise returns `null`.
+     * {@link MutableRegister} if possible, otherwise returns `null`.
      */
     get register(): MutableRegister | null;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `MutableRGA` if possible, otherwise returns `null`.
+     * {@link MutableRGA} if possible, otherwise returns `null`.
+     *
+     * @deprecated: RGA usage should be replaced. Use arrays inside Registers
+     * instead.
      */
     get rga(): MutableRGA | null;
     /**
      * Returns the value at the previously specified key in the document as a
-     * `AttachmentToken` if possible, otherwise returns `null`.
+     * {@link AttachmentToken} if possible, otherwise returns `null`.
      */
     get attachmentToken(): AttachmentToken | null;
     /**
-     * Sets a value at the document's key path defined by the receiver.
+     * Sets a value at the document's key-path defined by the receiver.
      *
      * @param isDefault Represents whether or not the value should be set as a
      * default value. Set this to `true` if you want to set a default value that
@@ -755,7 +891,7 @@ declare class MutableDocumentPath {
      */
     set(value: any, isDefault?: boolean): void;
     /**
-     * Removes a value at the document's key path defined by the receiver.
+     * Removes a value at the document's key-path defined by the receiver.
      * If removing an index from an `RGA`, any subsequent indexes will be shifted
      * left to fill the gap.
      */
@@ -782,8 +918,6 @@ declare class MutableDocumentPath {
     private recordUpdateResult;
 }
 
-/** Represents a unique identifier for a {@link Document}. */
-declare type DocumentIDValue = any;
 /**
  * A document value is a JavaScript object containing values for keys that
  * can be serialized via CBOR.
@@ -791,22 +925,6 @@ declare type DocumentIDValue = any;
 declare type DocumentValue = Record<string, any>;
 /** A document belonging to a {@link Collection} with an inner value. */
 declare class Document {
-    /**
-     * Returns a string representation of the passed in document ID value.
-     *
-     * The returned string can be used directly in queries that you use with
-     * other Ditto functions. For example you could create a query that was like
-     * this:
-     *
-     *  ``` TypeScript
-     *  collection.find(`_id == ${Document.stringForID(documentID)}`)
-     *  ```
-     */
-    static stringForID(documentID: DocumentIDValue): string;
-    /**
-     * Returns a byte representation of the document ID value as base64 string.
-     */
-    static base64StringForID(documentID: DocumentIDValue): string;
     /**
      * Returns a hash that represents the passed in document(s).
      */
@@ -817,9 +935,9 @@ declare class Document {
      */
     static hashMnemonic(documentOrMany: Document | Document[]): string;
     /**
-     * Returns the document ID as value.
+     * Returns the document ID.
      */
-    get _id(): DocumentIDValue;
+    get id(): DocumentID;
     /**
      * Returns the document path at the root of the document.
      */
@@ -835,6 +953,8 @@ declare class Document {
      */
     at(keyPathOrIndex: string | number): DocumentPath;
     /** @internal */
+    constructor();
+    /** @internal */
     static idCBOR(document: Document): Uint8Array;
     /** @internal */
     static canonicalizedIDCBOR(idCBOR: Uint8Array): Uint8Array;
@@ -853,7 +973,7 @@ declare class MutableDocument {
     /**
      * Returns the ID of the document.
      */
-    get _id(): DocumentIDValue;
+    get id(): DocumentID;
     /**
      * Returns the document path at the root of the document.
      */
@@ -878,10 +998,6 @@ declare class MutableDocument {
     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">;
@@ -915,6 +1031,7 @@ declare class Attachment {
     /** @internal */
     constructor(ditto: Ditto, token: AttachmentToken);
 }
+/** @internal */
 declare const attachmentBridge: Bridge<Attachment, "AttachmentHandle_t">;
 
 /**
@@ -999,11 +1116,15 @@ declare class AttachmentFetcher implements PromiseLike<Attachment | null> {
     private cancelToken;
 }
 
+/** @internal */
 declare type SubscriptionContextInfo = {
     ditto: Ditto;
     collectionName: string;
     query: string;
     queryArgsCBOR: Uint8Array | null;
+    orderBys: OrderBy[];
+    limit: number;
+    offset: number;
 };
 /**
  * Used to subscribe to receive updates from remote peers about matching
@@ -1032,7 +1153,7 @@ declare class Subscription {
      */
     cancel(): void;
     /** @internal */
-    constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null);
+    constructor(collection: Collection, query: string, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number);
     /**
      * The collection this subscription belongs to.
      * @internal Because not exposed in any of the other SDKs (yet?).
@@ -1050,8 +1171,8 @@ declare class Subscription {
 }
 
 /**
- * Maps a {@link DocumentIDValue} to an array of
- * @link UpdateResult | update results}. This is the data structure you get
+ * Maps a {@link DocumentID} to an array of
+ * {@link UpdateResult | update results}. This is the data structure you get
  * when {@link PendingCursorOperation.update | updating} a set of documents
  * with detailed info about the performed updates.
  */
@@ -1060,14 +1181,14 @@ declare class UpdateResultsMap {
      * Returns an array of {@link UpdateResult | update results} associated with
      * the `documentID` or undefined if not found.
      */
-    get(documentID: DocumentIDValue): UpdateResult[] | undefined;
+    get(documentIDOrValue: DocumentID | DocumentIDValue): UpdateResult[] | undefined;
     /**
-     * Returns all contained keys, i.e. {@link DocumentIDValue | document IDs}
+     * Returns all contained keys, i.e. {@link DocumentID | document IDs}
      * contained in this map.
      */
-    keys(): DocumentIDValue[];
+    keys(): DocumentID[];
     /** @internal */
-    constructor(documentIDs: DocumentIDValue[], updateResultsByDocumentIDString: object);
+    constructor(documentIDs: DocumentID[], updateResultsByDocumentIDString: object);
     private documentIDs;
     private updateResultsByDocumentIDString;
 }
@@ -1257,20 +1378,20 @@ declare type QueryObservationHandler = (documents: Document[], event: LiveQueryE
  * {@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 observe | observe()}, will notify
+ * A live query, established by calling {@link PendingCursorOperation.observe | observe()}, 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 subscribe | subscribe()}, will
+ * 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.
  *
- * Calling {@link observe | observe()} will generate both a subscription and a
+ * Calling {@link PendingCursorOperation.observe | observe()} will generate both a subscription and a
  * live query at the same time.
  *
  * If you'd like to only observe local changes then you can call
- * {@link observeLocal | observeLocal()}.
+ * {@link PendingCursorOperation.observeLocal | observeLocal()}.
  *
  * Update and remove functionality is also exposed through this object.
  */
@@ -1346,7 +1467,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * The `handler` block will be called 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 observe | observe()}. The returned
+     * that precedes the call to {@link PendingCursorOperation.observe | observe()}. 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.
      *
@@ -1366,7 +1487,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * The `handler` block will be called 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 observe | observe()}. The returned
+     * that precedes the call to {@link PendingCursorOperation.observe | observe()}. 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.
      *
@@ -1384,7 +1505,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * 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 then use {@link observe | observe()} or
+     * remotely performed updates as well then use {@link PendingCursorOperation.observe | observe()} or
      * call {@link 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.
@@ -1403,7 +1524,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      *
      * The `handler` block will be called 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 observe | observe()}. The returned
+     * that precedes the call to {@link PendingCursorOperation.observe | observe()}. 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.
      *
@@ -1423,7 +1544,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      * @returns An array promise containing the IDs of the documents that were
      * removed.
      */
-    remove(): Promise<DocumentIDValue[]>;
+    remove(): Promise<DocumentID[]>;
     /**
      * Evicts all documents that match the query generated by the preceding
      * function chaining.
@@ -1431,7 +1552,7 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
      * @return An array promise containing the IDs of the documents that were
      * evicted.
      */
-    evict(): Promise<DocumentIDValue[]>;
+    evict(): Promise<DocumentID[]>;
     /**
      * Executes the query generated by the preceding function chaining and return
      * the list of matching documents.
@@ -1470,33 +1591,33 @@ declare class PendingCursorOperation implements PromiseLike<Document[]> {
  */
 declare type SingleObservationHandler = (document: Document | null, event: SingleDocumentLiveQueryEvent, signalNext?: () => void) => void | Promise<void>;
 /**
- * These objects are returned when using {@link findByID | findByID()}
+ * These objects are returned when using {@link Collection.findByID | findByID()}
  * functionality on {@link Collection | collections}.
  *
  * You can either call {@link exec | exec()} on the  object to get 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 observe | observe()}, will notify
+ * A live query, established by calling {@link PendingIDSpecificOperation.observe | observe()}, will notify
  * you every time there's an update to the document with the ID you provided in
- * the preceding {@link findByID | findByID()} call.
+ * the preceding {@link Collection.findByID | findByID()} call.
  *
- * A subscription, established by calling {@link subscribe | subscribe()}, will
+ * A subscription, established by calling {@link PendingIDSpecificOperation.subscribe | subscribe()}, will
  * act as a signal to other peers that you would like to receive updates from
  * them about the document with the ID you provided in the preceding
- * {@link findByID | findByID()} call.
+ * {@link Collection.findByID | findByID()} call.
  *
- * Calling {@link observe | observe()} will generate both a subscription and a
+ * Calling {@link PendingIDSpecificOperation.observe | observe()} will generate both a subscription and a
  * live query at the same time.
  *
  * If you'd like to only observe local changes then you can call
- * {@link observeLocal | observeLocal()}.
+ * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}.
  *
  * Update and remove functionality is also exposed through this object.
  */
 declare class PendingIDSpecificOperation implements PromiseLike<Document | undefined> {
     /** The ID of the document this operation operates on. */
-    readonly documentID: DocumentIDValue;
+    readonly documentID: DocumentID;
     /** The collection the receiver is operating on. */
     readonly collection: Collection;
     /**
@@ -1519,8 +1640,8 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * locally and remotely.
      *
      * The `handler` closure will be called when local or remote changes are
-     * made to the document referenced by the {@link findByID | findByID()} call
-     * that precedes the call to {@link observe | observe()}.
+     * made to the document referenced by the {@link Collection.findByID | findByID()} call
+     * that precedes the call to {@link PendingIDSpecificOperation.observe | observe()}.
      *
      * 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.
@@ -1528,7 +1649,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * @param handler A closure that will be called every time there is a
      * transaction committed to the store that involves a modification to the
      * document with the relevant ID in the collection that
-     * {@link observe | observe()} was called on.
+     * {@link PendingIDSpecificOperation.observe | observe()} was called on.
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
@@ -1540,8 +1661,8 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * to deliver the next event.
      *
      * The `handler` closure will be called when local or remote changes are
-     * made to the document referenced by the {@link findByID | findByID()} call
-     * that precedes the call to {@link observe | observe()}.
+     * made to the document referenced by the {@link Collection.findByID | findByID()} call
+     * that precedes the call to {@link PendingIDSpecificOperation.observe | observe()}.
      *
      * 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.
@@ -1549,7 +1670,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * @param handler A closure that will be called every time there is a
      * transaction committed to the store that involves a modification to the
      * document with the relevant ID in the collection that
-     * {@link observe | observe()} was called on.
+     * {@link PendingIDSpecificOperation.observe | observe()} was called on.
      *
      * @return A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
@@ -1561,9 +1682,9 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      *
      * 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 then use {@link observe | observe()} or
+     * remotely performed updates as well then use {@link PendingIDSpecificOperation.observe | observe()} or
      * also call {@link subscribe | subscribe()} separately, using another
-     * {@link findByID | findByID()} call that references the same document ID.
+     * {@link Collection.findByID | findByID()} call that references the same document ID.
      *
      * 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
@@ -1572,7 +1693,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * @param handler A block that will be called every time there is a
      * transaction committed to the store that involves a modification to the
      * document with the relevant ID in the collection that
-     * {@link observeLocal | observeLocal()} was called on.
+     * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
      *
      * @returns A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
@@ -1585,9 +1706,9 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      *
      * 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 then use {@link observe | observe()} or
+     * remotely performed updates as well then use {@link PendingIDSpecificOperation.observe | observe()} or
      * also call {@link subscribe | subscribe()} separately, using another
-     * {@link findByID | findByID()} call that references the same document ID.
+     * {@link Collection.findByID | findByID()} call that references the same document ID.
      *
      * 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
@@ -1596,7 +1717,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * @param handler A block that will be called every time there is a
      * transaction committed to the store that involves a modification to the
      * document with the relevant ID in the collection that
-     * {@link observeLocal | observeLocal()} was called on.
+     * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
      *
      * @returns A {@link LiveQuery} object that must be kept in scope for as long
      * as you want to keep receiving updates.
@@ -1620,7 +1741,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      * Executes the find operation to return the document with the matching ID.
      *
      * @returns The {@link Document} promise with the ID provided in the
-     * {@link findByID | findByID()} call or `undefined` if the document was
+     * {@link Collection.findByID | findByID()} call or `undefined` if the document was
      * not found.
      */
     exec(): Promise<Document | undefined>;
@@ -1637,7 +1758,7 @@ declare class PendingIDSpecificOperation implements PromiseLike<Document | undef
      */
     update(closure: (document: MutableDocument) => void): Promise<UpdateResult[]>;
     /** @internal */
-    constructor(documentID: DocumentIDValue, collection: Collection, skipIDEncodingAndValidation?: boolean);
+    constructor(documentID: DocumentID, collection: 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>;
     private documentIDCBOR;
@@ -1691,13 +1812,13 @@ declare class Collection {
      * ID.
      *
      * The returned object can be used to find and return the document or you can
-     * chain a call to {@link observe | observe()}, or {@link subscribe | subscribe()}
+     * chain a call to {@link PendingIDSpecificOperation.observe | observe()}, or {@link PendingIDSpecificOperation.subscribe | subscribe()}
      * if you want to get updates about the document over time. It can also be
      * used to update, remove or evict the document.
      *
      * @param id The ID of the document to find.
      */
-    findByID(id: DocumentIDValue): PendingIDSpecificOperation;
+    findByID(id: DocumentID | 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
@@ -1708,7 +1829,7 @@ declare class Collection {
      * @param options.writeStrategy Specifies the desired strategy for inserting a
      * document, defaults to `'merge'`.
      */
-    upsert(value: DocumentValue, options?: UpsertOptions): Promise<DocumentIDValue>;
+    upsert(value: DocumentValue, options?: UpsertOptions): Promise<DocumentID>;
     /**
      * Creates a new {@link Attachment} object, which can then be inserted into a
      * document. Node only, throws when running in the web browser.
@@ -1821,8 +1942,10 @@ declare class CollectionsEvent {
      * about collections, that the collections have moved to.
      */
     readonly moves: LiveQueryMove[];
-    constructor(params: CollectionsEventParams);
+    /** @internal */
     static initial(collections: Collection[]): CollectionsEvent;
+    /** @internal */
+    constructor(params: CollectionsEventParams);
 }
 
 /**
@@ -1831,7 +1954,7 @@ declare class CollectionsEvent {
  */
 declare type CollectionsObservationHandler = (event: CollectionsEvent) => void | Promise<void>;
 /**
- * These objects are returned when calling {@link collections | collections()}
+ * These objects are returned when calling {@link Store.collections | collections()}
  * on {@link Store}.
  *
  * They allow chaining of further collections-related functions. You can either
@@ -1839,7 +1962,7 @@ declare type CollectionsObservationHandler = (event: CollectionsEvent) => void |
  * {@link Collection}s 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 observe | observe()}, will notify
+ * A live query, established by calling {@link PendingCollectionsOperation.observe | observe()}, will notify
  * you every time there's a change in the collections that the device knows
  * about.
  *
@@ -1847,16 +1970,8 @@ declare type CollectionsObservationHandler = (event: CollectionsEvent) => void |
  * act as a signal to other peers that the device connects to that you would
  * like to receive updates from them about the collections that they know about.
  *
- * Calling {@link observe | observe()} will generate both a subscription and a
+ * Calling {@link PendingCollectionsOperation.observe | observe()} will generate both a subscription and a
  * live query at the same time.
- *
- * If you'd like to only observe local changes then you can call
- * {@link observeLocal | observeLocal()}.
- *
- * If you want to observe changes in such a way that you can signal when you're
- * ready for the live query to deliver a new update then you can call
- * {@link observeWithNextSignal | observeWithNextSignal()} or
- * {@link observeLocalWithNextSignal | observeLocalWithNextSignal()}.
  */
 declare class PendingCollectionsOperation implements PromiseLike<Collection[]> {
     /**
@@ -1976,7 +2091,7 @@ declare class Store {
      * Private method, used only by the Portal https://github.com/getditto/ditto/pull/3652
      * @internal
      */
-    registerLiveQueryWebhook(collectionName: string, query: string, url: string): Promise<DocumentIDValue>;
+    registerLiveQueryWebhook(collectionName: string, query: string, url: string): Promise<DocumentID>;
 }
 
 /** @internal */
@@ -2039,8 +2154,8 @@ declare class Ditto {
      * When using {@link observePeers | observePeers()}, 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 `startSync()`. If it
-     * is too long it may be truncated.
+     * 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. */
@@ -2074,7 +2189,8 @@ declare class Ditto {
     readonly isActivated: boolean;
     /**
      * Returns `true` if sync is active, otherwise returns `false`. Use
-     * `startSync()` to activate and `stopSync()` to deactivate sync.
+     * {@link startSync | startSync()} to activate and {@link stopSync | stopSync()}
+     * to deactivate sync.
      */
     readonly isSyncActive: boolean;
     /**
@@ -2093,8 +2209,8 @@ declare class Ditto {
      * (in-memory at the moment, support for IndexedDB is in development).
      * Defaults to `"ditto"`.
      *
-     * @see {@link identity}
-     * @see {@link path}
+     * @see {@link Ditto.identity}
+     * @see {@link Ditto.path}
      */
     constructor(identity?: Identity, path?: string);
     /**
@@ -2138,16 +2254,18 @@ declare class Ditto {
      * 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 Bluetooth, WiFi/LAN, and AWDL. The network configuration can be
-     * customized with `setTransportConfig()`. On the **Web**, only connecting via
-     * Websockets is supported.
+     * 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 Node is experimental, this method
-     * panics if no BluetoothLE hardware is available. Therefore, contrary to
-     * the above, the BluetoothLE transport is temporarily disabled by default
+     * **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}
@@ -2244,7 +2362,6 @@ declare class ObserverManager {
     private hasObservers;
     private registerIfNeeded;
     private unregisterIfNeeded;
-    private generateToken;
     private finalize;
 }
 
@@ -2503,5 +2620,5 @@ declare class CBOR {
     static decode(data: Uint8Array): any;
 }
 
-export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, CBOR, Collection, CollectionsEvent, CollectionsEventParams, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentIDValue, DocumentPath, DocumentValue, Identity, IdentityManual, IdentityOfflinePlayground, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, InitOptions, KeepAlive, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRGA, MutableRegister, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RGA, Register, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge, validateDocumentIDCBOR, validateDocumentIDValue };
+export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, AuthenticationStatus, Authenticator, CBOR, Collection, CollectionsEvent, CollectionsEventParams, CollectionsObservationHandler, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentID, DocumentIDValue, DocumentPath, DocumentValue, Identity, IdentityManual, IdentityOfflinePlayground, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentitySharedKey, IdentityTypesRequiringOfflineLicenseToken, InitOptions, KeepAlive, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableCounter, MutableDocument, MutableDocumentPath, MutableRGA, MutableRegister, NotAvailableAuthenticator, Observer, ObserverOptions, OnlineAuthenticator, PendingCollectionsOperation, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RGA, Register, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, UpsertOptions, Value, WebAssemblyModule, WriteStrategy, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge, validateDocumentIDCBOR, validateDocumentIDValue };
 //# sourceMappingURL=ditto.d.ts.map