@typicalday/firegraph 0.13.0 → 0.14.1

package/dist/firestore-enterprise/index.d.cts

@@ -92,10 +92,15 @@ interface FirestoreEnterpriseOptions {
      * (search, aggregate, etc., once implemented) always use pipelines
      * regardless of this option.
      *
-     * The emulator does not execute pipeline queries, so this option is
-     * forced to `'classic'` whenever `FIRESTORE_EMULATOR_HOST` is set, with
-     * a one-time `console.warn` if the caller explicitly asked for pipeline
-     * mode.
+     * The legacy / standard-edition Firestore emulator does not execute
+     * pipeline queries, so this option is coerced to `'classic'` whenever
+     * `FIRESTORE_EMULATOR_HOST` is set AND the caller has NOT opted into
+     * the enterprise-edition emulator via `FIRESTORE_EMULATOR_EDITION=enterprise`
+     * (case-insensitive). When that env var is set, the requested mode is
+     * honored end-to-end — pipelines work in firebase-tools v15.14+ with
+     * `--database-edition enterprise`. A one-time `console.warn` fires when
+     * the emulator forces the fallback after the caller explicitly asked for
+     * pipeline mode.
      */
     defaultQueryMode?: FirestoreEnterpriseQueryMode;
     /**
@@ -127,15 +132,40 @@ interface FirestoreEnterpriseOptions {
     /** Internal: the logical scope path inherited from a parent subgraph. */
     scopePath?: string;
 }
+/**
+ * The runtime shape returned from `createFirestoreEnterpriseBackend`.
+ *
+ * Extends `StorageBackend<FirestoreEnterpriseCapability>` with the
+ * `queryMode` field. The field always reflects the *effective* mode after
+ * emulator coercion, not the mode the caller requested. The public
+ * `GraphClient` surface does not expose the backend, so to introspect
+ * `queryMode` keep a reference to the backend before passing it to
+ * `createGraphClient`:
+ *
+ * ```ts
+ * const backend = createFirestoreEnterpriseBackend(db, 'firegraph', { defaultQueryMode: 'pipeline' });
+ * console.log(backend.queryMode);
+ * const client = createGraphClient(backend);
+ * ```
+ */
+interface FirestoreEnterpriseBackend extends StorageBackend<FirestoreEnterpriseCapability> {
+    readonly queryMode: FirestoreEnterpriseQueryMode;
+}
 /**
  * Create a Firestore Enterprise-edition `StorageBackend`.
  *
- * Pipeline mode is the default. When `FIRESTORE_EMULATOR_HOST` is set the
- * effective mode is forced to `'classic'` because the emulator does not
- * execute pipelines; if the caller explicitly asked for pipeline mode in
- * that environment, a one-time `console.warn` surfaces the override so
- * the deployment mismatch is visible without breaking the test run.
+ * Pipeline mode is the default. The legacy / standard-edition Firestore
+ * emulator does not execute pipelines, so the effective mode is coerced
+ * to `'classic'` whenever `FIRESTORE_EMULATOR_HOST` is set AND the caller
+ * has NOT opted into the enterprise-edition emulator via
+ * `FIRESTORE_EMULATOR_EDITION=enterprise` (case-insensitive). The opt-in
+ * env var mirrors firebase-tools v15.14+'s `--database-edition enterprise`
+ * (and `firestore.edition` in `firebase.json`); when set, pipelines work
+ * end-to-end against the local emulator without patching firegraph. If
+ * the caller explicitly asked for pipeline mode in a non-enterprise
+ * emulator, a one-time `console.warn` surfaces the override so the
+ * deployment mismatch is visible without breaking the test run.
  */
-declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): StorageBackend<FirestoreEnterpriseCapability>;
+declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): FirestoreEnterpriseBackend;
 
-export { type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };
+export { type FirestoreEnterpriseBackend, type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };

package/dist/firestore-enterprise/index.d.ts

@@ -92,10 +92,15 @@ interface FirestoreEnterpriseOptions {
      * (search, aggregate, etc., once implemented) always use pipelines
      * regardless of this option.
      *
-     * The emulator does not execute pipeline queries, so this option is
-     * forced to `'classic'` whenever `FIRESTORE_EMULATOR_HOST` is set, with
-     * a one-time `console.warn` if the caller explicitly asked for pipeline
-     * mode.
+     * The legacy / standard-edition Firestore emulator does not execute
+     * pipeline queries, so this option is coerced to `'classic'` whenever
+     * `FIRESTORE_EMULATOR_HOST` is set AND the caller has NOT opted into
+     * the enterprise-edition emulator via `FIRESTORE_EMULATOR_EDITION=enterprise`
+     * (case-insensitive). When that env var is set, the requested mode is
+     * honored end-to-end — pipelines work in firebase-tools v15.14+ with
+     * `--database-edition enterprise`. A one-time `console.warn` fires when
+     * the emulator forces the fallback after the caller explicitly asked for
+     * pipeline mode.
      */
     defaultQueryMode?: FirestoreEnterpriseQueryMode;
     /**
@@ -127,15 +132,40 @@ interface FirestoreEnterpriseOptions {
     /** Internal: the logical scope path inherited from a parent subgraph. */
     scopePath?: string;
 }
+/**
+ * The runtime shape returned from `createFirestoreEnterpriseBackend`.
+ *
+ * Extends `StorageBackend<FirestoreEnterpriseCapability>` with the
+ * `queryMode` field. The field always reflects the *effective* mode after
+ * emulator coercion, not the mode the caller requested. The public
+ * `GraphClient` surface does not expose the backend, so to introspect
+ * `queryMode` keep a reference to the backend before passing it to
+ * `createGraphClient`:
+ *
+ * ```ts
+ * const backend = createFirestoreEnterpriseBackend(db, 'firegraph', { defaultQueryMode: 'pipeline' });
+ * console.log(backend.queryMode);
+ * const client = createGraphClient(backend);
+ * ```
+ */
+interface FirestoreEnterpriseBackend extends StorageBackend<FirestoreEnterpriseCapability> {
+    readonly queryMode: FirestoreEnterpriseQueryMode;
+}
 /**
  * Create a Firestore Enterprise-edition `StorageBackend`.
  *
- * Pipeline mode is the default. When `FIRESTORE_EMULATOR_HOST` is set the
- * effective mode is forced to `'classic'` because the emulator does not
- * execute pipelines; if the caller explicitly asked for pipeline mode in
- * that environment, a one-time `console.warn` surfaces the override so
- * the deployment mismatch is visible without breaking the test run.
+ * Pipeline mode is the default. The legacy / standard-edition Firestore
+ * emulator does not execute pipelines, so the effective mode is coerced
+ * to `'classic'` whenever `FIRESTORE_EMULATOR_HOST` is set AND the caller
+ * has NOT opted into the enterprise-edition emulator via
+ * `FIRESTORE_EMULATOR_EDITION=enterprise` (case-insensitive). The opt-in
+ * env var mirrors firebase-tools v15.14+'s `--database-edition enterprise`
+ * (and `firestore.edition` in `firebase.json`); when set, pipelines work
+ * end-to-end against the local emulator without patching firegraph. If
+ * the caller explicitly asked for pipeline mode in a non-enterprise
+ * emulator, a one-time `console.warn` surfaces the override so the
+ * deployment mismatch is visible without breaking the test run.
  */
-declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): StorageBackend<FirestoreEnterpriseCapability>;
+declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): FirestoreEnterpriseBackend;
 
-export { type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };
+export { type FirestoreEnterpriseBackend, type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };

package/dist/firestore-enterprise/index.js

@@ -2,6 +2,7 @@ import {
   compileEngineTraversal
 } from "../chunk-D4J7Z4FE.js";
 import {
+  buildFirestoreUpdateArgs,
   bulkRemoveEdges,
   createBatchAdapter,
   createFirestoreAdapter,
@@ -11,10 +12,8 @@ import {
   runFirestoreClassicExpand,
   runFirestoreFindEdgesProjected,
   runFirestoreFindNearest
-} from "../chunk-PAD7WFFU.js";
-import {
-  deserializeFirestoreTypes
-} from "../chunk-C2QMD7RY.js";
+} from "../chunk-DJI3VXXA.js";
+import "../chunk-C2QMD7RY.js";
 import {
   createCapabilities
 } from "../chunk-N5HFDWQX.js";
@@ -27,13 +26,11 @@ import {
   createMergedRegistry,
   createRegistry,
   generateId
-} from "../chunk-WRTFC5NG.js";
+} from "../chunk-3AHHXMWX.js";
 import {
   FiregraphError,
-  assertSafePath,
-  assertUpdatePayloadExclusive,
   flattenPatch
-} from "../chunk-TK64DNVK.js";
+} from "../chunk-SIHE4UY4.js";
 import "../chunk-EQJUUVFG.js";
 
 // src/firestore-enterprise/backend.ts
@@ -50,6 +47,13 @@ async function getFirestoreSurface() {
   }
   return { P: _Pipelines, Ts: _Timestamp };
 }
+var UNESCAPED_FIELD_NAME_RE = /^[_A-Za-z][_A-Za-z0-9]*$/;
+function buildDataPathAlias(segments) {
+  const encoded = segments.map(
+    (seg) => UNESCAPED_FIELD_NAME_RE.test(seg) ? seg : "`" + seg.replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`"
+  );
+  return ["data", ...encoded].join(".");
+}
 function buildFilterExpression(P, filter) {
   const { field: fieldName, op, value } = filter;
   switch (op) {
@@ -127,7 +131,7 @@ async function runFirestorePipelineUpdate(db, collectionPath, filters, patch, _o
   }
   const { P, Ts } = await getFirestoreSurface();
   const transforms = ops.map((op) => {
-    const alias = `data.${op.path.join(".")}`;
+    const alias = buildDataPathAlias(op.path);
     return P.constant(op.value).as(alias);
   });
   transforms.push(P.constant(Ts.now()).as("updatedAt"));
@@ -472,10 +476,13 @@ function decodeTree(rootRows, hops) {
 }
 async function runFirestoreEngineTraversal(db, collectionPath, params) {
   if (process.env.FIRESTORE_EMULATOR_HOST) {
-    throw new FiregraphError(
-      "engine traversal requires Pipelines \u2014 not supported on the Firestore emulator",
-      "UNSUPPORTED_OPERATION"
-    );
+    const emulatorEdition = (process.env.FIRESTORE_EMULATOR_EDITION ?? "").trim().toLowerCase();
+    if (emulatorEdition !== "enterprise") {
+      throw new FiregraphError(
+        "engine traversal requires Pipelines \u2014 not supported on the default Firestore emulator. Run firebase-tools v15.14+ with `--database-edition enterprise` and set `FIRESTORE_EMULATOR_EDITION=enterprise` to opt in.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
   }
   const compiled = compileEngineTraversal(params);
   if (!compiled.eligible) {
@@ -582,28 +589,6 @@ var ENTERPRISE_BASE_CAPS = /* @__PURE__ */ new Set([
 var _emulatorFallbackWarned = false;
 var _classicInProductionWarned = false;
 var _previewDmlWarned = false;
-function dottedDataPath(op) {
-  assertSafePath(op.path);
-  return `data.${op.path.join(".")}`;
-}
-function buildFirestoreUpdate(update, db) {
-  assertUpdatePayloadExclusive(update);
-  const out = {
-    updatedAt: FieldValue.serverTimestamp()
-  };
-  if (update.replaceData) {
-    out.data = deserializeFirestoreTypes(update.replaceData, db);
-  } else if (update.dataOps) {
-    for (const op of update.dataOps) {
-      const key = dottedDataPath(op);
-      out[key] = op.delete ? FieldValue.delete() : op.value;
-    }
-  }
-  if (update.v !== void 0) {
-    out.v = update.v;
-  }
-  return out;
-}
 function stampWritableRecord(record) {
   const now = FieldValue.serverTimestamp();
   const out = {
@@ -638,7 +623,7 @@ var FirestoreEnterpriseTransactionBackend = class {
     );
   }
   async updateDoc(docId, update) {
-    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+    this.adapter.updateDoc(docId, buildFirestoreUpdateArgs(update, this.db));
   }
   async deleteDoc(docId) {
     this.adapter.deleteDoc(docId);
@@ -657,7 +642,7 @@ var FirestoreEnterpriseBatchBackend = class {
     );
   }
   updateDoc(docId, update) {
-    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+    this.adapter.updateDoc(docId, buildFirestoreUpdateArgs(update, this.db));
   }
   deleteDoc(docId) {
     this.adapter.deleteDoc(docId);
@@ -669,8 +654,8 @@ var FirestoreEnterpriseBatchBackend = class {
 var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
   constructor(db, collectionPath, queryMode, scopePath, previewDml) {
     this.db = db;
-    this.queryMode = queryMode;
     this.previewDml = previewDml;
+    this.queryMode = queryMode;
     this.collectionPath = collectionPath;
     this.scopePath = scopePath;
     this.adapter = createFirestoreAdapter(db, collectionPath);
@@ -683,6 +668,7 @@ var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
   capabilities;
   collectionPath;
   scopePath;
+  queryMode;
   adapter;
   pipelineAdapter;
   // --- Reads ---
@@ -704,7 +690,7 @@ var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
     );
   }
   updateDoc(docId, update) {
-    return this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+    return this.adapter.updateDoc(docId, buildFirestoreUpdateArgs(update, this.db));
   }
   deleteDoc(docId) {
     return this.adapter.deleteDoc(docId);
@@ -944,11 +930,14 @@ var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
 function createFirestoreEnterpriseBackend(db, collectionPath, options = {}) {
   const requestedMode = options.defaultQueryMode ?? "pipeline";
   const isEmulator = !!process.env.FIRESTORE_EMULATOR_HOST;
-  const effectiveMode = isEmulator && requestedMode === "pipeline" ? "classic" : requestedMode;
-  if (isEmulator && requestedMode === "pipeline" && effectiveMode === "classic" && !_emulatorFallbackWarned) {
+  const emulatorEdition = (process.env.FIRESTORE_EMULATOR_EDITION ?? "").trim().toLowerCase();
+  const emulatorIsEnterprise = emulatorEdition === "enterprise";
+  const emulatorForcesClassic = isEmulator && !emulatorIsEnterprise;
+  const effectiveMode = emulatorForcesClassic && requestedMode === "pipeline" ? "classic" : requestedMode;
+  if (emulatorForcesClassic && requestedMode === "pipeline" && effectiveMode === "classic" && !_emulatorFallbackWarned) {
     _emulatorFallbackWarned = true;
     console.warn(
-      "[firegraph] Firestore Enterprise pipeline mode is unavailable in the emulator; falling back to classic Query API for this run. Set `defaultQueryMode: 'classic'` to silence this warning."
+      "[firegraph] Firestore Enterprise pipeline mode is unavailable in the default emulator; falling back to classic Query API for this run. If you are running firebase-tools v15.14+ with the enterprise-edition emulator (`firebase emulators:start --database-edition enterprise`), set `FIRESTORE_EMULATOR_EDITION=enterprise` in your environment to honor pipeline mode. Otherwise set `defaultQueryMode: 'classic'` to silence this warning."
     );
   }
   if (!isEmulator && requestedMode === "classic" && !_classicInProductionWarned) {