clefbase 1.3.6 → 1.3.8

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

package/dist/db/index.js.map

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

package/dist/db/transaction.d.ts

@@ -0,0 +1,96 @@
+import { HttpClient } from "../http";
+import type { ClefbaseDocument } from "../types";
+type TxWriteOp = {
+    type: "set" | "update" | "delete";
+    collectionPath: string;
+    id: string;
+    data?: Record<string, unknown>;
+    merge?: boolean;
+};
+/**
+ * Handle passed to your transaction callback.
+ * Accumulates reads and writes, then flushes them in a single atomic request.
+ */
+export declare class Transaction {
+    private readonly http;
+    /** @internal */
+    readonly _reads: {
+        collectionPath: string;
+        id: string;
+    }[];
+    /** @internal */
+    readonly _writes: TxWriteOp[];
+    private _writesStarted;
+    constructor(http: HttpClient);
+    /**
+     * Read a document inside the transaction.
+     * Must be called before any write operation.
+     *
+     * @example
+     * const user = await tx.get(db.collection("users").doc("u1"));
+     */
+    get<T extends ClefbaseDocument>(ref: {
+        collectionPath: string;
+        id: string;
+    }): Promise<T | null>;
+    /**
+     * Stage a full overwrite inside the transaction.
+     *
+     * @example
+     * tx.set(db.collection("users").doc("u1"), { name: "Alice", role: "admin" });
+     */
+    set<T extends ClefbaseDocument>(ref: {
+        collectionPath: string;
+        id: string;
+    }, data: Omit<T, "_id" | "_createdAt" | "_updatedAt">): this;
+    /**
+     * Stage a merge-patch update inside the transaction.
+     * Supports FieldValue sentinels.
+     *
+     * @example
+     * tx.update(db.collection("posts").doc("p1"), { views: FieldValue.increment(1) });
+     */
+    update<T extends ClefbaseDocument>(ref: {
+        collectionPath: string;
+        id: string;
+    }, data: Partial<Omit<T, "_id" | "_createdAt" | "_updatedAt">>): this;
+    /**
+     * Stage a document deletion inside the transaction.
+     *
+     * @example
+     * tx.delete(db.collection("sessions").doc("s9"));
+     */
+    delete(ref: {
+        collectionPath: string;
+        id: string;
+    }): this;
+}
+/**
+ * Execute an atomic transaction.
+ *
+ * Your callback receives a `Transaction` handle. Call `tx.get()` to read
+ * documents, then `tx.set()` / `tx.update()` / `tx.delete()` to stage writes.
+ * The SDK sends all writes in one atomic request after your callback resolves.
+ *
+ * The callback may be retried on contention — keep it free of side effects.
+ *
+ * @example
+ * await db.runTransaction(async (tx) => {
+ *   const counter = await tx.get(db.collection("stats").doc("global"));
+ *   const current = (counter?.total as number) ?? 0;
+ *   tx.update(db.collection("stats").doc("global"), { total: current + 1 });
+ * });
+ *
+ * @example
+ * // Transfer credits atomically
+ * await db.runTransaction(async (tx) => {
+ *   const from = await tx.get(db.collection("wallets").doc(fromId));
+ *   const to   = await tx.get(db.collection("wallets").doc(toId));
+ *   if (!from || (from.credits as number) < amount) throw new Error("Insufficient credits");
+ *   tx.update(db.collection("wallets").doc(fromId), { credits: (from.credits as number) - amount });
+ *   tx.update(db.collection("wallets").doc(toId),   { credits: ((to?.credits as number) ?? 0) + amount });
+ * });
+ */
+export declare function runTransaction<T = void>(http: HttpClient, updateFn: (tx: Transaction) => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=transaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAsBjD,KAAK,SAAS,GAAG;IACf,IAAI,EAAY,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,EAAE,EAAc,MAAM,CAAC;IACvB,IAAI,CAAC,EAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,KAAK,CAAC,EAAU,OAAO,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,qBAAa,WAAW;IAQV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,gBAAgB;IAChB,QAAQ,CAAC,MAAM,EAAG;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAM;IAChE,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,CAAM;IAEnC,OAAO,CAAC,cAAc,CAAS;gBAEF,IAAI,EAAE,UAAU;IAE7C;;;;;;OAMG;IACG,GAAG,CAAC,CAAC,SAAS,gBAAgB,EAClC,GAAG,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAC1C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgBpB;;;;;OAKG;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;;;;;;OAMG;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;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAS1D;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,IAAI,EAC3C,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/db/transaction.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+exports.runTransaction = runTransaction;
+/**
+ * Handle passed to your transaction callback.
+ * Accumulates reads and writes, then flushes them in a single atomic request.
+ */
+class Transaction {
+    constructor(http) {
+        this.http = http;
+        /** @internal */
+        this._reads = [];
+        /** @internal */
+        this._writes = [];
+        this._writesStarted = false;
+    }
+    /**
+     * Read a document inside the transaction.
+     * Must be called before any write operation.
+     *
+     * @example
+     * const user = await tx.get(db.collection("users").doc("u1"));
+     */
+    async get(ref) {
+        if (this._writesStarted) {
+            throw new Error("Transaction: all tx.get() calls must come before any write (set/update/delete).");
+        }
+        this._reads.push({ collectionPath: ref.collectionPath, id: ref.id });
+        try {
+            return await this.http.get(`/${ref.collectionPath}/${ref.id}`);
+        }
+        catch (err) {
+            if (err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Stage a full overwrite inside the transaction.
+     *
+     * @example
+     * tx.set(db.collection("users").doc("u1"), { name: "Alice", role: "admin" });
+     */
+    set(ref, data) {
+        this._writesStarted = true;
+        this._writes.push({
+            type: "set",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+            data: data,
+            merge: false,
+        });
+        return this;
+    }
+    /**
+     * Stage a merge-patch update inside the transaction.
+     * Supports FieldValue sentinels.
+     *
+     * @example
+     * tx.update(db.collection("posts").doc("p1"), { views: FieldValue.increment(1) });
+     */
+    update(ref, data) {
+        this._writesStarted = true;
+        this._writes.push({
+            type: "update",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+            data: data,
+            merge: true,
+        });
+        return this;
+    }
+    /**
+     * Stage a document deletion inside the transaction.
+     *
+     * @example
+     * tx.delete(db.collection("sessions").doc("s9"));
+     */
+    delete(ref) {
+        this._writesStarted = true;
+        this._writes.push({
+            type: "delete",
+            collectionPath: ref.collectionPath,
+            id: ref.id,
+        });
+        return this;
+    }
+}
+exports.Transaction = Transaction;
+// ─── runTransaction ───────────────────────────────────────────────────────────
+/**
+ * Execute an atomic transaction.
+ *
+ * Your callback receives a `Transaction` handle. Call `tx.get()` to read
+ * documents, then `tx.set()` / `tx.update()` / `tx.delete()` to stage writes.
+ * The SDK sends all writes in one atomic request after your callback resolves.
+ *
+ * The callback may be retried on contention — keep it free of side effects.
+ *
+ * @example
+ * await db.runTransaction(async (tx) => {
+ *   const counter = await tx.get(db.collection("stats").doc("global"));
+ *   const current = (counter?.total as number) ?? 0;
+ *   tx.update(db.collection("stats").doc("global"), { total: current + 1 });
+ * });
+ *
+ * @example
+ * // Transfer credits atomically
+ * await db.runTransaction(async (tx) => {
+ *   const from = await tx.get(db.collection("wallets").doc(fromId));
+ *   const to   = await tx.get(db.collection("wallets").doc(toId));
+ *   if (!from || (from.credits as number) < amount) throw new Error("Insufficient credits");
+ *   tx.update(db.collection("wallets").doc(fromId), { credits: (from.credits as number) - amount });
+ *   tx.update(db.collection("wallets").doc(toId),   { credits: ((to?.credits as number) ?? 0) + amount });
+ * });
+ */
+async function runTransaction(http, updateFn) {
+    const tx = new Transaction(http);
+    const result = await updateFn(tx);
+    // Flush all writes atomically (reads already happened inline above)
+    if (tx._writes.length > 0) {
+        await http.post("/transaction", {
+            reads: tx._reads,
+            writes: tx._writes,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=transaction.js.map

package/dist/db/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":";;;AA8JA,wCAgBC;AA/ID;;;GAGG;AACH,MAAa,WAAW;IAQtB,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;QAP7C,gBAAgB;QACP,WAAM,GAA8C,EAAE,CAAC;QAChE,gBAAgB;QACP,YAAO,GAAgB,EAAE,CAAC;QAE3B,mBAAc,GAAG,KAAK,CAAC;IAEiB,CAAC;IAEjD;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CACP,GAA2C;QAE3C,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QAErE,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAI,IAAI,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAK,GAA2B,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAC;YAC7D,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,GAAG,CACD,GAA2C,EAC3C,IAAkD;QAElD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,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;;;;;;OAMG;IACH,MAAM,CACJ,GAA2C,EAC3C,IAA2D;QAE3D,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,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;;;;;OAKG;IACH,MAAM,CAAC,GAA2C;QAChD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,IAAI,EAAY,QAAQ;YACxB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,EAAE,EAAc,GAAG,CAAC,EAAE;SACvB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA7FD,kCA6FC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,KAAK,UAAU,cAAc,CAClC,IAAgB,EAChB,QAAyC;IAEzC,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,EAAE,CAAC,CAAC;IAElC,oEAAoE;IACpE,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;YAC9B,KAAK,EAAG,EAAE,CAAC,MAAM;YACjB,MAAM,EAAE,EAAE,CAAC,OAAO;SACnB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/field_value.d.ts

@@ -0,0 +1,93 @@
+export type FieldValueType = "increment" | "decrement" | "serverTimestamp" | "delete" | "arrayUnion" | "arrayRemove";
+/**
+ * Opaque sentinel returned by every FieldValue factory.
+ * Never construct this directly — use the static helpers on FieldValue.
+ */
+export declare class FieldValueSentinel {
+    readonly _type: FieldValueType;
+    readonly _value?: number | unknown[] | undefined;
+    /** @internal discriminator so library code can detect sentinels */
+    readonly __fieldValue: true;
+    /** @internal */
+    constructor(_type: FieldValueType, _value?: number | unknown[] | undefined);
+    /**
+     * Serialize to the wire format the Clefbase server expects.
+     * Called automatically by JSON.stringify.
+     */
+    toJSON(): object;
+    toString(): string;
+}
+/**
+ * Atomic field-level sentinels for database writes.
+ *
+ * @example
+ * import { FieldValue } from "clefbase";
+ *
+ * await db.collection("posts").doc("p1").update({
+ *   views:      FieldValue.increment(1),
+ *   score:      FieldValue.decrement(0.5),
+ *   publishedAt: FieldValue.serverTimestamp(),
+ *   draftField: FieldValue.deleteField(),
+ *   tags:       FieldValue.arrayUnion("featured", "trending"),
+ *   oldTags:    FieldValue.arrayRemove("draft"),
+ * });
+ */
+export declare const FieldValue: {
+    /**
+     * Atomically increment a numeric field by `delta` (default 1).
+     * Creates the field with value `delta` if it does not yet exist.
+     *
+     * @example
+     * await ref.update({ views: FieldValue.increment(1) });
+     * await ref.update({ balance: FieldValue.increment(9.99) });
+     */
+    readonly increment: (delta?: number) => FieldValueSentinel;
+    /**
+     * Atomically decrement a numeric field by `delta` (default 1).
+     * Sugar for increment(-delta).
+     *
+     * @example
+     * await ref.update({ lives: FieldValue.decrement(1) });
+     */
+    readonly decrement: (delta?: number) => FieldValueSentinel;
+    /**
+     * Set the field to the server's current timestamp (ISO 8601 string).
+     * Avoids clock-skew issues by using the server clock instead of the client.
+     *
+     * @example
+     * await ref.update({ lastSeen: FieldValue.serverTimestamp() });
+     */
+    readonly serverTimestamp: () => FieldValueSentinel;
+    /**
+     * Remove this field from the document entirely.
+     * Only valid inside `.update()` — not `.set()`.
+     *
+     * @example
+     * await ref.update({ tempToken: FieldValue.deleteField() });
+     */
+    readonly deleteField: () => FieldValueSentinel;
+    /**
+     * Add one or more items to an array field, ignoring duplicates.
+     * Creates the field as a new array if it does not yet exist.
+     *
+     * @example
+     * await ref.update({ roles: FieldValue.arrayUnion("editor", "moderator") });
+     */
+    readonly arrayUnion: (...items: unknown[]) => FieldValueSentinel;
+    /**
+     * Remove one or more items from an array field (all matching occurrences).
+     * No-ops silently if the item or field does not exist.
+     *
+     * @example
+     * await ref.update({ roles: FieldValue.arrayRemove("moderator") });
+     */
+    readonly arrayRemove: (...items: unknown[]) => FieldValueSentinel;
+    /**
+     * Type-guard — returns true if `value` is any FieldValue sentinel.
+     *
+     * @example
+     * if (FieldValue.isSentinel(val)) console.log(val._type);
+     */
+    readonly isSentinel: (value: unknown) => value is FieldValueSentinel;
+};
+//# sourceMappingURL=field_value.d.ts.map

package/dist/field_value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field_value.d.ts","sourceRoot":"","sources":["../src/field_value.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,WAAW,GACX,iBAAiB,GACjB,QAAQ,GACR,YAAY,GACZ,aAAa,CAAC;AAElB;;;GAGG;AACH,qBAAa,kBAAkB;IAM3B,QAAQ,CAAC,KAAK,EAAE,cAAc;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE;IANtC,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAG,IAAI,CAAU;IAEtC,gBAAgB;gBAEL,KAAK,EAAE,cAAc,EACrB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,YAAA;IAGtC;;;OAGG;IACH,MAAM,IAAI,MAAM;IAiBhB,QAAQ,IAAI,MAAM;CAGnB;AAID;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU;IACrB;;;;;;;OAOG;iCACc,MAAM,KAAO,kBAAkB;IAOhD;;;;;;OAMG;iCACc,MAAM,KAAO,kBAAkB;IAOhD;;;;;;OAMG;oCACgB,kBAAkB;IAIrC;;;;;;OAMG;gCACY,kBAAkB;IAIjC;;;;;;OAMG;oCACkB,OAAO,EAAE,KAAG,kBAAkB;IAOnD;;;;;;OAMG;qCACmB,OAAO,EAAE,KAAG,kBAAkB;IAOpD;;;;;OAKG;iCACe,OAAO,KAAG,KAAK,IAAI,kBAAkB;CAG/C,CAAC"}