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

A typescript implementation of the Squid client

import { DocumentReference } from './document-reference';
import { Alias, DocIdOrDocIdObj, DocumentData } from './public-types';
import { JoinQueryBuilder } from './query/join-query-builder.factory';
import { QueryBuilder } from './query/query-builder.factory';
import { SnapshotEmitter } from './query/snapshot-emitter';
/**
 * Represents a docId and the data to be inserted.
 * If the docId is not provided, it will be generated on the server in case the integration supports it.
 * Read more about docId in the
 * {@link https://docs.squid.cloud/docs/api-reference/client-sdk-reference/classes/CollectionReference#doc
 * documentation}.
 * @category Database
 */
export interface DocIdAndData<T extends DocumentData> {
    /** Optional document ID. If not provided, it may be generated by the server. */
    id?: DocIdOrDocIdObj;
    /** Data associated with the document. */
    data: T;
}
/**
 *  Holds a reference to a data collection. A collection reference is a reference to a collection in a database. You
 * can use it to read or write data to the collection. A collection can refer to a table in a relational database or a
 * collection in a NoSQL database.
 *
 * Read more about collection references in the
 * {@link https://docs.getsquid.ai/docs/sdk/client-sdk/database/collection-reference documentation}.
 * @typeParam T The type of the document data.
 * @category Database
 */
export declare class CollectionReference<T extends DocumentData> {
    private readonly collectionName;
    private integrationId;
    private readonly documentReferenceFactory;
    private readonly queryBuilderFactory;
    private readonly querySubscriptionManager;
    private readonly dataManager;
    /** A string that uniquely identifies this collection reference. */
    refId: string;
    /**
     * Returns a document reference for the given document id.
     * The document id is an object that maps the primary keys of the collection (as defined in the Squid Console)
     * to their values. There are a few exceptions:
     * 1 - String document id is only supported for the `built_in_db` when a schema was not defined.
     * 2 - Not all the fields in the document id are required. If a field is not provided, it will be generated on the
     *     server once the document is created (if the integration supports it).
     * 3 - When a document id is not provided, it will be treated as an empty object or empty string.
     * 4 - When the document id is just a `string` and not provided (applies only for the `built_in_db`), it will be
     *    generated on the server.
     * 5 - If the collection in the `built_in_db` does not have a schema, the document id must be provided as a string.
     *
     * Examples:
     * ```typescript
     * // For a collection in the built_in_db that does not have a schema
     * const docRef = collectionRef.doc('my-doc-id');
     * const docRef = collectionRef.doc({id: my-doc-id'});
     *
     * // For a collection with a single primary key field called "id"
     * const docRef = collectionRef.doc({id: 'my-doc-id'});
     *
     * // For a collection with a composite primary key
     * const docRef = collectionRef.doc({id1: 'my-doc-id1', id2: 'my-doc-id2'});
     * const docRef = collectionRef.doc({id1: 'my-doc-id1'}); // id2 will be generated on the server if the integration
     * supports it
     *
     * // For a collection from the `built_in_db` without a defined schema when an id is not provided
     *  const docRef = collectionRef.doc(); // The id will be generated on the server
     * ```
     *
     * @param docId The document id as an object for the different fields in the primary key or a string.
     * @returns A document reference for the given document id.
     */
    doc(docId?: DocIdOrDocIdObj): DocumentReference<T>;
    /**
     * Inserts multiple documents into the collection.
     */
    insertMany(docs: Array<DocIdAndData<T>>, txId?: string): Promise<void>;
    /**
     * Deletes multiple documents from the collection.
     */
    deleteMany(docIdsOrReferences: Array<DocIdOrDocIdObj | DocumentReference<T>>, txId?: string): Promise<void>;
    /**
     * Creates a `QueryBuilder` that can be used to query the collection.
     *
     * @returns A `QueryBuilder` that can be used to query the collection.
     */
    query(): QueryBuilder<T>;
    /**
     * Creates a `JoinQueryBuilder` that can be used to query the collection
     * Note that when using a join query, you have to provide an alias for the query and for every other query
     * participating in the join.
     *
     * @param alias The alias for the query.
     * @returns A `JoinQueryBuilder` that can be used to query the collection and joins with other queries.
     */
    joinQuery<A extends Alias>(alias: A): JoinQueryBuilder<Record<A, []>, Record<A, T>, A, A>;
    /**
     * Performs `or` on a list of queries. All the queries need to be on the same collection.
     * The result will be a merge of all the queries sorted by the same sort condition of the first query.
     * Duplicate items will be removed.
     * @param builders The list of query builders to merge. (A query builder can be returned from the {@link query}
     *   method).
     * @returns A query builder that can be used to perform the `or` operation.
     */
    or(...builders: QueryBuilder<T>[]): SnapshotEmitter<DocumentReference<T>>;
}