@typicalday/firegraph 0.13.0 → 0.14.0

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

@@ -472,10 +472,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) {
@@ -669,8 +672,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 +686,7 @@ var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
   capabilities;
   collectionPath;
   scopePath;
+  queryMode;
   adapter;
   pipelineAdapter;
   // --- Reads ---
@@ -944,11 +948,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) {