@typicalday/firegraph 0.12.0 → 0.13.0

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

@@ -0,0 +1,141 @@
+export { c as createGraphClient } from '../client-BrsaXtDV.cjs';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-Bc7h6WTM.cjs';
+import { Firestore } from '@google-cloud/firestore';
+import { S as StorageBackend } from '../backend-DuvHGgK1.cjs';
+
+/**
+ * Firestore Enterprise edition `StorageBackend`.
+ *
+ * The Enterprise edition wires the classic Query API (transactions, single-
+ * doc reads/writes, listeners) alongside the Pipelines query engine. Pipeline
+ * mode is the default for `query()` outside the emulator; classic mode is
+ * always used for transactions and doc-level operations because pipelines
+ * have no transactional binding (per Firestore's GA notes — April 2026).
+ *
+ * Capability declarations target the full Enterprise surface that the
+ * shipped `@google-cloud/firestore@8.5.0` SDK exposes typed APIs for:
+ * core read/write/transactions/batch/subgraph, `query.aggregate`,
+ * `query.select`, `query.join` (via Pipelines `equalAny(field, values)`
+ * for single-statement multi-source fan-out), `query.dml` (gated by
+ * the opt-in `previewDml` flag — Pipeline `delete()` / `update(...)`
+ * stages are `@beta` in 8.5.0; see the per-capability rationale below),
+ * `search.vector` (via the classic `findNearest` API for parity with
+ * Standard), `search.fullText` (via Pipelines
+ * `search({ query: documentMatches(...) })`), `search.geo` (via
+ * Pipelines `search({ query: geoDistance(...).lessThanOrEqual(...) })`),
+ * and `raw.firestore`. Capabilities that remain fundamentally absent on
+ * 8.5.0 — `realtime.listen` — stay undeclared until the SDK exposes an
+ * addressable feature. See the comment block above
+ * `FirestoreEnterpriseCapability` for the per-capability rationale.
+ */
+
+/**
+ * Capability union declared by the Firestore Enterprise backend.
+ *
+ * `core.transactions` is included because transactions are still supported
+ * via the classic Query API (pipelines themselves are not transactionally
+ * bound; the GA notes call this out explicitly). `search.vector` (Phase 8)
+ * is implemented via the classic `Query.findNearest(...)` API for parity
+ * with the Standard edition — see `findNearest()` below.
+ *
+ * `search.fullText` and `search.geo` (Phase 12) are implemented via the
+ * Pipelines `search(...)` stage exposed in `@google-cloud/firestore@8.5.0`.
+ * The 8.5.0 typed surface adds `documentMatches(...)`, `score()`, and
+ * `geoDistance(...)` as first-class expressions (all `@beta` and gated to
+ * the `Search` stage); the `Pipeline.search(options)` method itself is
+ * also first-class. Standard does NOT declare these caps — full-text
+ * search and geospatial queries are Enterprise-only product features
+ * regardless of SDK shape, so the routing invariant (declared cap ⇒
+ * method exists ⇒ index exists) demands that the cap stay edition-gated.
+ *
+ * Conservative declaration matters here: declaring a capability we don't
+ * implement turns the type-level gate (Phase 3) into a lie that throws at
+ * runtime instead of failing to compile. The inverse also matters:
+ * implementing without declaring leaves the surface accessible only via
+ * `as any` casts, which silently bypasses the capability gate.
+ *
+ * **`query.join` (Phase 13a) is implemented via Pipelines `equalAny`.**
+ * Multi-source fan-out collapses to a single round trip:
+ * `db.pipeline().collection(path).where(equalAny(sourceField, sources))
+ * .execute()`. The shared helper lives at `src/internal/firestore-expand.ts`.
+ * The classic Query API caps `'in'` at 30 elements per call, forcing
+ * `ceil(N/30)` round trips; pipeline `equalAny(field, values)` accepts
+ * an arbitrary list, so a 1k-source fan-out goes from ~34 round trips
+ * to one. When `queryMode === 'classic'` (emulator or explicit override),
+ * the classic chunked path in `firestore-classic-expand.ts` is used
+ * instead — same observable contract, different round-trip profile.
+ *
+ * **`query.dml` (Phase 13b) is wired through `runFirestorePipelineDelete`
+ * and `runFirestorePipelineUpdate` (`src/internal/firestore-bulk-dml.ts`)
+ * but is gated by an opt-in `FirestoreEnterpriseOptions.previewDml`
+ * flag.** The underlying `Pipeline.delete()` and
+ * `Pipeline.update(transformedFields)` stages are `@beta` in
+ * `@google-cloud/firestore@8.5.0` (`firestore.d.ts:12647` /
+ * `firestore.d.ts:12662`). When `previewDml: true`, the cap is declared
+ * and `bulkDelete` / `bulkUpdate` dispatch to single-statement Pipelines
+ * stages — same observable contract as SQLite/DO, one round trip per
+ * call, no fetch-then-write loop. A one-time `console.warn` fires on
+ * backend construction so the `@beta` status is visible. When
+ * `previewDml: false` (default), the cap is NOT declared; `bulk.ts`
+ * cascade and `client.bulkDelete()` / `client.bulkUpdate()` route
+ * through the existing `bulkRemoveEdges` fetch-then-write fallback.
+ * SQLite and Cloudflare DO declare `query.dml` unconditionally because
+ * their `DELETE … WHERE …` / `UPDATE … SET …` paths are GA, not preview.
+ */
+type FirestoreEnterpriseCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.select' | 'query.join' | 'query.dml' | 'traversal.serverSide' | 'search.vector' | 'search.fullText' | 'search.geo' | 'raw.firestore';
+type FirestoreEnterpriseQueryMode = 'pipeline' | 'classic';
+interface FirestoreEnterpriseOptions {
+    /**
+     * Query execution mode for `findEdges` / `findNodes`. `'pipeline'` (the
+     * default outside the emulator) routes through the Pipeline query engine;
+     * `'classic'` falls back to the Query API. Pipeline-only capabilities
+     * (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.
+     */
+    defaultQueryMode?: FirestoreEnterpriseQueryMode;
+    /**
+     * Opt in to Pipelines DML stages (`@beta` in `@google-cloud/firestore@8.5.0`:
+     * `Pipeline.delete()` at `firestore.d.ts:12647`,
+     * `Pipeline.update(transformedFields)` at `firestore.d.ts:12662`).
+     *
+     * When `false` (default), this backend does NOT declare `query.dml` and
+     * `client.bulkDelete()` / `client.bulkUpdate()` throw
+     * `UNSUPPORTED_OPERATION` (or, via `bulk.ts`'s cascade path, fall back
+     * to the read-then-write loop in `bulkRemoveEdges`).
+     *
+     * When `true`, the backend declares `query.dml` and dispatches both
+     * methods to single-statement Pipeline stages via
+     * `runFirestorePipelineDelete` / `runFirestorePipelineUpdate`. A
+     * one-time `console.warn` fires on the first backend created with the
+     * flag so the `@beta` status is visible without disrupting tests or
+     * production traffic. The flag intentionally has no effect on
+     * `defaultQueryMode: 'classic'` — the classic-API path has no DML stage
+     * to fall back to, so opting into preview DML in classic mode is a
+     * misconfiguration; we accept the flag silently rather than throw to
+     * keep the option surface ergonomic across the dual-mode toggle. The
+     * routing layer relies on `query.dml` being a structural cap, not a
+     * runtime promise — so the cap is still declared even in classic mode,
+     * and the methods still dispatch through Pipelines (Pipeline DML works
+     * regardless of the read-path `queryMode`).
+     */
+    previewDml?: boolean;
+    /** Internal: the logical scope path inherited from a parent subgraph. */
+    scopePath?: string;
+}
+/**
+ * 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.
+ */
+declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): StorageBackend<FirestoreEnterpriseCapability>;
+
+export { type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };

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

@@ -0,0 +1,141 @@
+export { c as createGraphClient } from '../client-BKi3vk0Q.js';
+export { M as META_EDGE_TYPE, a as META_NODE_TYPE, b as createMergedRegistry, d as createRegistry, f as generateId } from '../registry-C2KUPVZj.js';
+import { Firestore } from '@google-cloud/firestore';
+import { S as StorageBackend } from '../backend-DuvHGgK1.js';
+
+/**
+ * Firestore Enterprise edition `StorageBackend`.
+ *
+ * The Enterprise edition wires the classic Query API (transactions, single-
+ * doc reads/writes, listeners) alongside the Pipelines query engine. Pipeline
+ * mode is the default for `query()` outside the emulator; classic mode is
+ * always used for transactions and doc-level operations because pipelines
+ * have no transactional binding (per Firestore's GA notes — April 2026).
+ *
+ * Capability declarations target the full Enterprise surface that the
+ * shipped `@google-cloud/firestore@8.5.0` SDK exposes typed APIs for:
+ * core read/write/transactions/batch/subgraph, `query.aggregate`,
+ * `query.select`, `query.join` (via Pipelines `equalAny(field, values)`
+ * for single-statement multi-source fan-out), `query.dml` (gated by
+ * the opt-in `previewDml` flag — Pipeline `delete()` / `update(...)`
+ * stages are `@beta` in 8.5.0; see the per-capability rationale below),
+ * `search.vector` (via the classic `findNearest` API for parity with
+ * Standard), `search.fullText` (via Pipelines
+ * `search({ query: documentMatches(...) })`), `search.geo` (via
+ * Pipelines `search({ query: geoDistance(...).lessThanOrEqual(...) })`),
+ * and `raw.firestore`. Capabilities that remain fundamentally absent on
+ * 8.5.0 — `realtime.listen` — stay undeclared until the SDK exposes an
+ * addressable feature. See the comment block above
+ * `FirestoreEnterpriseCapability` for the per-capability rationale.
+ */
+
+/**
+ * Capability union declared by the Firestore Enterprise backend.
+ *
+ * `core.transactions` is included because transactions are still supported
+ * via the classic Query API (pipelines themselves are not transactionally
+ * bound; the GA notes call this out explicitly). `search.vector` (Phase 8)
+ * is implemented via the classic `Query.findNearest(...)` API for parity
+ * with the Standard edition — see `findNearest()` below.
+ *
+ * `search.fullText` and `search.geo` (Phase 12) are implemented via the
+ * Pipelines `search(...)` stage exposed in `@google-cloud/firestore@8.5.0`.
+ * The 8.5.0 typed surface adds `documentMatches(...)`, `score()`, and
+ * `geoDistance(...)` as first-class expressions (all `@beta` and gated to
+ * the `Search` stage); the `Pipeline.search(options)` method itself is
+ * also first-class. Standard does NOT declare these caps — full-text
+ * search and geospatial queries are Enterprise-only product features
+ * regardless of SDK shape, so the routing invariant (declared cap ⇒
+ * method exists ⇒ index exists) demands that the cap stay edition-gated.
+ *
+ * Conservative declaration matters here: declaring a capability we don't
+ * implement turns the type-level gate (Phase 3) into a lie that throws at
+ * runtime instead of failing to compile. The inverse also matters:
+ * implementing without declaring leaves the surface accessible only via
+ * `as any` casts, which silently bypasses the capability gate.
+ *
+ * **`query.join` (Phase 13a) is implemented via Pipelines `equalAny`.**
+ * Multi-source fan-out collapses to a single round trip:
+ * `db.pipeline().collection(path).where(equalAny(sourceField, sources))
+ * .execute()`. The shared helper lives at `src/internal/firestore-expand.ts`.
+ * The classic Query API caps `'in'` at 30 elements per call, forcing
+ * `ceil(N/30)` round trips; pipeline `equalAny(field, values)` accepts
+ * an arbitrary list, so a 1k-source fan-out goes from ~34 round trips
+ * to one. When `queryMode === 'classic'` (emulator or explicit override),
+ * the classic chunked path in `firestore-classic-expand.ts` is used
+ * instead — same observable contract, different round-trip profile.
+ *
+ * **`query.dml` (Phase 13b) is wired through `runFirestorePipelineDelete`
+ * and `runFirestorePipelineUpdate` (`src/internal/firestore-bulk-dml.ts`)
+ * but is gated by an opt-in `FirestoreEnterpriseOptions.previewDml`
+ * flag.** The underlying `Pipeline.delete()` and
+ * `Pipeline.update(transformedFields)` stages are `@beta` in
+ * `@google-cloud/firestore@8.5.0` (`firestore.d.ts:12647` /
+ * `firestore.d.ts:12662`). When `previewDml: true`, the cap is declared
+ * and `bulkDelete` / `bulkUpdate` dispatch to single-statement Pipelines
+ * stages — same observable contract as SQLite/DO, one round trip per
+ * call, no fetch-then-write loop. A one-time `console.warn` fires on
+ * backend construction so the `@beta` status is visible. When
+ * `previewDml: false` (default), the cap is NOT declared; `bulk.ts`
+ * cascade and `client.bulkDelete()` / `client.bulkUpdate()` route
+ * through the existing `bulkRemoveEdges` fetch-then-write fallback.
+ * SQLite and Cloudflare DO declare `query.dml` unconditionally because
+ * their `DELETE … WHERE …` / `UPDATE … SET …` paths are GA, not preview.
+ */
+type FirestoreEnterpriseCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.select' | 'query.join' | 'query.dml' | 'traversal.serverSide' | 'search.vector' | 'search.fullText' | 'search.geo' | 'raw.firestore';
+type FirestoreEnterpriseQueryMode = 'pipeline' | 'classic';
+interface FirestoreEnterpriseOptions {
+    /**
+     * Query execution mode for `findEdges` / `findNodes`. `'pipeline'` (the
+     * default outside the emulator) routes through the Pipeline query engine;
+     * `'classic'` falls back to the Query API. Pipeline-only capabilities
+     * (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.
+     */
+    defaultQueryMode?: FirestoreEnterpriseQueryMode;
+    /**
+     * Opt in to Pipelines DML stages (`@beta` in `@google-cloud/firestore@8.5.0`:
+     * `Pipeline.delete()` at `firestore.d.ts:12647`,
+     * `Pipeline.update(transformedFields)` at `firestore.d.ts:12662`).
+     *
+     * When `false` (default), this backend does NOT declare `query.dml` and
+     * `client.bulkDelete()` / `client.bulkUpdate()` throw
+     * `UNSUPPORTED_OPERATION` (or, via `bulk.ts`'s cascade path, fall back
+     * to the read-then-write loop in `bulkRemoveEdges`).
+     *
+     * When `true`, the backend declares `query.dml` and dispatches both
+     * methods to single-statement Pipeline stages via
+     * `runFirestorePipelineDelete` / `runFirestorePipelineUpdate`. A
+     * one-time `console.warn` fires on the first backend created with the
+     * flag so the `@beta` status is visible without disrupting tests or
+     * production traffic. The flag intentionally has no effect on
+     * `defaultQueryMode: 'classic'` — the classic-API path has no DML stage
+     * to fall back to, so opting into preview DML in classic mode is a
+     * misconfiguration; we accept the flag silently rather than throw to
+     * keep the option surface ergonomic across the dual-mode toggle. The
+     * routing layer relies on `query.dml` being a structural cap, not a
+     * runtime promise — so the cap is still declared even in classic mode,
+     * and the methods still dispatch through Pipelines (Pipeline DML works
+     * regardless of the read-path `queryMode`).
+     */
+    previewDml?: boolean;
+    /** Internal: the logical scope path inherited from a parent subgraph. */
+    scopePath?: string;
+}
+/**
+ * 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.
+ */
+declare function createFirestoreEnterpriseBackend(db: Firestore, collectionPath: string, options?: FirestoreEnterpriseOptions): StorageBackend<FirestoreEnterpriseCapability>;
+
+export { type FirestoreEnterpriseCapability, type FirestoreEnterpriseOptions, type FirestoreEnterpriseQueryMode, createFirestoreEnterpriseBackend };