@typicalday/firegraph 0.11.1 → 0.12.0

package/dist/cloudflare/index.js

@@ -1,14 +1,173 @@
 import {
   DEFAULT_CORE_INDEXES,
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
   NODE_RELATION,
   buildEdgeQueryPlan,
   computeEdgeDocId,
   computeNodeDocId,
-  createGraphClientFromBackend
-} from "../chunk-6SB34IPQ.js";
+  createGraphClientFromBackend,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+} from "../chunk-HONQY4HF.js";
 import {
-  FiregraphError
-} from "../chunk-R7CRGYY4.js";
+  FiregraphError,
+  assertUpdatePayloadExclusive,
+  deleteField,
+  flattenPatch,
+  isDeleteSentinel
+} from "../chunk-AWW4MUJ5.js";
+import {
+  SERIALIZATION_TAG
+} from "../chunk-EQJUUVFG.js";
+
+// src/internal/sqlite-data-ops.ts
+var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function isFirestoreSpecialType(value) {
+  const ctorName = value.constructor?.name;
+  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
+  return null;
+}
+var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function validateJsonPathKey(key, backendLabel) {
+  if (key.length === 0) {
+    throw new FiregraphError(
+      `${backendLabel}: empty JSON path component is not allowed`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!JSON_PATH_KEY_RE.test(key)) {
+    throw new FiregraphError(
+      `${backendLabel}: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceNode/replaceEdge (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+function jsonBind(value, backendLabel) {
+  if (value === void 0) return "null";
+  if (value !== null && typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `${backendLabel} cannot persist a Firestore ${firestoreType} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp).`,
+        "INVALID_ARGUMENT"
+      );
+    }
+  }
+  return JSON.stringify(value);
+}
+function compileDataOpsExpr(ops, base, params, backendLabel) {
+  if (ops.length === 0) return null;
+  const deletes = [];
+  const sets = [];
+  for (const op of ops) (op.delete ? deletes : sets).push(op);
+  let expr = base;
+  if (deletes.length > 0) {
+    const placeholders = deletes.map(() => "?").join(", ");
+    expr = `json_remove(${expr}, ${placeholders})`;
+    for (const op of deletes) {
+      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
+      params.push(`$.${op.path.join(".")}`);
+    }
+  }
+  if (sets.length > 0) {
+    const pieces = sets.map(() => "?, json(?)").join(", ");
+    expr = `json_set(${expr}, ${pieces})`;
+    for (const op of sets) {
+      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
+      params.push(`$.${op.path.join(".")}`);
+      params.push(jsonBind(op.value, backendLabel));
+    }
+  }
+  return expr;
+}
+
+// src/internal/sqlite-payload-guard.ts
+var FIRESTORE_TYPE_NAMES2 = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function assertJsonSafePayload(data, label) {
+  walk(data, [], label);
+}
+function walk(node, path, label) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    throw new FiregraphError(
+      `${label} backend cannot persist a deleteField() sentinel inside a full-data payload (replaceNode/replaceEdge or first-insert). The sentinel is only valid inside an updateNode/updateEdge dataOps patch. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const t = typeof node;
+  if (t === "symbol" || t === "function") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type ${t}. JSON.stringify drops it silently. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t === "bigint") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type bigint. JSON.stringify cannot serialize this type (throws TypeError). Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t !== "object") return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walk(node[i], [...path, String(i)], label);
+    }
+    return;
+  }
+  const obj = node;
+  if (Object.prototype.hasOwnProperty.call(obj, SERIALIZATION_TAG)) {
+    const tagValue = obj[SERIALIZATION_TAG];
+    throw new FiregraphError(
+      `${label} backend cannot persist an object with a \`${SERIALIZATION_TAG}\` key (value: ${formatTagValue(tagValue)}). Recognised tags are valid only on the Firestore backend (migration-sandbox output); a literal \`${SERIALIZATION_TAG}\` field in user data is reserved and not allowed. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) {
+    const ctor = node.constructor;
+    const ctorName = ctor && typeof ctor.name === "string" ? ctor.name : "<anonymous>";
+    if (FIRESTORE_TYPE_NAMES2.has(ctorName)) {
+      throw new FiregraphError(
+        `${label} backend cannot persist a Firestore ${ctorName} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp, \`{lat,lng}\` for GeoPoint). Path: ${formatPath(path)}.`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    if (node instanceof Date) return;
+    throw new FiregraphError(
+      `${label} backend cannot persist a class instance of type ${ctorName}. Only plain objects, arrays, and primitives round-trip safely through JSON storage. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  for (const key of Object.keys(obj)) {
+    walk(obj[key], [...path, key], label);
+  }
+}
+function formatPath(path) {
+  return path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+}
+function formatTagValue(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return typeof value;
+}
 
 // src/timestamp.ts
 var GraphTimestampImpl = class _GraphTimestampImpl {
@@ -37,7 +196,7 @@ var GraphTimestampImpl = class _GraphTimestampImpl {
 
 // src/internal/sqlite-index-ddl.ts
 var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 function quoteIdent(name) {
   if (!IDENT_RE.test(name)) {
     throw new FiregraphError(
@@ -85,7 +244,7 @@ function compileFieldExpr(path, fieldToColumn) {
     const suffix = path.slice(5);
     const parts = suffix.split(".");
     for (const part of parts) {
-      if (!JSON_PATH_KEY_RE.test(part)) {
+      if (!JSON_PATH_KEY_RE2.test(part)) {
         throw new FiregraphError(
           `IndexSpec data path "${path}" has invalid component "${part}". Each component must match /^[A-Za-z_][A-Za-z0-9_-]*$/.`,
           "INVALID_INDEX"
@@ -180,6 +339,8 @@ function buildDOSchemaStatements(table, options = {}) {
 }
 
 // src/cloudflare/sql.ts
+var DO_BACKEND_LABEL = "DO SQLite";
+var DO_BACKEND_ERR_LABEL = "DO SQLite backend";
 function compileFieldRef(field) {
   const column = DO_FIELD_TO_COLUMN[field];
   if (column) {
@@ -188,7 +349,7 @@ function compileFieldRef(field) {
   if (field.startsWith("data.")) {
     const suffix = field.slice(5);
     for (const part of suffix.split(".")) {
-      validateJsonPathKey(part);
+      validateJsonPathKey(part, DO_BACKEND_ERR_LABEL);
     }
     return { expr: `json_extract("data", '$.${suffix}')` };
   }
@@ -200,18 +361,6 @@ function compileFieldRef(field) {
     "INVALID_QUERY"
   );
 }
-var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
-  "Timestamp",
-  "GeoPoint",
-  "VectorValue",
-  "DocumentReference",
-  "FieldValue"
-]);
-function isFirestoreSpecialType(value) {
-  const ctorName = value.constructor?.name;
-  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
-  return null;
-}
 function bindValue(value) {
   if (value === null || value === void 0) return null;
   if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
@@ -230,21 +379,6 @@ function bindValue(value) {
   }
   return String(value);
 }
-var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-function validateJsonPathKey(key) {
-  if (key.length === 0) {
-    throw new FiregraphError(
-      "DO SQLite backend: empty JSON path component is not allowed",
-      "INVALID_QUERY"
-    );
-  }
-  if (!JSON_PATH_KEY_RE2.test(key)) {
-    throw new FiregraphError(
-      `DO SQLite backend: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceData (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
-      "INVALID_QUERY"
-    );
-  }
-}
 function compileFilter(filter, params) {
   const { expr } = compileFieldRef(filter.field);
   switch (filter.op) {
@@ -331,11 +465,27 @@ function compileDOSelectByDocId(table, docId) {
     params: [docId]
   };
 }
-function compileDOSet(table, docId, record, nowMillis) {
-  const sql = `INSERT OR REPLACE INTO ${quoteDOIdent(table)} (
-    doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
-  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
-  const params = [
+function compileDOSet(table, docId, record, nowMillis, mode) {
+  assertJsonSafePayload(record.data, DO_BACKEND_LABEL);
+  if (mode === "replace") {
+    const sql2 = `INSERT OR REPLACE INTO ${quoteDOIdent(table)} (
+      doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+    const params = [
+      docId,
+      record.aType,
+      record.aUid,
+      record.axbType,
+      record.bType,
+      record.bUid,
+      JSON.stringify(record.data ?? {}),
+      record.v ?? null,
+      nowMillis,
+      nowMillis
+    ];
+    return { sql: sql2, params };
+  }
+  const insertParams = [
     docId,
     record.aType,
     record.aUid,
@@ -347,22 +497,44 @@ function compileDOSet(table, docId, record, nowMillis) {
     nowMillis,
     nowMillis
   ];
-  return { sql, params };
+  const ops = flattenPatch(record.data ?? {});
+  const updateParams = [];
+  const dataExpr = compileDataOpsExpr(ops, `COALESCE("data", '{}')`, updateParams, DO_BACKEND_ERR_LABEL) ?? `COALESCE("data", '{}')`;
+  const sql = `INSERT INTO ${quoteDOIdent(table)} (
+      doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(doc_id) DO UPDATE SET
+      "a_type" = excluded."a_type",
+      "a_uid" = excluded."a_uid",
+      "axb_type" = excluded."axb_type",
+      "b_type" = excluded."b_type",
+      "b_uid" = excluded."b_uid",
+      "data" = ${dataExpr},
+      "v" = COALESCE(excluded."v", "v"),
+      "created_at" = excluded."created_at",
+      "updated_at" = excluded."updated_at"`;
+  return { sql, params: [...insertParams, ...updateParams] };
 }
 function compileDOUpdate(table, docId, update, nowMillis) {
+  assertUpdatePayloadExclusive(update);
   const setClauses = [];
   const params = [];
   if (update.replaceData) {
+    assertJsonSafePayload(update.replaceData, DO_BACKEND_LABEL);
     setClauses.push(`"data" = ?`);
     params.push(JSON.stringify(update.replaceData));
-  } else if (update.dataFields && Object.keys(update.dataFields).length > 0) {
-    const entries = Object.entries(update.dataFields);
-    const pathArgs = entries.map(() => `?, ?`).join(", ");
-    setClauses.push(`"data" = json_set(COALESCE("data", '{}'), ${pathArgs})`);
-    for (const [k, v] of entries) {
-      validateJsonPathKey(k);
-      params.push(`$.${k}`);
-      params.push(bindValue(v));
+  } else if (update.dataOps && update.dataOps.length > 0) {
+    for (const op of update.dataOps) {
+      if (!op.delete) assertJsonSafePayload(op.value, DO_BACKEND_LABEL);
+    }
+    const expr = compileDataOpsExpr(
+      update.dataOps,
+      `COALESCE("data", '{}')`,
+      params,
+      DO_BACKEND_ERR_LABEL
+    );
+    if (expr !== null) {
+      setClauses.push(`"data" = ${expr}`);
     }
   }
   if (update.v !== void 0) {
@@ -458,8 +630,8 @@ var DORPCBatchBackend = class {
     this.getStub = getStub;
   }
   ops = [];
-  setDoc(docId, record) {
-    this.ops.push({ kind: "set", docId, record });
+  setDoc(docId, record, mode) {
+    this.ops.push({ kind: "set", docId, record, mode });
   }
   updateDoc(docId, update) {
     this.ops.push({ kind: "update", docId, update });
@@ -509,8 +681,8 @@ var DORPCBackend = class _DORPCBackend {
     return wires.map(hydrateDORecord);
   }
   // --- Writes ---
-  async setDoc(docId, record) {
-    return this.stub._fgSetDoc(docId, record);
+  async setDoc(docId, record, mode) {
+    return this.stub._fgSetDoc(docId, record, mode);
   }
   async updateDoc(docId, update) {
     return this.stub._fgUpdateDoc(docId, update);
@@ -697,15 +869,28 @@ function createSiblingClient(client, siblingRootKey) {
 }
 
 // src/cloudflare/do.ts
+import { DurableObject } from "cloudflare:workers";
 var DEFAULT_OPTIONS = {
   table: "firegraph",
   autoMigrate: true
 };
-var FiregraphDO = class {
-  /** @internal — exposed for subclass access, not part of the public RPC. */
-  ctx;
-  /** @internal — exposed for subclass access; opaque to this class. */
-  env;
+var FiregraphDO = class extends DurableObject {
+  /**
+   * @internal — locally-narrowed alias for `this.ctx`, used only by
+   * FiregraphDO's own SQL helpers. Same runtime object as the inherited
+   * `this.ctx`, but typed as `DurableObjectStateLike` (just `storage.sql`
+   * / `transactionSync` / `blockConcurrencyWhile`) so internal calls
+   * don't trip over workers-types' stricter
+   * `SqlStorage.exec<T extends Record<string, SqlStorageValue>>`
+   * constraint vs the `Record<string, unknown>` rows firegraph passes.
+   *
+   * **Subclasses should use `this.ctx`, not `this.state`.** `this.state`
+   * deliberately exposes only the slice FiregraphDO needs internally;
+   * subclasses that want `id`, `acceptWebSocket`, `setAlarm`, `getAlarm`,
+   * `waitUntil`, `props`, etc. must reach for the inherited `this.ctx`
+   * (the full workers-types `DurableObjectState`).
+   */
+  state;
   /** @internal — table name used by every compiled statement. */
   table;
   /** @internal — registry consulted by `runSchema` for per-entry indexes. */
@@ -713,8 +898,8 @@ var FiregraphDO = class {
   /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
   coreIndexes;
   constructor(ctx, env, options = {}) {
-    this.ctx = ctx;
-    this.env = env;
+    super(ctx, env);
+    this.state = ctx;
     const table = options.table ?? DEFAULT_OPTIONS.table;
     validateDOTableName(table);
     this.table = table;
@@ -722,7 +907,7 @@ var FiregraphDO = class {
     this.coreIndexes = options.coreIndexes;
     const autoMigrate = options.autoMigrate ?? DEFAULT_OPTIONS.autoMigrate;
     if (autoMigrate) {
-      void this.ctx.blockConcurrencyWhile(async () => {
+      void this.state.blockConcurrencyWhile(async () => {
         this.runSchema();
       });
     }
@@ -747,14 +932,14 @@ var FiregraphDO = class {
   // ---------------------------------------------------------------------------
   // RPC: writes
   // ---------------------------------------------------------------------------
-  async _fgSetDoc(docId, record) {
-    const stmt = compileDOSet(this.table, docId, record, Date.now());
+  async _fgSetDoc(docId, record, mode) {
+    const stmt = compileDOSet(this.table, docId, record, Date.now(), mode);
     this.execRun(stmt);
   }
   async _fgUpdateDoc(docId, update) {
     const stmt = compileDOUpdate(this.table, docId, update, Date.now());
     const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
-    const rows = this.ctx.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
+    const rows = this.state.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
     if (rows.length === 0) {
       throw new FiregraphError(`updateDoc: no document found for doc_id=${docId}`, "NOT_FOUND");
     }
@@ -778,16 +963,16 @@ var FiregraphDO = class {
     const statements = ops.map((op) => {
       switch (op.kind) {
         case "set":
-          return compileDOSet(this.table, op.docId, op.record, now);
+          return compileDOSet(this.table, op.docId, op.record, now, op.mode);
         case "update":
           return compileDOUpdate(this.table, op.docId, op.update, now);
         case "delete":
           return compileDODelete(this.table, op.docId);
       }
     });
-    this.ctx.storage.transactionSync(() => {
+    this.state.storage.transactionSync(() => {
       for (const stmt of statements) {
-        this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+        this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
       }
     });
   }
@@ -836,9 +1021,9 @@ var FiregraphDO = class {
       };
     }
     try {
-      this.ctx.storage.transactionSync(() => {
+      this.state.storage.transactionSync(() => {
         for (const stmt of statements) {
-          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+          this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
         }
       });
       return {
@@ -878,9 +1063,9 @@ var FiregraphDO = class {
     }
     const deleteStmts = docIds.map((id) => compileDODelete(this.table, id));
     try {
-      this.ctx.storage.transactionSync(() => {
+      this.state.storage.transactionSync(() => {
         for (const stmt of deleteStmts) {
-          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+          this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
         }
       });
       return { deleted: deleteStmts.length, batches: 1, errors: [] };
@@ -914,21 +1099,27 @@ var FiregraphDO = class {
       registry: this.registry
     });
     for (const sql of statements) {
-      this.ctx.storage.sql.exec(sql).toArray();
+      this.state.storage.sql.exec(sql).toArray();
     }
   }
   execAll(stmt) {
-    return this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    return this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
   }
   execRun(stmt) {
-    this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
   }
 };
 export {
   DORPCBackend,
   FiregraphDO,
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
   buildDOSchemaStatements,
   createDOClient,
-  createSiblingClient
+  createMergedRegistry,
+  createRegistry,
+  createSiblingClient,
+  deleteField,
+  generateId
 };
 //# sourceMappingURL=index.js.map