@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/collections.d.ts

@@ -0,0 +1,189 @@
+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';
+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;
+}
+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 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 path: string;
+    readonly id: string;
+    constructor(sdk: DocumentsTransport, path: string, body?: JsonObject);
+    private with;
+    where(field: string, op: WhereOp, value: unknown): Query<T>;
+    orderBy(field: string, direction?: Direction): Query<T>;
+    limit(n: number): Query<T>;
+    limitToLast(n: number): Query<T>;
+    private static 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;
+    get(): Promise<QuerySnapshot<T>>;
+    count(): Promise<number>;
+    /** 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 closed;
+    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 {};

package/dist/collections.js

@@ -0,0 +1,467 @@
+/**
+ * Firestore-style document collections: field queries, cursors, live listeners, batches,
+ * transactions and field transforms.
+ *
+ * ```ts
+ * const posts = sov.collection('posts')
+ * const page = await posts.where('published', '==', true).orderBy('likes', 'desc').limit(20).get()
+ * const next = await posts.where('published', '==', true).orderBy('likes', 'desc').limit(20).startAfter(page.docs.at(-1)!).get()
+ *
+ * await sov.doc('posts/p1').update({ likes: FieldValue.increment(1), tags: FieldValue.arrayUnion('new') })
+ *
+ * await sov.runTransaction(async (tx) => {
+ *   const a = await tx.get(sov.doc('accounts/a'))
+ *   tx.update(sov.doc('accounts/a'), { balance: (a.data?.balance as number) - 10 })
+ *   tx.update(sov.doc('accounts/b'), { balance: FieldValue.increment(10) })
+ * })
+ *
+ * const stop = await posts.where('room', '==', 'r1').onSnapshot((snap) => render(snap.docs))
+ * stop()
+ * ```
+ *
+ * Every call goes through the gateway with the caller's credentials, so collection rules (Guard)
+ * and the project's row policies decide what a query returns and what a write may change.
+ */
+import { SovariaError } from './errors.js';
+const BASE = '/api/v1/data/doc';
+function quotePath(path) {
+    return path.split('/').filter(Boolean).map(encodeURIComponent).join('/');
+}
+// ── field values ──────────────────────────────────────────────────────────────
+const TRANSFORM = Symbol('sovaria.fieldValue');
+function transform(op, value) {
+    return { [TRANSFORM]: true, op, value };
+}
+function isTransform(value) {
+    return typeof value === 'object' && value !== null && value[TRANSFORM] === true;
+}
+/** Atomic field updates, applied by the server inside the commit. */
+export const FieldValue = {
+    increment: (n) => transform('increment', n),
+    maximum: (n) => transform('maximum', n),
+    minimum: (n) => transform('minimum', n),
+    arrayUnion: (...elements) => transform('array_union', elements),
+    arrayRemove: (...elements) => transform('array_remove', elements),
+    serverTimestamp: () => transform('server_timestamp'),
+    delete: () => transform('delete'),
+};
+function fieldPath(parts) {
+    return parts.map((p) => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(p) ? p : '`' + p.replace(/\\/g, '\\\\').replace(/`/g, '\\`') + '`')).join('.');
+}
+/** Pull FieldValue sentinels out of nested data into the API's `transforms` list. */
+export function splitTransforms(data, prefix = []) {
+    const clean = {};
+    const transforms = [];
+    for (const [key, value] of Object.entries(data)) {
+        const path = [...prefix, key];
+        if (isTransform(value)) {
+            transforms.push({ field: fieldPath(path), op: value.op, value: (value.value ?? null) });
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const inner = splitTransforms(value, path);
+            transforms.push(...inner.transforms);
+            if (Object.keys(inner.data).length || !inner.transforms.length)
+                clean[key] = inner.data;
+        }
+        else {
+            clean[key] = value;
+        }
+    }
+    return { data: clean, transforms };
+}
+function setWrite(path, data, opts = {}) {
+    const split = splitTransforms(data);
+    const write = { op: opts.op ?? 'set', path, data: split.data, transforms: split.transforms };
+    if (opts.merge)
+        write.merge = true;
+    if (opts.mergeFields?.length)
+        write.merge_fields = opts.mergeFields;
+    return write;
+}
+function updateWrite(path, fields) {
+    const data = {};
+    const transforms = [];
+    for (const [key, value] of Object.entries(fields)) {
+        if (isTransform(value))
+            transforms.push({ field: key, op: value.op, value: (value.value ?? null) });
+        else
+            data[key] = value;
+    }
+    return { op: 'update', path, data, transforms };
+}
+function toSnapshot(raw) {
+    const exists = raw.exists !== false && raw.data !== null && raw.data !== undefined;
+    const path = String(raw.path ?? '');
+    return {
+        id: String(raw.id ?? path.split('/').pop() ?? ''),
+        path,
+        exists,
+        data: exists ? raw.data : null,
+        version: Number(raw.version ?? 0),
+        updateTime: raw.update_time ? String(raw.update_time) : undefined,
+        createTime: raw.create_time ? String(raw.create_time) : undefined,
+        ...(raw.from_cache ? { fromCache: true } : {}),
+        ...(raw.pending ? { hasPendingWrites: true } : {}),
+    };
+}
+function querySnapshot(docs, changes = [], extra = {}) {
+    return { docs, changes, hasMore: false, nextCursor: null, ...extra, empty: docs.length === 0, size: docs.length };
+}
+export class DocumentReference {
+    sdk;
+    path;
+    id;
+    constructor(sdk, path) {
+        this.sdk = sdk;
+        const parts = path.split('/').filter(Boolean);
+        if (parts.length < 2 || parts.length % 2)
+            throw SovariaError.config('A document path is collection/id (or collection/id/sub/id)');
+        this.path = parts.join('/');
+        this.id = parts[parts.length - 1];
+    }
+    get parent() {
+        return new Query(this.sdk, this.path.split('/').slice(0, -1).join('/'));
+    }
+    collection(name) {
+        return new Query(this.sdk, `${this.path}/${name}`);
+    }
+    async get() {
+        try {
+            const raw = await this.sdk.request('GET', `${BASE}/${quotePath(this.path)}`);
+            return toSnapshot({ ...raw, id: this.id, path: this.path });
+        }
+        catch (error) {
+            if (error instanceof SovariaError && error.statusCode === 404) {
+                return { id: this.id, path: this.path, exists: false, data: null, version: 0 };
+            }
+            throw error;
+        }
+    }
+    async commitOne(write) {
+        const out = await commitWrites(this.sdk, [write]);
+        return out.results[0];
+    }
+    /** Replace the document (or merge into it with `{ merge: true }`). */
+    set(data, opts = {}) {
+        return this.commitOne(setWrite(this.path, data, opts));
+    }
+    /** Create it; fails with 409 ALREADY_EXISTS when it exists. */
+    create(data) {
+        return this.commitOne(setWrite(this.path, data, { op: 'create' }));
+    }
+    /** Change fields (dotted paths allowed); fails with 404 when the document doesn't exist. */
+    update(fields, opts = {}) {
+        const write = updateWrite(this.path, fields);
+        if (opts.version !== undefined)
+            write.precondition = { version: opts.version };
+        return this.commitOne(write);
+    }
+    async delete(opts = {}) {
+        const write = { op: 'delete', path: this.path };
+        if (opts.version !== undefined)
+            write.precondition = { version: opts.version };
+        await commitWrites(this.sdk, [write]);
+    }
+    /** Live document: `callback` runs now and after every change. Returns a function that stops it. */
+    onSnapshot(callback, onError) {
+        return this.parent.where('__key__', '==', this.id).onSnapshot((snap) => {
+            callback(snap.docs[0] ?? { id: this.id, path: this.path, exists: false, data: null, version: 0 });
+        }, onError);
+    }
+}
+export class Query {
+    sdk;
+    body;
+    path;
+    id;
+    constructor(sdk, path, body = {}) {
+        this.sdk = sdk;
+        this.body = body;
+        const parts = path.split('/').filter(Boolean);
+        if (!parts.length || parts.length % 2 === 0)
+            throw SovariaError.config('A collection path is collection or collection/id/subcollection');
+        this.path = parts.join('/');
+        this.id = parts[parts.length - 1];
+    }
+    with(changes) {
+        const body = { ...this.body };
+        for (const [k, v] of Object.entries(changes)) {
+            if (v === undefined)
+                delete body[k];
+            else
+                body[k] = v;
+        }
+        return new Query(this.sdk, this.path, body);
+    }
+    where(field, op, value) {
+        return this.with({ where: [...(this.body.where ?? []), [field, op, value]] });
+    }
+    orderBy(field, direction = 'asc') {
+        return this.with({ order_by: [...(this.body.order_by ?? []), [field, direction]] });
+    }
+    limit(n) {
+        return this.with({ limit: n, limit_to_last: undefined });
+    }
+    limitToLast(n) {
+        return this.with({ limit_to_last: n, limit: undefined });
+    }
+    static cursor(args) {
+        const [first] = args;
+        if (args.length === 1 && first && typeof first === 'object' && !Array.isArray(first)) {
+            const obj = first;
+            if ('exists' in obj && typeof obj.id === 'string')
+                return { key: obj.id }; // a DocumentSnapshot
+            if (obj.values || obj.key)
+                return { values: obj.values, key: obj.key };
+        }
+        return { values: args };
+    }
+    startAt(...values) { return this.with({ start_at: Query.cursor(values), start_after: undefined }); }
+    startAfter(...values) { return this.with({ start_after: Query.cursor(values), start_at: undefined }); }
+    endAt(...values) { return this.with({ end_at: Query.cursor(values), end_before: undefined }); }
+    endBefore(...values) { return this.with({ end_before: Query.cursor(values), end_at: undefined }); }
+    doc(id) {
+        return new DocumentReference(this.sdk, `${this.path}/${id ?? newDocumentId()}`);
+    }
+    async add(data) {
+        const ref = this.doc();
+        await ref.create(data);
+        return ref;
+    }
+    toJSON() {
+        return JSON.parse(JSON.stringify(this.body));
+    }
+    async get() {
+        const raw = await this.sdk.request('POST', `${BASE}/_query/${quotePath(this.path)}`, { body: this.toJSON() });
+        const docs = (raw.documents ?? []).map((d) => toSnapshot(raw.from_cache ? { ...d, from_cache: true } : d));
+        return querySnapshot(docs, [], {
+            hasMore: Boolean(raw.has_more),
+            nextCursor: raw.next_cursor ?? null,
+            indexHint: raw.index_hint,
+        });
+    }
+    async count() {
+        const body = this.toJSON();
+        delete body.limit;
+        delete body.limit_to_last;
+        const raw = await this.sdk.request('POST', `${BASE}/_count/${quotePath(this.path)}`, { body });
+        return Number(raw.count ?? 0);
+    }
+    /** Every matching document, one request per page. */
+    async *pages(pageSize = 100) {
+        let query = this.limit(pageSize);
+        for (;;) {
+            const snap = await query.get();
+            yield* snap.docs;
+            if (!snap.hasMore || !snap.nextCursor)
+                return;
+            query = query.with({ start_after: snap.nextCursor, start_at: undefined });
+        }
+    }
+    /** Live results: `callback` runs with the first snapshot and after every change. Await it for the stop function. */
+    async onSnapshot(callback, onError) {
+        const listener = new LiveQuery(this.sdk, this, callback, onError);
+        await listener.start();
+        return () => listener.close();
+    }
+}
+export function newDocumentId() {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    const bytes = new Uint8Array(20);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join('');
+}
+export class LiveQuery {
+    sdk;
+    query;
+    callback;
+    onError;
+    id = '';
+    channel = '';
+    docs = new Map();
+    order = [];
+    seq = 0;
+    pending = [];
+    renewTimer;
+    socket;
+    closed = false;
+    constructor(sdk, query, callback, onError) {
+        this.sdk = sdk;
+        this.query = query;
+        this.callback = callback;
+        this.onError = onError;
+    }
+    async start() {
+        const raw = await this.sdk.request('POST', `${BASE}/_listen/${quotePath(this.query.path)}`, { body: this.query.toJSON() });
+        this.id = String(raw.id);
+        this.channel = String(raw.channel);
+        this.applyFull((raw.documents ?? []).map((d) => toSnapshot(d)), true);
+        const ttl = Number(raw.ttl_seconds ?? 600);
+        this.renewTimer = setInterval(() => {
+            this.sdk.request('POST', `${BASE}/_listeners/${this.id}/renew`).catch((error) => this.onError?.(error));
+        }, Math.max(30, ttl / 2) * 1000);
+        this.socket = this.sdk.openChannel(this.channel, {
+            onMessage: (payload) => void this.applyMessage(payload),
+            onStatus: (status) => {
+                // Changes published while the socket was (re)connecting: catch up with one query.
+                if (status === 'live')
+                    void this.resync();
+            },
+            onError: (error) => this.onError?.(error),
+        });
+    }
+    emit(changes) {
+        try {
+            this.callback(querySnapshot(this.order.map((id) => this.docs.get(id)), changes));
+        }
+        catch (error) {
+            this.onError?.(error);
+        }
+    }
+    applyFull(docs, initial = false) {
+        const oldIndex = new Map(this.order.map((id, i) => [id, i]));
+        const changes = [];
+        const ids = new Set(docs.map((d) => d.id));
+        for (const [id, i] of oldIndex)
+            if (!ids.has(id))
+                changes.push({ type: 'removed', doc: this.docs.get(id), oldIndex: i, newIndex: -1 });
+        docs.forEach((d, i) => {
+            const prev = this.docs.get(d.id);
+            if (!prev)
+                changes.push({ type: 'added', doc: d, oldIndex: -1, newIndex: i });
+            else if (prev.version !== d.version)
+                changes.push({ type: 'modified', doc: d, oldIndex: oldIndex.get(d.id) ?? -1, newIndex: i });
+        });
+        this.docs = new Map(docs.map((d) => [d.id, d]));
+        this.order = docs.map((d) => d.id);
+        if (changes.length || initial)
+            this.emit(changes);
+    }
+    async resync() {
+        if (this.closed)
+            return;
+        try {
+            this.applyFull((await this.query.get()).docs);
+        }
+        catch (error) {
+            this.onError?.(error);
+        }
+    }
+    async applyMessage(msg) {
+        // Offline mode: a local write or a sync asks the listener to re-read (served from the cache offline).
+        if (msg.type === 'local_resync' && (!msg.listener_id || msg.listener_id === this.id))
+            return this.resync();
+        if (msg.type !== 'doc_changes' || msg.listener_id !== this.id)
+            return;
+        const seq = Number(msg.seq ?? 0);
+        if (seq <= this.seq && (msg.part ?? 1) === 1)
+            return;
+        if (seq > this.seq + 1 || msg.resync || (msg.changes ?? []).some((c) => c.data_omitted)) {
+            this.seq = seq;
+            await this.resync();
+            return;
+        }
+        for (const c of msg.changes ?? []) {
+            if (c.type === 'removed') {
+                const gone = this.docs.get(String(c.id));
+                if (gone) {
+                    this.docs.delete(String(c.id));
+                    this.pending.push({ type: 'removed', doc: gone, oldIndex: Number(c.old_index ?? -1), newIndex: -1 });
+                }
+            }
+            else {
+                const snap = toSnapshot(c);
+                this.docs.set(snap.id, snap);
+                this.pending.push({ type: c.type, doc: snap, oldIndex: Number(c.old_index ?? -1), newIndex: Number(c.new_index ?? -1) });
+            }
+        }
+        if ((msg.part ?? 1) < (msg.parts ?? 1))
+            return;
+        this.seq = seq;
+        if (msg.ids)
+            this.order = msg.ids.filter((id) => this.docs.has(id));
+        else
+            this.order = this.order.filter((id) => this.docs.has(id)).concat([...this.docs.keys()].filter((id) => !this.order.includes(id)));
+        for (const id of [...this.docs.keys()])
+            if (!this.order.includes(id))
+                this.docs.delete(id);
+        const changes = this.pending;
+        this.pending = [];
+        this.emit(changes);
+    }
+    close() {
+        this.closed = true;
+        if (this.renewTimer)
+            clearInterval(this.renewTimer);
+        this.socket?.close();
+        this.sdk.request('DELETE', `${BASE}/_listeners/${this.id}`).catch(() => undefined);
+    }
+}
+// ── batches and transactions ──────────────────────────────────────────────────
+export function commitWrites(sdk, writes, reads = []) {
+    return sdk.request('POST', `${BASE}/_commit`, { body: { writes, reads } });
+}
+/** Writes committed together: every one or none (up to the plan's docs.max_transaction_writes). */
+export class WriteBatch {
+    sdk;
+    writes = [];
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    set(ref, data, opts = {}) {
+        this.writes.push(setWrite(ref.path, data, opts));
+        return this;
+    }
+    create(ref, data) {
+        this.writes.push(setWrite(ref.path, data, { op: 'create' }));
+        return this;
+    }
+    update(ref, fields) {
+        this.writes.push(updateWrite(ref.path, fields));
+        return this;
+    }
+    delete(ref) {
+        this.writes.push({ op: 'delete', path: ref.path });
+        return this;
+    }
+    commit() {
+        return commitWrites(this.sdk, this.writes);
+    }
+}
+export class Transaction extends WriteBatch {
+    reads = new Map();
+    async get(ref) {
+        if (this.writes.length)
+            throw SovariaError.config('Read every document before the first write in a transaction');
+        const raw = await this.sdk.request('POST', `${BASE}/_get`, { body: { paths: [ref.path] } });
+        const snap = toSnapshot(raw.documents[0]);
+        this.reads.set(ref.path, snap.version);
+        return snap;
+    }
+    get hasWrites() {
+        return this.writes.length > 0;
+    }
+    commit() {
+        return commitWrites(this.sdk, this.writes, [...this.reads].map(([path, version]) => ({ path, version })));
+    }
+}
+/** Run `fn` and commit its writes atomically; retried when a document it read changed meanwhile. */
+export async function runTransaction(sdk, fn, maxAttempts = 5) {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const tx = new Transaction(sdk);
+        const result = await fn(tx);
+        if (!tx.hasWrites)
+            return result;
+        try {
+            await tx.commit();
+            return result;
+        }
+        catch (error) {
+            // Contention only; ALREADY_EXISTS / NOT_FOUND / FAILED_PRECONDITION are final.
+            if (!(error instanceof SovariaError) || error.statusCode !== 409 || error.serverCode !== 'ABORTED')
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(2000, 50 * 2 ** attempt) * (0.5 + Math.random())));
+        }
+    }
+    throw new SovariaError(409, { code: 'ABORTED', message: `Transaction still conflicting after ${maxAttempts} attempts` });
+}