@squidcloud/client/dist/typescript-client/src/document-reference.d.ts

A typescript implementation of the Squid client

import { Observable } from 'rxjs';
import { DeepRecord, Paths } from '../../internal-common/src/public-types/typescript.public-types';
import { DocumentData } from './public-types';
import { TransactionId } from './types';
/**
 * Holds a reference to a document. A document reference is a reference to a specific record in a collection. You can
 * use it to read or write data to the document. A document can refer to a row in a table in a relational database or a
 * document in a NoSQL database. Additionally, a document reference can refer to a non-existent document, which you can
 * use to create a new document.
 *
 * Read more about document references in the
 * {@link https://docs.getsquid.ai/docs/sdk/client-sdk/database/document-reference documentation}.
 * @typeParam T The type of the document data.
 * @category Database
 */
export declare class DocumentReference<T extends DocumentData = any> {
    private _squidDocId;
    private readonly dataManager;
    private readonly queryBuilderFactory;
    /** A string that uniquely identifies this document reference. */
    refId: string;
    /**
     * Returns the document data. Throws an error if the document does not exist.
     *
     * @returns The document data.
     * @throws Error if the document does not exist.
     */
    get data(): T;
    /**
     * Returns a read-only internal copy of the document data. This works similar to `this.data`, except it does not
     * perform a defensive copy. The caller may not modify this object, on penalty of unexpected behavior.
     *
     * @returns The document data.
     * @throws Error if the document does not exist.
     */
    get dataRef(): T;
    /**
     * Returns whether data has been populated for this document reference. Data
     * will not present if a document has not been queried, does not exist, or
     * has been deleted.
     *
     * @returns Whether the document has data.
     */
    get hasData(): boolean;
    /**
     * A promise that resolves with the latest data from the server or undefined if the document does not exist on the
     * server.
     *
     * @returns A promise that resolves with latest data from the server or undefined if the document does not exist on
     * the server.
     */
    snapshot(): Promise<T | undefined>;
    /**
     * Returns an observable that emits the latest data from the server or undefined if the document is deleted or does
     * not exist on the server.
     *
     * @returns An observable that emits the latest data from the server or undefined if the document is deleted or does
     * not exist on the server.
     */
    snapshots(): Observable<T | undefined>;
    /**
     * Returns the data that is currently available on the client or undefined if data has not yet been populated.
     *
     * @returns The data that is currently available on the client or undefined if data has not yet been populated.
     */
    peek(): T | undefined;
    /**
     * Returns whether the locally available version of the document may not be the latest version on the server.
     *
     * @returns Whether the locally available version of the document may not be the latest version on the server.
     */
    isDirty(): boolean;
    private isTracked;
    /**
     * Updates the document with the given data.
     * The `update` will be reflected optimistically locally and will be applied to the server later.
     * If a transactionId is provided, the `update` will be applied to the server as an atomic operation together with
     * the rest of the operations in the transaction and the `update` will not reflect locally until the transaction is
     * completed locally.
     *
     * The returned promise will resolve once the `update` has been applied to the server or immediately if the `update`
     * is part of a transaction.
     *
     * @param data The data to update - can be partial.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    update(data: Partial<DeepRecord<T>>, transactionId?: TransactionId): Promise<void>;
    /**
     * Similar to {@link update}, but only updates the given path.
     * @param path The path to update.
     * @param value The value to set at the given path.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    setInPath<K extends Paths<T>>(path: K, value: DeepRecord<T>[K], transactionId?: TransactionId): Promise<void>;
    /**
     * Similar to `update`, but only deletes the given path.
     * @param path The path to delete.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    deleteInPath(path: Paths<T>, transactionId?: TransactionId): Promise<void>;
    /**
     * Increments the value at the given path by the given value. The value may be both positive and negative.
     * @param path The path to the value to increment.
     * @param value The value to increment by.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    incrementInPath(path: Paths<T>, value: number, transactionId?: TransactionId): Promise<void>;
    /**
     * Decrements the value at the given path by the given value. The value may be both positive and negative.
     * @param path The path to the value to decrement.
     * @param value The value to decrement by.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    decrementInPath(path: Paths<T>, value: number, transactionId?: TransactionId): Promise<void>;
    /**
     * Inserts the document with the given data. If the document already exists, the operation will be treated as
     * `upsert`. The `insert` will be reflected optimistically locally and will be applied to the server later. If a
     * transactionId is provided, the `insert` will be applied to the server as an atomic operation together with the
     * rest
     * of the operations in the transaction and the `insert` will not reflect locally until the transaction is completed
     * locally.
     *
     * The returned promise will resolve once the `insert` has been applied to the server or immediately if the `insert`
     * is part of a transaction.
     *
     * @param data The data to insert.
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    insert(data: Omit<T, '__id'>, transactionId?: TransactionId): Promise<void>;
    /**
     * Deletes the document.
     * The `delete` will be reflected optimistically locally and will be applied to the server later.
     * If a transactionId is provided, the `delete` will be applied to the server as an atomic operation together with
     * the rest of the operations in the transaction and the `delete` will not reflect locally until the transaction is
     * completed locally.
     *
     * The returned promise will resolve once the `delete` has been applied to the server or immediately if the `delete`
     * is part of a transaction.
     *
     * @param transactionId The transaction to use for this operation. If not provided, the operation will be applied
     *   immediately.
     */
    delete(transactionId?: TransactionId): Promise<void>;
    private hasSquidPlaceholderId;
}