@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/sqlite/index.d.cts

@@ -0,0 +1,111 @@
+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 { S as StorageBackend } from '../backend-DuvHGgK1.cjs';
+import '@google-cloud/firestore';
+
+/**
+ * Driver-level SQLite abstraction.
+ *
+ * The `SqliteBackend` only depends on this interface, not on any particular
+ * SQLite driver. Callers wire up whichever driver suits their runtime —
+ * `better-sqlite3` in Node tests, D1 in Workers, DO SQLite inside a Durable
+ * Object, etc. — and `createSqliteBackend` composes the rest.
+ *
+ * Some drivers are fully async with native atomic batches (e.g. D1); others
+ * are synchronous and wrap `run`/`all` in immediately-resolved promises while
+ * providing interactive transactions via a sync primitive (e.g. DO SQLite's
+ * `transactionSync`). Both shapes fit behind this interface.
+ */
+interface SqliteExecutor {
+    /** Run a query and return all rows. */
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    /** Run a write statement. */
+    run(sql: string, params: unknown[]): Promise<void>;
+    /**
+     * Execute a list of write statements atomically. Drivers that lack
+     * native batch support (e.g., a wrapped synchronous SQLite) should still
+     * implement this so `BatchBackend.commit()` works.
+     */
+    batch(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
+    /**
+     * Run an interactive transaction. Optional — if absent, the SqliteBackend
+     * throws on `runTransaction()`. D1 has no interactive transactions.
+     */
+    transaction?<T>(fn: (tx: SqliteTxExecutor) => Promise<T>): Promise<T>;
+    /**
+     * Maximum statements the driver will accept in a single `batch()` call.
+     * The backend uses this to chunk large bulk operations (cascade delete,
+     * bulkRemoveEdges) so a hub node with thousands of edges doesn't trip the
+     * driver's hard limit. D1 caps at ~100 statements per batch; DO SQLite has
+     * no documented cap (a single `transactionSync` over many statements is
+     * fine). When `undefined`, the backend submits all statements in one batch
+     * (preserving cross-batch atomicity for drivers that support it).
+     */
+    readonly maxBatchSize?: number;
+    /**
+     * Maximum total bound parameters the driver will accept across one
+     * `batch()` call. D1 caps at ~1000 bound parameters per batch — separate
+     * from `maxBatchSize`. Most cascade/bulk batches consist of 2-param
+     * `DELETE` statements so this rarely triggers, but driver authors should
+     * declare it for safety. When `undefined`, the backend doesn't split on
+     * parameter count.
+     */
+    readonly maxBatchParams?: number;
+}
+interface SqliteTxExecutor {
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    run(sql: string, params: unknown[]): Promise<void>;
+}
+
+/**
+ * SQLite implementation of `StorageBackend`.
+ *
+ * Uses a single table keyed by `(scope, doc_id)`. Subgraphs are encoded in
+ * the `scope` column as a materialized path of interleaved parent UIDs and
+ * subgraph names — `''` at the root, `'<uid>/<name>'` one level down,
+ * `'<uid1>/<name1>/<uid2>/<name2>'` two levels down, and so on. Cascade
+ * delete uses a single `DELETE … WHERE scope LIKE 'prefix/%'` instead of
+ * walking subcollections.
+ */
+
+interface SqliteBackendOptions {
+    /** Logical scope path (chained subgraph names) — used for `allowedIn` matching. */
+    scopePath?: string;
+    /** Internal storage scope (interleaved parent-uid/name path). */
+    storageScope?: string;
+}
+/**
+ * Capability union declared by the SQLite-backed `StorageBackend`.
+ *
+ * `core.transactions` is part of the static union because `runTransaction`
+ * is always present as a method on the class. The runtime cap-set determines
+ * whether that method is *functional*: D1 leaves `executor.transaction`
+ * undefined and the call throws `UNSUPPORTED_OPERATION`; DO SQLite and
+ * better-sqlite3 wire the executor and the call works. The static type
+ * therefore promises only that the method exists — callers that care about
+ * portability check `client.capabilities.has('core.transactions')` before
+ * opening a tx, and code that runs against an unknown driver can rely on the
+ * runtime guard inside `runTransaction`.
+ *
+ * The `query.*` extension capabilities follow the same conservative
+ * declaration rule as the cap descriptor itself — only land in the union
+ * when the corresponding method is actually wired up. Today that's
+ * `query.aggregate` (Phase 4), `query.dml` (Phase 5), `query.join`
+ * (Phase 6 — fan-out via `IN (…)` in one statement), and `query.select`
+ * (Phase 7 — server-side projection via `json_extract`).
+ */
+type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select' | 'raw.sql';
+/**
+ * Create a SQLite-backed `StorageBackend`.
+ *
+ * `tableName` is the single table that holds every triple. The driver must
+ * have already created the table and indexes via `buildSchemaStatements()`
+ * before any reads/writes arrive — callers that ship their own SQLite
+ * driver are responsible for wiring that up.
+ */
+declare function createSqliteBackend(executor: SqliteExecutor, tableName: string, options?: SqliteBackendOptions): StorageBackend<SqliteCapability>;
+
+export { type SqliteBackendOptions, type SqliteCapability, createSqliteBackend };

package/dist/sqlite/index.d.ts

@@ -0,0 +1,111 @@
+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 { S as StorageBackend } from '../backend-DuvHGgK1.js';
+import '@google-cloud/firestore';
+
+/**
+ * Driver-level SQLite abstraction.
+ *
+ * The `SqliteBackend` only depends on this interface, not on any particular
+ * SQLite driver. Callers wire up whichever driver suits their runtime —
+ * `better-sqlite3` in Node tests, D1 in Workers, DO SQLite inside a Durable
+ * Object, etc. — and `createSqliteBackend` composes the rest.
+ *
+ * Some drivers are fully async with native atomic batches (e.g. D1); others
+ * are synchronous and wrap `run`/`all` in immediately-resolved promises while
+ * providing interactive transactions via a sync primitive (e.g. DO SQLite's
+ * `transactionSync`). Both shapes fit behind this interface.
+ */
+interface SqliteExecutor {
+    /** Run a query and return all rows. */
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    /** Run a write statement. */
+    run(sql: string, params: unknown[]): Promise<void>;
+    /**
+     * Execute a list of write statements atomically. Drivers that lack
+     * native batch support (e.g., a wrapped synchronous SQLite) should still
+     * implement this so `BatchBackend.commit()` works.
+     */
+    batch(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
+    /**
+     * Run an interactive transaction. Optional — if absent, the SqliteBackend
+     * throws on `runTransaction()`. D1 has no interactive transactions.
+     */
+    transaction?<T>(fn: (tx: SqliteTxExecutor) => Promise<T>): Promise<T>;
+    /**
+     * Maximum statements the driver will accept in a single `batch()` call.
+     * The backend uses this to chunk large bulk operations (cascade delete,
+     * bulkRemoveEdges) so a hub node with thousands of edges doesn't trip the
+     * driver's hard limit. D1 caps at ~100 statements per batch; DO SQLite has
+     * no documented cap (a single `transactionSync` over many statements is
+     * fine). When `undefined`, the backend submits all statements in one batch
+     * (preserving cross-batch atomicity for drivers that support it).
+     */
+    readonly maxBatchSize?: number;
+    /**
+     * Maximum total bound parameters the driver will accept across one
+     * `batch()` call. D1 caps at ~1000 bound parameters per batch — separate
+     * from `maxBatchSize`. Most cascade/bulk batches consist of 2-param
+     * `DELETE` statements so this rarely triggers, but driver authors should
+     * declare it for safety. When `undefined`, the backend doesn't split on
+     * parameter count.
+     */
+    readonly maxBatchParams?: number;
+}
+interface SqliteTxExecutor {
+    all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
+    run(sql: string, params: unknown[]): Promise<void>;
+}
+
+/**
+ * SQLite implementation of `StorageBackend`.
+ *
+ * Uses a single table keyed by `(scope, doc_id)`. Subgraphs are encoded in
+ * the `scope` column as a materialized path of interleaved parent UIDs and
+ * subgraph names — `''` at the root, `'<uid>/<name>'` one level down,
+ * `'<uid1>/<name1>/<uid2>/<name2>'` two levels down, and so on. Cascade
+ * delete uses a single `DELETE … WHERE scope LIKE 'prefix/%'` instead of
+ * walking subcollections.
+ */
+
+interface SqliteBackendOptions {
+    /** Logical scope path (chained subgraph names) — used for `allowedIn` matching. */
+    scopePath?: string;
+    /** Internal storage scope (interleaved parent-uid/name path). */
+    storageScope?: string;
+}
+/**
+ * Capability union declared by the SQLite-backed `StorageBackend`.
+ *
+ * `core.transactions` is part of the static union because `runTransaction`
+ * is always present as a method on the class. The runtime cap-set determines
+ * whether that method is *functional*: D1 leaves `executor.transaction`
+ * undefined and the call throws `UNSUPPORTED_OPERATION`; DO SQLite and
+ * better-sqlite3 wire the executor and the call works. The static type
+ * therefore promises only that the method exists — callers that care about
+ * portability check `client.capabilities.has('core.transactions')` before
+ * opening a tx, and code that runs against an unknown driver can rely on the
+ * runtime guard inside `runTransaction`.
+ *
+ * The `query.*` extension capabilities follow the same conservative
+ * declaration rule as the cap descriptor itself — only land in the union
+ * when the corresponding method is actually wired up. Today that's
+ * `query.aggregate` (Phase 4), `query.dml` (Phase 5), `query.join`
+ * (Phase 6 — fan-out via `IN (…)` in one statement), and `query.select`
+ * (Phase 7 — server-side projection via `json_extract`).
+ */
+type SqliteCapability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.dml' | 'query.join' | 'query.select' | 'raw.sql';
+/**
+ * Create a SQLite-backed `StorageBackend`.
+ *
+ * `tableName` is the single table that holds every triple. The driver must
+ * have already created the table and indexes via `buildSchemaStatements()`
+ * before any reads/writes arrive — callers that ship their own SQLite
+ * driver are responsible for wiring that up.
+ */
+declare function createSqliteBackend(executor: SqliteExecutor, tableName: string, options?: SqliteBackendOptions): StorageBackend<SqliteCapability>;
+
+export { type SqliteBackendOptions, type SqliteCapability, createSqliteBackend };