@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/backend.cjs

@@ -20,10 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/backend.ts
 var backend_exports = {};
 __export(backend_exports, {
+  CapabilityNotSupportedError: () => CapabilityNotSupportedError,
   CrossBackendTransactionError: () => CrossBackendTransactionError,
+  DELETE_FIELD: () => DELETE_FIELD,
   appendStorageScope: () => appendStorageScope,
+  createCapabilities: () => createCapabilities,
   createRoutingBackend: () => createRoutingBackend,
+  deleteField: () => deleteField,
+  flattenPatch: () => flattenPatch,
+  intersectCapabilities: () => intersectCapabilities,
   isAncestorScopeUid: () => isAncestorScopeUid,
+  isDeleteSentinel: () => isDeleteSentinel,
   parseStorageScope: () => parseStorageScope,
   resolveAncestorScope: () => resolveAncestorScope
 });
@@ -43,6 +50,34 @@ var CrossBackendTransactionError = class extends FiregraphError {
     this.name = "CrossBackendTransactionError";
   }
 };
+var CapabilityNotSupportedError = class extends FiregraphError {
+  constructor(capability, backendDescription) {
+    super(
+      `Capability "${capability}" is not supported by ${backendDescription}.`,
+      "CAPABILITY_NOT_SUPPORTED"
+    );
+    this.capability = capability;
+    this.name = "CapabilityNotSupportedError";
+  }
+};
+
+// src/internal/backend.ts
+function createCapabilities(caps) {
+  return {
+    has: (capability) => caps.has(capability),
+    values: () => caps.values()
+  };
+}
+function intersectCapabilities(parts) {
+  if (parts.length === 0) return createCapabilities(/* @__PURE__ */ new Set());
+  const sets = parts.map((p) => new Set(p.values()));
+  const [first, ...rest] = sets;
+  const intersection = /* @__PURE__ */ new Set();
+  for (const c of first) {
+    if (rest.every((s) => s.has(c))) intersection.add(c);
+  }
+  return createCapabilities(intersection);
+}
 
 // src/internal/routing-backend.ts
 function assertValidSubgraphArgs(parentNodeUid, name) {
@@ -60,16 +95,70 @@ function assertValidSubgraphArgs(parentNodeUid, name) {
   }
 }
 var RoutingStorageBackend = class _RoutingStorageBackend {
-  constructor(base, options, storageScope, logicalScopePath) {
+  constructor(base, options, storageScope, logicalScopePath, capabilities) {
     this.base = base;
     this.options = options;
     this.collectionPath = base.collectionPath;
     this.scopePath = logicalScopePath;
     this.storageScope = storageScope;
+    if (capabilities) {
+      this.capabilities = capabilities;
+    } else if (options.routedCapabilities && options.routedCapabilities.length > 0) {
+      this.capabilities = intersectCapabilities([base.capabilities, ...options.routedCapabilities]);
+    } else {
+      this.capabilities = base.capabilities;
+    }
     if (base.findEdgesGlobal) {
       this.findEdgesGlobal = (params, collectionName) => base.findEdgesGlobal(params, collectionName);
     }
+    if (base.aggregate && this.capabilities.has("query.aggregate")) {
+      this.aggregate = (spec, filters) => base.aggregate(spec, filters);
+    }
+    if (base.bulkDelete && this.capabilities.has("query.dml")) {
+      this.bulkDelete = (filters, options2) => base.bulkDelete(filters, options2);
+    }
+    if (base.bulkUpdate && this.capabilities.has("query.dml")) {
+      this.bulkUpdate = (filters, patch, options2) => base.bulkUpdate(filters, patch, options2);
+    }
+    if (base.expand && this.capabilities.has("query.join")) {
+      this.expand = (params) => base.expand(params);
+    }
+    if (base.runEngineTraversal && this.capabilities.has("traversal.serverSide")) {
+      this.runEngineTraversal = (params) => base.runEngineTraversal(params);
+    }
+    if (base.findEdgesProjected && this.capabilities.has("query.select")) {
+      this.findEdgesProjected = (select, filters, options2) => base.findEdgesProjected(select, filters, options2);
+    }
+    if (base.findNearest && this.capabilities.has("search.vector")) {
+      this.findNearest = (params) => base.findNearest(params);
+    }
+    if (base.fullTextSearch && this.capabilities.has("search.fullText")) {
+      this.fullTextSearch = (params) => base.fullTextSearch(params);
+    }
+    if (base.geoSearch && this.capabilities.has("search.geo")) {
+      this.geoSearch = (params) => base.geoSearch(params);
+    }
   }
+  /**
+   * Effective capability set for this wrapper.
+   *
+   * - **Root wrapper** (`createRoutingBackend(...)` direct return): if the
+   *   caller supplied `options.routedCapabilities`, the cap set is the
+   *   intersection of `base.capabilities` and every set in that list. If
+   *   not, the cap set mirrors `base.capabilities` (suitable when routes
+   *   target peers of the same backend type — no capability differential
+   *   to honour).
+   * - **Child wrapper** (returned from `subgraph()`): the cap set mirrors
+   *   the *wrapped* backend (either `base.subgraph(...)` or the backend
+   *   returned by `route()`). Each child handle reflects what's safe to
+   *   call against the specific backend it targets — invariant 3 holds
+   *   per-instance.
+   *
+   * This satisfies invariant 5 (intersection across mixed-backend graphs)
+   * when callers opt in, and falls back to a non-lying mirror when they
+   * don't.
+   */
+  capabilities;
   collectionPath;
   /**
    * Logical (names-only) scope path for *this* wrapper. Tracked
@@ -96,6 +185,125 @@ var RoutingStorageBackend = class _RoutingStorageBackend {
    * shape in the `StorageBackend` interface.
    */
   findEdgesGlobal;
+  /**
+   * Same conditional-install pattern as `findEdgesGlobal`. The router's
+   * declared capability set is mirrored from the base (or intersected with
+   * the user's `routedCapabilities`) — if `query.aggregate` is in that
+   * set, the underlying method must be present, otherwise `client.aggregate()`
+   * would resolve `UNSUPPORTED_OPERATION` despite the cap claim. This
+   * ensures the "declared capability ⇒ method exists" invariant holds
+   * through routing wrappers (Phase 4 audit C1).
+   */
+  aggregate;
+  /**
+   * DML pass-throughs. Same conditional-install pattern as `aggregate`:
+   * gated on BOTH the base method's existence AND `this.capabilities`
+   * advertising `query.dml`. If `routedCapabilities` intersected
+   * `query.dml` away (e.g. one routed peer is Firestore Standard which
+   * has no pipeline-DML support), the methods are *not* installed even
+   * though `base.bulkDelete` exists — otherwise the router would silently
+   * outperform what the declared cap set promises across hops. This
+   * preserves the "declared capability ⇒ method exists" invariant in
+   * both directions (Phase 5).
+   */
+  bulkDelete;
+  bulkUpdate;
+  /**
+   * Multi-source fan-out pass-through. Same conditional-install pattern as
+   * `aggregate` and the bulk-DML methods: gated on BOTH the base method's
+   * existence AND `this.capabilities` advertising `query.join`. If
+   * `routedCapabilities` intersected `query.join` away (e.g. one routed peer
+   * is Firestore Standard which has no pipeline-join support), the method is
+   * not installed even though `base.expand` exists. This preserves the
+   * "declared capability ⇒ method exists" invariant in both directions.
+   *
+   * Like `aggregate` and bulk DML, `expand` runs against the base backend
+   * only — it cannot fan out across routed children, since each routed
+   * subgraph is a separate physical store. Cross-graph hops (which resolve
+   * to per-source subgraph readers) are therefore never dispatched through
+   * `expand` by `traverse.ts`; the same constraint applies here, naturally.
+   */
+  expand;
+  /**
+   * Engine-level multi-hop traversal pass-through. Same conditional-install
+   * pattern as `aggregate`, bulk DML, and `expand`: gated on BOTH the base
+   * method's existence AND `this.capabilities` advertising
+   * `traversal.serverSide`. If `routedCapabilities` intersected
+   * `traversal.serverSide` away (e.g. one routed peer is a SQLite-shaped
+   * backend that has no nested-pipeline path), the method is not installed
+   * even though `base.runEngineTraversal` exists. This preserves the
+   * "declared capability ⇒ method exists" invariant in both directions.
+   *
+   * Like the other extensions, engine traversal runs against the base
+   * backend only — a routed child's own `runEngineTraversal` is reached
+   * through `.subgraph().runEngineTraversal()` against the routed handle.
+   * Cross-graph hops never reach this method anyway: the traversal
+   * compiler in `firestore-traverse-compiler.ts` rejects specs whose
+   * hops carry `targetGraph`, falling back to the per-hop loop. Routed
+   * children are physically distinct backends, so even an "in-graph"
+   * traversal across a routed-child boundary is structurally a
+   * cross-backend hop and never compiles for engine dispatch.
+   */
+  runEngineTraversal;
+  /**
+   * Server-side projection pass-through. Same conditional-install pattern as
+   * `aggregate`, bulk DML, and `expand`: gated on BOTH the base method's
+   * existence AND `this.capabilities` advertising `query.select`. If
+   * `routedCapabilities` intersected `query.select` away (e.g. one routed
+   * peer doesn't implement projection), the method is not installed even
+   * though `base.findEdgesProjected` exists. This preserves the "declared
+   * capability ⇒ method exists" invariant in both directions.
+   *
+   * Like `aggregate` and `expand`, projection runs against the base backend
+   * only — a routed child's own projection is reached through
+   * `.subgraph().findEdgesProjected()` against the routed handle.
+   */
+  findEdgesProjected;
+  /**
+   * Vector / nearest-neighbour pass-through. Same conditional-install
+   * pattern as `aggregate`, bulk DML, `expand`, and `findEdgesProjected`:
+   * gated on BOTH the base method's existence AND `this.capabilities`
+   * advertising `search.vector`. If `routedCapabilities` intersected
+   * `search.vector` away (e.g. one routed peer is a SQLite-shaped backend
+   * that has no native ANN index), the method is not installed even
+   * though `base.findNearest` exists. This preserves the "declared
+   * capability ⇒ method exists" invariant in both directions.
+   *
+   * Like the other extensions, vector search runs against the base
+   * backend only — a routed child's own `findNearest` is reached through
+   * `.subgraph().findNearest()` against the routed handle.
+   */
+  findNearest;
+  /**
+   * Full-text search pass-through. Same conditional-install pattern as
+   * `findNearest`: gated on BOTH the base method's existence AND
+   * `this.capabilities` advertising `search.fullText`. If
+   * `routedCapabilities` intersected `search.fullText` away (e.g. one
+   * routed peer is Firestore Standard or a SQLite-shaped backend that
+   * has no native FTS index), the method is not installed even though
+   * `base.fullTextSearch` exists. This preserves the "declared
+   * capability ⇒ method exists" invariant in both directions.
+   *
+   * Like the other extensions, FTS runs against the base backend only —
+   * a routed child's own `fullTextSearch` is reached through
+   * `.subgraph().fullTextSearch()` against the routed handle.
+   */
+  fullTextSearch;
+  /**
+   * Geospatial distance pass-through. Same conditional-install pattern
+   * as `fullTextSearch`: gated on BOTH the base method's existence AND
+   * `this.capabilities` advertising `search.geo`. If `routedCapabilities`
+   * intersected `search.geo` away (e.g. one routed peer is Firestore
+   * Standard or a SQLite-shaped backend that has no native geo index),
+   * the method is not installed even though `base.geoSearch` exists.
+   * This preserves the "declared capability ⇒ method exists" invariant
+   * in both directions.
+   *
+   * Like the other extensions, geo search runs against the base backend
+   * only — a routed child's own `geoSearch` is reached through
+   * `.subgraph().geoSearch()` against the routed handle.
+   */
+  geoSearch;
   // --- Pass-through reads ---
   getDoc(docId) {
     return this.base.getDoc(docId);
@@ -104,8 +312,8 @@ var RoutingStorageBackend = class _RoutingStorageBackend {
     return this.base.query(filters, options);
   }
   // --- Pass-through writes ---
-  setDoc(docId, record) {
-    return this.base.setDoc(docId, record);
+  setDoc(docId, record, mode) {
+    return this.base.setDoc(docId, record, mode);
   }
   updateDoc(docId, update) {
     return this.base.updateDoc(docId, update);
@@ -132,10 +340,22 @@ var RoutingStorageBackend = class _RoutingStorageBackend {
       storageScope: childStorageScope
     });
     if (routed) {
-      return new _RoutingStorageBackend(routed, this.options, childStorageScope, childScopePath);
+      return new _RoutingStorageBackend(
+        routed,
+        this.options,
+        childStorageScope,
+        childScopePath,
+        routed.capabilities
+      );
     }
     const childBase = this.base.subgraph(parentNodeUid, name);
-    return new _RoutingStorageBackend(childBase, this.options, childStorageScope, childScopePath);
+    return new _RoutingStorageBackend(
+      childBase,
+      this.options,
+      childStorageScope,
+      childScopePath,
+      childBase.capabilities
+    );
   }
   // --- Bulk operations: delegate, but cascade is base-scope only ---
   removeNodeCascade(uid, reader, options) {
@@ -161,6 +381,139 @@ function createRoutingBackend(base, options) {
   return new RoutingStorageBackend(base, options, "", base.scopePath);
 }
 
+// src/internal/serialization-tag.ts
+var SERIALIZATION_TAG = "__firegraph_ser__";
+var KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+
+// src/internal/write-plan.ts
+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 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/scope-path.ts
 function parseStorageScope(scope) {
   if (scope === "") return [];
@@ -212,10 +565,17 @@ function appendStorageScope(parentScope, uid, name) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CapabilityNotSupportedError,
   CrossBackendTransactionError,
+  DELETE_FIELD,
   appendStorageScope,
+  createCapabilities,
   createRoutingBackend,
+  deleteField,
+  flattenPatch,
+  intersectCapabilities,
   isAncestorScopeUid,
+  isDeleteSentinel,
   parseStorageScope,
   resolveAncestorScope
 });