@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/collections.d.ts

@@ -0,0 +1,255 @@
+type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+type JsonObject = {
+    [key: string]: Json;
+};
+/** What the collection API needs from the SDK (keeps this module free of a circular import). */
+export interface DocumentsTransport {
+    request<T = unknown>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | number | boolean | null | undefined>;
+    }): Promise<T>;
+    openChannel(name: string, handlers: {
+        onMessage?: (payload: JsonObject) => void;
+        onStatus?: (status: string) => void;
+        onError?: (error: unknown) => void;
+    }): {
+        close: () => void;
+    };
+}
+export type WhereOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any';
+/** One filter or an `or` / `and` group: `posts.where(or(filter('a', '==', 1), filter('b', '<', 2)))`. */
+export type QueryFilter = [string, WhereOp, Json] | {
+    or: QueryFilter[];
+} | {
+    and: QueryFilter[];
+};
+export declare function filter(field: string, op: WhereOp, value: unknown): QueryFilter;
+/** Matches documents that match any of `filters` (Firestore `or()`; at most 30 OR terms after expansion). */
+export declare function or(...filters: QueryFilter[]): QueryFilter;
+/** Matches documents that match all of `filters` (Firestore `and()`), for nesting inside `or`. */
+export declare function and(...filters: QueryFilter[]): QueryFilter;
+/** An aggregation for `Query.aggregate`: `count()`, `sum('price')`, `average('rating')`. */
+export type AggregateField = {
+    op: 'count' | 'sum' | 'avg';
+    field?: string;
+};
+export declare const count: () => AggregateField;
+export declare const sum: (field: string) => AggregateField;
+export declare const average: (field: string) => AggregateField;
+export type Direction = 'asc' | 'desc';
+declare const TRANSFORM: unique symbol;
+export interface FieldTransform {
+    readonly [TRANSFORM]: true;
+    readonly op: string;
+    readonly value?: unknown;
+}
+/** Atomic field updates, applied by the server inside the commit. */
+export declare const FieldValue: {
+    increment: (n: number) => FieldTransform;
+    maximum: (n: number) => FieldTransform;
+    minimum: (n: number) => FieldTransform;
+    arrayUnion: (...elements: unknown[]) => FieldTransform;
+    arrayRemove: (...elements: unknown[]) => FieldTransform;
+    serverTimestamp: () => FieldTransform;
+    delete: () => FieldTransform;
+};
+/** Pull FieldValue sentinels out of nested data into the API's `transforms` list. */
+export declare function splitTransforms(data: Record<string, unknown>, prefix?: string[]): {
+    data: Record<string, unknown>;
+    transforms: JsonObject[];
+};
+export interface DocumentSnapshot<T = JsonObject> {
+    id: string;
+    path: string;
+    exists: boolean;
+    data: T | null;
+    version: number;
+    updateTime?: string;
+    createTime?: string;
+    /** Offline mode: read from the local cache (the server couldn't be reached). */
+    fromCache?: boolean;
+    /** Offline mode: a local write that hasn't reached the server yet. */
+    hasPendingWrites?: boolean;
+    /** Vector search (`findNearest`): the distance to the query vector (dot_product: the inner product). */
+    distance?: number;
+}
+export interface DocumentChange<T = JsonObject> {
+    type: 'added' | 'modified' | 'removed';
+    doc: DocumentSnapshot<T>;
+    oldIndex: number;
+    newIndex: number;
+}
+export interface QuerySnapshot<T = JsonObject> {
+    docs: DocumentSnapshot<T>[];
+    changes: DocumentChange<T>[];
+    hasMore: boolean;
+    /** Pass to `startAfter(cursor)` for the next page. */
+    nextCursor: {
+        values: Json[];
+    } | null;
+    /** A composite index that would serve this query (create it in Collections › Indexes). */
+    indexHint?: {
+        collection: string;
+        fields: {
+            path: string;
+            order: string;
+        }[];
+    };
+    empty: boolean;
+    size: number;
+}
+export type DistanceMeasure = 'cosine' | 'euclidean' | 'dot_product';
+export interface FindNearestOptions {
+    /** The vector field: an array of numbers in each document. */
+    vectorField: string;
+    queryVector: number[];
+    limit: number;
+    /** Default cosine. */
+    distanceMeasure?: DistanceMeasure | 'COSINE' | 'EUCLIDEAN' | 'DOT_PRODUCT';
+    /** Also write the distance into each result's data under this field. */
+    distanceResultField?: string;
+    /** cosine / euclidean: at most this distance; dot_product: at least this product. */
+    distanceThreshold?: number;
+}
+/** A `findNearest` query: `await query.findNearest({...}).get()`. */
+export declare class VectorQuery<T = JsonObject> {
+    private readonly sdk;
+    readonly path: string;
+    private readonly body;
+    constructor(sdk: DocumentsTransport, path: string, body: JsonObject);
+    toJSON(): JsonObject;
+    get(): Promise<QuerySnapshot<T>>;
+}
+export declare class DocumentReference<T = JsonObject> {
+    private readonly sdk;
+    readonly path: string;
+    readonly id: string;
+    constructor(sdk: DocumentsTransport, path: string);
+    get parent(): Query<T>;
+    collection<U = JsonObject>(name: string): Query<U>;
+    get(): Promise<DocumentSnapshot<T>>;
+    private commitOne;
+    /** Replace the document (or merge into it with `{ merge: true }`). */
+    set(data: Partial<T> & Record<string, unknown>, opts?: {
+        merge?: boolean;
+        mergeFields?: string[];
+    }): Promise<JsonObject>;
+    /** Create it; fails with 409 ALREADY_EXISTS when it exists. */
+    create(data: Partial<T> & Record<string, unknown>): Promise<JsonObject>;
+    /** Change fields (dotted paths allowed); fails with 404 when the document doesn't exist. */
+    update(fields: Record<string, unknown>, opts?: {
+        version?: number;
+    }): Promise<JsonObject>;
+    delete(opts?: {
+        version?: number;
+    }): Promise<void>;
+    /** Live document: `callback` runs now and after every change. Returns a function that stops it. */
+    onSnapshot(callback: (doc: DocumentSnapshot<T>) => void, onError?: (error: unknown) => void): Promise<() => void>;
+}
+export declare class Query<T = JsonObject> {
+    private readonly sdk;
+    private readonly body;
+    readonly isGroup: boolean;
+    readonly path: string;
+    readonly id: string;
+    /**
+     * A collection, or with `isGroup` (`sov.collectionGroup('comments')`) every collection with that id at any
+     * depth; in a group, document cursors and `__key__` are full document paths.
+     */
+    constructor(sdk: DocumentsTransport, path: string, body?: JsonObject, isGroup?: boolean);
+    private with;
+    where(field: string, op: WhereOp, value: unknown): Query<T>;
+    where(filter: QueryFilter): Query<T>;
+    orderBy(field: string, direction?: Direction): Query<T>;
+    limit(n: number): Query<T>;
+    limitToLast(n: number): Query<T>;
+    private cursor;
+    startAt(...values: unknown[]): Query<T>;
+    startAfter(...values: unknown[]): Query<T>;
+    endAt(...values: unknown[]): Query<T>;
+    endBefore(...values: unknown[]): Query<T>;
+    doc(id?: string): DocumentReference<T>;
+    add(data: Partial<T> & Record<string, unknown>): Promise<DocumentReference<T>>;
+    toJSON(): JsonObject;
+    /**
+     * Vector search like Firestore's `findNearest`: this query's `where` filters run first, then the `limit`
+     * documents whose `vectorField` is closest to `queryVector` come back closest first, each with `distance`.
+     */
+    findNearest(opts: FindNearestOptions): VectorQuery<T>;
+    get(): Promise<QuerySnapshot<T>>;
+    count(): Promise<number>;
+    /**
+     * count / sum / average on the server, like Firestore's `getAggregateFromServer`:
+     * `await orders.where('paid', '==', true).aggregate({ n: count(), revenue: sum('total'), avg: average('total') })`.
+     * sum and average only use numeric values; average is null when there are none. With `limit`, they cover
+     * the first `limit` results; without, every match.
+     */
+    aggregate<S extends Record<string, AggregateField>>(spec: S): Promise<{
+        [K in keyof S]: number | null;
+    }>;
+    /** Every matching document, one request per page. */
+    pages(pageSize?: number): AsyncGenerator<DocumentSnapshot<T>>;
+    /** Live results: `callback` runs with the first snapshot and after every change. Await it for the stop function. */
+    onSnapshot(callback: (snap: QuerySnapshot<T>) => void, onError?: (error: unknown) => void): Promise<() => void>;
+}
+export declare function newDocumentId(): string;
+interface ChangeMessage {
+    type?: string;
+    listener_id?: string;
+    seq?: number;
+    part?: number;
+    parts?: number;
+    changes?: JsonObject[];
+    ids?: string[];
+    resync?: boolean;
+}
+export declare class LiveQuery<T = JsonObject> {
+    private readonly sdk;
+    private readonly query;
+    private readonly callback;
+    private readonly onError?;
+    id: string;
+    channel: string;
+    private docs;
+    private order;
+    private seq;
+    private pending;
+    private renewTimer?;
+    private socket?;
+    private pollTimer?;
+    private closed;
+    /** A server without collection-group listeners (older): the group query is re-run this often (ms). */
+    static groupPollMs: number;
+    constructor(sdk: DocumentsTransport, query: Query<T>, callback: (snap: QuerySnapshot<T>) => void, onError?: ((error: unknown) => void) | undefined);
+    start(): Promise<void>;
+    private emit;
+    applyFull(docs: DocumentSnapshot<T>[], initial?: boolean): void;
+    resync(): Promise<void>;
+    applyMessage(msg: ChangeMessage): Promise<void>;
+    close(): void;
+}
+export declare function commitWrites(sdk: DocumentsTransport, writes: JsonObject[], reads?: JsonObject[]): Promise<JsonObject>;
+/** Writes committed together: every one or none (up to the plan's docs.max_transaction_writes). */
+export declare class WriteBatch {
+    protected readonly sdk: DocumentsTransport;
+    protected writes: JsonObject[];
+    constructor(sdk: DocumentsTransport);
+    set(ref: DocumentReference<any>, data: Record<string, unknown>, opts?: {
+        merge?: boolean;
+    }): this;
+    create(ref: DocumentReference<any>, data: Record<string, unknown>): this;
+    update(ref: DocumentReference<any>, fields: Record<string, unknown>): this;
+    delete(ref: DocumentReference<any>): this;
+    commit(): Promise<JsonObject>;
+}
+export declare class Transaction extends WriteBatch {
+    private reads;
+    get<T = JsonObject>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    get hasWrites(): boolean;
+    commit(): Promise<JsonObject>;
+}
+/** Run `fn` and commit its writes atomically; retried when a document it read changed meanwhile. */
+export declare function runTransaction<R>(sdk: DocumentsTransport, fn: (tx: Transaction) => Promise<R>, maxAttempts?: number): Promise<R>;
+export {};