@typicalday/firegraph 0.14.1 → 0.15.0

package/dist/sqlite/local.d.ts

@@ -0,0 +1,83 @@
+import { Database } from 'better-sqlite3';
+import { S as StorageBackend } from '../backend-BpYLdwCW.js';
+import { a as SqliteCapability, S as SqliteBackendOptions, b as SqliteExecutor } from '../backend-YH5HtawN.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.
+ */
+
+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<SqliteCapability>;
+    /** 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 ...
+ * 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, createBetterSqliteExecutor, createLocalSqliteBackend };

package/dist/sqlite/local.js

@@ -0,0 +1,121 @@
+import {
+  createSqliteBackend
+} from "../chunk-FODIMIWY.js";
+import "../chunk-ULRDQ6HZ.js";
+import "../chunk-2DHMNTV6.js";
+import "../chunk-N5HFDWQX.js";
+import "../chunk-NGAJCALM.js";
+import {
+  FiregraphError
+} from "../chunk-SIHE4UY4.js";
+import "../chunk-EQJUUVFG.js";
+
+// src/sqlite/local.ts
+function createBetterSqliteExecutor(db) {
+  return {
+    async all(sql, params) {
+      return db.prepare(sql).all(...params);
+    },
+    async run(sql, params) {
+      db.prepare(sql).run(...params);
+    },
+    async batch(statements) {
+      const tx = db.transaction((stmts) => {
+        for (const s of stmts) {
+          db.prepare(s.sql).run(...s.params);
+        }
+      });
+      tx(statements);
+    },
+    async transaction(fn) {
+      db.exec("BEGIN IMMEDIATE");
+      try {
+        const result = await fn({
+          async all(sql, params) {
+            return db.prepare(sql).all(...params);
+          },
+          async run(sql, params) {
+            db.prepare(sql).run(...params);
+          }
+        });
+        db.exec("COMMIT");
+        return result;
+      } catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+      }
+    }
+  };
+}
+function isDatabase(value) {
+  return typeof value === "object" && value !== null && typeof value.prepare === "function" && typeof value.exec === "function";
+}
+var PRAGMA_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var PRAGMA_VALUE_PATTERN = /^-?[A-Za-z0-9_]+$/;
+function applyPragmas(db, pragmas) {
+  for (const [key, value] of Object.entries(pragmas)) {
+    if (!PRAGMA_KEY_PATTERN.test(key)) {
+      throw new FiregraphError(`Invalid pragma name: ${JSON.stringify(key)}`, "INVALID_ARGUMENT");
+    }
+    if (!PRAGMA_VALUE_PATTERN.test(String(value)) || typeof value === "number" && !Number.isFinite(value)) {
+      throw new FiregraphError(
+        `Invalid pragma value for ${key}: ${JSON.stringify(value)}`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    db.pragma(`${key} = ${value}`);
+  }
+}
+async function createLocalSqliteBackend(pathOrDb, options = {}) {
+  const {
+    tableName = "firegraph",
+    busyTimeoutMs = 5e3,
+    pragmas,
+    fileMustExist,
+    ...backendOptions
+  } = options;
+  let db;
+  let ownsDb;
+  if (typeof pathOrDb === "string") {
+    let Database;
+    try {
+      Database = (await import("better-sqlite3")).default;
+    } catch (err) {
+      throw new FiregraphError(
+        `createLocalSqliteBackend requires the optional peer dependency 'better-sqlite3' \u2014 install it to use the local SQLite backend (${err instanceof Error ? err.message : String(err)})`,
+        "MISSING_DEPENDENCY"
+      );
+    }
+    db = new Database(pathOrDb, fileMustExist ? { fileMustExist: true } : {});
+    ownsDb = true;
+    db.pragma("journal_mode = WAL");
+  } else if (isDatabase(pathOrDb)) {
+    db = pathOrDb;
+    ownsDb = false;
+  } else {
+    throw new FiregraphError(
+      "createLocalSqliteBackend expects a file path or an open better-sqlite3 Database",
+      "INVALID_ARGUMENT"
+    );
+  }
+  db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
+  if (pragmas) {
+    applyPragmas(db, pragmas);
+  }
+  const backend = createSqliteBackend(createBetterSqliteExecutor(db), tableName, backendOptions);
+  let closed = false;
+  return {
+    backend,
+    db,
+    close() {
+      if (closed || !ownsDb) return;
+      closed = true;
+      db.close();
+    }
+  };
+}
+export {
+  createBetterSqliteExecutor,
+  createLocalSqliteBackend
+};
+//# sourceMappingURL=local.js.map

package/dist/sqlite/local.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sqlite/local.ts"],"sourcesContent":["/**\n * Local SQLite backend over `better-sqlite3`.\n *\n * This entry point is published as `firegraph/sqlite-local` and is the only\n * module in the library that references `better-sqlite3` — keep it out of\n * `firegraph/sqlite` so that D1 / workerd bundles never see the native\n * dependency. `better-sqlite3` is loaded via dynamic `import()` at factory\n * call time, so merely importing this module stays side-effect free.\n *\n * The factory accepts either a database file path (`':memory:'` works) or an\n * already-open `better-sqlite3` Database. Path-opened databases get\n * `journal_mode = WAL` and a `busy_timeout` applied; caller-provided\n * databases are used as-is (only `busy_timeout` is set) since the caller\n * owns their pragma configuration.\n */\n\nimport type { Database as BetterSqliteDb, default as BetterSqliteDatabase } from 'better-sqlite3';\n\nimport { FiregraphError } from '../errors.js';\nimport type { StorageBackend } from '../internal/backend.js';\nimport type { SqliteExecutor, SqliteTxExecutor } from '../internal/sqlite-executor.js';\nimport type { SqliteBackendOptions, SqliteCapability } from './backend.js';\nimport { createSqliteBackend } from './backend.js';\n\nexport interface LocalSqliteBackendOptions extends SqliteBackendOptions {\n  /** Root graph table name. Defaults to `'firegraph'`. */\n  tableName?: string;\n  /**\n   * `PRAGMA busy_timeout` in milliseconds — how long a connection waits on a\n   * lock held by another process before erroring. Defaults to 5000.\n   */\n  busyTimeoutMs?: number;\n  /**\n   * Extra pragmas applied after the defaults, e.g.\n   * `{ synchronous: 'NORMAL', cache_size: -64000 }`. Applied in object\n   * order via `PRAGMA <key> = <value>`.\n   */\n  pragmas?: Record<string, string | number>;\n  /**\n   * When opening by path: throw if the file does not already exist instead\n   * of creating it. Defaults to false.\n   */\n  fileMustExist?: boolean;\n}\n\nexport interface LocalSqliteBackend {\n  /** The graph storage backend — pass to `createGraphClient`. */\n  backend: StorageBackend<SqliteCapability>;\n  /** The underlying better-sqlite3 database, for raw access. */\n  db: BetterSqliteDb;\n  /**\n   * Close the database. No-op when the factory was given an already-open\n   * Database (the caller owns its lifecycle).\n   */\n  close(): void;\n}\n\n/**\n * Build a transaction-capable `SqliteExecutor` over a better-sqlite3\n * Database. Interactive transactions use manual `BEGIN IMMEDIATE` /\n * `COMMIT` / `ROLLBACK` because `db.transaction()` requires a synchronous\n * callback while `SqliteExecutor.transaction` callbacks are async.\n *\n * Exported for callers that want to wire `createSqliteBackend` directly\n * (e.g. to share one executor across several root tables).\n */\nexport function createBetterSqliteExecutor(db: BetterSqliteDb): SqliteExecutor {\n  return {\n    async all(sql: string, params: unknown[]): Promise<Record<string, unknown>[]> {\n      return db.prepare(sql).all(...params) as Record<string, unknown>[];\n    },\n    async run(sql: string, params: unknown[]): Promise<void> {\n      db.prepare(sql).run(...params);\n    },\n    async batch(statements): Promise<void> {\n      const tx = db.transaction((stmts: typeof statements) => {\n        for (const s of stmts) {\n          db.prepare(s.sql).run(...s.params);\n        }\n      });\n      tx(statements);\n    },\n    async transaction<T>(fn: (tx: SqliteTxExecutor) => Promise<T>): Promise<T> {\n      db.exec('BEGIN IMMEDIATE');\n      try {\n        const result = await fn({\n          async all(sql: string, params: unknown[]) {\n            return db.prepare(sql).all(...params) as Record<string, unknown>[];\n          },\n          async run(sql: string, params: unknown[]) {\n            db.prepare(sql).run(...params);\n          },\n        });\n        db.exec('COMMIT');\n        return result;\n      } catch (err) {\n        db.exec('ROLLBACK');\n        throw err;\n      }\n    },\n  };\n}\n\nfunction isDatabase(value: unknown): value is BetterSqliteDb {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { prepare?: unknown }).prepare === 'function' &&\n    typeof (value as { exec?: unknown }).exec === 'function'\n  );\n}\n\nconst PRAGMA_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;\n// Pragma values are identifiers (WAL, NORMAL) or integers — never compound\n// expressions, so anything else is rejected rather than interpolated.\nconst PRAGMA_VALUE_PATTERN = /^-?[A-Za-z0-9_]+$/;\n\nfunction applyPragmas(db: BetterSqliteDb, pragmas: Record<string, string | number>): void {\n  for (const [key, value] of Object.entries(pragmas)) {\n    if (!PRAGMA_KEY_PATTERN.test(key)) {\n      throw new FiregraphError(`Invalid pragma name: ${JSON.stringify(key)}`, 'INVALID_ARGUMENT');\n    }\n    if (\n      !PRAGMA_VALUE_PATTERN.test(String(value)) ||\n      (typeof value === 'number' && !Number.isFinite(value))\n    ) {\n      throw new FiregraphError(\n        `Invalid pragma value for ${key}: ${JSON.stringify(value)}`,\n        'INVALID_ARGUMENT',\n      );\n    }\n    db.pragma(`${key} = ${value}`);\n  }\n}\n\n/**\n * Open (or wrap) a local SQLite database and return a graph storage backend\n * over it.\n *\n * ```typescript\n * import { createLocalSqliteBackend } from 'firegraph/sqlite-local';\n * import { createGraphClient } from 'firegraph/sqlite';\n *\n * const { backend, close } = await createLocalSqliteBackend('./graph.db');\n * const client = createGraphClient(backend);\n * // ... use the client ...\n * close();\n * ```\n *\n * Requires `better-sqlite3` to be installed (declared as an optional peer\n * dependency). The factory is async because the driver is loaded via\n * dynamic `import()`.\n */\nexport async function createLocalSqliteBackend(\n  pathOrDb: string | BetterSqliteDb,\n  options: LocalSqliteBackendOptions = {},\n): Promise<LocalSqliteBackend> {\n  const {\n    tableName = 'firegraph',\n    busyTimeoutMs = 5000,\n    pragmas,\n    fileMustExist,\n    ...backendOptions\n  } = options;\n\n  let db: BetterSqliteDb;\n  let ownsDb: boolean;\n  if (typeof pathOrDb === 'string') {\n    let Database: typeof BetterSqliteDatabase;\n    try {\n      Database = (await import('better-sqlite3')).default;\n    } catch (err) {\n      throw new FiregraphError(\n        `createLocalSqliteBackend requires the optional peer dependency 'better-sqlite3' — install it to use the local SQLite backend (${\n          err instanceof Error ? err.message : String(err)\n        })`,\n        'MISSING_DEPENDENCY',\n      );\n    }\n    db = new Database(pathOrDb, fileMustExist ? { fileMustExist: true } : {});\n    ownsDb = true;\n    // WAL lets concurrent readers coexist with a writer — the right default\n    // for a long-lived local graph file. On ':memory:' databases SQLite\n    // reports 'memory' and ignores the request, which is fine.\n    db.pragma('journal_mode = WAL');\n  } else if (isDatabase(pathOrDb)) {\n    db = pathOrDb;\n    ownsDb = false;\n  } else {\n    throw new FiregraphError(\n      'createLocalSqliteBackend expects a file path or an open better-sqlite3 Database',\n      'INVALID_ARGUMENT',\n    );\n  }\n\n  db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);\n  if (pragmas) {\n    applyPragmas(db, pragmas);\n  }\n\n  const backend = createSqliteBackend(createBetterSqliteExecutor(db), tableName, backendOptions);\n  let closed = false;\n  return {\n    backend,\n    db,\n    close(): void {\n      if (closed || !ownsDb) return;\n      closed = true;\n      db.close();\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typicalday/firegraph",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Generic Firestore adjacency graph client with smart query planning",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -96,6 +96,16 @@
         "types": "./dist/sqlite/index.d.cts",
         "default": "./dist/sqlite/index.cjs"
       }
+    },
+    "./sqlite-local": {
+      "import": {
+        "types": "./dist/sqlite/local.d.ts",
+        "default": "./dist/sqlite/local.js"
+      },
+      "require": {
+        "types": "./dist/sqlite/local.d.cts",
+        "default": "./dist/sqlite/local.cjs"
+      }
     }
   },
   "bin": {
@@ -136,6 +146,7 @@
   "peerDependencies": {
     "@cloudflare/workers-types": "^4.20240419.0",
     "@google-cloud/firestore": "^8.5.0",
+    "better-sqlite3": ">=9.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "svelte": "^5.0.0"
@@ -144,6 +155,9 @@
     "@cloudflare/workers-types": {
       "optional": true
     },
+    "better-sqlite3": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },