@dittolive/ditto 1.0.15-alpha1 → 1.0.18-alpha1

package/types/ditto.d.ts

@@ -23,6 +23,10 @@ declare type Pointer<Type> = {
 };
 /** @internal */
 declare type AuthClientType = 'CAuthClient_t';
+declare type OrderBy = {
+    query: string;
+    direction: 'Ascending' | 'Descending';
+};
 /** Various options to pass the web assembly module to Ditto. */
 declare type WebAssemblyModule = RequestInfo | URL | Response | BufferSource | WebAssembly.Module | string | null;
 
@@ -243,7 +247,7 @@ interface IdentityOnlinePlayground {
      * found at https://portal.ditto.live.
      */
     appID: string;
-    /** If true, auto-configure sync with Ditto Cloud. */
+    /** If true, auto-configure sync with Ditto Cloud. Default is `true`. */
     enableDittoCloudSync?: boolean;
 }
 /**
@@ -534,86 +538,6 @@ declare class Bridge<JSClass extends object, FFIType> {
     private finalize;
 }
 
-/** Represents a unique identifier for a {@link Document}. */
-declare class DocumentID {
-    /**
-     * 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.
-     */
-    constructor(value: any, skipCBOREncoding?: 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 the value of the receiver, lazily decoded from its CBOR
-     * representation if needed.
-     */
-    get value(): any;
-}
-
-declare class Counter {
-    /** The value of the counter. */
-    readonly value: number;
-    /** Whether the counter is set as a default value. */
-    readonly isDefault: boolean;
-    /**
-     * Creates a new counter with an initial value that can be used as part
-     * of a document's content.
-     *
-     * @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
-     * you expect to be overwritten by other devices in the network. The default
-     * value is `false`.
-     */
-    constructor(value: number, isDefault?: boolean);
-    /**
-     * 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.
-     */
-    increment(amount: number): void;
-    /** @internal */
-    static __newInternal(mutDoc: any, path: any, value: any): Counter;
-    private mutDoc;
-    private path;
-}
-
 /**
  * The types of an {@link UpdateResult}.
  */
@@ -622,7 +546,7 @@ declare class UpdateResult {
     /** The update result's type. */
     readonly type: UpdateResultType;
     /** The ID of the document that was updated. */
-    readonly docID: DocumentID;
+    readonly docID: DocumentIDValue;
     /** The path to the key in the document that was updated. */
     readonly path: string;
     /**
@@ -642,19 +566,19 @@ declare class UpdateResult {
     /** The associated amount, only set if {@link type} is `incremented`. */
     readonly amount?: number;
     /** @internal */
-    static set(docID: DocumentID, path: string, value?: any): UpdateResult;
+    static set(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
     /** @internal */
-    static replacedWithCounter(docID: DocumentID, path: string): UpdateResult;
+    static replacedWithCounter(docID: DocumentIDValue, path: string): UpdateResult;
     /** @internal */
-    static incremented(docID: DocumentID, path: string, amount: number): UpdateResult;
+    static incremented(docID: DocumentIDValue, path: string, amount: number): UpdateResult;
     /** @internal */
-    static inserted(docID: DocumentID, path: string, value?: any): UpdateResult;
+    static inserted(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
     /** @internal */
-    static removed(docID: DocumentID, path: string): UpdateResult;
+    static removed(docID: DocumentIDValue, path: string): UpdateResult;
     /** @internal */
-    static pushed(docID: DocumentID, path: string, value?: any): UpdateResult;
+    static pushed(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
     /** @internal */
-    static popped(docID: DocumentID, path: string, value?: any): UpdateResult;
+    static popped(docID: DocumentIDValue, path: string, value?: any): UpdateResult;
     /** @internal */
     private constructor();
 }
@@ -787,53 +711,8 @@ declare class MutableDocumentPath {
     atIndex(index: number): MutableDocumentPath;
 }
 
-/**
- * Serves as a token for a specific attachment that you can pass to a call to
- * {@link Collection.fetchAttachment | fetchAttachment()} on a
- * {@link Collection}.
- */
-declare class AttachmentToken {
-    /** @internal */
-    readonly id: Uint8Array;
-    /** @internal */
-    readonly len: number;
-    /** @internal */
-    readonly metadata: {
-        [key: string]: string;
-    };
-    /** @internal */
-    constructor(jsObj: object);
-}
-
-/**
- * Represents an attachment and can be used to insert the associated attachment
- * into a document at a specific key.
- */
-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.
-     */
-    getData(): Promise<Uint8Array>;
-    /**
-     * 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.
-     */
-    copyToPath(path: string): Promise<void>;
-    /** @internal */
-    constructor(ditto: Ditto, token: AttachmentToken);
-}
-declare const attachmentBridge: Bridge<Attachment, "AttachmentHandle_t">;
-
+/** Represents a unique identifier for a {@link Document}. */
+declare type DocumentIDValue = any;
 /**
  * This is used whenever you can access the document content properties
  * directly via the document.
@@ -848,15 +727,13 @@ declare type MutableDocumentLike = MutableDocument | DocumentValue | any;
  * A document value is a JavaScript object containing values for keys that
  * can be serialized via CBOR.
  */
-declare type DocumentValue = {
-    [key: string]: null | boolean | boolean[] | number | number[] | string | string[] | DocumentID | DocumentValue | DocumentValue[] | Counter | Attachment | AttachmentToken;
-};
+declare type DocumentValue = Record<string, any>;
 /** A document belonging to a {@link Collection} with an inner value. */
 declare class Document {
     /**
      * Returns the ID of the document.
      */
-    readonly _id: DocumentID;
+    readonly _id: DocumentIDValue;
     /**
      * Returns the content (aka value) of the document.
      */
@@ -872,11 +749,27 @@ declare class Document {
     /**
      * Returns the ID for a document.
      */
-    static id(document: DocumentLike): DocumentID;
+    static id(document: DocumentLike): DocumentIDValue;
     /**
      * Returns the content (aka inner value) of a document.
      */
     static value(document: DocumentLike): DocumentValue;
+    /**
+     * 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 the content (aka inner value) of a document at the given path.
      */
@@ -909,7 +802,7 @@ declare class MutableDocument {
     /**
      * Returns the ID of the document.
      */
-    readonly _id: DocumentID;
+    readonly _id: DocumentIDValue;
     /**
      * Returns the content (aka value) of the document. What you actually get is
      * a proxy that you can freely manipulate and Ditto will register the changes,
@@ -940,7 +833,7 @@ declare class MutableDocument {
      */
     readonly _incrementCounterAt: (mutableDocument: MutableDocumentLike, keyPath: string, amount: number, skipValidation?: boolean) => void;
     /** Returns the ID for a mutable document. */
-    static id(mutableDocument: MutableDocumentLike): DocumentID;
+    static id(mutableDocument: MutableDocumentLike): DocumentIDValue;
     /**
      * Returns the content (aka inner value) of a mutable document.
      */
@@ -972,6 +865,53 @@ declare const documentBridge: Bridge<Document, "CDocument_t">;
 /** @internal */
 declare const mutableDocumentBridge: Bridge<MutableDocument, "CDocument_t">;
 
+/**
+ * Serves as a token for a specific attachment that you can pass to a call to
+ * {@link Collection.fetchAttachment | fetchAttachment()} on a
+ * {@link Collection}.
+ */
+declare class AttachmentToken {
+    /** @internal */
+    readonly id: Uint8Array;
+    /** @internal */
+    readonly len: number;
+    /** @internal */
+    readonly metadata: {
+        [key: string]: string;
+    };
+    /** @internal */
+    constructor(jsObj: object);
+}
+
+/**
+ * Represents an attachment and can be used to insert the associated attachment
+ * into a document at a specific key.
+ */
+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.
+     */
+    getData(): Promise<Uint8Array>;
+    /**
+     * 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.
+     */
+    copyToPath(path: string): Promise<void>;
+    /** @internal */
+    constructor(ditto: Ditto, token: AttachmentToken);
+}
+declare const attachmentBridge: Bridge<Attachment, "AttachmentHandle_t">;
+
 /**
  * The types of attachment fetch events that can be delivered to an attachment
  * fetcher's `callback`.
@@ -1105,7 +1045,7 @@ declare class Subscription {
 }
 
 /**
- * Maps a {@link DocumentID} object to an array of
+ * Maps a {@link DocumentIDValue} 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.
@@ -1115,14 +1055,14 @@ declare class UpdateResultsMap {
      * Returns an array of {@link UpdateResult | update results} associated with
      * the `documentID` or undefined if not found.
      */
-    get(documentID: DocumentID): UpdateResult[] | undefined;
+    get(documentID: DocumentIDValue): UpdateResult[] | undefined;
     /**
-     * Returns all contained keys, i.e. {@link DocumentID | document IDs} of
+     * Returns all contained keys, i.e. {@link DocumentIDValue | document IDs}
      * contained in this map.
      */
-    keys(): DocumentID[];
+    keys(): DocumentIDValue[];
     /** @internal */
-    constructor(documentIDs: DocumentID[], updateResultsByDocumentIDString: object);
+    constructor(documentIDs: DocumentIDValue[], updateResultsByDocumentIDString: object);
     private documentIDs;
     private updateResultsByDocumentIDString;
 }
@@ -1162,9 +1102,10 @@ declare class LiveQuery {
     /** @internal */
     readonly waitsForNextSignal: boolean;
     /** @internal */
-    constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, limit: number, offset: number, collection: Collection, subscription: Subscription | null, waitsForNextSignal: boolean, handler: QueryObservationHandler);
+    constructor(query: string, queryArgs: QueryArguments | null, queryArgsCBOR: Uint8Array | null, orderBys: OrderBy[], limit: number, offset: number, collection: Collection, subscription: Subscription | null, waitsForNextSignal: boolean, handler: QueryObservationHandler);
     /** @internal */
     signalNext(): Promise<void>;
+    private orderBys;
     private queryArgsCBOR;
     private liveQueryID;
 }
@@ -1474,7 +1415,7 @@ declare class PendingCursorOperation implements PromiseLike<DocumentLike[]> {
      * @returns An array promise containing the IDs of the documents that were
      * removed.
      */
-    remove(): Promise<DocumentID[]>;
+    remove(): Promise<DocumentIDValue[]>;
     /**
      * Evicts all documents that match the query generated by the preceding
      * function chaining.
@@ -1482,7 +1423,7 @@ declare class PendingCursorOperation implements PromiseLike<DocumentLike[]> {
      * @return An array promise containing the IDs of the documents that were
      * evicted.
      */
-    evict(): Promise<DocumentID[]>;
+    evict(): Promise<DocumentIDValue[]>;
     /**
      * Executes the query generated by the preceding function chaining and return
      * the list of matching documents.
@@ -1547,7 +1488,7 @@ declare type SingleObservationHandler = (document: DocumentLike | null, event: S
  */
 declare class PendingIDSpecificOperation implements PromiseLike<DocumentLike | undefined> {
     /** The ID of the document this operation operates on. */
-    readonly documentID: DocumentID;
+    readonly documentID: DocumentIDValue;
     /** The collection the receiver is operating on. */
     readonly collection: Collection;
     /**
@@ -1688,9 +1629,10 @@ declare class PendingIDSpecificOperation implements PromiseLike<DocumentLike | u
      */
     update(closure: (document: MutableDocumentLike) => void): Promise<UpdateResult[]>;
     /** @internal */
-    constructor(documentID: DocumentID, collection: Collection);
+    constructor(documentID: DocumentIDValue, 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;
     private get query();
     private _observe;
 }
@@ -1747,20 +1689,16 @@ declare class Collection {
      * 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. If not an instance of
-     * {@link DocumentID} then Ditto will automatically create a {@link DocumentID}
-     * instance from it.
+     * @param id The ID of the document to find.
      */
-    findByID(id: DocumentID | any): PendingIDSpecificOperation;
+    findByID(id: DocumentIDValue): PendingIDSpecificOperation;
     /**
      * Inserts a new document into the collection and returns its ID.
      *
      * @param value The content for the new document to insert.
      *
      * @param options.id The ID to use for the document. If `null` or `undefined`
-     * then Ditto will automatically generate an ID. If not an instance of
-     * {@link DocumentID} then Ditto will automatically create a
-     * {@link DocumentID} instance from it.
+     * then Ditto will automatically generate an ID.
      *
      * @param options.isDefault This option is now deprecated. You should instead
      * specify a `writeStrategy` if you wish to insert data as default data. If
@@ -1773,7 +1711,7 @@ declare class Collection {
      * @param options.writeStrategy Specifies the desired strategy for inserting a
      * document. The default value is `'overwrite'`.
      */
-    insert(value: DocumentValue, options?: InsertOptions): Promise<DocumentID>;
+    insert(value: DocumentValue, options?: InsertOptions): Promise<DocumentIDValue>;
     /**
      * Creates a new {@link Attachment} object, which can then be inserted into a
      * document. Node only, throws when running in the web browser.
@@ -1791,8 +1729,7 @@ declare class Collection {
      *
      * ``` JavaScript
      * const attachment = collection.newAttachment('/path/to/my/file.pdf')
-     * const docID = new DocumentID('123')
-     * collection.insert({ _id: docID, attachment, other: 'some-string' })
+     * collection.insert({ _id: '123', attachment, other: 'some-string' })
      * }
      * ```
      *
@@ -2038,7 +1975,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): DocumentID;
+    registerLiveQueryWebhook(collectionName: string, query: string, url: string): DocumentIDValue;
 }
 
 /** @internal */
@@ -2279,6 +2216,33 @@ declare class Value {
     constructor(value: unknown, options?: unknown);
 }
 
+declare class Counter {
+    /** The value of the counter. */
+    readonly value: number;
+    /** Whether the counter is set as a default value. */
+    readonly isDefault: boolean;
+    /**
+     * Creates a new counter with an initial value that can be used as part
+     * of a document's content.
+     *
+     * @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
+     * you expect to be overwritten by other devices in the network. The default
+     * value is `false`.
+     */
+    constructor(value: number, isDefault?: boolean);
+    /**
+     * 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.
+     */
+    increment(amount: number): void;
+    /** @internal */
+    static __newInternal(mutDoc: any, path: any, value: any): Counter;
+    private mutDoc;
+    private path;
+}
+
 /** The log levels supported by Ditto. */
 declare type LogLevel = 'Error' | 'Warning' | 'Info' | 'Debug' | 'Verbose';
 /**
@@ -2445,5 +2409,5 @@ declare class Logger {
     private constructor();
 }
 
-export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, Authenticator, Collection, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentID, DocumentLike, DocumentPath, DocumentValue, Identity, IdentityDevelopment, IdentityManual, IdentityOfflinePlayground, IdentityOnline, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentityProduction, IdentitySharedKey, InitOptions, InsertOptions, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableDocument, MutableDocumentLike, MutableDocumentPath, NotAvailableAuthenticator, Observer, OnlineWithAuthenticationAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, Value, WebAssemblyModule, WriteStrategy, __log, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge };
+export { Attachment, AttachmentFetchEvent, AttachmentFetchEventCompleted, AttachmentFetchEventDeleted, AttachmentFetchEventProgress, AttachmentFetchEventType, AttachmentFetcher, AttachmentToken, AuthenticationHandler, Authenticator, Collection, CollectionsEvent, CollectionsEventParams, ConditionSource, Counter, CustomLogCallback, Ditto, Document, DocumentIDValue, DocumentLike, DocumentPath, DocumentValue, Identity, IdentityDevelopment, IdentityManual, IdentityOfflinePlayground, IdentityOnline, IdentityOnlinePlayground, IdentityOnlineWithAuthentication, IdentityProduction, IdentitySharedKey, InitOptions, InsertOptions, LiveQuery, LiveQueryEvent, LiveQueryEventInitial, LiveQueryEventUpdate, LiveQueryEventUpdateParams, LiveQueryMove, LogLevel, Logger, MutableDocument, MutableDocumentLike, MutableDocumentPath, NotAvailableAuthenticator, Observer, OnlineWithAuthenticationAuthenticator, PendingCursorOperation, PendingIDSpecificOperation, PresenceConnectionType, QueryArguments, QueryObservationHandler, RemotePeer, SingleDocumentLiveQueryEvent, SingleObservationHandler, SortDirection, Store, Subscription, SubscriptionContextInfo, TransportCondition, TransportConfig, TransportConfigConnect, TransportConfigGlobal, TransportConfigLan, TransportConfigListen, TransportConfigListenHTTP, TransportConfigListenTCP, TransportConfigPeerToPeer, UpdateResult, UpdateResultType, UpdateResultsMap, Value, WebAssemblyModule, WriteStrategy, __log, attachmentBridge, dittoBridge, documentBridge, init, mutableDocumentBridge };
 //# sourceMappingURL=ditto.d.ts.map