clefbase 1.3.7 → 1.3.8

package/dist/cli.js

@@ -34523,7 +34523,7 @@ async function runSitesList(cwd = process.cwd()) {
 }
 
 // package.json
-var version = "1.3.7";
+var version = "1.3.8";
 
 // src/cli/index.ts
 var program2 = new Command();

package/dist/db/batch.d.ts

@@ -0,0 +1,62 @@
+import { HttpClient } from "../http";
+import type { ClefbaseDocument } from "../types";
+/**
+ * Atomic multi-document writer.
+ *
+ * @example
+ * const batch = db.batch();
+ *
+ * // set — full overwrite (no merge)
+ * batch.set(db.collection("users").doc("u1"), { name: "Alice", role: "admin" });
+ *
+ * // update — merge patch (same as doc.update())
+ * batch.update(db.collection("posts").doc("p1"), { views: FieldValue.increment(1) });
+ *
+ * // delete a document
+ * batch.delete(db.collection("sessions").doc("s9"));
+ *
+ * await batch.commit();
+ */
+export declare class WriteBatch {
+    private readonly http;
+    private readonly _ops;
+    private _committed;
+    constructor(http: HttpClient);
+    /** Number of operations staged so far. */
+    get size(): number;
+    private _assertNotCommitted;
+    /**
+     * Stage a full overwrite for the given document reference.
+     * Equivalent to `ref.set(data)`.
+     */
+    set<T extends ClefbaseDocument>(ref: {
+        collectionPath: string;
+        id: string;
+    }, data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): this;
+    /**
+     * Stage a merge-patch update for the given document reference.
+     * Equivalent to `ref.update(data)`.
+     * Supports FieldValue sentinels.
+     */
+    update<T extends ClefbaseDocument>(ref: {
+        collectionPath: string;
+        id: string;
+    }, data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>): this;
+    /**
+     * Stage a document deletion.
+     * Equivalent to `ref.delete()`.
+     */
+    delete(ref: {
+        collectionPath: string;
+        id: string;
+    }): this;
+    /**
+     * Execute all staged operations atomically.
+     * After commit() the batch is sealed — calling commit() again throws.
+     *
+     * @example
+     * await batch.commit();
+     */
+    commit(): Promise<void>;
+}
+//# sourceMappingURL=batch.d.ts.map

package/dist/db/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/db/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AA6BjD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,UAAU,CAAS;gBAEE,IAAI,EAAE,UAAU;IAE7C,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAA6B;IAE/C,OAAO,CAAC,mBAAmB;IAM3B;;;OAGG;IACH,GAAG,CAAC,CAAC,SAAS,gBAAgB,EAC5B,GAAG,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC3C,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,YAAY,GAAG,YAAY,CAAC,GACjD,IAAI;IAYP;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,gBAAgB,EAC/B,GAAG,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC3C,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GAC1D,IAAI;IAYP;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAUzD;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ9B"}

package/dist/db/batch.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteBatch = void 0;
+/**
+ * Atomic multi-document writer.
+ *
+ * @example
+ * const batch = db.batch();
+ *
+ * // set — full overwrite (no merge)
+ * batch.set(db.collection("users").doc("u1"), { name: "Alice", role: "admin" });
+ *
+ * // update — merge patch (same as doc.update())
+ * batch.update(db.collection("posts").doc("p1"), { views: FieldValue.increment(1) });
+ *
+ * // delete a document
+ * batch.delete(db.collection("sessions").doc("s9"));
+ *
+ * await batch.commit();
+ */
+class WriteBatch {
+    constructor(http) {
+        this.http = http;
+        this._ops = [];
+        this._committed = false;
+    }
+    /** Number of operations staged so far. */
+    get size() { return this._ops.length; }
+    _assertNotCommitted() {
+        if (this._committed) {
+            throw new Error("WriteBatch: cannot add operations after commit()");
+        }
+    }
+    /**
+     * Stage a full overwrite for the given document reference.
+     * Equivalent to `ref.set(data)`.
+     */
+    set(ref, data) {
+        this._assertNotCommitted();
+        this._ops.push({
+            type: "set",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+            data: data,
+            merge: false,
+        });
+        return this;
+    }
+    /**
+     * Stage a merge-patch update for the given document reference.
+     * Equivalent to `ref.update(data)`.
+     * Supports FieldValue sentinels.
+     */
+    update(ref, data) {
+        this._assertNotCommitted();
+        this._ops.push({
+            type: "update",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+            data: data,
+            merge: true,
+        });
+        return this;
+    }
+    /**
+     * Stage a document deletion.
+     * Equivalent to `ref.delete()`.
+     */
+    delete(ref) {
+        this._assertNotCommitted();
+        this._ops.push({
+            type: "delete",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+        });
+        return this;
+    }
+    /**
+     * Execute all staged operations atomically.
+     * After commit() the batch is sealed — calling commit() again throws.
+     *
+     * @example
+     * await batch.commit();
+     */
+    async commit() {
+        this._assertNotCommitted();
+        this._committed = true;
+        if (this._ops.length === 0)
+            return;
+        await this.http.post("/batch", { operations: this._ops });
+    }
+}
+exports.WriteBatch = WriteBatch;
+//# sourceMappingURL=batch.js.map

package/dist/db/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/db/batch.ts"],"names":[],"mappings":";;;AA8BA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,UAAU;IAIrB,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;QAH5B,SAAI,GAAc,EAAE,CAAC;QAC9B,eAAU,GAAG,KAAK,CAAC;IAEqB,CAAC;IAEjD,0CAA0C;IAC1C,IAAI,IAAI,KAAa,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvC,mBAAmB;QACzB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,GAAG,CACD,GAA2C,EAC3C,IAAkD;QAElD,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,IAAI,EAAY,KAAK;YACrB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,EAAE,EAAc,GAAG,CAAC,EAAE;YACtB,IAAI,EAAY,IAA+B;YAC/C,KAAK,EAAW,KAAK;SACtB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,MAAM,CACJ,GAA2C,EAC3C,IAA2D;QAE3D,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,IAAI,EAAY,QAAQ;YACxB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,EAAE,EAAc,GAAG,CAAC,EAAE;YACtB,IAAI,EAAY,IAA+B;YAC/C,KAAK,EAAW,IAAI;SACrB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,GAA2C;QAChD,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,IAAI,EAAY,QAAQ;YACxB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,EAAE,EAAc,GAAG,CAAC,EAAE;SACvB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QAEvB,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEnC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF;AAnFD,gCAmFC"}

package/dist/db/index.d.ts

@@ -1,6 +1,10 @@
 import { HttpClient } from "../http";
+import { WriteBatch } from "./batch";
+import { Transaction } from "./transaction";
 import type { ClefbaseDocument, QueryResult, WhereClause } from "../types";
 export type { WhereClause, WhereValue } from "../types";
+export { WriteBatch } from "./batch";
+export { Transaction, runTransaction } from "./transaction";
 /**
  * A typed reference to a single document.
  *
@@ -16,11 +20,14 @@ export declare class DocumentReference<T extends ClefbaseDocument = ClefbaseDocu
     readonly collectionPath: string;
     readonly id: string;
     constructor(http: HttpClient, collectionPath: string, id: string);
+    /** Fully-qualified path string, e.g. "posts/p1" or "posts/p1/comments/c1". */
+    get path(): string;
     /** Fetch this document. Returns null when it does not exist. */
     get(): Promise<T | null>;
     /**
      * Patch this document (merge by default).
      * Pass `{ merge: false }` to fully replace the document.
+     * Supports FieldValue sentinels — they are serialized by JSON.stringify.
      */
     update(data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>, opts?: {
         merge?: boolean;
@@ -39,6 +46,20 @@ export declare class DocumentReference<T extends ClefbaseDocument = ClefbaseDocu
     collection<S extends ClefbaseDocument = ClefbaseDocument>(name: string): CollectionReference<S>;
     /** @deprecated Use .collection() — kept for backwards compat */
     subcollection<S extends ClefbaseDocument = ClefbaseDocument>(name: string): CollectionReference<S>;
+    /**
+     * Subscribe to real-time updates for this document.
+     * Returns an unsubscribe function.
+     * Requires the server to support SSE at GET /<collection>/<id>/stream.
+     *
+     * @example
+     * const unsub = ref.onSnapshot((doc) => {
+     *   if (doc) console.log("Updated:", doc);
+     *   else     console.log("Deleted");
+     * });
+     * // later:
+     * unsub();
+     */
+    onSnapshot(callback: (doc: T | null) => void, onError?: (err: Error) => void): () => void;
 }
 /**
  * A chainable query builder.
@@ -65,9 +86,10 @@ export declare class Query<T extends ClefbaseDocument = ClefbaseDocument> {
     /**
      * Filter by field values or operators.
      * Multiple calls are AND-merged.
+     * Supports dot-notation for nested fields: `where({ "address.city": "London" })`
      */
     where(clauses: WhereClause): this;
-    /** Sort by a field. */
+    /** Sort by a field. Supports dot-notation: `orderBy("meta.score", "desc")` */
     orderBy(field: string, dir?: "asc" | "desc"): this;
     /** Cap results (server max: 500). */
     limit(n: number): this;
@@ -82,6 +104,36 @@ export declare class Query<T extends ClefbaseDocument = ClefbaseDocument> {
     get(): Promise<T[]>;
     /** @alias get() */
     getDocs(): Promise<T[]>;
+    /**
+     * Count matching documents without fetching their data.
+     *
+     * @example
+     * const total = await db.collection("orders").where({ status: "pending" }).count();
+     */
+    count(): Promise<number>;
+    /**
+     * Fetch a single matching document (first result).
+     * Returns null when no document matches.
+     *
+     * @example
+     * const admin = await db.collection("users").where({ role: "admin" }).findOne();
+     */
+    findOne(): Promise<T | null>;
+    /**
+     * Iterate over all matching documents in pages, calling `callback` for
+     * each page. Useful for large datasets you don't want to load at once.
+     *
+     * @example
+     * await db.collection("logs")
+     *   .where({ level: "error" })
+     *   .orderBy("_createdAt")
+     *   .forEach(async (page) => {
+     *     for (const doc of page) await process(doc);
+     *   }, { pageSize: 100 });
+     */
+    forEach(callback: (docs: T[]) => Promise<void> | void, opts?: {
+        pageSize?: number;
+    }): Promise<void>;
 }
 /**
  * A reference to a collection (or subcollection path).
@@ -107,23 +159,90 @@ export declare class CollectionReference<T extends ClefbaseDocument = ClefbaseDo
         offset?: number;
     }): Promise<QueryResult<T>>;
 }
+/**
+ * Query across ALL collections (and subcollections) that share the same name.
+ *
+ * @example
+ * // Find all comments across every post
+ * const allComments = await db
+ *   .collectionGroup("comments")
+ *   .where({ approved: true })
+ *   .orderBy("_createdAt", "desc")
+ *   .limit(50)
+ *   .getDocs();
+ */
+export declare class CollectionGroup<T extends ClefbaseDocument = ClefbaseDocument> extends Query<T> {
+    constructor(http: HttpClient, collectionId: string);
+}
 /**
  * Top-level database service. Obtain via `getDatabase(app)`.
  *
  * @example
  * const db = getDatabase(app);
+ *
+ * // Document reads / writes
  * const post = await db.collection("posts").doc("p1").get();
- * const user = await db.getDoc("users", "uid-123");
+ * await db.collection("posts").doc("p1").update({ views: FieldValue.increment(1) });
+ *
+ * // Atomic batch write
+ * const batch = db.batch();
+ * batch.update(db.collection("counters").doc("hits"), { n: FieldValue.increment(1) });
+ * batch.delete(db.collection("sessions").doc("expired-id"));
+ * await batch.commit();
+ *
+ * // Transaction (read-then-write)
+ * await db.runTransaction(async (tx) => {
+ *   const doc = await tx.get(db.collection("wallets").doc(id));
+ *   tx.update(db.collection("wallets").doc(id), { balance: (doc?.balance as number ?? 0) + 10 });
+ * });
  */
 export declare class Database {
     private readonly http;
     constructor(http: HttpClient);
     collection<T extends ClefbaseDocument = ClefbaseDocument>(name: string): CollectionReference<T>;
+    /**
+     * Query across ALL collections that share `collectionId`, regardless of
+     * where they are nested in the document tree.
+     *
+     * @example
+     * const allLikes = await db.collectionGroup("likes").where({ userId: uid }).getDocs();
+     */
+    collectionGroup<T extends ClefbaseDocument = ClefbaseDocument>(collectionId: string): CollectionGroup<T>;
     getDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, id: string): Promise<T | null>;
     addDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): Promise<T>;
     updateDoc<T extends ClefbaseDocument = ClefbaseDocument>(collectionName: string, id: string, data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>, opts?: {
         merge?: boolean;
     }): Promise<T>;
     deleteDoc(collectionName: string, id: string): Promise<void>;
+    /**
+     * Fetch a document by its full slash-separated path string.
+     *
+     * @example
+     * const comment = await db.doc("posts/p1/comments/c1");
+     */
+    doc<T extends ClefbaseDocument = ClefbaseDocument>(path: string): Promise<T | null>;
+    /**
+     * Create an atomic WriteBatch. Stage operations with `batch.set()`,
+     * `batch.update()`, `batch.delete()`, then call `batch.commit()`.
+     *
+     * @example
+     * const batch = db.batch();
+     * batch.set(db.collection("users").doc("u1"), { name: "Alice" });
+     * batch.update(db.collection("counters").doc("users"), { total: FieldValue.increment(1) });
+     * await batch.commit();
+     */
+    batch(): WriteBatch;
+    /**
+     * Execute a transaction — reads are consistent, writes are atomic.
+     *
+     * @example
+     * await db.runTransaction(async (tx) => {
+     *   const wallet = await tx.get(db.collection("wallets").doc(userId));
+     *   if ((wallet?.credits as number ?? 0) < cost) throw new Error("Insufficient credits");
+     *   tx.update(db.collection("wallets").doc(userId), { credits: (wallet!.credits as number) - cost });
+     *   tx.update(db.collection("items").doc(itemId),   { ownerId: userId });
+     * });
+     */
+    runTransaction<T = void>(updateFn: (tx: Transaction) => Promise<T>): Promise<T>;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}

package/dist/db/index.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Database = exports.CollectionReference = exports.Query = exports.DocumentReference = void 0;
+exports.Database = exports.CollectionGroup = exports.CollectionReference = exports.Query = exports.DocumentReference = exports.runTransaction = exports.Transaction = exports.WriteBatch = void 0;
+const batch_1 = require("./batch");
+const transaction_1 = require("./transaction");
+var batch_2 = require("./batch");
+Object.defineProperty(exports, "WriteBatch", { enumerable: true, get: function () { return batch_2.WriteBatch; } });
+var transaction_2 = require("./transaction");
+Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return transaction_2.Transaction; } });
+Object.defineProperty(exports, "runTransaction", { enumerable: true, get: function () { return transaction_2.runTransaction; } });
 // ─── DocumentReference ────────────────────────────────────────────────────────
 /**
  * A typed reference to a single document.
@@ -18,6 +25,10 @@ class DocumentReference {
         this.collectionPath = collectionPath;
         this.id = id;
     }
+    /** Fully-qualified path string, e.g. "posts/p1" or "posts/p1/comments/c1". */
+    get path() {
+        return `${this.collectionPath}/${this.id}`;
+    }
     /** Fetch this document. Returns null when it does not exist. */
     async get() {
         try {
@@ -32,6 +43,7 @@ class DocumentReference {
     /**
      * Patch this document (merge by default).
      * Pass `{ merge: false }` to fully replace the document.
+     * Supports FieldValue sentinels — they are serialized by JSON.stringify.
      */
     async update(data, opts) {
         const merge = opts?.merge ?? true;
@@ -59,6 +71,36 @@ class DocumentReference {
     subcollection(name) {
         return this.collection(name);
     }
+    /**
+     * Subscribe to real-time updates for this document.
+     * Returns an unsubscribe function.
+     * Requires the server to support SSE at GET /<collection>/<id>/stream.
+     *
+     * @example
+     * const unsub = ref.onSnapshot((doc) => {
+     *   if (doc) console.log("Updated:", doc);
+     *   else     console.log("Deleted");
+     * });
+     * // later:
+     * unsub();
+     */
+    onSnapshot(callback, onError) {
+        const url = `${this.http.getBaseUrl()}/${this.collectionPath}/${this.id}/stream`;
+        const es = new globalThis.EventSource(url);
+        es.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                callback(data);
+            }
+            catch (err) {
+                onError?.(err);
+            }
+        };
+        es.onerror = () => {
+            onError?.(new Error("DocumentReference.onSnapshot: SSE connection error"));
+        };
+        return () => es.close();
+    }
 }
 exports.DocumentReference = DocumentReference;
 // ─── Query ────────────────────────────────────────────────────────────────────
@@ -84,12 +126,13 @@ class Query {
     /**
      * Filter by field values or operators.
      * Multiple calls are AND-merged.
+     * Supports dot-notation for nested fields: `where({ "address.city": "London" })`
      */
     where(clauses) {
         this._filter = { ...this._filter, ...clauses };
         return this;
     }
-    /** Sort by a field. */
+    /** Sort by a field. Supports dot-notation: `orderBy("meta.score", "desc")` */
     orderBy(field, dir = "asc") {
         this._sort = { field, dir };
         return this;
@@ -125,6 +168,69 @@ class Query {
     async getDocs() {
         return this.get();
     }
+    /**
+     * Count matching documents without fetching their data.
+     *
+     * @example
+     * const total = await db.collection("orders").where({ status: "pending" }).count();
+     */
+    async count() {
+        const body = {
+            filter: Object.keys(this._filter).length > 0 ? this._filter : undefined,
+            limit: 500,
+            offset: 0,
+        };
+        const result = await this.http.post(`/${this.path}/count`, body);
+        // Fallback: if server doesn't have /count, use the total from /query
+        if ("count" in result)
+            return result.count;
+        return result.total;
+    }
+    /**
+     * Fetch a single matching document (first result).
+     * Returns null when no document matches.
+     *
+     * @example
+     * const admin = await db.collection("users").where({ role: "admin" }).findOne();
+     */
+    async findOne() {
+        const prev = this._limit;
+        this._limit = 1;
+        const docs = await this.get();
+        this._limit = prev;
+        return docs[0] ?? null;
+    }
+    /**
+     * Iterate over all matching documents in pages, calling `callback` for
+     * each page. Useful for large datasets you don't want to load at once.
+     *
+     * @example
+     * await db.collection("logs")
+     *   .where({ level: "error" })
+     *   .orderBy("_createdAt")
+     *   .forEach(async (page) => {
+     *     for (const doc of page) await process(doc);
+     *   }, { pageSize: 100 });
+     */
+    async forEach(callback, opts) {
+        const pageSize = opts?.pageSize ?? 100;
+        let offset = 0;
+        while (true) {
+            const body = {
+                filter: Object.keys(this._filter).length > 0 ? this._filter : undefined,
+                sort: this._sort,
+                limit: pageSize,
+                offset,
+            };
+            const result = await this.http.post(`/${this.path}/query`, body);
+            if (result.data.length === 0)
+                break;
+            await callback(result.data);
+            offset += result.data.length;
+            if (result.data.length < pageSize)
+                break;
+        }
+    }
 }
 exports.Query = Query;
 // ─── CollectionReference ──────────────────────────────────────────────────────
@@ -161,22 +267,68 @@ class CollectionReference extends Query {
     }
 }
 exports.CollectionReference = CollectionReference;
+// ─── CollectionGroup ──────────────────────────────────────────────────────────
+/**
+ * Query across ALL collections (and subcollections) that share the same name.
+ *
+ * @example
+ * // Find all comments across every post
+ * const allComments = await db
+ *   .collectionGroup("comments")
+ *   .where({ approved: true })
+ *   .orderBy("_createdAt", "desc")
+ *   .limit(50)
+ *   .getDocs();
+ */
+class CollectionGroup extends Query {
+    constructor(http, collectionId) {
+        // The server exposes collection-group queries at a special path
+        super(http, `__group__/${collectionId}`);
+    }
+}
+exports.CollectionGroup = CollectionGroup;
 // ─── Database ─────────────────────────────────────────────────────────────────
 /**
  * Top-level database service. Obtain via `getDatabase(app)`.
  *
  * @example
  * const db = getDatabase(app);
+ *
+ * // Document reads / writes
  * const post = await db.collection("posts").doc("p1").get();
- * const user = await db.getDoc("users", "uid-123");
+ * await db.collection("posts").doc("p1").update({ views: FieldValue.increment(1) });
+ *
+ * // Atomic batch write
+ * const batch = db.batch();
+ * batch.update(db.collection("counters").doc("hits"), { n: FieldValue.increment(1) });
+ * batch.delete(db.collection("sessions").doc("expired-id"));
+ * await batch.commit();
+ *
+ * // Transaction (read-then-write)
+ * await db.runTransaction(async (tx) => {
+ *   const doc = await tx.get(db.collection("wallets").doc(id));
+ *   tx.update(db.collection("wallets").doc(id), { balance: (doc?.balance as number ?? 0) + 10 });
+ * });
  */
 class Database {
     constructor(http) {
         this.http = http;
     }
+    // ─── Collection / document accessors ───────────────────────────────────────
     collection(name) {
         return new CollectionReference(this.http, name);
     }
+    /**
+     * Query across ALL collections that share `collectionId`, regardless of
+     * where they are nested in the document tree.
+     *
+     * @example
+     * const allLikes = await db.collectionGroup("likes").where({ userId: uid }).getDocs();
+     */
+    collectionGroup(collectionId) {
+        return new CollectionGroup(this.http, collectionId);
+    }
+    // ─── Convenience document helpers ──────────────────────────────────────────
     async getDoc(collectionName, id) {
         return this.collection(collectionName).doc(id).get();
     }
@@ -189,6 +341,49 @@ class Database {
     async deleteDoc(collectionName, id) {
         return this.collection(collectionName).doc(id).delete();
     }
+    /**
+     * Fetch a document by its full slash-separated path string.
+     *
+     * @example
+     * const comment = await db.doc("posts/p1/comments/c1");
+     */
+    async doc(path) {
+        const parts = path.split("/").filter(Boolean);
+        if (parts.length < 2 || parts.length % 2 !== 0) {
+            throw new Error(`db.doc(): path must have an even number of segments (collection/id), got "${path}"`);
+        }
+        const id = parts.pop();
+        const collectionPath = parts.join("/");
+        return new DocumentReference(this.http, collectionPath, id).get();
+    }
+    // ─── Atomic writes ─────────────────────────────────────────────────────────
+    /**
+     * Create an atomic WriteBatch. Stage operations with `batch.set()`,
+     * `batch.update()`, `batch.delete()`, then call `batch.commit()`.
+     *
+     * @example
+     * const batch = db.batch();
+     * batch.set(db.collection("users").doc("u1"), { name: "Alice" });
+     * batch.update(db.collection("counters").doc("users"), { total: FieldValue.increment(1) });
+     * await batch.commit();
+     */
+    batch() {
+        return new batch_1.WriteBatch(this.http);
+    }
+    /**
+     * Execute a transaction — reads are consistent, writes are atomic.
+     *
+     * @example
+     * await db.runTransaction(async (tx) => {
+     *   const wallet = await tx.get(db.collection("wallets").doc(userId));
+     *   if ((wallet?.credits as number ?? 0) < cost) throw new Error("Insufficient credits");
+     *   tx.update(db.collection("wallets").doc(userId), { credits: (wallet!.credits as number) - cost });
+     *   tx.update(db.collection("items").doc(itemId),   { ownerId: userId });
+     * });
+     */
+    async runTransaction(updateFn) {
+        return (0, transaction_1.runTransaction)(this.http, updateFn);
+    }
 }
 exports.Database = Database;
 //# sourceMappingURL=index.js.map