@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/firestore-enterprise/index.js

@@ -0,0 +1,985 @@
+import {
+  compileEngineTraversal
+} from "../chunk-D4J7Z4FE.js";
+import {
+  bulkRemoveEdges,
+  createBatchAdapter,
+  createFirestoreAdapter,
+  createTransactionAdapter,
+  removeNodeCascade,
+  runFirestoreAggregate,
+  runFirestoreClassicExpand,
+  runFirestoreFindEdgesProjected,
+  runFirestoreFindNearest
+} from "../chunk-PAD7WFFU.js";
+import {
+  deserializeFirestoreTypes
+} from "../chunk-C2QMD7RY.js";
+import {
+  createCapabilities
+} from "../chunk-N5HFDWQX.js";
+import {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
+  NODE_RELATION,
+  buildEdgeQueryPlan,
+  createGraphClient,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+} from "../chunk-WRTFC5NG.js";
+import {
+  FiregraphError,
+  assertSafePath,
+  assertUpdatePayloadExclusive,
+  flattenPatch
+} from "../chunk-TK64DNVK.js";
+import "../chunk-EQJUUVFG.js";
+
+// src/firestore-enterprise/backend.ts
+import { FieldValue } from "@google-cloud/firestore";
+
+// src/internal/firestore-bulk-dml.ts
+var _Pipelines = null;
+var _Timestamp = null;
+async function getFirestoreSurface() {
+  if (!_Pipelines || !_Timestamp) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines = mod.Pipelines;
+    _Timestamp = mod.Timestamp;
+  }
+  return { P: _Pipelines, Ts: _Timestamp };
+}
+function buildFilterExpression(P, filter) {
+  const { field: fieldName, op, value } = filter;
+  switch (op) {
+    case "==":
+      return P.equal(fieldName, value);
+    case "!=":
+      return P.notEqual(fieldName, value);
+    case "<":
+      return P.lessThan(fieldName, value);
+    case "<=":
+      return P.lessThanOrEqual(fieldName, value);
+    case ">":
+      return P.greaterThan(fieldName, value);
+    case ">=":
+      return P.greaterThanOrEqual(fieldName, value);
+    case "in":
+      return P.equalAny(fieldName, value);
+    case "not-in":
+      return P.notEqualAny(fieldName, value);
+    case "array-contains":
+      return P.arrayContains(fieldName, value);
+    case "array-contains-any":
+      return P.arrayContainsAny(fieldName, value);
+    default:
+      throw new FiregraphError(
+        `bulkDelete/bulkUpdate: unsupported filter op "${op}" for pipeline DML.`,
+        "INVALID_QUERY"
+      );
+  }
+}
+function applyWhere(P, pipeline, filters) {
+  const exprs = filters.map((f) => buildFilterExpression(P, f));
+  if (exprs.length === 1) {
+    return pipeline.where(exprs[0]);
+  }
+  const [first, second, ...rest] = exprs;
+  return pipeline.where(P.and(first, second, ...rest));
+}
+function assertNonEmptyFilters(filters, op) {
+  if (filters.length === 0) {
+    throw new FiregraphError(
+      `bulk${op === "delete" ? "Delete" : "Update"}() on Firestore requires at least one filter; an empty filter list would target the whole collection. To wipe a subgraph, use removeNodeCascade() on the parent node instead.`,
+      "INVALID_QUERY"
+    );
+  }
+}
+async function runFirestorePipelineDelete(db, collectionPath, filters, _options) {
+  assertNonEmptyFilters(filters, "delete");
+  const { P } = await getFirestoreSurface();
+  let pipeline = db.pipeline().collection(collectionPath);
+  pipeline = applyWhere(P, pipeline, filters);
+  const snap = await pipeline.delete().execute();
+  return {
+    deleted: snap.results.length,
+    batches: 1,
+    errors: []
+  };
+}
+async function runFirestorePipelineUpdate(db, collectionPath, filters, patch, _options) {
+  assertNonEmptyFilters(filters, "update");
+  const ops = flattenPatch(patch.data);
+  if (ops.length === 0) {
+    throw new FiregraphError(
+      "bulkUpdate(): patch.data produced no field updates. An empty patch would only stamp updatedAt, which is almost certainly a bug.",
+      "INVALID_QUERY"
+    );
+  }
+  for (const op of ops) {
+    if (op.delete) {
+      throw new FiregraphError(
+        `bulkUpdate(): preview Pipeline DML does not support deleteField() sentinels (no typed delete-transform on @google-cloud/firestore@8.5.0's Pipeline.update(AliasedExpression[])). Drop the delete from the patch or use replaceEdge/replaceNode for the affected rows.`,
+        "INVALID_QUERY"
+      );
+    }
+  }
+  const { P, Ts } = await getFirestoreSurface();
+  const transforms = ops.map((op) => {
+    const alias = `data.${op.path.join(".")}`;
+    return P.constant(op.value).as(alias);
+  });
+  transforms.push(P.constant(Ts.now()).as("updatedAt"));
+  let pipeline = db.pipeline().collection(collectionPath);
+  pipeline = applyWhere(P, pipeline, filters);
+  const snap = await pipeline.update(transforms).execute();
+  return {
+    deleted: snap.results.length,
+    batches: 1,
+    errors: []
+  };
+}
+
+// src/internal/firestore-expand.ts
+var _Pipelines2 = null;
+async function getPipelines() {
+  if (!_Pipelines2) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines2 = mod.Pipelines;
+  }
+  return _Pipelines2;
+}
+async function runFirestorePipelineExpand(db, collectionPath, params) {
+  if (params.sources.length === 0) {
+    return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+  }
+  if (params.axbType.length === 0) {
+    throw new FiregraphError("expand(): axbType must be a non-empty string.", "INVALID_QUERY");
+  }
+  const direction = params.direction ?? "forward";
+  const sourceField = direction === "forward" ? "aUid" : "bUid";
+  const P = await getPipelines();
+  const exprs = [
+    P.equal("axbType", params.axbType),
+    P.equalAny(sourceField, params.sources)
+  ];
+  if (params.aType !== void 0) exprs.push(P.equal("aType", params.aType));
+  if (params.bType !== void 0) exprs.push(P.equal("bType", params.bType));
+  let pipeline = db.pipeline().collection(collectionPath);
+  if (exprs.length === 1) {
+    pipeline = pipeline.where(exprs[0]);
+  } else {
+    const [first, second, ...rest] = exprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  if (params.orderBy) {
+    const f = P.field(params.orderBy.field);
+    const ordering = params.orderBy.direction === "desc" ? f.descending() : f.ascending();
+    pipeline = pipeline.sort(ordering);
+  }
+  const totalLimit = params.limitPerSource !== void 0 ? params.sources.length * params.limitPerSource : void 0;
+  if (totalLimit !== void 0) {
+    pipeline = pipeline.limit(totalLimit);
+  }
+  const snap = await pipeline.execute();
+  let edges = snap.results.map((r) => r.data());
+  if (params.axbType === NODE_RELATION) {
+    edges = edges.filter((e) => e.aUid !== e.bUid);
+  }
+  if (!params.hydrate) return { edges };
+  const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+  const uniqueTargets = [...new Set(targetUids)];
+  if (uniqueTargets.length === 0) {
+    return { edges, targets: [] };
+  }
+  const hydratePipeline = db.pipeline().collection(collectionPath).where(
+    P.and(P.equal("axbType", NODE_RELATION), P.equalAny("aUid", uniqueTargets))
+  );
+  const hydrateSnap = await hydratePipeline.execute();
+  const byUid = /* @__PURE__ */ new Map();
+  for (const r of hydrateSnap.results) {
+    const row = r.data();
+    byUid.set(row.bUid, row);
+  }
+  const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+  return { edges, targets };
+}
+
+// src/internal/firestore-fulltext.ts
+var ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeFullTextFieldPath(field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `fullTextSearch(): field '${field}' is a built-in envelope field \u2014 text-indexed fields must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+var _Pipelines3 = null;
+async function getPipelines2() {
+  if (!_Pipelines3) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines3 = mod.Pipelines;
+  }
+  return _Pipelines3;
+}
+async function runFirestoreFullTextSearch(db, collectionPath, params) {
+  if (typeof params.query !== "string" || params.query.length === 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): query must be a non-empty string.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0) {
+    throw new FiregraphError(
+      `fullTextSearch(): limit must be a positive integer (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const normalizedFields = params.fields?.map((f) => normalizeFullTextFieldPath(f));
+  const P = await getPipelines2();
+  if (normalizedFields !== void 0 && normalizedFields.length > 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): the `fields` option is not yet supported \u2014 per-field text predicates are not available in @google-cloud/firestore@8.5.0. Omit `fields` to search all indexed fields.",
+      "INVALID_QUERY"
+    );
+  }
+  const searchQuery = P.documentMatches(params.query);
+  let pipeline = db.pipeline().collection(collectionPath).search({
+    query: searchQuery,
+    sort: P.score().descending()
+  });
+  const whereExprs = [];
+  if (params.aType) whereExprs.push(P.equal("aType", params.aType));
+  if (params.axbType) whereExprs.push(P.equal("axbType", params.axbType));
+  if (params.bType) whereExprs.push(P.equal("bType", params.bType));
+  if (whereExprs.length === 1) {
+    pipeline = pipeline.where(whereExprs[0]);
+  } else if (whereExprs.length > 1) {
+    const [first, second, ...rest] = whereExprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  pipeline = pipeline.limit(params.limit);
+  const snap = await pipeline.execute();
+  return snap.results.map((r) => r.data());
+}
+
+// src/internal/firestore-geo.ts
+import { GeoPoint } from "@google-cloud/firestore";
+var ENVELOPE_FIELDS2 = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeGeoFieldPath(field) {
+  if (ENVELOPE_FIELDS2.has(field)) {
+    throw new FiregraphError(
+      `geoSearch(): geoField '${field}' is a built-in envelope field \u2014 geo-indexed fields must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function assertValidGeoPoint(lat, lng) {
+  if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+    throw new FiregraphError(
+      `geoSearch(): point.lat must be in [-90, 90] (got ${lat}).`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isFinite(lng) || lng < -180 || lng > 180) {
+    throw new FiregraphError(
+      `geoSearch(): point.lng must be in [-180, 180] (got ${lng}).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+var _Pipelines4 = null;
+async function getPipelines3() {
+  if (!_Pipelines4) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines4 = mod.Pipelines;
+  }
+  return _Pipelines4;
+}
+async function runFirestoreGeoSearch(db, collectionPath, params) {
+  if (!Number.isFinite(params.radiusMeters) || params.radiusMeters <= 0) {
+    throw new FiregraphError(
+      `geoSearch(): radiusMeters must be a positive finite number (got ${params.radiusMeters}).`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0) {
+    throw new FiregraphError(
+      `geoSearch(): limit must be a positive integer (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  assertValidGeoPoint(params.point.lat, params.point.lng);
+  const geoFieldPath = normalizeGeoFieldPath(params.geoField);
+  const center = new GeoPoint(params.point.lat, params.point.lng);
+  const P = await getPipelines3();
+  const distanceQuery = P.geoDistance(geoFieldPath, center).lessThanOrEqual(params.radiusMeters);
+  const orderByDistance = params.orderByDistance !== false;
+  const opts = {
+    query: distanceQuery
+  };
+  if (orderByDistance) {
+    opts.sort = P.geoDistance(geoFieldPath, center).ascending();
+  }
+  let pipeline = db.pipeline().collection(collectionPath).search(opts);
+  const whereExprs = [];
+  if (params.aType) whereExprs.push(P.equal("aType", params.aType));
+  if (params.axbType) whereExprs.push(P.equal("axbType", params.axbType));
+  if (params.bType) whereExprs.push(P.equal("bType", params.bType));
+  if (whereExprs.length === 1) {
+    pipeline = pipeline.where(whereExprs[0]);
+  } else if (whereExprs.length > 1) {
+    const [first, second, ...rest] = whereExprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  pipeline = pipeline.limit(params.limit);
+  const snap = await pipeline.execute();
+  return snap.results.map((r) => r.data());
+}
+
+// src/internal/firestore-traverse.ts
+function childArrayKey(depth) {
+  return `hop_${depth}_children`;
+}
+function joinVarName(depth) {
+  return `hop_${depth}_join`;
+}
+var _Pipelines5 = null;
+async function getPipelines4() {
+  if (!_Pipelines5) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines5 = mod.Pipelines;
+  }
+  return _Pipelines5;
+}
+function buildHopPredicates(P, hop, sourcePredicate) {
+  const exprs = [P.equal("axbType", hop.axbType), sourcePredicate];
+  if (hop.aType !== void 0) exprs.push(P.equal("aType", hop.aType));
+  if (hop.bType !== void 0) exprs.push(P.equal("bType", hop.bType));
+  const [first, second, ...rest] = exprs;
+  return P.and(first, second, ...rest);
+}
+function applyHopOrderingAndLimit(P, pipeline, hop, totalLimit) {
+  let p = pipeline;
+  if (hop.orderBy) {
+    const f = P.field(hop.orderBy.field);
+    const ordering = hop.orderBy.direction === "desc" ? f.descending() : f.ascending();
+    p = p.sort(ordering);
+  }
+  p = p.limit(totalLimit);
+  return p;
+}
+function buildSubPipeline(P, db, collectionPath, hops, depth) {
+  const hop = hops[depth];
+  const parentDepth = depth - 1;
+  const sourceField = hop.direction === "forward" ? "aUid" : "bUid";
+  const sourcePredicate = P.equal(
+    sourceField,
+    P.variable(joinVarName(parentDepth))
+  );
+  const where = buildHopPredicates(P, hop, sourcePredicate);
+  let pipeline = db.pipeline().collection(collectionPath).where(where);
+  pipeline = applyHopOrderingAndLimit(P, pipeline, hop, hop.limitPerSource);
+  if (depth + 1 < hops.length) {
+    const targetField = hop.direction === "forward" ? "bUid" : "aUid";
+    pipeline = pipeline.define(P.field(targetField).as(joinVarName(depth)));
+    const child = buildSubPipeline(P, db, collectionPath, hops, depth + 1);
+    pipeline = pipeline.addFields(child.toArrayExpression().as(childArrayKey(depth)));
+  }
+  return pipeline;
+}
+function buildRootPipeline(P, db, collectionPath, spec) {
+  const hop0 = spec.hops[0];
+  const sourceField = hop0.direction === "forward" ? "aUid" : "bUid";
+  const sourcePredicate = P.equalAny(
+    sourceField,
+    spec.sources
+  );
+  const where = buildHopPredicates(P, hop0, sourcePredicate);
+  let pipeline = db.pipeline().collection(collectionPath).where(where);
+  pipeline = applyHopOrderingAndLimit(P, pipeline, hop0, spec.sources.length * hop0.limitPerSource);
+  if (spec.hops.length > 1) {
+    const targetField = hop0.direction === "forward" ? "bUid" : "aUid";
+    pipeline = pipeline.define(P.field(targetField).as(joinVarName(0)));
+    const child = buildSubPipeline(P, db, collectionPath, spec.hops, 1);
+    pipeline = pipeline.addFields(child.toArrayExpression().as(childArrayKey(0)));
+  }
+  return pipeline;
+}
+function stripScaffolding(row, depth) {
+  const stripped = { ...row };
+  delete stripped[childArrayKey(depth)];
+  delete stripped[joinVarName(depth)];
+  return stripped;
+}
+function decodeTree(rootRows, hops) {
+  const out = [];
+  let frontier = rootRows;
+  for (let depth = 0; depth < hops.length; depth++) {
+    const hop = hops[depth];
+    const targetField = hop.direction === "forward" ? "bUid" : "aUid";
+    const seen = /* @__PURE__ */ new Set();
+    const edges = [];
+    const nextFrontier = [];
+    for (const row of frontier) {
+      const childKey = childArrayKey(depth);
+      const children = row[childKey];
+      if (Array.isArray(children)) {
+        for (const child of children) {
+          if (child && typeof child === "object") {
+            nextFrontier.push(child);
+          }
+        }
+      }
+      const stripped = stripScaffolding(row, depth);
+      if (hop.axbType === NODE_RELATION && stripped.aUid === stripped.bUid) continue;
+      const dedupKey = stripped[targetField];
+      if (typeof dedupKey !== "string" || seen.has(dedupKey)) continue;
+      seen.add(dedupKey);
+      edges.push(stripped);
+    }
+    out.push({ edges, sourceCount: depth === 0 ? -1 : out[depth - 1].edges.length });
+    frontier = nextFrontier;
+  }
+  return {
+    hops: out,
+    totalReads: 1
+  };
+}
+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 compiled = compileEngineTraversal(params);
+  if (!compiled.eligible) {
+    throw new FiregraphError(
+      `engine traversal not eligible: ${compiled.reason}`,
+      "UNSUPPORTED_OPERATION"
+    );
+  }
+  const spec = compiled.normalized;
+  if (spec.sources.length === 0) {
+    return {
+      hops: spec.hops.map(() => ({ edges: [], sourceCount: 0 })),
+      totalReads: 0
+    };
+  }
+  const P = await getPipelines4();
+  const pipeline = buildRootPipeline(P, db, collectionPath, spec);
+  const snap = await pipeline.execute();
+  const rows = snap.results.map((r) => r.data());
+  const result = decodeTree(rows, spec.hops);
+  if (result.hops.length > 0) {
+    result.hops[0] = { ...result.hops[0], sourceCount: spec.sources.length };
+  }
+  return result;
+}
+
+// src/firestore-enterprise/pipeline-adapter.ts
+var _Pipelines6 = null;
+async function getPipelines5() {
+  if (!_Pipelines6) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines6 = mod.Pipelines;
+  }
+  return _Pipelines6;
+}
+function buildFilterExpression2(P, filter) {
+  const { field: fieldName, op, value } = filter;
+  switch (op) {
+    case "==":
+      return P.equal(fieldName, value);
+    case "!=":
+      return P.notEqual(fieldName, value);
+    case "<":
+      return P.lessThan(fieldName, value);
+    case "<=":
+      return P.lessThanOrEqual(fieldName, value);
+    case ">":
+      return P.greaterThan(fieldName, value);
+    case ">=":
+      return P.greaterThanOrEqual(fieldName, value);
+    case "in":
+      return P.equalAny(fieldName, value);
+    case "not-in":
+      return P.notEqualAny(fieldName, value);
+    case "array-contains":
+      return P.arrayContains(fieldName, value);
+    case "array-contains-any":
+      return P.arrayContainsAny(fieldName, value);
+    default:
+      throw new Error(`Unsupported filter op for pipeline mode: ${op}`);
+  }
+}
+function createPipelineQueryAdapter(db, collectionPath) {
+  return {
+    async query(filters, options) {
+      const P = await getPipelines5();
+      let pipeline = db.pipeline().collection(collectionPath);
+      if (filters.length === 1) {
+        pipeline = pipeline.where(buildFilterExpression2(P, filters[0]));
+      } else if (filters.length > 1) {
+        const [first, second, ...rest] = filters.map((f) => buildFilterExpression2(P, f));
+        pipeline = pipeline.where(P.and(first, second, ...rest));
+      }
+      if (options?.orderBy) {
+        const f = P.field(options.orderBy.field);
+        const ordering = options.orderBy.direction === "desc" ? f.descending() : f.ascending();
+        pipeline = pipeline.sort(ordering);
+      }
+      if (options?.limit !== void 0) {
+        pipeline = pipeline.limit(options.limit);
+      }
+      const snap = await pipeline.execute();
+      return snap.results.map((r) => r.data());
+    }
+  };
+}
+
+// src/firestore-enterprise/backend.ts
+var ENTERPRISE_BASE_CAPS = /* @__PURE__ */ new Set([
+  "core.read",
+  "core.write",
+  "core.transactions",
+  "core.batch",
+  "core.subgraph",
+  "query.aggregate",
+  "query.select",
+  "query.join",
+  "traversal.serverSide",
+  "search.vector",
+  "search.fullText",
+  "search.geo",
+  "raw.firestore"
+]);
+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 = {
+    aType: record.aType,
+    aUid: record.aUid,
+    axbType: record.axbType,
+    bType: record.bType,
+    bUid: record.bUid,
+    data: record.data,
+    createdAt: now,
+    updatedAt: now
+  };
+  if (record.v !== void 0) out.v = record.v;
+  return out;
+}
+var FirestoreEnterpriseTransactionBackend = class {
+  constructor(adapter, db) {
+    this.adapter = adapter;
+    this.db = db;
+  }
+  getDoc(docId) {
+    return this.adapter.getDoc(docId);
+  }
+  query(filters, options) {
+    return this.adapter.query(filters, options);
+  }
+  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));
+  }
+  async deleteDoc(docId) {
+    this.adapter.deleteDoc(docId);
+  }
+};
+var FirestoreEnterpriseBatchBackend = class {
+  constructor(adapter, db) {
+    this.adapter = adapter;
+    this.db = db;
+  }
+  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));
+  }
+  deleteDoc(docId) {
+    this.adapter.deleteDoc(docId);
+  }
+  commit() {
+    return this.adapter.commit();
+  }
+};
+var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
+  constructor(db, collectionPath, queryMode, scopePath, previewDml) {
+    this.db = db;
+    this.queryMode = queryMode;
+    this.previewDml = previewDml;
+    this.collectionPath = collectionPath;
+    this.scopePath = scopePath;
+    this.adapter = createFirestoreAdapter(db, collectionPath);
+    if (queryMode === "pipeline") {
+      this.pipelineAdapter = createPipelineQueryAdapter(db, collectionPath);
+    }
+    const caps = previewDml ? /* @__PURE__ */ new Set([...ENTERPRISE_BASE_CAPS, "query.dml"]) : ENTERPRISE_BASE_CAPS;
+    this.capabilities = createCapabilities(caps);
+  }
+  capabilities;
+  collectionPath;
+  scopePath;
+  adapter;
+  pipelineAdapter;
+  // --- Reads ---
+  getDoc(docId) {
+    return this.adapter.getDoc(docId);
+  }
+  query(filters, options) {
+    if (this.pipelineAdapter) {
+      return this.pipelineAdapter.query(filters, options);
+    }
+    return this.adapter.query(filters, options);
+  }
+  // --- Writes ---
+  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));
+  }
+  deleteDoc(docId) {
+    return this.adapter.deleteDoc(docId);
+  }
+  // --- Transactions / Batches ---
+  runTransaction(fn) {
+    return this.db.runTransaction(async (firestoreTx) => {
+      const txAdapter = createTransactionAdapter(this.db, this.collectionPath, firestoreTx);
+      return fn(new FirestoreEnterpriseTransactionBackend(txAdapter, this.db));
+    });
+  }
+  createBatch() {
+    const batchAdapter = createBatchAdapter(this.db, this.collectionPath);
+    return new FirestoreEnterpriseBatchBackend(batchAdapter, this.db);
+  }
+  // --- Subgraphs ---
+  subgraph(parentNodeUid, name) {
+    const subPath = `${this.collectionPath}/${parentNodeUid}/${name}`;
+    const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _FirestoreEnterpriseBackendImpl(
+      this.db,
+      subPath,
+      this.queryMode,
+      newScope,
+      this.previewDml
+    );
+  }
+  // --- Cascade & bulk ---
+  removeNodeCascade(uid, reader, options) {
+    return removeNodeCascade(this.db, this.collectionPath, reader, uid, options);
+  }
+  bulkRemoveEdges(params, reader, options) {
+    return bulkRemoveEdges(this.db, this.collectionPath, reader, params, options);
+  }
+  // --- Cross-collection ---
+  async findEdgesGlobal(params, collectionName) {
+    const name = collectionName ?? this.collectionPath.split("/").pop();
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "findEdgesGlobal() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    const collectionGroupRef = this.db.collectionGroup(name);
+    let q = collectionGroupRef;
+    for (const f of plan.filters) {
+      q = q.where(f.field, f.op, f.value);
+    }
+    if (plan.options?.orderBy) {
+      q = q.orderBy(plan.options.orderBy.field, plan.options.orderBy.direction ?? "asc");
+    }
+    if (plan.options?.limit !== void 0) {
+      q = q.limit(plan.options.limit);
+    }
+    const snap = await q.get();
+    return snap.docs.map((doc) => doc.data());
+  }
+  // --- Aggregate ---
+  /**
+   * Aggregate via the classic `Query.aggregate()` API. Supports count/sum/avg
+   * — min/max throws `UNSUPPORTED_AGGREGATE`. The Pipelines `aggregate()`
+   * stage could in principle add min/max on Enterprise, but that is deferred
+   * to a future phase; both editions currently route through the same
+   * classic-API helper so capability semantics stay symmetric.
+   */
+  aggregate(spec, filters) {
+    return runFirestoreAggregate(this.db.collection(this.collectionPath), spec, filters, {
+      edition: "enterprise"
+    });
+  }
+  // --- Server-side projection (capability: query.select) ---
+  /**
+   * Run a projecting query via the shared classic-API helper. Enterprise and
+   * Standard delegate to the same implementation so the projection contract
+   * stays consistent.
+   *
+   * Why classic and not the pipeline `select()` stage: the byte-savings
+   * deliverable (the only reason `findEdgesProjected` exists) is achieved
+   * by either path; the classic API works on both editions today and
+   * sidesteps the pipeline-vs-emulator forking the rest of this backend has
+   * to manage. When pipeline `select()` becomes preferable for some other
+   * reason — e.g. composing with a future pipeline-only stage — swap the
+   * implementation behind `runFirestoreFindEdgesProjected`; callers and
+   * the capability declaration stay put.
+   */
+  findEdgesProjected(select, filters, options) {
+    return runFirestoreFindEdgesProjected(
+      this.db.collection(this.collectionPath),
+      select,
+      filters,
+      options
+    );
+  }
+  // --- Native vector / nearest-neighbour search (capability: search.vector) ---
+  /**
+   * Run a vector / nearest-neighbour query via the shared classic-API
+   * helper. Enterprise and Standard delegate to one implementation so the
+   * field-path normalisation, validation surface, and result shape stay
+   * consistent across editions.
+   *
+   * Why classic and not the pipeline `findNearest` stage: the deliverable
+   * (top-K by similarity) is achieved by either path; the classic API
+   * works identically on both editions today and sidesteps the
+   * pipeline-vs-emulator forking the rest of this backend has to manage.
+   * When pipeline `findNearest` becomes preferable for composing with
+   * other pipeline stages, swap the implementation behind
+   * `runFirestoreFindNearest`; callers and the capability declaration
+   * stay put.
+   *
+   * Index requirements are identical to Standard — single-field vector
+   * index on the indexed `vectorField`, plus a composite index whenever
+   * additional `where` filters narrow the candidate set.
+   */
+  findNearest(params) {
+    return runFirestoreFindNearest(this.db.collection(this.collectionPath), params);
+  }
+  // --- Native full-text search (capability: search.fullText) ---
+  /**
+   * Run a full-text search via Firestore Pipelines `search(...)` stage.
+   * Translates `documentMatches(query)` against the indexed search
+   * fields, sorts by relevance score (`score().descending()`), and
+   * applies identifying filters as a follow-up `where(...)` stage
+   * because `search` must be the first stage of a pipeline.
+   *
+   * Enterprise-only: full-text search is an Enterprise product feature.
+   * Standard does not declare `search.fullText` regardless of SDK
+   * surface, and the SQLite-shaped backends have no native FTS index.
+   *
+   * Index requirements: an FTS index on the indexed search fields
+   * (configured in Firestore's index config). Without the index the
+   * underlying `search` stage returns no rows; the firegraph layer
+   * cannot detect that case ahead of time.
+   */
+  fullTextSearch(params) {
+    return runFirestoreFullTextSearch(this.db, this.collectionPath, params);
+  }
+  // --- Native geospatial distance search (capability: search.geo) ---
+  /**
+   * Run a geospatial distance query via Firestore Pipelines
+   * `search(...)` stage. The same `geoDistance(geoField, point)`
+   * expression feeds the radius cap (`<= radiusMeters`) and the
+   * nearest-first sort (when `orderByDistance` is true / unset).
+   * Identifying filters apply as a follow-up `where(...)` stage.
+   *
+   * Enterprise-only: same Enterprise-product-feature gating as FTS.
+   *
+   * Index requirements: a geospatial index on the indexed `geoField`.
+   * Same caveat as FTS — unindexed geo searches return no rows
+   * server-side and the firegraph layer cannot pre-detect that.
+   */
+  geoSearch(params) {
+    return runFirestoreGeoSearch(this.db, this.collectionPath, params);
+  }
+  // --- Server-side multi-source fan-out (capability: query.join) ---
+  /**
+   * Fan out from `params.sources` over a single edge type in one server-
+   * side round trip when running in pipeline mode, or via a chunked
+   * classic-API fan-out when running in classic mode.
+   *
+   * Pipeline mode (default outside the emulator): one call to
+   * `db.pipeline().collection(path).where(equalAny(sourceField, sources))
+   * .execute()`. `equalAny` has no documented cap, so a 1k-source fan-
+   * out is one round trip.
+   *
+   * Classic mode (emulator, or `defaultQueryMode: 'classic'`): chunks
+   * `params.sources` into 30-element groups (the classic `'in'`
+   * operator's documented cap), dispatches one query per chunk in
+   * parallel, concats the results, and applies a cross-chunk re-sort +
+   * total-limit slice. Same observable contract, `ceil(N/30)` round
+   * trips. The chunked path is still a win over the per-source
+   * `findEdges` loop in `traverse.ts` — 100 sources go from 100 round
+   * trips to 4.
+   */
+  expand(params) {
+    if (this.queryMode === "pipeline") {
+      return runFirestorePipelineExpand(this.db, this.collectionPath, params);
+    }
+    return runFirestoreClassicExpand(this.adapter, params);
+  }
+  // --- Server-side DML (capability: query.dml, gated by previewDml) ---
+  /**
+   * Single-statement bulk DELETE via Pipeline `delete()` stage. Wired only
+   * when the backend was created with `previewDml: true`; otherwise the
+   * cap isn't declared and `client.bulkDelete()` throws
+   * `UNSUPPORTED_OPERATION` (or `bulk.ts` cascade falls back to
+   * `bulkRemoveEdges`).
+   *
+   * Empty filter lists are rejected at the helper boundary —
+   * see `runFirestorePipelineDelete`'s `assertNonEmptyFilters`.
+   *
+   * Subgraph isolation comes from `this.collectionPath`: the pipeline's
+   * `collection(path)` source IS the subgraph, so there's no separate
+   * `scope` predicate to enforce (unlike SQLite's leading-`scope`-`?`
+   * filter).
+   */
+  bulkDelete(filters, options) {
+    return runFirestorePipelineDelete(this.db, this.collectionPath, filters, options);
+  }
+  /**
+   * Single-statement bulk UPDATE via Pipeline
+   * `update(transformedFields)` stage. Same gating and scoping as
+   * `bulkDelete` above. The patch is flattened into one
+   * `AliasedExpression` per terminal leaf via the shared `flattenPatch`
+   * pipeline; `deleteField()` sentinels are rejected at the helper
+   * boundary (the typed `update(AliasedExpression[])` surface in 8.5.0
+   * has no field-deletion transform — see `runFirestorePipelineUpdate`).
+   */
+  bulkUpdate(filters, patch, options) {
+    return runFirestorePipelineUpdate(this.db, this.collectionPath, filters, patch, options);
+  }
+  // --- Engine-level multi-hop traversal (capability: traversal.serverSide) ---
+  /**
+   * Compile a multi-hop traversal spec into one nested Pipeline and
+   * dispatch a single round trip via `define` + `addFields(child
+   * .toArrayExpression().as(...))`. The compiler in
+   * `firestore-traverse-compiler.ts` validates spec eligibility (depth
+   * ≤ `MAX_PIPELINE_DEPTH`, every hop has `limitPerSource`, response-
+   * size product ≤ `maxReads`) and the executor in
+   * `firestore-traverse.ts` builds + decodes the tree.
+   *
+   * Unlike `bulkDelete` / `bulkUpdate`, this method is GA-typed in 8.5.0
+   * (no `@beta` annotation on `define`, `addFields`, `toArrayExpression`,
+   * or `variable`), so it does NOT need a `previewDml`-style opt-in.
+   *
+   * `defaultQueryMode` is irrelevant here — engine traversal always
+   * dispatches through Pipelines because the join-key binding (`define`
+   * + `variable`) has no classic Query API equivalent. Specs that
+   * arrive on a classic-mode backend still execute via Pipelines; the
+   * `queryMode` toggle only affects the read query path
+   * (`query()` / `expand()`).
+   */
+  runEngineTraversal(params) {
+    return runFirestoreEngineTraversal(this.db, this.collectionPath, params);
+  }
+};
+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) {
+    _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."
+    );
+  }
+  if (!isEmulator && requestedMode === "classic" && !_classicInProductionWarned) {
+    _classicInProductionWarned = true;
+    console.warn(
+      "[firegraph] Firestore Enterprise backend created with `defaultQueryMode: 'classic'`. Classic-mode `query()` against Enterprise causes full collection scans for `data.*` filters (high billing). For production reads on Standard Firestore, import from `'firegraph/firestore-standard'` instead."
+    );
+  }
+  const previewDml = options.previewDml ?? false;
+  if (previewDml && !_previewDmlWarned) {
+    _previewDmlWarned = true;
+    console.warn(
+      "[firegraph] Firestore Enterprise backend created with `previewDml: true`. bulkDelete()/bulkUpdate() will dispatch through Pipeline.delete() / Pipeline.update(transformedFields), both `@beta` in @google-cloud/firestore@8.5.0. The typed surface may shift before GA \u2014 pin your firestore SDK or be ready to set `previewDml: false` and route through the read-then-write fallback if needed."
+    );
+  }
+  const scopePath = options.scopePath ?? "";
+  return new FirestoreEnterpriseBackendImpl(
+    db,
+    collectionPath,
+    effectiveMode,
+    scopePath,
+    previewDml
+  );
+}
+export {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
+  createFirestoreEnterpriseBackend,
+  createGraphClient,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+};
+//# sourceMappingURL=index.js.map