@typicalday/firegraph 0.11.2 → 0.12.0

package/dist/index.cjs

@@ -30,6 +30,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/internal/serialization-tag.ts
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+var SERIALIZATION_TAG, KNOWN_TYPES;
+var init_serialization_tag = __esm({
+  "src/internal/serialization-tag.ts"() {
+    "use strict";
+    SERIALIZATION_TAG = "__firegraph_ser__";
+    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+  }
+});
+
 // src/serialization.ts
 var serialization_exports = {};
 __export(serialization_exports, {
@@ -38,11 +53,6 @@ __export(serialization_exports, {
   isTaggedValue: () => isTaggedValue,
   serializeFirestoreTypes: () => serializeFirestoreTypes
 });
-function isTaggedValue(value) {
-  if (value === null || typeof value !== "object") return false;
-  const tag = value[SERIALIZATION_TAG];
-  return typeof tag === "string" && KNOWN_TYPES.has(tag);
-}
 function isTimestamp(value) {
   return value instanceof import_firestore.Timestamp;
 }
@@ -143,13 +153,13 @@ function deserializeValue(value, db) {
   }
   return result;
 }
-var import_firestore, SERIALIZATION_TAG, KNOWN_TYPES, _docRefWarned;
+var import_firestore, _docRefWarned;
 var init_serialization = __esm({
   "src/serialization.ts"() {
     "use strict";
     import_firestore = require("@google-cloud/firestore");
-    SERIALIZATION_TAG = "__firegraph_ser__";
-    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+    init_serialization_tag();
+    init_serialization_tag();
     _docRefWarned = false;
   }
 });
@@ -202,6 +212,7 @@ __export(index_exports, {
   defaultExecutor: () => defaultExecutor,
   defineConfig: () => defineConfig,
   defineViews: () => defineViews,
+  deleteField: () => deleteField,
   deserializeFirestoreTypes: () => deserializeFirestoreTypes,
   destroySandboxWorker: () => destroySandboxWorker,
   discoverEntities: () => discoverEntities,
@@ -255,6 +266,146 @@ function computeEdgeDocId(aUid, axbType, bUid) {
   return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
 }
 
+// src/internal/write-plan.ts
+init_serialization_tag();
+var DELETE_FIELD = /* @__PURE__ */ Symbol.for("firegraph.deleteField");
+function deleteField() {
+  return DELETE_FIELD;
+}
+function isDeleteSentinel(value) {
+  return value === DELETE_FIELD;
+}
+var FIRESTORE_TERMINAL_CTOR = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue",
+  "NumericIncrementTransform",
+  "ArrayUnionTransform",
+  "ArrayRemoveTransform",
+  "ServerTimestampTransform",
+  "DeleteTransform"
+]);
+function isTerminalValue(value) {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t !== "object") return true;
+  if (Array.isArray(value)) return true;
+  if (isTaggedValue(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return false;
+  const ctor = value.constructor;
+  if (ctor && typeof ctor.name === "string" && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;
+  return true;
+}
+var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function assertUpdatePayloadExclusive(update) {
+  if (update.replaceData !== void 0 && update.dataOps !== void 0) {
+    throw new Error(
+      "firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. Use one or the other \u2014 `replaceData` is the migration-write-back form, `dataOps` is the standard partial-update form."
+    );
+  }
+}
+function assertNoDeleteSentinels(data, callerLabel) {
+  walkForDeleteSentinels(data, [], { kind: "root" }, ({ path }) => {
+    const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+    throw new Error(
+      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. deleteField() is only valid inside updateNode/updateEdge \u2014 full-data writes (put*, replace*) cannot delete individual fields. Use updateNode with a deleteField() value, or omit the field from the replace payload.`
+    );
+  });
+}
+function walkForDeleteSentinels(node, path, parent, visit) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    visit({ path, parent });
+    return;
+  }
+  if (typeof node !== "object") return;
+  if (isTaggedValue(node)) return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: "array", index: i }, visit);
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) return;
+  const obj = node;
+  for (const key of Object.keys(obj)) {
+    walkForDeleteSentinels(obj[key], [...path, key], { kind: "object" }, visit);
+  }
+}
+function assertSafePath(path) {
+  for (const seg of path) {
+    if (!SAFE_KEY_RE.test(seg)) {
+      throw new Error(
+        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Keys used inside update payloads must match /^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in SQLite JSON paths.`
+      );
+    }
+  }
+}
+function flattenPatch(data) {
+  const ops = [];
+  walk(data, [], ops);
+  return ops;
+}
+function assertNoDeleteSentinelsInArrayValue(arr, arrayPath) {
+  walkForDeleteSentinels(arr, arrayPath, { kind: "root" }, ({ parent }) => {
+    const arrayPathStr = arrayPath.length === 0 ? "<root>" : arrayPath.map((p) => JSON.stringify(p)).join(" > ");
+    if (parent.kind === "array") {
+      throw new Error(
+        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at path ${arrayPathStr}. Arrays are terminal in update payloads (replaced as a unit), so the sentinel would be silently dropped by JSON serialization. To remove the field entirely, pass deleteField() in place of the whole array.`
+      );
+    }
+    throw new Error(
+      `firegraph: deleteField() sentinel inside an array element at path ${arrayPathStr}. Arrays are terminal in update payloads \u2014 the sentinel would be silently dropped by JSON serialization.`
+    );
+  });
+}
+function walk(node, path, out) {
+  if (node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    if (path.length === 0) {
+      throw new Error("firegraph: deleteField() cannot be the entire update payload.");
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: void 0, delete: true });
+    return;
+  }
+  if (isTerminalValue(node)) {
+    if (path.length === 0) {
+      throw new Error(
+        "firegraph: update payload must be a plain object. Got " + (node === null ? "null" : Array.isArray(node) ? "array" : typeof node) + "."
+      );
+    }
+    if (Array.isArray(node)) {
+      assertNoDeleteSentinelsInArrayValue(node, path);
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: node, delete: false });
+    return;
+  }
+  const obj = node;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    if (path.length > 0) {
+      assertSafePath(path);
+      out.push({ path: [...path], value: {}, delete: false });
+    }
+    return;
+  }
+  for (const key of keys) {
+    if (key === SERIALIZATION_TAG) {
+      const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+      throw new Error(
+        `firegraph: update payload contains a literal \`${SERIALIZATION_TAG}\` key at ${where}. That key is reserved for firegraph's serialization envelope and cannot appear on a plain object in user data. Use a different field name, or pass a recognized tagged value through replaceNode/replaceEdge instead.`
+      );
+    }
+    walk(obj[key], [...path, key], out);
+  }
+}
+
 // src/batch.ts
 function buildWritableNodeRecord(aType, uid, data) {
   return { aType, aUid: uid, axbType: NODE_RELATION, bType: aType, bUid: uid, data };
@@ -269,6 +420,19 @@ var GraphBatchImpl = class {
     this.scopePath = scopePath;
   }
   async putNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -280,9 +444,10 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -294,11 +459,15 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    this.backend.updateDoc(docId, { dataFields: data });
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1409,6 +1578,19 @@ var GraphTransactionImpl = class {
     return results.map((r) => r.record);
   }
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -1420,9 +1602,10 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -1434,11 +1617,15 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1637,6 +1824,19 @@ var GraphClientImpl = class _GraphClientImpl {
   // GraphWriter
   // ---------------------------------------------------------------------------
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, NODE_RELATION, aType, data, this.backend.scopePath);
@@ -1650,9 +1850,10 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, axbType, bType, data, this.backend.scopePath);
@@ -1666,11 +1867,15 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -2344,8 +2549,12 @@ function createFirestoreAdapter(db, collectionPath) {
       if (!snap.exists) return null;
       return snap.data();
     },
-    async setDoc(docId, data) {
-      await collectionRef.doc(docId).set(data);
+    async setDoc(docId, data, options) {
+      if (options?.merge) {
+        await collectionRef.doc(docId).set(data, { merge: true });
+      } else {
+        await collectionRef.doc(docId).set(data);
+      }
     },
     async updateDoc(docId, data) {
       await collectionRef.doc(docId).update(data);
@@ -2377,8 +2586,12 @@ function createTransactionAdapter(db, collectionPath, tx) {
       if (!snap.exists) return null;
       return snap.data();
     },
-    setDoc(docId, data) {
-      tx.set(collectionRef.doc(docId), data);
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        tx.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        tx.set(collectionRef.doc(docId), data);
+      }
     },
     updateDoc(docId, data) {
       tx.update(collectionRef.doc(docId), data);
@@ -2406,8 +2619,12 @@ function createBatchAdapter(db, collectionPath) {
   const collectionRef = db.collection(collectionPath);
   const batch = db.batch();
   return {
-    setDoc(docId, data) {
-      batch.set(collectionRef.doc(docId), data);
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        batch.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        batch.set(collectionRef.doc(docId), data);
+      }
     },
     updateDoc(docId, data) {
       batch.update(collectionRef.doc(docId), data);
@@ -2483,16 +2700,21 @@ function createPipelineQueryAdapter(db, collectionPath) {
 }
 
 // src/internal/firestore-backend.ts
+function dottedDataPath(op) {
+  assertSafePath(op.path);
+  return `data.${op.path.join(".")}`;
+}
 function buildFirestoreUpdate(update, db) {
+  assertUpdatePayloadExclusive(update);
   const out = {
     updatedAt: import_firestore2.FieldValue.serverTimestamp()
   };
   if (update.replaceData) {
     out.data = deserializeFirestoreTypes(update.replaceData, db);
-  }
-  if (update.dataFields) {
-    for (const [k, v] of Object.entries(update.dataFields)) {
-      out[`data.${k}`] = v;
+  } else if (update.dataOps) {
+    for (const op of update.dataOps) {
+      const key = dottedDataPath(op);
+      out[key] = op.delete ? import_firestore2.FieldValue.delete() : op.value;
     }
   }
   if (update.v !== void 0) {
@@ -2526,8 +2748,12 @@ var FirestoreTransactionBackend = class {
   query(filters, options) {
     return this.adapter.query(filters, options);
   }
-  async setDoc(docId, record) {
-    this.adapter.setDoc(docId, stampWritableRecord(record));
+  async setDoc(docId, record, mode) {
+    this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
   }
   async updateDoc(docId, update) {
     this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
@@ -2541,8 +2767,12 @@ var FirestoreBatchBackend = class {
     this.adapter = adapter;
     this.db = db;
   }
-  setDoc(docId, record) {
-    this.adapter.setDoc(docId, stampWritableRecord(record));
+  setDoc(docId, record, mode) {
+    this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
   }
   updateDoc(docId, update) {
     this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
@@ -2580,8 +2810,12 @@ var FirestoreBackendImpl = class _FirestoreBackendImpl {
     return this.adapter.query(filters, options);
   }
   // --- Writes ---
-  setDoc(docId, record) {
-    return this.adapter.setDoc(docId, stampWritableRecord(record));
+  setDoc(docId, record, mode) {
+    return this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
   }
   updateDoc(docId, update) {
     return this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
@@ -3441,6 +3675,7 @@ function defineViews(input) {
   defaultExecutor,
   defineConfig,
   defineViews,
+  deleteField,
   deserializeFirestoreTypes,
   destroySandboxWorker,
   discoverEntities,