shelving 1.274.0 → 1.276.0

package/extract/ModuleExtractor.d.ts

@@ -6,7 +6,7 @@ import { Extractor } from "./Extractor.js";
  * @see https://shelving.cc/extract/ModuleExtractorInput
  */
 export interface ModuleExtractorInput {
-    /** Display name for the module, derived from the package.json export key (e.g. `"util/string"`, `"firestore/client"`). */
+    /** Display name for the module, derived from the package.json export key (e.g. `"util/string"`, `"firebase"`). */
     readonly name: string;
     /**
      * The source element this module is built from.

package/extract/PackageExtractor.d.ts

@@ -29,7 +29,7 @@ export interface PackageExtractorOptions {
 /**
  * Extractor that reads a `package.json` and produces a flat tree of modules — one `kind: "module"`
  * `DocumentationElement` per export entry, in declaration order.
- * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
+ * - Static export keys (e.g. `"./api"`, `"./firebase"`) become one module each.
  * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - Each module's `title` is prefixed with the package `name` (e.g. `ui` → `shelving/ui`) so listings read as package subpaths.
@@ -50,7 +50,7 @@ export declare class PackageExtractor extends Extractor<Path, TreeElement> {
     extract(packageJson: Path): Promise<TreeElement>;
     /** Source extensions to try for an export `target`, derived from the target's own extension via the `extensions` mapping. */
     private _sourceExtensions;
-    /** Resolve a static export subpath (e.g. `"firestore/client"`) to a file or directory element in the tree. */
+    /** Resolve a static export subpath (e.g. `"nested/client"`) to a file or directory element in the tree. */
     private _resolve;
     /** Expand a wildcard export subpath (e.g. `"util/*"`) into one module per matching child. */
     private _expandWildcard;

package/extract/PackageExtractor.js

@@ -13,7 +13,7 @@ const DEFAULT_EXTENSIONS = {
 /**
  * Extractor that reads a `package.json` and produces a flat tree of modules — one `kind: "module"`
  * `DocumentationElement` per export entry, in declaration order.
- * - Static export keys (e.g. `"./api"`, `"./firestore/client"`) become one module each.
+ * - Static export keys (e.g. `"./api"`, `"./firebase"`) become one module each.
  * - Wildcard export keys (e.g. `"./util/*"`) expand against the source tree — one module per matching child file or subdirectory.
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - Each module's `title` is prefixed with the package `name` (e.g. `ui` → `shelving/ui`) so listings read as package subpaths.
@@ -86,7 +86,7 @@ export class PackageExtractor extends Extractor {
         const ext = dot >= 0 ? target.slice(dot + 1) : "";
         return this._extensions[ext] ?? (ext ? [ext] : []);
     }
-    /** Resolve a static export subpath (e.g. `"firestore/client"`) to a file or directory element in the tree. */
+    /** Resolve a static export subpath (e.g. `"nested/client"`) to a file or directory element in the tree. */
     _resolve(subpath, sourceExtensions) {
         const segments = subpath.split("/");
         let current = this._tree;

package/firebase/FirestoreProvider.d.ts

@@ -0,0 +1,117 @@
+import type { Collection } from "../db/collection/Collection.js";
+import { DBProvider } from "../db/provider/DBProvider.js";
+import type { ImmutableArray } from "../util/array.js";
+import type { Data } from "../util/data.js";
+import type { AnyCaller } from "../util/function.js";
+import type { Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } from "../util/item.js";
+import { type Query } from "../util/query.js";
+import type { Updates } from "../util/update.js";
+import type { FirestoreFields, FirestoreValue } from "./value.js";
+/** JSON representation of a Firestore REST API `Write` operation. */
+type _FirestoreWrite = {
+    readonly update?: {
+        readonly name: string;
+        readonly fields: FirestoreFields;
+    };
+    readonly delete?: string;
+    readonly updateMask?: {
+        readonly fieldPaths: ImmutableArray<string>;
+    };
+    readonly updateTransforms?: ImmutableArray<_FirestoreTransform>;
+    readonly currentDocument?: {
+        readonly exists: boolean;
+    };
+};
+/** JSON representation of a Firestore REST API `FieldTransform` operation. */
+type _FirestoreTransform = {
+    readonly fieldPath: string;
+    readonly increment?: FirestoreValue;
+    readonly appendMissingElements?: {
+        readonly values: ImmutableArray<FirestoreValue>;
+    };
+    readonly removeAllFromArray?: {
+        readonly values: ImmutableArray<FirestoreValue>;
+    };
+};
+/** Options for `FirestoreProvider`. */
+export interface FirestoreProviderOptions {
+    /** Google Cloud project id. */
+    readonly project: string;
+    /**
+     * Firestore database id.
+     * @default "(default)"
+     */
+    readonly database?: string | undefined;
+    /**
+     * Base URL of the Firestore API, e.g. `"http://127.0.0.1:8080"` for the Firestore emulator.
+     * @default "https://firestore.googleapis.com"
+     */
+    readonly host?: string | undefined;
+    /**
+     * Return an OAuth2 access token for each request, e.g. from `google-auth-library` or a hand-rolled service-account JWT exchange.
+     * - Omit to send no `Authorization` header (correct for the Firestore emulator).
+     */
+    readonly token?: (() => string | PromiseLike<string>) | undefined;
+    /** Fetch implementation to use for requests (defaults to the global `fetch`). */
+    readonly fetch?: ((input: string, init: RequestInit) => Promise<Response>) | undefined;
+}
+/**
+ * Cloud Firestore database provider that talks to the Firestore REST API using `fetch`, implementing the `DBProvider` abstraction.
+ *
+ * - Zero dependencies, so it runs anywhere `fetch` runs: Node.js, Bun, Cloudflare Workers, Deno, and other edge runtimes.
+ * - Supports transactions via `transact()` — reads see a consistent snapshot, writes buffer and commit atomically, and contended commits retry.
+ * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError` (the `:listen` endpoint requires a streaming session the plain REST API cannot provide).
+ * - Data read from Firestore is unvalidated — wrap in `ValidationDBProvider` to guarantee types.
+ *
+ * @example
+ *  const provider = new FirestoreProvider({ project: "my-project", token: () => auth.getAccessToken() });
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/firebase/FirestoreProvider
+ */
+export declare class FirestoreProvider<I extends string = string, T extends Data = Data> extends DBProvider<I, T> {
+    /** Options this provider was created with (shared with transaction providers). */
+    protected readonly _options: FirestoreProviderOptions;
+    /** Path of the documents root, `projects/{project}/databases/{database}/documents`. */
+    protected readonly _root: string;
+    /** Transaction id included as the consistency selector in reads (set only on transaction providers). */
+    protected _transaction: string | undefined;
+    constructor(options: FirestoreProviderOptions);
+    /** Get the full Firestore document name for an item. */
+    protected _getDocumentName(collection: Collection<string, I, Data>, id: string): string;
+    /** POST a request to a Firestore REST method on the documents root, e.g. `commit`, and return the parsed JSON response. */
+    protected _request(method: string, body: Data): Promise<unknown>;
+    /** The consistency selector props included in read request bodies. */
+    protected get _consistency(): Data;
+    /**
+     * Send a set of `Write` operations.
+     * - Committed immediately in batches of up to 500 (overridden by transaction providers to buffer until commit).
+     */
+    protected _write(writes: ImmutableArray<_FirestoreWrite>): Promise<void>;
+    /** Run a query returning only the matching document names. */
+    protected _getQueryNames<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>> | undefined, caller: AnyCaller): Promise<ImmutableArray<string>>;
+    getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
+    /** Not supported — the REST API has no realtime listeners, so this throws `UnsupportedError`. */
+    getItemSequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _id: II): OptionalItemSequence<II, TT>;
+    /** Generates a random 20-character id for the new item (fails if the id already exists). */
+    addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
+    setItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, data: TT): Promise<void>;
+    /** Fails if the item does not exist. */
+    updateItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, updates: Updates<Item<II, TT>>): Promise<void>;
+    deleteItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    countQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<number>;
+    getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query?: Query<Item<II, TT>>): Promise<Items<II, TT>>;
+    /** Not supported — the REST API has no realtime listeners, so this throws `UnsupportedError`. */
+    getQuerySequence<II extends I, TT extends T>(_collection: Collection<string, II, TT>, _query?: Query<Item<II, TT>>): ItemsSequence<II, TT>;
+    setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
+    updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
+    deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    /**
+     * Runs the callback in a Firestore transaction: begin → reads with the transaction id → buffered writes committed atomically.
+     * - Retries the whole callback (up to 5 attempts) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
+     * - Rolls back and rethrows if the callback throws.
+     * - Reads see a consistent snapshot and never the transaction's own buffered writes.
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+}
+export {};

package/firebase/FirestoreProvider.js

@@ -0,0 +1,313 @@
+import { DBProvider } from "../db/provider/DBProvider.js";
+import { ResponseError } from "../error/ResponseError.js";
+import { UnsupportedError } from "../error/UnsupportedError.js";
+import { joinDataPath } from "../util/data.js";
+import { BLACKHOLE } from "../util/function.js";
+import { getItem } from "../util/item.js";
+import { isPlainObject } from "../util/object.js";
+import { getQueryFilters, getQueryLimit, getQueryOrders } from "../util/query.js";
+import { getRandomKey } from "../util/random.js";
+import { getUpdates } from "../util/update.js";
+import { toData, toFirestoreFields, toFirestoreValue } from "./value.js";
+// Constants.
+const WRITE_BATCH = 500;
+const TRANSACTION_ATTEMPTS = 5;
+// Map `Filter.types` to Firestore REST `FieldFilter` operators.
+const OPERATORS = {
+    is: "EQUAL",
+    not: "NOT_EQUAL",
+    in: "IN",
+    out: "NOT_IN",
+    contains: "ARRAY_CONTAINS",
+    gt: "GREATER_THAN",
+    gte: "GREATER_THAN_OR_EQUAL",
+    lt: "LESS_THAN",
+    lte: "LESS_THAN_OR_EQUAL",
+};
+/** Get the last segment of a Firestore document name, i.e. its id. */
+function _getDocumentID(name) {
+    return name.slice(name.lastIndexOf("/") + 1); // `as I` needed: Firestore names are always plain strings.
+}
+/** Convert a Firestore REST document to an `Item`. */
+function _getItem(document, caller) {
+    return getItem(_getDocumentID(document.name), toData(document.fields, caller)); // `as TT` needed: validate with `ValidationDBProvider` for real type safety.
+}
+/**
+ * Convert a query to a Firestore REST `StructuredQuery`, or `undefined` if the query provably matches nothing (e.g. an empty `in` filter).
+ * - `id` keys map to the `__name__` field path with document-reference values.
+ */
+function _getStructuredQuery(root, collection, query, select, caller) {
+    const structured = { from: [{ collectionId: collection }] };
+    const filters = [];
+    if (query) {
+        for (const { key, operator, value } of getQueryFilters(query)) {
+            const k = joinDataPath(key);
+            const fieldPath = k === "id" ? "__name__" : k;
+            const encode = (v) => k === "id" ? { referenceValue: `${root}/${collection}/${String(v)}` } : toFirestoreValue(v, caller);
+            if (value === null && operator === "is")
+                filters.push({ unaryFilter: { op: "IS_NULL", field: { fieldPath } } });
+            else if (value === null && operator === "not")
+                filters.push({ unaryFilter: { op: "IS_NOT_NULL", field: { fieldPath } } });
+            else if (operator === "in" || operator === "out") {
+                const values = value;
+                if (!values.length) {
+                    if (operator === "in")
+                        return undefined; // `in []` matches nothing.
+                    continue; // `out []` matches everything, so skip the filter.
+                }
+                filters.push({
+                    fieldFilter: { field: { fieldPath }, op: OPERATORS[operator], value: { arrayValue: { values: values.map(encode) } } },
+                });
+            }
+            else
+                filters.push({ fieldFilter: { field: { fieldPath }, op: OPERATORS[operator], value: encode(value) } });
+        }
+        const orders = getQueryOrders(query).map(({ key, direction }) => {
+            const k = joinDataPath(key);
+            return { field: { fieldPath: k === "id" ? "__name__" : k }, direction: direction === "asc" ? "ASCENDING" : "DESCENDING" };
+        });
+        if (orders.length)
+            structured.orderBy = orders;
+        const limit = getQueryLimit(query);
+        if (typeof limit === "number")
+            structured.limit = limit;
+    }
+    const [firstFilter] = filters;
+    if (filters.length > 1)
+        structured.where = { compositeFilter: { op: "AND", filters } };
+    else if (firstFilter)
+        structured.where = firstFilter;
+    if (select)
+        structured.select = { fields: [{ fieldPath: "__name__" }] };
+    return structured;
+}
+/** Convert an `Updates` object to a Firestore REST `Write` against a document name. */
+function _getUpdateWrite(name, updates, caller) {
+    const fields = {};
+    const fieldPaths = [];
+    const transforms = [];
+    for (const { key, action, value } of getUpdates(updates)) {
+        const fieldPath = joinDataPath(key);
+        if (action === "set") {
+            _setDeepField(fields, key, toFirestoreValue(value, caller));
+            fieldPaths.push(fieldPath);
+        }
+        else if (action === "sum")
+            transforms.push({ fieldPath, increment: toFirestoreValue(value, caller) });
+        else if (action === "with")
+            transforms.push({ fieldPath, appendMissingElements: { values: value.map(v => toFirestoreValue(v, caller)) } });
+        else if (action === "omit")
+            transforms.push({ fieldPath, removeAllFromArray: { values: value.map(v => toFirestoreValue(v, caller)) } });
+    }
+    return {
+        update: { name, fields },
+        updateMask: { fieldPaths },
+        ...(transforms.length ? { updateTransforms: transforms } : {}),
+        currentDocument: { exists: true },
+    };
+}
+/** Set a value into nested Firestore fields at a deep key, creating intermediate maps. */
+function _setDeepField(fields, segments, value) {
+    const [first, ...rest] = segments;
+    if (!rest.length) {
+        fields[first] = value;
+        return;
+    }
+    const existing = fields[first]?.mapValue?.fields;
+    const nested = existing ? { ...existing } : {};
+    fields[first] = { mapValue: { fields: nested } };
+    _setDeepField(nested, rest, value);
+}
+/**
+ * Cloud Firestore database provider that talks to the Firestore REST API using `fetch`, implementing the `DBProvider` abstraction.
+ *
+ * - Zero dependencies, so it runs anywhere `fetch` runs: Node.js, Bun, Cloudflare Workers, Deno, and other edge runtimes.
+ * - Supports transactions via `transact()` — reads see a consistent snapshot, writes buffer and commit atomically, and contended commits retry.
+ * - Does not support realtime subscriptions: `getItemSequence()` and `getQuerySequence()` throw `UnsupportedError` (the `:listen` endpoint requires a streaming session the plain REST API cannot provide).
+ * - Data read from Firestore is unvalidated — wrap in `ValidationDBProvider` to guarantee types.
+ *
+ * @example
+ *  const provider = new FirestoreProvider({ project: "my-project", token: () => auth.getAccessToken() });
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/firebase/FirestoreProvider
+ */
+export class FirestoreProvider extends DBProvider {
+    /** Options this provider was created with (shared with transaction providers). */
+    _options;
+    /** Path of the documents root, `projects/{project}/databases/{database}/documents`. */
+    _root;
+    /** Transaction id included as the consistency selector in reads (set only on transaction providers). */
+    _transaction = undefined;
+    constructor(options) {
+        super();
+        this._options = options;
+        const { project, database = "(default)" } = options;
+        this._root = `projects/${project}/databases/${database}/documents`;
+    }
+    /** Get the full Firestore document name for an item. */
+    _getDocumentName(collection, id) {
+        return `${this._root}/${collection.name}/${id}`;
+    }
+    /** POST a request to a Firestore REST method on the documents root, e.g. `commit`, and return the parsed JSON response. */
+    async _request(method, body) {
+        const { host = "https://firestore.googleapis.com", token, fetch: customFetch } = this._options;
+        const headers = { "Content-Type": "application/json" };
+        if (token)
+            headers.Authorization = `Bearer ${await token()}`;
+        const url = `${host}/v1/${this._root}:${method}`;
+        const init = { method: "POST", headers, body: JSON.stringify(body) };
+        const response = customFetch ? await customFetch(url, init) : await globalThis.fetch(url, init);
+        const json = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            const error = isPlainObject(json) && isPlainObject(json.error) ? json.error : undefined;
+            throw new ResponseError(typeof error?.message === "string" ? error.message : `Firestore ${method} request failed`, {
+                code: response.status,
+                status: error?.status,
+                provider: this,
+            });
+        }
+        return json;
+    }
+    /** The consistency selector props included in read request bodies. */
+    get _consistency() {
+        return this._transaction ? { transaction: this._transaction } : {};
+    }
+    /**
+     * Send a set of `Write` operations.
+     * - Committed immediately in batches of up to 500 (overridden by transaction providers to buffer until commit).
+     */
+    async _write(writes) {
+        for (let i = 0; i < writes.length; i += WRITE_BATCH)
+            await this._request("commit", { writes: writes.slice(i, i + WRITE_BATCH) });
+    }
+    /** Run a query returning only the matching document names. */
+    async _getQueryNames(collection, query, caller) {
+        const structuredQuery = _getStructuredQuery(this._root, collection.name, query, true, caller);
+        if (!structuredQuery)
+            return [];
+        const results = (await this._request("runQuery", { structuredQuery, ...this._consistency }));
+        return results.flatMap(r => (r.document ? [r.document.name] : []));
+    }
+    async getItem(collection, id) {
+        const results = (await this._request("batchGet", {
+            documents: [this._getDocumentName(collection, id)],
+            ...this._consistency,
+        }));
+        const found = results[0]?.found;
+        if (found)
+            return _getItem(found, this.getItem);
+    }
+    /** Not supported — the REST API has no realtime listeners, so this throws `UnsupportedError`. */
+    getItemSequence(_collection, _id) {
+        throw new UnsupportedError("FirestoreProvider does not support realtime subscriptions");
+    }
+    /** Generates a random 20-character id for the new item (fails if the id already exists). */
+    async addItem(collection, data) {
+        const id = getRandomKey(20); // `as II` needed: generated keys are always plain strings.
+        await this._write([
+            {
+                update: { name: this._getDocumentName(collection, id), fields: toFirestoreFields(data, this.addItem) },
+                currentDocument: { exists: false },
+            },
+        ]);
+        return id;
+    }
+    async setItem(collection, id, data) {
+        await this._write([{ update: { name: this._getDocumentName(collection, id), fields: toFirestoreFields(data, this.setItem) } }]);
+    }
+    /** Fails if the item does not exist. */
+    async updateItem(collection, id, updates) {
+        await this._write([_getUpdateWrite(this._getDocumentName(collection, id), updates, this.updateItem)]);
+    }
+    async deleteItem(collection, id) {
+        await this._write([{ delete: this._getDocumentName(collection, id) }]);
+    }
+    async countQuery(collection, query) {
+        const structuredQuery = _getStructuredQuery(this._root, collection.name, query, false, this.countQuery);
+        if (!structuredQuery)
+            return 0;
+        const results = (await this._request("runAggregationQuery", {
+            structuredAggregationQuery: { structuredQuery, aggregations: [{ alias: "count", count: {} }] },
+            ...this._consistency,
+        }));
+        const count = results[0]?.result?.aggregateFields?.count;
+        return count ? Number(toData({ count }, this.countQuery).count) : 0;
+    }
+    async getQuery(collection, query) {
+        const structuredQuery = _getStructuredQuery(this._root, collection.name, query, false, this.getQuery);
+        if (!structuredQuery)
+            return [];
+        const results = (await this._request("runQuery", { structuredQuery, ...this._consistency }));
+        return results.flatMap(r => (r.document ? [_getItem(r.document, this.getQuery)] : []));
+    }
+    /** Not supported — the REST API has no realtime listeners, so this throws `UnsupportedError`. */
+    getQuerySequence(_collection, _query) {
+        throw new UnsupportedError("FirestoreProvider does not support realtime subscriptions");
+    }
+    async setQuery(collection, query, data) {
+        const names = await this._getQueryNames(collection, query, this.setQuery);
+        const fields = toFirestoreFields(data, this.setQuery);
+        await this._write(names.map(name => ({ update: { name, fields } })));
+    }
+    async updateQuery(collection, query, updates) {
+        const names = await this._getQueryNames(collection, query, this.updateQuery);
+        await this._write(names.map(name => _getUpdateWrite(name, updates, this.updateQuery)));
+    }
+    async deleteQuery(collection, query) {
+        const names = await this._getQueryNames(collection, query, this.deleteQuery);
+        await this._write(names.map(name => ({ delete: name })));
+    }
+    /**
+     * Runs the callback in a Firestore transaction: begin → reads with the transaction id → buffered writes committed atomically.
+     * - Retries the whole callback (up to 5 attempts) when the commit is aborted by contention, so the callback must have no side effects other than through its provider.
+     * - Rolls back and rethrows if the callback throws.
+     * - Reads see a consistent snapshot and never the transaction's own buffered writes.
+     */
+    async transact(callback) {
+        let retryTransaction;
+        let aborted;
+        for (let attempt = 0; attempt < TRANSACTION_ATTEMPTS; attempt++) {
+            const { transaction } = (await this._request("beginTransaction", {
+                options: { readWrite: retryTransaction ? { retryTransaction } : {} },
+            }));
+            const provider = new _FirestoreTransaction(this._options, transaction);
+            let result;
+            try {
+                result = await callback(provider);
+            }
+            catch (thrown) {
+                await this._request("rollback", { transaction }).catch(BLACKHOLE);
+                throw thrown;
+            }
+            try {
+                await this._request("commit", { transaction, writes: provider.writes });
+                return result;
+            }
+            catch (thrown) {
+                if (!(thrown instanceof ResponseError) || thrown.status !== "ABORTED")
+                    throw thrown;
+                retryTransaction = transaction; // Retry the transaction after contention.
+                aborted = thrown;
+            }
+        }
+        throw aborted;
+    }
+}
+/** Transaction-scoped provider for `FirestoreProvider.transact()` — reads carry the transaction id, writes buffer until commit. */
+class _FirestoreTransaction extends FirestoreProvider {
+    /** The buffered `Write` operations, sent in the transaction's final commit. */
+    writes = [];
+    constructor(options, transaction) {
+        super(options);
+        this._transaction = transaction;
+    }
+    /** Buffer the writes until the transaction commits. */
+    async _write(writes) {
+        this.writes.push(...writes);
+    }
+    /** Not supported inside a transaction — always throws `UnsupportedError`. */
+    transact(_callback) {
+        throw new UnsupportedError("FirestoreProvider does not support nested transactions");
+    }
+}

package/firebase/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./FirestoreProvider.js";
+export * from "./value.js";

package/firebase/index.js

@@ -0,0 +1,2 @@
+export * from "./FirestoreProvider.js";
+export * from "./value.js";

package/firebase/value.d.ts

@@ -0,0 +1,80 @@
+import type { ImmutableArray } from "../util/array.js";
+import type { Data } from "../util/data.js";
+import type { AnyCaller } from "../util/function.js";
+/** JSON representation of a single value in the Firestore REST API. */
+export type FirestoreValue = {
+    readonly nullValue?: null;
+    readonly booleanValue?: boolean;
+    readonly integerValue?: string | number;
+    readonly doubleValue?: string | number;
+    readonly stringValue?: string;
+    readonly timestampValue?: string;
+    readonly bytesValue?: string;
+    readonly referenceValue?: string;
+    readonly geoPointValue?: {
+        readonly latitude?: number;
+        readonly longitude?: number;
+    };
+    readonly arrayValue?: {
+        readonly values?: ImmutableArray<FirestoreValue>;
+    };
+    readonly mapValue?: {
+        readonly fields?: FirestoreFields;
+    };
+};
+/** JSON representation of the fields of a Firestore document in the Firestore REST API. */
+export type FirestoreFields = {
+    readonly [key: string]: FirestoreValue;
+};
+/**
+ * Convert a data value to its Firestore REST API JSON representation.
+ *
+ * - Safe integers become `integerValue` (which the REST API encodes as a string), other finite numbers become `doubleValue`.
+ * - Arrays and plain objects convert recursively.
+ *
+ * @param value The value to convert (null, boolean, string, finite number, array, or plain object).
+ * @param caller Caller function used to attribute thrown errors.
+ * @returns The Firestore JSON value.
+ * @throws `ValueError` if the value cannot be represented (e.g. `undefined`, functions, non-finite numbers, class instances).
+ * @example toFirestoreValue(123) // { integerValue: "123" }
+ * @see https://shelving.cc/firebase/toFirestoreValue
+ */
+export declare function toFirestoreValue(value: unknown, caller?: AnyCaller): FirestoreValue;
+/**
+ * Convert a data object to Firestore REST API document fields.
+ *
+ * - Props with `undefined` value are skipped (matching JSON serialisation).
+ *
+ * @param data The data object to convert.
+ * @param caller Caller function used to attribute thrown errors.
+ * @returns The Firestore fields object.
+ * @throws `ValueError` if any prop value cannot be represented.
+ * @example toFirestoreFields({ num: 123 }) // { num: { integerValue: "123" } }
+ * @see https://shelving.cc/firebase/toFirestoreFields
+ */
+export declare function toFirestoreFields(data: Data, caller?: AnyCaller): FirestoreFields;
+/**
+ * Convert a Firestore REST API JSON value back to a data value.
+ *
+ * - `integerValue` parses to a `number`, so integers beyond `Number.MAX_SAFE_INTEGER` lose precision.
+ * - `timestampValue`, `bytesValue`, and `referenceValue` pass through as their string form; `geoPointValue` becomes a plain `{ latitude, longitude }` object — wrap the provider in `ValidationDBProvider` to reject types your schemas don't allow.
+ *
+ * @param value The Firestore JSON value to convert.
+ * @param caller Caller function used to attribute thrown errors.
+ * @returns The plain data value.
+ * @throws `ValueError` if the value has no recognised type.
+ * @example toDataValue({ integerValue: "123" }) // 123
+ * @see https://shelving.cc/firebase/toDataValue
+ */
+export declare function toDataValue(value: FirestoreValue, caller?: AnyCaller): unknown;
+/**
+ * Convert Firestore REST API document fields back to a data object.
+ *
+ * @param fields The Firestore fields object to convert (missing means an empty document).
+ * @param caller Caller function used to attribute thrown errors.
+ * @returns The plain data object.
+ * @throws `ValueError` if any field value has no recognised type.
+ * @example toData({ num: { integerValue: "123" } }) // { num: 123 }
+ * @see https://shelving.cc/firebase/toData
+ */
+export declare function toData(fields: FirestoreFields | undefined, caller?: AnyCaller): Data;