@typicalday/firegraph 0.14.1 → 0.16.0

package/dist/sqlite/local.d.cts

@@ -0,0 +1,109 @@
+import { Database } from 'better-sqlite3';
+import { S as StorageBackend } from '../backend-DNzv8KSR.cjs';
+import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-EjFfw9yO.cjs';
+import '@google-cloud/firestore';
+
+/**
+ * Local SQLite backend over `better-sqlite3`.
+ *
+ * This entry point is published as `firegraph/sqlite-local` and is the only
+ * module in the library that references `better-sqlite3` — keep it out of
+ * `firegraph/sqlite` so that D1 / workerd bundles never see the native
+ * dependency. `better-sqlite3` is loaded via dynamic `import()` at factory
+ * call time, so merely importing this module stays side-effect free.
+ *
+ * The factory accepts either a database file path (`':memory:'` works) or an
+ * already-open `better-sqlite3` Database. Path-opened databases get
+ * `journal_mode = WAL` and a `busy_timeout` applied; caller-provided
+ * databases are used as-is (only `busy_timeout` is set) since the caller
+ * owns their pragma configuration.
+ *
+ * ## Search capabilities
+ *
+ * On top of the shared SQLite capability set, the local backend declares
+ * `search.fullText` and `search.vector` (see `src/internal/sqlite-search.ts`
+ * for the mechanics):
+ *
+ *   - **Full-text search** is backed by one FTS5 table per graph table,
+ *     kept in sync by pure-SQL triggers installed with the table's DDL.
+ *     Because the triggers live in the database file, writes from ANY
+ *     process or connection stay indexed. The trade-off is a per-write
+ *     overhead (text extraction via `json_tree` + an FTS index update) on
+ *     every insert/update/delete.
+ *   - **Vector search** is a brute-force scan scored by a deterministic
+ *     scalar UDF registered on this connection. UDFs are connection-local:
+ *     `findNearest` only works through a backend created by this factory
+ *     (other connections to the same file can read/write normally — only
+ *     vector *search* needs the UDF).
+ */
+
+/**
+ * Capability union for the local better-sqlite3 backend: everything the
+ * shared SQLite edition declares, plus native FTS5 full-text search and
+ * brute-force vector search. `search.geo` stays out — there is no geo
+ * index in stock SQLite, and a UDF-scored scan without a haversine
+ * contract pinned by Firestore parity tests would be guesswork.
+ */
+type LocalSqliteCapability = SqliteCapability | 'search.fullText' | 'search.vector';
+interface LocalSqliteBackendOptions extends SqliteBackendOptions {
+    /** Root graph table name. Defaults to `'firegraph'`. */
+    tableName?: string;
+    /**
+     * `PRAGMA busy_timeout` in milliseconds — how long a connection waits on a
+     * lock held by another process before erroring. Defaults to 5000.
+     */
+    busyTimeoutMs?: number;
+    /**
+     * Extra pragmas applied after the defaults, e.g.
+     * `{ synchronous: 'NORMAL', cache_size: -64000 }`. Applied in object
+     * order via `PRAGMA <key> = <value>`.
+     */
+    pragmas?: Record<string, string | number>;
+    /**
+     * When opening by path: throw if the file does not already exist instead
+     * of creating it. Defaults to false.
+     */
+    fileMustExist?: boolean;
+}
+interface LocalSqliteBackend {
+    /** The graph storage backend — pass to `createGraphClient`. */
+    backend: StorageBackend<LocalSqliteCapability>;
+    /** The underlying better-sqlite3 database, for raw access. */
+    db: Database;
+    /**
+     * Close the database. No-op when the factory was given an already-open
+     * Database (the caller owns its lifecycle).
+     */
+    close(): void;
+}
+/**
+ * Build a transaction-capable `SqliteExecutor` over a better-sqlite3
+ * Database. Interactive transactions use manual `BEGIN IMMEDIATE` /
+ * `COMMIT` / `ROLLBACK` because `db.transaction()` requires a synchronous
+ * callback while `SqliteExecutor.transaction` callbacks are async.
+ *
+ * Exported for callers that want to wire `createSqliteBackend` directly
+ * (e.g. to share one executor across several root tables).
+ */
+declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
+/**
+ * Open (or wrap) a local SQLite database and return a graph storage backend
+ * over it.
+ *
+ * ```typescript
+ * import { createLocalSqliteBackend } from 'firegraph/sqlite-local';
+ * import { createGraphClient } from 'firegraph/sqlite';
+ *
+ * const { backend, close } = await createLocalSqliteBackend('./graph.db');
+ * const client = createGraphClient(backend);
+ * // ... use the client — including fullTextSearch() and findNearest() ...
+ * close();
+ * ```
+ *
+ * Requires `better-sqlite3` to be installed (declared as an optional peer
+ * dependency). The factory is async because the driver is loaded via
+ * dynamic `import()`.
+ */
+declare function createLocalSqliteBackend(pathOrDb: string | Database, options?: LocalSqliteBackendOptions): Promise<LocalSqliteBackend>;
+
+export { type LocalSqliteBackend, type LocalSqliteBackendOptions, type LocalSqliteCapability, createBetterSqliteExecutor, createLocalSqliteBackend };

package/dist/sqlite/local.d.ts

@@ -0,0 +1,109 @@
+import { Database } from 'better-sqlite3';
+import { S as StorageBackend } from '../backend-DNzv8KSR.js';
+import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-CE3pM9-T.js';
+import '@google-cloud/firestore';
+
+/**
+ * Local SQLite backend over `better-sqlite3`.
+ *
+ * This entry point is published as `firegraph/sqlite-local` and is the only
+ * module in the library that references `better-sqlite3` — keep it out of
+ * `firegraph/sqlite` so that D1 / workerd bundles never see the native
+ * dependency. `better-sqlite3` is loaded via dynamic `import()` at factory
+ * call time, so merely importing this module stays side-effect free.
+ *
+ * The factory accepts either a database file path (`':memory:'` works) or an
+ * already-open `better-sqlite3` Database. Path-opened databases get
+ * `journal_mode = WAL` and a `busy_timeout` applied; caller-provided
+ * databases are used as-is (only `busy_timeout` is set) since the caller
+ * owns their pragma configuration.
+ *
+ * ## Search capabilities
+ *
+ * On top of the shared SQLite capability set, the local backend declares
+ * `search.fullText` and `search.vector` (see `src/internal/sqlite-search.ts`
+ * for the mechanics):
+ *
+ *   - **Full-text search** is backed by one FTS5 table per graph table,
+ *     kept in sync by pure-SQL triggers installed with the table's DDL.
+ *     Because the triggers live in the database file, writes from ANY
+ *     process or connection stay indexed. The trade-off is a per-write
+ *     overhead (text extraction via `json_tree` + an FTS index update) on
+ *     every insert/update/delete.
+ *   - **Vector search** is a brute-force scan scored by a deterministic
+ *     scalar UDF registered on this connection. UDFs are connection-local:
+ *     `findNearest` only works through a backend created by this factory
+ *     (other connections to the same file can read/write normally — only
+ *     vector *search* needs the UDF).
+ */
+
+/**
+ * Capability union for the local better-sqlite3 backend: everything the
+ * shared SQLite edition declares, plus native FTS5 full-text search and
+ * brute-force vector search. `search.geo` stays out — there is no geo
+ * index in stock SQLite, and a UDF-scored scan without a haversine
+ * contract pinned by Firestore parity tests would be guesswork.
+ */
+type LocalSqliteCapability = SqliteCapability | 'search.fullText' | 'search.vector';
+interface LocalSqliteBackendOptions extends SqliteBackendOptions {
+    /** Root graph table name. Defaults to `'firegraph'`. */
+    tableName?: string;
+    /**
+     * `PRAGMA busy_timeout` in milliseconds — how long a connection waits on a
+     * lock held by another process before erroring. Defaults to 5000.
+     */
+    busyTimeoutMs?: number;
+    /**
+     * Extra pragmas applied after the defaults, e.g.
+     * `{ synchronous: 'NORMAL', cache_size: -64000 }`. Applied in object
+     * order via `PRAGMA <key> = <value>`.
+     */
+    pragmas?: Record<string, string | number>;
+    /**
+     * When opening by path: throw if the file does not already exist instead
+     * of creating it. Defaults to false.
+     */
+    fileMustExist?: boolean;
+}
+interface LocalSqliteBackend {
+    /** The graph storage backend — pass to `createGraphClient`. */
+    backend: StorageBackend<LocalSqliteCapability>;
+    /** The underlying better-sqlite3 database, for raw access. */
+    db: Database;
+    /**
+     * Close the database. No-op when the factory was given an already-open
+     * Database (the caller owns its lifecycle).
+     */
+    close(): void;
+}
+/**
+ * Build a transaction-capable `SqliteExecutor` over a better-sqlite3
+ * Database. Interactive transactions use manual `BEGIN IMMEDIATE` /
+ * `COMMIT` / `ROLLBACK` because `db.transaction()` requires a synchronous
+ * callback while `SqliteExecutor.transaction` callbacks are async.
+ *
+ * Exported for callers that want to wire `createSqliteBackend` directly
+ * (e.g. to share one executor across several root tables).
+ */
+declare function createBetterSqliteExecutor(db: Database): SqliteExecutor;
+/**
+ * Open (or wrap) a local SQLite database and return a graph storage backend
+ * over it.
+ *
+ * ```typescript
+ * import { createLocalSqliteBackend } from 'firegraph/sqlite-local';
+ * import { createGraphClient } from 'firegraph/sqlite';
+ *
+ * const { backend, close } = await createLocalSqliteBackend('./graph.db');
+ * const client = createGraphClient(backend);
+ * // ... use the client — including fullTextSearch() and findNearest() ...
+ * close();
+ * ```
+ *
+ * Requires `better-sqlite3` to be installed (declared as an optional peer
+ * dependency). The factory is async because the driver is loaded via
+ * dynamic `import()`.
+ */
+declare function createLocalSqliteBackend(pathOrDb: string | Database, options?: LocalSqliteBackendOptions): Promise<LocalSqliteBackend>;
+
+export { type LocalSqliteBackend, type LocalSqliteBackendOptions, type LocalSqliteCapability, createBetterSqliteExecutor, createLocalSqliteBackend };