@typicalday/firegraph 0.8.0 → 0.10.0

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,454 @@
+import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-BrqFkbid.js';
+import { i as QueryFilter, y as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, c as GraphRegistry, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-DOemdlVA.js';
+import '@google-cloud/firestore';
+
+/**
+ * SQL compilation for the DO SQLite backend.
+ *
+ * Every `FiregraphDO` instance owns one SQLite database holding exactly one
+ * subgraph's triples — there is no `scope` column and no scope discriminator
+ * on any statement. Contrast with `src/internal/sqlite-sql.ts`, which
+ * carries a scope prefix on every read and write for the legacy shared-table
+ * D1/DO SQLite backend.
+ *
+ * Filter compilation, JSON-path validation, and value binding mirror the
+ * legacy module so the query planner (`src/query.ts`) emits the same
+ * `QueryFilter[]` shape regardless of backend.
+ */
+
+/**
+ * Wire representation of a stored record across the DO RPC boundary.
+ *
+ * Durable Object RPC uses structured clone, which preserves plain data but
+ * drops user-defined class prototypes — a `GraphTimestampImpl` from the DO
+ * arrives at the client as a plain `{seconds, nanoseconds}` object without
+ * its `toMillis()` / `toDate()` methods. To avoid silent `.toMillis is not a
+ * function` crashes downstream, records returned from DO RPC carry the two
+ * timestamps as plain millisecond numbers in `createdAtMs` / `updatedAtMs`;
+ * the client-side backend rewraps them as `GraphTimestampImpl` via
+ * `hydrateDORecord` before handing the record to the GraphClient.
+ */
+interface DORecordWire {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    v?: number;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+
+/**
+ * `FiregraphDO` — the Durable Object class that holds a single subgraph's
+ * triples.
+ *
+ * The Cloudflare-native Firegraph design puts each subgraph in its own DO
+ * instance: the root graph in one DO, `client.subgraph(uid, 'memories')` in
+ * another, nested subgraphs in their own DOs, and so on. Each DO owns a
+ * private flat SQLite database (`src/cloudflare/schema.ts`) — no `scope`
+ * column, no shared table, no discriminator. The client routes to a
+ * specific DO by hashing a stable name (`namespace.idFromName(storageKey)`);
+ * on first RPC, the DO lazily materializes and runs the schema DDL.
+ *
+ * ## Using it in a Worker
+ *
+ * Bind the class in `wrangler.toml` and re-export it from the Worker entry:
+ *
+ * ```toml
+ * [[durable_objects.bindings]]
+ * name = "GRAPH"
+ * class_name = "FiregraphDO"
+ *
+ * [[migrations]]
+ * tag = "v1"
+ * new_sqlite_classes = ["FiregraphDO"]
+ * ```
+ *
+ * ```ts
+ * // worker.ts
+ * export { FiregraphDO } from '@typicalday/firegraph/cloudflare';
+ * ```
+ *
+ * To add custom RPC methods, extend the class:
+ *
+ * ```ts
+ * export class GraphDO extends FiregraphDO {
+ *   async myCustomRpc() { ... }
+ * }
+ * ```
+ *
+ * ## Why a plain class (not `extends DurableObject`)?
+ *
+ * Cloudflare accepts any class with the `(state, env)` constructor shape as
+ * a DO class. Extending `DurableObject` from `cloudflare:workers` would pull
+ * a runtime import into this module and prevent it from loading in Node
+ * tests. The plain-class form keeps this file runtime-neutral — the only
+ * Cloudflare thing we touch is `ctx.storage.sql`, typed via local minimal
+ * interfaces.
+ */
+
+interface DOSqlCursor<T> {
+    toArray(): T[];
+}
+interface DOSqlExecutor {
+    exec<T = Record<string, unknown>>(sql: string, ...params: unknown[]): DOSqlCursor<T>;
+}
+interface DOStorage {
+    sql: DOSqlExecutor;
+    transactionSync<T>(fn: () => T): T;
+}
+interface DurableObjectStateLike {
+    readonly storage: DOStorage;
+    blockConcurrencyWhile<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * One op in a `batch()` RPC call. Discriminated by `kind` so the DO can
+ * dispatch to the correct compiler.
+ */
+type BatchOp = {
+    kind: 'set';
+    docId: string;
+    record: WritableRecord;
+} | {
+    kind: 'update';
+    docId: string;
+    update: UpdatePayload;
+} | {
+    kind: 'delete';
+    docId: string;
+};
+/**
+ * Options controlling `FiregraphDO` construction.
+ */
+interface FiregraphDOOptions {
+    /** Table name for firegraph triples. Default: `firegraph`. */
+    table?: string;
+    /** Run schema DDL on first boot. Default: `true`. */
+    autoMigrate?: boolean;
+}
+declare class FiregraphDO {
+    /** @internal — exposed for subclass access, not part of the public RPC. */
+    protected readonly ctx: DurableObjectStateLike;
+    /** @internal — exposed for subclass access; opaque to this class. */
+    protected readonly env: unknown;
+    /** @internal — table name used by every compiled statement. */
+    protected readonly table: string;
+    constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
+    _fgGetDoc(docId: string): Promise<DORecordWire | null>;
+    _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
+    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    _fgDeleteDoc(docId: string): Promise<void>;
+    /**
+     * Execute a list of write ops atomically. DO SQLite's `transactionSync`
+     * provides real atomicity — either every statement commits or none do.
+     * No statement-count cap applies (contrast with D1's ~100-statement batch
+     * limit), so the caller can submit as many ops as they like in one call.
+     */
+    _fgBatch(ops: BatchOp[]): Promise<void>;
+    _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
+    _fgBulkRemoveEdges(params: FindEdgesParams, _options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Wipe every row. Called by the client when tearing down a subgraph DO as
+     * part of cascade — the DO itself can't be destroyed (DO IDs persist
+     * forever), but its storage can be emptied.
+     */
+    _fgDestroy(): Promise<void>;
+    protected runSchema(): void;
+    private execAll;
+    private execRun;
+}
+
+/**
+ * Client-side `StorageBackend` that forwards every operation to a
+ * `FiregraphDO` instance over Durable Object RPC.
+ *
+ * One `DORPCBackend` corresponds to one DO — the root graph's DO, or a
+ * subgraph's DO. `subgraph()` returns a new `DORPCBackend` bound to a
+ * different DO, identified by deriving a new stable name from the chain of
+ * parent UIDs and subgraph names. The library uses `namespace.idFromName()`
+ * on that key, so two clients with the same key always reach the same DO.
+ *
+ * Key invariants:
+ *
+ * - There is no shared table and no `scope` column. Each DO owns its own
+ *   flat SQLite database; isolation is physical.
+ * - Interactive transactions throw `UNSUPPORTED_OPERATION` — holding a
+ *   synchronous SQLite transaction across async RPC calls would block the
+ *   DO's single-threaded executor (see `transactionsUnsupported` below).
+ * - `findEdgesGlobal` is deliberately left undefined on this class. The
+ *   `GraphClient` surfaces the generic "not supported by current storage
+ *   backend" error before running any query planning, which is both
+ *   accurate and sidesteps the misleading `QuerySafetyError` that would
+ *   otherwise fire for scan-unsafe calls. `createDOClient`'s docstring
+ *   explains the design rationale (no collection-group index across DOs).
+ * - `removeNodeCascade` cascades across DOs: when a registry accessor is
+ *   wired, the backend walks `registry.getSubgraphTopology(aType)` for the
+ *   node being removed and destroys every descendant subgraph DO before
+ *   deleting the node itself. Pass `{ deleteSubcollections: false }` to
+ *   disable the cross-DO fan-out (parent node is still removed, child DOs
+ *   are left intact — matching the Firestore/SQLite backends' semantic).
+ *   Without an accessor (e.g. registry-less clients) it cascades within
+ *   the current DO only.
+ */
+
+interface DurableObjectIdLike {
+    toString(): string;
+}
+/**
+ * The RPC surface this backend calls on the DO stub. Every method matches a
+ * `_fg…` method on `FiregraphDO`. Kept structurally typed so users can bring
+ * their own subclass without the types having to know about it.
+ *
+ * Reads return `DORecordWire` (plain data — safe through DO structured
+ * clone); the backend rewraps each record via `hydrateDORecord` before
+ * handing it to the GraphClient, which expects `GraphTimestampImpl`
+ * instances (not plain `{seconds, nanoseconds}` objects).
+ */
+interface FiregraphStub {
+    _fgGetDoc(docId: string): Promise<DORecordWire | null>;
+    _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
+    _fgSetDoc(docId: string, record: WritableRecord): Promise<void>;
+    _fgUpdateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    _fgDeleteDoc(docId: string): Promise<void>;
+    _fgBatch(ops: BatchOp[]): Promise<void>;
+    _fgRemoveNodeCascade(uid: string): Promise<CascadeResult>;
+    _fgBulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    _fgDestroy(): Promise<void>;
+}
+interface FiregraphNamespace {
+    idFromName(name: string): DurableObjectIdLike;
+    get(id: DurableObjectIdLike): FiregraphStub;
+}
+interface DORPCBackendOptions {
+    /** Scope path (names-only chain, used for `allowedIn`). Default: `''`. */
+    scopePath?: string;
+    /**
+     * Opaque storage key used to derive the DO instance via
+     * `namespace.idFromName(storageKey)`. Defaults to the root key passed to
+     * `createDOClient` when the backend is first created.
+     */
+    storageKey: string;
+    /**
+     * Live registry accessor used by `removeNodeCascade` to consult the
+     * subgraph topology and fan out `_fgDestroy` calls to child subgraph DOs.
+     *
+     * A function (not a snapshot) so that dynamic-registry clients see the
+     * latest definitions after `reloadRegistry()`. Wired by `createDOClient`
+     * via a forward reference to the constructed `GraphClient`. When
+     * `undefined`, cross-DO cascade is disabled and `removeNodeCascade`
+     * cascades within this DO only.
+     * @internal
+     */
+    registryAccessor?: () => GraphRegistry | undefined;
+    /**
+     * Factory used by `createSiblingClient` to construct a peer `GraphClient`
+     * that shares this client's namespace, registry, and other options but
+     * targets a different root DO. Wired by `createDOClient`. Leaving it
+     * `undefined` (e.g. when `DORPCBackend` is instantiated directly) disables
+     * sibling-client construction — `createSiblingClient` will throw.
+     *
+     * The union return type mirrors `createDOClient`'s two overloads: dynamic
+     * mode yields a `DynamicGraphClient`, everything else yields a plain
+     * `GraphClient`. `createSiblingClient` narrows at the boundary via its
+     * own overload signatures.
+     * @internal
+     */
+    makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+}
+declare class DORPCBackend implements StorageBackend {
+    readonly collectionPath = "firegraph";
+    readonly scopePath: string;
+    /** @internal */
+    readonly storageKey: string;
+    /** @internal */
+    readonly namespace: FiregraphNamespace;
+    private readonly registryAccessor?;
+    /** @internal — see `DORPCBackendOptions.makeSiblingClient` for the union-type rationale. */
+    readonly makeSiblingClient?: (siblingStorageKey: string) => GraphClient | DynamicGraphClient;
+    private cachedStub;
+    constructor(namespace: FiregraphNamespace, options: DORPCBackendOptions);
+    private get stub();
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(_fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, _reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Wipe this DO's storage. The DO itself can't be deleted — its ID
+     * persists forever — but its rows can be emptied, which is what the
+     * cascade walk does on every descendant subgraph DO.
+     *
+     * Exposed on the concrete class (not `StorageBackend`) so generic
+     * backend code doesn't reach for it.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Tear down every descendant subgraph DO, then wipe this DO's own rows.
+     *
+     * Invoked by cross-DO cascade: for each node in this DO we enumerate the
+     * subgraph topology and recurse into child DOs depth-first before
+     * wiping the current DO. The current DO's own rows are destroyed last so
+     * that a partial failure mid-recursion leaves the caller's reader able
+     * to discover what's still present.
+     *
+     * @internal
+     */
+    destroyRecursively(registry: GraphRegistry): Promise<void>;
+}
+
+/**
+ * `createDOClient` — the user-facing factory for the Cloudflare DO backend.
+ *
+ * Given a Durable Object namespace binding and a stable root key, returns a
+ * `GraphClient` that speaks to a `FiregraphDO` instance. The root key is
+ * hashed via `namespace.idFromName()` to derive the DO ID, so two clients
+ * instantiated with the same key always reach the same DO — that's how we
+ * achieve "subgraphs are auto-provisioned" without a separate allocation
+ * step. Subsequent `.subgraph(uid, name)` calls derive child DO IDs from the
+ * extended key chain (`${key}/${uid}/${name}`).
+ *
+ * ## What's supported
+ *
+ * - **Static registries.** Pass `registry` and every read/write validates
+ *   and migrates exactly like the Firestore/SQLite backends.
+ * - **Dynamic registries.** Pass `registryMode: { mode: 'dynamic' }` and
+ *   call `defineNodeType` / `defineEdgeType` / `reloadRegistry` as with
+ *   any other backend. Meta-types live in the root DO by default; pass
+ *   `registryMode: { mode: 'dynamic', collection: 'meta-root' }` to put
+ *   them in a separately-addressed DO. Merged mode (static `registry`
+ *   plus `registryMode`) is also supported.
+ * - **Cross-DO cascade.** `removeNodeCascade` consults the registry's
+ *   subgraph topology and wipes every descendant subgraph DO before
+ *   deleting the node. Requires a registry; without one it cascades
+ *   within the current DO only. Pass `{ deleteSubcollections: false }` to
+ *   keep the node removal but leave every descendant DO intact (mirrors
+ *   the Firestore/SQLite `bulk` option). In dynamic mode the accessor is
+ *   live, so cascading a node whose subgraph topology was just added via
+ *   `defineEdgeType` correctly fans out to the new descendants — **but
+ *   only after a `reloadRegistry()` call**. A cascade invoked between
+ *   `defineEdgeType` and `reloadRegistry` sees only the pre-define
+ *   topology and silently skips newly-declared subgraphs. This is the
+ *   same trade-off every dynamic-registry backend makes.
+ * - **Static migrations** on registry entries (`migrations`,
+ *   `migrationWriteBack`, `migrationSandbox`) run in-process on the
+ *   Worker and don't cross the DO RPC boundary. The read-path migration
+ *   pipeline lives in `GraphClient`, not in `FiregraphDO`.
+ *
+ * ## Performance note on cascade
+ *
+ * Cross-DO cascade instantiates (via `namespace.get`) every declared child
+ * subgraph DO even when it's empty — Durable Objects have no "does this ID
+ * exist" primitive, and the cheapest way to tear a DO down is to issue one
+ * RPC. For a node with N declared subgraph segments, expect N+1 RPCs per
+ * cascade (one per child DO wipe, one for the parent). Topology width is
+ * typically small and bounded by registry size, but keep it in mind for
+ * wide fan-out designs.
+ *
+ * ## What's not supported
+ *
+ * - **Interactive transactions.** Would require pinning a SQLite
+ *   transaction open across async RPC calls — see `backend.ts` for the
+ *   rationale. Use `batch()` for atomic multi-write commits.
+ * - **`findEdgesGlobal`.** Cross-DO collection-group queries don't map
+ *   onto "one DO owns one subgraph's rows" — each subgraph is a separate
+ *   DO with private SQLite and there's no namespace-wide catalog. The
+ *   method is intentionally undefined on the backend so `GraphClient`
+ *   surfaces a generic `UNSUPPORTED_OPERATION` error immediately, before
+ *   any query planning. Callers that need this should maintain an
+ *   application-level index DO or run an explicit traversal via
+ *   `client.subgraph(...)`.
+ *
+ * ## Binding example
+ *
+ * ```ts
+ * // worker.ts
+ * export { FiregraphDO } from '@typicalday/firegraph/cloudflare';
+ *
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const client = createDOClient(env.GRAPH, 'main', { registry });
+ *     const project = await client.getNode('project', projectUid);
+ *     return Response.json(project);
+ *   },
+ * };
+ * ```
+ *
+ * ```toml
+ * # wrangler.toml
+ * [[durable_objects.bindings]]
+ * name = "GRAPH"
+ * class_name = "FiregraphDO"
+ *
+ * [[migrations]]
+ * tag = "v1"
+ * new_sqlite_classes = ["FiregraphDO"]
+ * ```
+ */
+
+/**
+ * Options for `createDOClient`. Same shape as `GraphClientOptions`; the DO
+ * backend does not expose a table label of its own — the DO owns its SQLite
+ * schema (see `FiregraphDOOptions.table`, defaults to `'firegraph'`) and
+ * that choice isn't surfaced through the client factory.
+ */
+type DOClientOptions = GraphClientOptions;
+/**
+ * Create a `GraphClient` backed by a `FiregraphDO` Durable Object.
+ *
+ * @param namespace  The DO namespace binding (`env.GRAPH` in Worker code).
+ * @param rootKey    Stable name for the root graph's DO. The same value
+ *                   always addresses the same DO — treat it as the graph's
+ *                   identity. Subgraph DOs derive their names from this.
+ * @param options    Optional `GraphClientOptions` (registry, query mode,
+ *                   `registryMode` for dynamic registries, etc.).
+ *                   When `registryMode` is set the return type is
+ *                   narrowed to `DynamicGraphClient`.
+ */
+declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options: DOClientOptions & {
+    registryMode: DynamicRegistryConfig;
+}): DynamicGraphClient;
+declare function createDOClient(namespace: FiregraphNamespace, rootKey: string, options?: DOClientOptions): GraphClient;
+/**
+ * Construct a peer `GraphClient` that shares `client`'s DO namespace and
+ * construction options but targets a different root DO (i.e. a different
+ * root key — typically another tenant, workspace, or shard).
+ *
+ * This is the cheap, ergonomic way to talk to another root graph from
+ * inside a single Worker request without re-plumbing `createDOClient`'s
+ * arguments. The namespace binding plus the options snapshot captured at
+ * the original `createDOClient` call (registry, query mode, migration
+ * sandbox, `registryMode`, etc.) are inherited by the sibling.
+ *
+ * Works from any DO-backed client — root or subgraph. Passing a client
+ * that wasn't produced by `createDOClient` (e.g. a Firestore-backed
+ * client, or a `DORPCBackend` instantiated directly without the sibling
+ * factory wired in) throws `UNSUPPORTED_OPERATION` with an explanation.
+ *
+ * ## Dynamic-registry caveat
+ *
+ * When the original client uses `registryMode: 'dynamic'`, siblings
+ * inherit the *config* (so they're also dynamic clients) but NOT the
+ * compiled runtime state. Meta-type nodes and `reloadRegistry()` results
+ * are per-client; a sibling's `defineNodeType`/`defineEdgeType` calls go
+ * to that sibling's own root DO, and its registry must be independently
+ * populated and reloaded. If every tenant shares the same schema, pass a
+ * static `registry` instead of dynamic mode — static registries ARE
+ * inherited verbatim.
+ *
+ * @param client           A client previously returned by `createDOClient`.
+ * @param siblingRootKey   Root key for the peer DO. Same validation rules
+ *                         as `createDOClient`'s `rootKey`: non-empty,
+ *                         no `/`.
+ */
+declare function createSiblingClient(client: GraphClient, siblingRootKey: string): GraphClient;
+declare function createSiblingClient(client: DynamicGraphClient, siblingRootKey: string): DynamicGraphClient;
+
+export { type BatchOp, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, createDOClient, createSiblingClient };