@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/chunk-EQJUUVFG.js

@@ -0,0 +1,14 @@
+// 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);
+}
+
+export {
+  SERIALIZATION_TAG,
+  isTaggedValue
+};
+//# sourceMappingURL=chunk-EQJUUVFG.js.map

package/dist/chunk-EQJUUVFG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/serialization-tag.ts"],"sourcesContent":["/**\n * Firegraph serialization tag — split from `src/serialization.ts` so it can\n * be imported from Workers-facing code without dragging in\n * `@google-cloud/firestore`.\n *\n * The full serialization module (with Timestamp/GeoPoint round-tripping)\n * lives one folder up because the sandbox migration pipeline needs it; the\n * write-plan helper only needs to recognise tagged objects to keep them\n * terminal during patch flattening, so it imports just the tag from here.\n */\n\n/** Sentinel key used to tag serialized Firestore types. */\nexport const SERIALIZATION_TAG = '__firegraph_ser__' as const;\n\nconst KNOWN_TYPES = new Set(['Timestamp', 'GeoPoint', 'VectorValue', 'DocumentReference']);\n\n/** Check if a value is a tagged serialized Firestore type. */\nexport function isTaggedValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const tag = (value as Record<string, unknown>)[SERIALIZATION_TAG];\n  return typeof tag === 'string' && KNOWN_TYPES.has(tag);\n}\n"],"mappings":";AAYO,IAAM,oBAAoB;AAEjC,IAAM,cAAc,oBAAI,IAAI,CAAC,aAAa,YAAY,eAAe,mBAAmB,CAAC;AAGlF,SAAS,cAAc,OAAyB;AACrD,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AACxD,QAAM,MAAO,MAAkC,iBAAiB;AAChE,SAAO,OAAO,QAAQ,YAAY,YAAY,IAAI,GAAG;AACvD;","names":[]}

package/dist/chunk-N5HFDWQX.js

@@ -0,0 +1,23 @@
+// 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);
+}
+
+export {
+  createCapabilities,
+  intersectCapabilities
+};
+//# sourceMappingURL=chunk-N5HFDWQX.js.map

package/dist/chunk-N5HFDWQX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/backend.ts"],"sourcesContent":["/**\n * Backend abstraction for firegraph.\n *\n * `StorageBackend` is the single interface every storage driver implements.\n * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend\n * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.\n *\n * `GraphClientImpl` and friends depend only on this interface — they have\n * no direct knowledge of Firestore or SQLite.\n */\n\nimport type {\n  AggregateSpec,\n  BulkOptions,\n  BulkResult,\n  BulkUpdatePatch,\n  Capability,\n  CascadeResult,\n  EngineTraversalParams,\n  EngineTraversalResult,\n  ExpandParams,\n  ExpandResult,\n  FindEdgesParams,\n  FindNearestParams,\n  FullTextSearchParams,\n  GeoSearchParams,\n  GraphReader,\n  QueryFilter,\n  QueryOptions,\n  StoredGraphRecord,\n} from '../types.js';\nimport type { DataPathOp } from './write-plan.js';\n\n/**\n * Runtime descriptor of which `Capability`s a `StorageBackend` actually\n * implements. Static for the lifetime of a backend instance; declared at\n * construction. The phantom `_phantom` field is a type-level marker\n * (never read at runtime) that lets the type parameter `C` flow through\n * the descriptor for use by `GraphClient<C>` conditional gating.\n *\n * Use `createCapabilities` to construct one. Use `.has(c)` to check\n * membership at runtime; the type system gates extension methods on the\n * client level (see `.claude/backend-capabilities.md`).\n */\nexport interface BackendCapabilities<C extends Capability = Capability> {\n  /** Runtime membership check. */\n  has(capability: Capability): boolean;\n  /** Iterate declared capabilities (diagnostics, error messages). */\n  values(): IterableIterator<Capability>;\n  /** Type-level marker. Never read at runtime. */\n  readonly _phantom?: C;\n}\n\n/**\n * Construct a `BackendCapabilities<C>` from an explicit set. The set is\n * captured by reference; callers should treat it as readonly after passing\n * it in. The runtime cost of `has()` is one Set lookup.\n */\nexport function createCapabilities<C extends Capability>(\n  caps: ReadonlySet<C>,\n): BackendCapabilities<C> {\n  return {\n    has: (capability: Capability): boolean => caps.has(capability as C),\n    values: () => caps.values() as IterableIterator<Capability>,\n  };\n}\n\n/**\n * Intersect multiple capability sets. Used by `RoutingStorageBackend` to\n * derive the capability set of a composite backend: a routed graph can\n * only honour a capability if every wrapped backend honours it.\n */\nexport function intersectCapabilities(\n  parts: ReadonlyArray<BackendCapabilities>,\n): BackendCapabilities {\n  if (parts.length === 0) return createCapabilities(new Set<Capability>());\n  const sets = parts.map((p) => new Set<Capability>(p.values()));\n  const [first, ...rest] = sets;\n  const intersection = new Set<Capability>();\n  for (const c of first) {\n    if (rest.every((s) => s.has(c))) intersection.add(c);\n  }\n  return createCapabilities(intersection);\n}\n\n/**\n * Per-record write payload — backend-agnostic. Timestamps are not present;\n * the backend supplies them via `serverTimestamp()` placeholders that it\n * itself resolves at commit time.\n */\nexport interface WritableRecord {\n  aType: string;\n  aUid: string;\n  axbType: string;\n  bType: string;\n  bUid: string;\n  data: Record<string, unknown>;\n  /** Schema version (set by the writer when registry has migrations). */\n  v?: number;\n}\n\n/**\n * Write semantics for `setDoc`.\n *\n *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned\n *     in the new data survive; nested objects are recursively merged;\n *     arrays are replaced as a unit. This is the default for\n *     `putNode` / `putEdge`.\n *   - `'replace'` — the document is replaced wholesale, dropping any\n *     fields not present in the payload. This is the explicit escape\n *     hatch surfaced as `replaceNode` / `replaceEdge` and used by\n *     migration write-back.\n */\nexport type WriteMode = 'merge' | 'replace';\n\n/**\n * Patch shape for `updateDoc`.\n *\n *   - `dataOps`: list of deep-path terminal ops produced by\n *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore\n *     special types are terminal). Used by `updateNode` / `updateEdge`.\n *     Sibling keys at every depth are preserved.\n *   - `replaceData`: full `data` replacement. Used only by the migration\n *     write-back path, which has already produced a complete migrated\n *     document.\n *   - `v`: optional schema-version stamp.\n *\n * `updatedAt` is always set by the backend.\n */\nexport interface UpdatePayload {\n  dataOps?: DataPathOp[];\n  replaceData?: Record<string, unknown>;\n  v?: number;\n}\n\n/**\n * Read/write transaction adapter. Mirrors Firestore's transaction semantics:\n * reads are snapshot-consistent; writes are issued inside the transaction\n * and a rejection from any write aborts the surrounding `runTransaction`.\n *\n * Writes return `Promise<void>` so SQL drivers can surface row-level errors\n * (constraint violations, malformed JSON paths) rather than swallowing them.\n * Firestore implementations can resolve synchronously since the underlying\n * `Transaction.set/update/delete` calls are themselves synchronous buffers.\n */\nexport interface TransactionBackend {\n  getDoc(docId: string): Promise<StoredGraphRecord | null>;\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;\n  setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;\n  updateDoc(docId: string, update: UpdatePayload): Promise<void>;\n  deleteDoc(docId: string): Promise<void>;\n}\n\n/**\n * Atomic multi-write batch.\n */\nexport interface BatchBackend {\n  setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;\n  updateDoc(docId: string, update: UpdatePayload): void;\n  deleteDoc(docId: string): void;\n  commit(): Promise<void>;\n}\n\n/**\n * The single storage abstraction.\n *\n * Each backend instance is scoped to a \"graph location\" — for Firestore\n * that's a collection path; for SQLite it's a (table, scopePath) pair.\n * `subgraph()` returns a child backend bound to a nested location.\n */\nexport interface StorageBackend<C extends Capability = Capability> {\n  /** Capabilities this backend instance declares. Static for the lifetime of the backend. */\n  readonly capabilities: BackendCapabilities<C>;\n  /** Backend-internal location identifier (collection path or table name). */\n  readonly collectionPath: string;\n  /** Subgraph scope (empty string for root). */\n  readonly scopePath: string;\n\n  // --- Reads ---\n  getDoc(docId: string): Promise<StoredGraphRecord | null>;\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;\n\n  // --- Writes ---\n  setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;\n  updateDoc(docId: string, update: UpdatePayload): Promise<void>;\n  deleteDoc(docId: string): Promise<void>;\n\n  // --- Transactions & batches ---\n  runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;\n  createBatch(): BatchBackend;\n\n  // --- Subgraphs ---\n  subgraph(parentNodeUid: string, name: string): StorageBackend;\n\n  // --- Cascade & bulk ---\n  removeNodeCascade(\n    uid: string,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<CascadeResult>;\n  bulkRemoveEdges(\n    params: FindEdgesParams,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<BulkResult>;\n\n  // --- Cross-collection queries ---\n  /**\n   * Find edges across all subgraphs sharing a given collection name.\n   * Optional — backends that can't support this should throw a clear error.\n   */\n  findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;\n\n  // --- Aggregations ---\n  /**\n   * Run an aggregate query (count/sum/avg/min/max). Present only on backends\n   * that declare `query.aggregate`. The map's keys are caller-defined aliases\n   * matching `AggregateSpec`; values are the resolved numeric results.\n   *\n   * Backends that can't satisfy a particular op throw `FiregraphError` with\n   * code `UNSUPPORTED_AGGREGATE` (e.g. Firestore Standard rejects min/max).\n   */\n  aggregate?(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number>>;\n\n  // --- Server-side DML ---\n  /**\n   * Delete every row matching `filters` in one server-side statement.\n   * Present only on backends that declare `query.dml`. The default cascade\n   * implementation in `bulk.ts` uses this when available; backends without\n   * the cap (e.g. Firestore Standard) fall back to a fetch-then-delete\n   * loop driven by `findEdges` + per-row `deleteDoc`.\n   *\n   * The contract matches `findEdges`: scope predicates are honoured\n   * automatically by the backend's own internal scope tracking. Callers\n   * supply only the filter list — the same shape produced by\n   * `buildEdgeQueryPlan`.\n   */\n  bulkDelete?(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;\n  /**\n   * Update every row matching `filters` with `patch` in one server-side\n   * statement. The patch is deep-merged into each row's `data` field, the\n   * same flatten-then-merge pipeline `updateDoc` uses. Identifying columns\n   * (`aType`, `axbType`, `aUid`, `bType`, `bUid`, `v`) are not writable\n   * through this path.\n   */\n  bulkUpdate?(\n    filters: QueryFilter[],\n    patch: BulkUpdatePatch,\n    options?: BulkOptions,\n  ): Promise<BulkResult>;\n\n  // --- Server-side multi-source fan-out ---\n  /**\n   * Fan out from `params.sources` over a single edge type in one server-side\n   * round trip. Present only on backends that declare `query.join`. The\n   * traversal layer (`traverse.ts`) calls `expand` once per hop when the\n   * backend declares the cap; otherwise it falls back to the per-source\n   * `findEdges` loop.\n   *\n   * Cross-graph hops are never dispatched through `expand` — each source\n   * UID resolves to a distinct subgraph location, which can't be fanned\n   * out as a single statement. The traversal layer enforces that\n   * boundary; `expand` itself does not need to inspect `targetGraph`.\n   */\n  expand?(params: ExpandParams): Promise<ExpandResult>;\n\n  // --- Engine-level multi-hop traversal ---\n  /**\n   * Compile a multi-hop traversal spec into one server-side query and\n   * dispatch a single round trip. Present only on backends that declare\n   * `traversal.serverSide` (Firestore Enterprise today, via nested\n   * Pipelines that combine `define`, `addFields`, and\n   * `toArrayExpression`).\n   *\n   * The traversal layer (`traverse.ts`) compiles a `TraversalBuilder`\n   * spec into `EngineTraversalParams` only when the spec is eligible\n   * (no cross-graph hops, no JS filters, depth ≤ `MAX_PIPELINE_DEPTH`,\n   * `Π(limitPerSource_i × N_i) ≤ maxReads`, `limitPerSource` set on\n   * every hop). Ineligible specs fall back to the per-hop `expand()`\n   * loop without invoking this method.\n   *\n   * The result collapses the nested-pipeline tree into per-hop edge\n   * arrays so the traversal layer can fold the result into the same\n   * `HopResult[]` shape it produces from the per-hop loop.\n   */\n  runEngineTraversal?(params: EngineTraversalParams): Promise<EngineTraversalResult>;\n\n  // --- Server-side projection ---\n  /**\n   * Run a projecting query — return only the listed fields per row. Present\n   * only on backends that declare `query.select`. The cap-less fallback is\n   * `findEdges` followed by a JS-side projection in user code; firegraph\n   * does not auto-fall-back because the wire-payload reduction is the only\n   * reason to call this method.\n   *\n   * `select` is the explicit field list; `filters` and `options` mirror the\n   * `query()` shape. The returned rows have one slot per unique entry in\n   * `select`. Field-name interpretation is the backend's responsibility:\n   * built-in fields resolve to columns / Firestore field names, bare names\n   * resolve to `data.<name>`, and dotted paths resolve verbatim. See\n   * `FindEdgesProjectedParams` for the user-facing contract.\n   *\n   * Migrations are not applied to the result — the caller asked for a\n   * specific projection shape, and rehydrating a partial record into the\n   * migration pipeline would require synthesising every absent field.\n   */\n  findEdgesProjected?(\n    select: ReadonlyArray<string>,\n    filters: QueryFilter[],\n    options?: QueryOptions,\n  ): Promise<Array<Record<string, unknown>>>;\n\n  // --- Native vector / nearest-neighbour search ---\n  /**\n   * Run a vector / nearest-neighbour query. Present only on backends that\n   * declare `search.vector`. There is no client-side fallback — the\n   * SQLite-shaped backends (shared SQLite, Cloudflare DO) genuinely have\n   * no native ANN index, and a JS-side k-NN sweep over `findEdges()` would\n   * scale catastrophically. Backends without the cap throw\n   * `UNSUPPORTED_OPERATION` from the client wrapper.\n   *\n   * `params` carries the user-facing shape (vector field path, query\n   * vector, distance metric, optional threshold and result-field). The\n   * client wrapper has already run scan-protection on the identifying\n   * / `where` filter list before dispatching.\n   *\n   * Path normalisation is the backend's responsibility: rewriting bare\n   * `vectorField` / `distanceResultField` names to `data.<name>` and\n   * rejecting envelope fields (`aType`, `axbType`, `bType`, `aUid`,\n   * `bUid`, `v`, etc.) with `INVALID_QUERY` happens inside the\n   * backend, not the client wrapper. The two in-tree Firestore-edition\n   * backends share `runFirestoreFindNearest` (see\n   * `src/internal/firestore-vector.ts`) for this; third-party backends\n   * declaring `search.vector` must apply equivalent normalisation\n   * before calling their underlying SDK.\n   *\n   * The backend is also responsible for translating to the underlying\n   * SDK call (`Query.findNearest` on Firestore today) and decoding the\n   * result snapshot into `StoredGraphRecord[]`.\n   *\n   * Migrations are not applied to the result. The vector index walks the\n   * raw stored shape; rehydrating into the migration pipeline before\n   * returning would change the candidate set the index already chose.\n   */\n  findNearest?(params: FindNearestParams): Promise<StoredGraphRecord[]>;\n\n  // --- Native full-text search ---\n  /**\n   * Run a full-text search query. Present only on backends that declare\n   * `search.fullText`. There is no client-side fallback — the only\n   * in-tree backend that supports it is Firestore Enterprise (via\n   * Pipeline `search({ query: documentMatches(...) })`); Standard and\n   * the SQLite-shaped backends throw `UNSUPPORTED_OPERATION` from the\n   * client wrapper.\n   *\n   * The backend is responsible for path normalisation (rewriting\n   * bare `fields` entries to `data.<name>`, rejecting envelope fields\n   * with `INVALID_QUERY`), translating to the underlying SDK call,\n   * and decoding the result into `StoredGraphRecord[]`.\n   *\n   * Migrations are not applied to the result. The search index walked\n   * the raw stored shape; rehydrating into the migration pipeline\n   * would change the candidate set the index already scored.\n   */\n  fullTextSearch?(params: FullTextSearchParams): Promise<StoredGraphRecord[]>;\n\n  // --- Native geospatial distance search ---\n  /**\n   * Run a geospatial distance search. Present only on backends that\n   * declare `search.geo`. There is no client-side fallback — only\n   * Firestore Enterprise has a native geo index (translated via\n   * Pipeline `search({ query: geoDistance(...).lessThanOrEqual(...) })`).\n   * Backends without the cap throw `UNSUPPORTED_OPERATION` from the\n   * client wrapper.\n   *\n   * The backend is responsible for `geoField` path normalisation,\n   * translating `point` to a Firestore `GeoPoint`, applying the\n   * radius cap inside the search query, and (when\n   * `orderByDistance` is true / unset) emitting the\n   * `geoDistance(...).ascending()` ordering inside the search stage.\n   *\n   * Migrations are not applied to the result.\n   */\n  geoSearch?(params: GeoSearchParams): Promise<StoredGraphRecord[]>;\n}\n"],"mappings":";AA0DO,SAAS,mBACd,MACwB;AACxB,SAAO;AAAA,IACL,KAAK,CAAC,eAAoC,KAAK,IAAI,UAAe;AAAA,IAClE,QAAQ,MAAM,KAAK,OAAO;AAAA,EAC5B;AACF;AAOO,SAAS,sBACd,OACqB;AACrB,MAAI,MAAM,WAAW,EAAG,QAAO,mBAAmB,oBAAI,IAAgB,CAAC;AACvE,QAAM,OAAO,MAAM,IAAI,CAAC,MAAM,IAAI,IAAgB,EAAE,OAAO,CAAC,CAAC;AAC7D,QAAM,CAAC,OAAO,GAAG,IAAI,IAAI;AACzB,QAAM,eAAe,oBAAI,IAAgB;AACzC,aAAW,KAAK,OAAO;AACrB,QAAI,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,EAAG,cAAa,IAAI,CAAC;AAAA,EACrD;AACA,SAAO,mBAAmB,YAAY;AACxC;","names":[]}

package/dist/chunk-PAD7WFFU.js

@@ -0,0 +1,573 @@
+import {
+  NODE_RELATION,
+  computeEdgeDocId,
+  computeNodeDocId
+} from "./chunk-WRTFC5NG.js";
+import {
+  FiregraphError
+} from "./chunk-TK64DNVK.js";
+
+// src/bulk.ts
+var MAX_BATCH_SIZE = 500;
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_DELAY_MS = 200;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function chunk(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+async function bulkDeleteDocIds(db, collectionPath, docIds, options) {
+  if (docIds.length === 0) {
+    return { deleted: 0, batches: 0, errors: [] };
+  }
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const onProgress = options?.onProgress;
+  const chunks = chunk(docIds, batchSize);
+  const errors = [];
+  let deleted = 0;
+  let completedBatches = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    const ids = chunks[i];
+    let committed = false;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const batch = db.batch();
+        const collectionRef = db.collection(collectionPath);
+        for (const id of ids) {
+          batch.delete(collectionRef.doc(id));
+        }
+        await batch.commit();
+        committed = true;
+        deleted += ids.length;
+        break;
+      } catch (err) {
+        if (attempt < maxRetries) {
+          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+          await sleep(delay);
+        } else {
+          errors.push({
+            batchIndex: i,
+            error: err instanceof Error ? err : new Error(String(err)),
+            operationCount: ids.length
+          });
+        }
+      }
+    }
+    if (committed) {
+      completedBatches++;
+    }
+    if (onProgress) {
+      onProgress({
+        completedBatches,
+        totalBatches: chunks.length,
+        deletedSoFar: deleted
+      });
+    }
+  }
+  return { deleted, batches: completedBatches, errors };
+}
+async function bulkRemoveEdges(db, collectionPath, reader, params, options) {
+  const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+  const edges = await reader.findEdges(effectiveParams);
+  const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  return bulkDeleteDocIds(db, collectionPath, docIds, options);
+}
+async function deleteSubcollectionsRecursive(db, collectionPath, docId, options) {
+  const docRef = db.collection(collectionPath).doc(docId);
+  const subcollections = await docRef.listCollections();
+  if (subcollections.length === 0) return { deleted: 0, errors: [] };
+  let totalDeleted = 0;
+  const allErrors = [];
+  const subOptions = options ? { batchSize: options.batchSize, maxRetries: options.maxRetries } : void 0;
+  for (const subCollRef of subcollections) {
+    const subCollPath = subCollRef.path;
+    const snapshot = await subCollRef.select().get();
+    const subDocIds = snapshot.docs.map((d) => d.id);
+    for (const subDocId of subDocIds) {
+      const subResult = await deleteSubcollectionsRecursive(db, subCollPath, subDocId, subOptions);
+      totalDeleted += subResult.deleted;
+      allErrors.push(...subResult.errors);
+    }
+    if (subDocIds.length > 0) {
+      const result = await bulkDeleteDocIds(db, subCollPath, subDocIds, subOptions);
+      totalDeleted += result.deleted;
+      allErrors.push(...result.errors);
+    }
+  }
+  return { deleted: totalDeleted, errors: allErrors };
+}
+async function removeNodeCascade(db, collectionPath, reader, uid, options) {
+  const [outgoingRaw, incomingRaw] = await Promise.all([
+    reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+    reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
+  ]);
+  const outgoing = outgoingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const incoming = incomingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const edgeDocIdSet = /* @__PURE__ */ new Set();
+  const allEdges = [];
+  for (const edge of [...outgoing, ...incoming]) {
+    const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
+    if (!edgeDocIdSet.has(docId)) {
+      edgeDocIdSet.add(docId);
+      allEdges.push(edge);
+    }
+  }
+  const shouldDeleteSubcollections = options?.deleteSubcollections !== false;
+  const nodeDocId = computeNodeDocId(uid);
+  let subcollectionResult = { deleted: 0, errors: [] };
+  if (shouldDeleteSubcollections) {
+    subcollectionResult = await deleteSubcollectionsRecursive(
+      db,
+      collectionPath,
+      nodeDocId,
+      options
+    );
+  }
+  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  const allDocIds = [...edgeDocIds, nodeDocId];
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const result = await bulkDeleteDocIds(db, collectionPath, allDocIds, {
+    ...options,
+    batchSize
+  });
+  const totalChunks = Math.ceil(allDocIds.length / batchSize);
+  const nodeChunkIndex = totalChunks - 1;
+  const nodeDeleted = !result.errors.some((e) => e.batchIndex === nodeChunkIndex);
+  const topLevelEdgesDeleted = nodeDeleted ? result.deleted - 1 : result.deleted;
+  return {
+    deleted: result.deleted + subcollectionResult.deleted,
+    batches: result.batches,
+    errors: [...result.errors, ...subcollectionResult.errors],
+    edgesDeleted: topLevelEdgesDeleted,
+    nodeDeleted
+  };
+}
+
+// src/internal/firestore-aggregate.ts
+import { AggregateField } from "@google-cloud/firestore";
+function applyFiltersToQuery(base, filters) {
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  return q;
+}
+async function runFirestoreAggregate(base, spec, filters, { edition }) {
+  if (Object.keys(spec).length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const filtered = applyFiltersToQuery(base, filters);
+  const aggregations = {};
+  for (const [alias, { op, field }] of Object.entries(spec)) {
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      aggregations[alias] = AggregateField.count();
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    if (op === "sum") {
+      aggregations[alias] = AggregateField.sum(field);
+    } else if (op === "avg") {
+      aggregations[alias] = AggregateField.average(field);
+    } else {
+      const editionLabel = edition === "enterprise" ? "Firestore Enterprise" : "Firestore Standard";
+      throw new FiregraphError(
+        `Aggregate op '${op}' is not supported on ${editionLabel}. Both Firestore editions support count/sum/avg via the classic Query API; min/max requires a backend with SQL aggregation (SQLite or DO).`,
+        "UNSUPPORTED_AGGREGATE"
+      );
+    }
+  }
+  const snap = await filtered.aggregate(aggregations).get();
+  const data = snap.data();
+  const out = {};
+  for (const alias of Object.keys(spec)) {
+    const v = data[alias];
+    if (v === null || v === void 0) {
+      const op = spec[alias].op;
+      out[alias] = op === "avg" ? Number.NaN : 0;
+    } else {
+      out[alias] = v;
+    }
+  }
+  return out;
+}
+
+// src/internal/firestore-classic-adapter.ts
+function createFirestoreAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    collectionPath,
+    async getDoc(docId) {
+      const snap = await collectionRef.doc(docId).get();
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    async setDoc(docId, data, options) {
+      if (options?.merge) {
+        await collectionRef.doc(docId).set(data, { merge: true });
+      } else {
+        await collectionRef.doc(docId).set(data);
+      }
+    },
+    async updateDoc(docId, data) {
+      await collectionRef.doc(docId).update(data);
+    },
+    async deleteDoc(docId) {
+      await collectionRef.doc(docId).delete();
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await q.get();
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createTransactionAdapter(db, collectionPath, tx) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    async getDoc(docId) {
+      const snap = await tx.get(collectionRef.doc(docId));
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        tx.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        tx.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      tx.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      tx.delete(collectionRef.doc(docId));
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await tx.get(q);
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createBatchAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  const batch = db.batch();
+  return {
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        batch.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        batch.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      batch.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      batch.delete(collectionRef.doc(docId));
+    },
+    async commit() {
+      await batch.commit();
+    }
+  };
+}
+
+// src/internal/firestore-classic-expand.ts
+var FIRESTORE_CLASSIC_IN_CHUNK_SIZE = 30;
+function readField(record, path) {
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  let cursor = record;
+  for (const seg of path.split(".")) {
+    if (cursor === null || typeof cursor !== "object") return void 0;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+function compareFieldValues(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return -1;
+  if (b === void 0 || b === null) return 1;
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta === tb) {
+    return a < b ? -1 : 1;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+async function runFirestoreClassicExpand(adapter, 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 chunks = chunkUids(params.sources, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const totalLimit = params.limitPerSource !== void 0 ? params.sources.length * params.limitPerSource : void 0;
+  const buildFilters = (chunk2) => {
+    const filters = [
+      { field: "axbType", op: "==", value: params.axbType },
+      { field: sourceField, op: "in", value: chunk2 }
+    ];
+    if (params.aType !== void 0) {
+      filters.push({ field: "aType", op: "==", value: params.aType });
+    }
+    if (params.bType !== void 0) {
+      filters.push({ field: "bType", op: "==", value: params.bType });
+    }
+    return filters;
+  };
+  const buildOptions = (chunk2) => {
+    const opts = {};
+    if (params.orderBy) opts.orderBy = params.orderBy;
+    if (params.limitPerSource !== void 0) {
+      opts.limit = chunk2.length * params.limitPerSource;
+    }
+    return opts;
+  };
+  const chunkResults = await Promise.all(
+    chunks.map((chunk2) => adapter.query(buildFilters(chunk2), buildOptions(chunk2)))
+  );
+  let edges = chunkResults.flat();
+  if (params.axbType === NODE_RELATION) {
+    edges = edges.filter((e) => e.aUid !== e.bUid);
+  }
+  if (params.orderBy) {
+    const sortField = params.orderBy.field;
+    const dir = params.orderBy.direction ?? "asc";
+    edges.sort((a, b) => {
+      const cmp = compareFieldValues(readField(a, sortField), readField(b, sortField));
+      return dir === "asc" ? cmp : -cmp;
+    });
+  }
+  if (totalLimit !== void 0 && edges.length > totalLimit) {
+    edges = edges.slice(0, totalLimit);
+  }
+  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 hydrateChunks = chunkUids(uniqueTargets, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const hydrateResults = await Promise.all(
+    hydrateChunks.map(
+      (chunk2) => adapter.query([
+        { field: "axbType", op: "==", value: NODE_RELATION },
+        { field: "aUid", op: "in", value: chunk2 }
+      ])
+    )
+  );
+  const byUid = /* @__PURE__ */ new Map();
+  for (const row of hydrateResults.flat()) {
+    byUid.set(row.bUid, row);
+  }
+  const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+  return { edges, targets };
+}
+function chunkUids(uids, chunkSize) {
+  if (chunkSize <= 0) {
+    throw new FiregraphError(
+      `chunkUids: chunkSize must be positive (got ${chunkSize}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const out = [];
+  for (let i = 0; i < uids.length; i += chunkSize) {
+    out.push(uids.slice(i, i + chunkSize));
+  }
+  return out;
+}
+
+// src/internal/projection.ts
+var PROJECTION_BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeFirestoreProjectionField(field) {
+  if (PROJECTION_BUILTIN_FIELDS.has(field)) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function readProjectionPath(obj, path) {
+  if (obj === void 0 || obj === null) return null;
+  const raw = !path.includes(".") ? obj[path] : (() => {
+    const parts = path.split(".");
+    let cur = obj;
+    for (const part of parts) {
+      if (cur === void 0 || cur === null) return void 0;
+      if (typeof cur !== "object") return void 0;
+      cur = cur[part];
+    }
+    return cur;
+  })();
+  return raw === void 0 ? null : raw;
+}
+
+// src/internal/firestore-projection.ts
+async function runFirestoreFindEdgesProjected(base, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "findEdgesProjected requires a non-empty select list \u2014 an empty projection has no representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const fields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      fields.push({ original: f, canonical: normalizeFirestoreProjectionField(f) });
+    }
+  }
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  if (options?.orderBy) {
+    q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+  }
+  if (options?.limit !== void 0) {
+    q = q.limit(options.limit);
+  }
+  q = q.select(...fields.map((p) => p.canonical));
+  const snap = await q.get();
+  return snap.docs.map((doc) => {
+    const data = doc.data();
+    const out = {};
+    for (const { original, canonical } of fields) {
+      out[original] = readProjectionPath(data, canonical);
+    }
+    return out;
+  });
+}
+
+// src/internal/firestore-vector.ts
+var ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeVectorFieldPath(label, field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `findNearest(): ${label} '${field}' is a built-in envelope field \u2014 vectors 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 buildVectorFilters(params) {
+  const filters = [];
+  if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+  if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+  if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+  if (params.where) filters.push(...params.where);
+  return filters;
+}
+function toNumberArray(qv) {
+  if (Array.isArray(qv)) return qv;
+  if (typeof qv.toArray === "function") {
+    return qv.toArray();
+  }
+  throw new FiregraphError(
+    "findNearest(): queryVector must be a number[] or a Firestore VectorValue.",
+    "INVALID_QUERY"
+  );
+}
+async function runFirestoreFindNearest(base, params) {
+  const vec = toNumberArray(params.queryVector);
+  if (vec.length === 0) {
+    throw new FiregraphError(
+      "findNearest(): queryVector is empty \u2014 at least one dimension is required.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0 || params.limit > 1e3) {
+    throw new FiregraphError(
+      `findNearest(): limit must be a positive integer \u2264 1000 (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const vectorField = normalizeVectorFieldPath("vectorField", params.vectorField);
+  const distanceResultField = params.distanceResultField !== void 0 ? normalizeVectorFieldPath("distanceResultField", params.distanceResultField) : void 0;
+  const filtered = applyFiltersToQuery(base, buildVectorFilters(params));
+  const opts = {
+    vectorField,
+    queryVector: vec,
+    limit: params.limit,
+    distanceMeasure: params.distanceMeasure
+  };
+  if (params.distanceThreshold !== void 0) opts.distanceThreshold = params.distanceThreshold;
+  if (distanceResultField !== void 0) opts.distanceResultField = distanceResultField;
+  const snap = await filtered.findNearest(opts).get();
+  return snap.docs.map((doc) => doc.data());
+}
+
+export {
+  bulkRemoveEdges,
+  removeNodeCascade,
+  runFirestoreAggregate,
+  createFirestoreAdapter,
+  createTransactionAdapter,
+  createBatchAdapter,
+  runFirestoreClassicExpand,
+  runFirestoreFindEdgesProjected,
+  runFirestoreFindNearest
+};
+//# sourceMappingURL=chunk-PAD7WFFU.js.map