@typicalday/firegraph 0.14.0 → 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":";;;;;;;;;;;;;AAkEO,SAAS,2BAA2B,IAAoC;AAC7E,SAAO;AAAA,IACL,MAAM,IAAI,KAAa,QAAuD;AAC5E,aAAO,GAAG,QAAQ,GAAG,EAAE,IAAI,GAAG,MAAM;AAAA,IACtC;AAAA,IACA,MAAM,IAAI,KAAa,QAAkC;AACvD,SAAG,QAAQ,GAAG,EAAE,IAAI,GAAG,MAAM;AAAA,IAC/B;AAAA,IACA,MAAM,MAAM,YAA2B;AACrC,YAAM,KAAK,GAAG,YAAY,CAAC,UAA6B;AACtD,mBAAW,KAAK,OAAO;AACrB,aAAG,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,EAAE,MAAM;AAAA,QACnC;AAAA,MACF,CAAC;AACD,SAAG,UAAU;AAAA,IACf;AAAA,IACA,MAAM,YAAe,IAAsD;AACzE,SAAG,KAAK,iBAAiB;AACzB,UAAI;AACF,cAAM,SAAS,MAAM,GAAG;AAAA,UACtB,MAAM,IAAI,KAAa,QAAmB;AACxC,mBAAO,GAAG,QAAQ,GAAG,EAAE,IAAI,GAAG,MAAM;AAAA,UACtC;AAAA,UACA,MAAM,IAAI,KAAa,QAAmB;AACxC,eAAG,QAAQ,GAAG,EAAE,IAAI,GAAG,MAAM;AAAA,UAC/B;AAAA,QACF,CAAC;AACD,WAAG,KAAK,QAAQ;AAChB,eAAO;AAAA,MACT,SAAS,KAAK;AACZ,WAAG,KAAK,UAAU;AAClB,cAAM;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,WAAW,OAAyC;AAC3D,SACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAgC,YAAY,cACpD,OAAQ,MAA6B,SAAS;AAElD;AAEA,IAAM,qBAAqB;AAG3B,IAAM,uBAAuB;AAE7B,SAAS,aAAa,IAAoB,SAAgD;AACxF,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,mBAAmB,KAAK,GAAG,GAAG;AACjC,YAAM,IAAI,eAAe,wBAAwB,KAAK,UAAU,GAAG,CAAC,IAAI,kBAAkB;AAAA,IAC5F;AACA,QACE,CAAC,qBAAqB,KAAK,OAAO,KAAK,CAAC,KACvC,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GACpD;AACA,YAAM,IAAI;AAAA,QACR,4BAA4B,GAAG,KAAK,KAAK,UAAU,KAAK,CAAC;AAAA,QACzD;AAAA,MACF;AAAA,IACF;AACA,OAAG,OAAO,GAAG,GAAG,MAAM,KAAK,EAAE;AAAA,EAC/B;AACF;AAoBA,eAAsB,yBACpB,UACA,UAAqC,CAAC,GACT;AAC7B,QAAM;AAAA,IACJ,YAAY;AAAA,IACZ,gBAAgB;AAAA,IAChB;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,IAAI;AAEJ,MAAI;AACJ,MAAI;AACJ,MAAI,OAAO,aAAa,UAAU;AAChC,QAAI;AACJ,QAAI;AACF,kBAAY,MAAM,OAAO,gBAAgB,GAAG;AAAA,IAC9C,SAAS,KAAK;AACZ,YAAM,IAAI;AAAA,QACR,sIACE,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CACjD;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,SAAK,IAAI,SAAS,UAAU,gBAAgB,EAAE,eAAe,KAAK,IAAI,CAAC,CAAC;AACxE,aAAS;AAIT,OAAG,OAAO,oBAAoB;AAAA,EAChC,WAAW,WAAW,QAAQ,GAAG;AAC/B,SAAK;AACL,aAAS;AAAA,EACX,OAAO;AACL,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,KAAG,OAAO,kBAAkB,KAAK,IAAI,GAAG,KAAK,MAAM,aAAa,CAAC,CAAC,EAAE;AACpE,MAAI,SAAS;AACX,iBAAa,IAAI,OAAO;AAAA,EAC1B;AAEA,QAAM,UAAU,oBAAoB,2BAA2B,EAAE,GAAG,WAAW,cAAc;AAC7F,MAAI,SAAS;AACb,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,QAAc;AACZ,UAAI,UAAU,CAAC,OAAQ;AACvB,eAAS;AACT,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typicalday/firegraph",
-  "version": "0.14.0",
+  "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
     },

package/dist/chunk-4MMQ5W74.js

@@ -1,288 +0,0 @@
-import {
-  FiregraphError,
-  isDeleteSentinel
-} from "./chunk-TK64DNVK.js";
-import {
-  SERIALIZATION_TAG
-} from "./chunk-EQJUUVFG.js";
-
-// src/internal/sqlite-index-ddl.ts
-var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-function quoteIdent(name) {
-  if (!IDENT_RE.test(name)) {
-    throw new FiregraphError(
-      `Invalid SQL identifier in index DDL: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
-      "INVALID_INDEX"
-    );
-  }
-  return `"${name}"`;
-}
-function fnv1a32(str) {
-  let h = 2166136261;
-  for (let i = 0; i < str.length; i++) {
-    h ^= str.charCodeAt(i);
-    h = Math.imul(h, 16777619);
-  }
-  return (h >>> 0).toString(16).padStart(8, "0");
-}
-function normalizeFields(fields) {
-  return fields.map((f) => {
-    if (typeof f === "string") return { path: f, desc: false };
-    if (!f.path || typeof f.path !== "string") {
-      throw new FiregraphError(
-        `IndexSpec field must be a string or { path: string, desc?: boolean }; got ${JSON.stringify(f)}`,
-        "INVALID_INDEX"
-      );
-    }
-    return { path: f.path, desc: !!f.desc };
-  });
-}
-function specFingerprint(spec, leadingColumns) {
-  const normalized = {
-    lead: leadingColumns,
-    fields: normalizeFields(spec.fields),
-    where: spec.where ?? ""
-  };
-  return fnv1a32(JSON.stringify(normalized));
-}
-function compileFieldExpr(path, fieldToColumn) {
-  const col = fieldToColumn[path];
-  if (col) return quoteIdent(col);
-  if (path === "data") {
-    return `json_extract("data", '$')`;
-  }
-  if (path.startsWith("data.")) {
-    const suffix = path.slice(5);
-    const parts = suffix.split(".");
-    for (const part of parts) {
-      if (!JSON_PATH_KEY_RE.test(part)) {
-        throw new FiregraphError(
-          `IndexSpec data path "${path}" has invalid component "${part}". Each component must match /^[A-Za-z_][A-Za-z0-9_-]*$/.`,
-          "INVALID_INDEX"
-        );
-      }
-    }
-    return `json_extract("data", '$.${suffix}')`;
-  }
-  throw new FiregraphError(
-    `IndexSpec field "${path}" is not a known firegraph field. Use a top-level field (aType, aUid, axbType, bType, bUid, createdAt, updatedAt, v) or a dotted data path like 'data.status'.`,
-    "INVALID_INDEX"
-  );
-}
-function buildIndexDDL(spec, options) {
-  const { table, fieldToColumn, leadingColumns = [] } = options;
-  if (!spec.fields || spec.fields.length === 0) {
-    throw new FiregraphError("IndexSpec.fields must be a non-empty array", "INVALID_INDEX");
-  }
-  const normalized = normalizeFields(spec.fields);
-  const hash = specFingerprint(spec, leadingColumns);
-  const indexName = `${table}_idx_${hash}`;
-  const cols = [];
-  for (const col of leadingColumns) {
-    cols.push(quoteIdent(col));
-  }
-  for (const f of normalized) {
-    const expr = compileFieldExpr(f.path, fieldToColumn);
-    cols.push(f.desc ? `${expr} DESC` : expr);
-  }
-  let ddl = `CREATE INDEX IF NOT EXISTS ${quoteIdent(indexName)} ON ${quoteIdent(table)}(${cols.join(", ")})`;
-  if (spec.where) {
-    ddl += ` WHERE ${spec.where}`;
-  }
-  return ddl;
-}
-function dedupeIndexSpecs(specs, leadingColumns = []) {
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const spec of specs) {
-    const fp = specFingerprint(spec, leadingColumns);
-    if (seen.has(fp)) continue;
-    seen.add(fp);
-    out.push(spec);
-  }
-  return out;
-}
-
-// src/internal/sqlite-data-ops.ts
-var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
-  "Timestamp",
-  "GeoPoint",
-  "VectorValue",
-  "DocumentReference",
-  "FieldValue"
-]);
-function isFirestoreSpecialType(value) {
-  const ctorName = value.constructor?.name;
-  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
-  return null;
-}
-var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-function validateJsonPathKey(key, backendLabel) {
-  if (key.length === 0) {
-    throw new FiregraphError(
-      `${backendLabel}: empty JSON path component is not allowed`,
-      "INVALID_QUERY"
-    );
-  }
-  if (!JSON_PATH_KEY_RE2.test(key)) {
-    throw new FiregraphError(
-      `${backendLabel}: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceNode/replaceEdge (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
-      "INVALID_QUERY"
-    );
-  }
-}
-function jsonBind(value, backendLabel) {
-  if (value === void 0) return "null";
-  if (value !== null && typeof value === "object") {
-    const firestoreType = isFirestoreSpecialType(value);
-    if (firestoreType) {
-      throw new FiregraphError(
-        `${backendLabel} cannot persist a Firestore ${firestoreType} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp).`,
-        "INVALID_ARGUMENT"
-      );
-    }
-  }
-  return JSON.stringify(value);
-}
-function compileDataOpsExpr(ops, base, params, backendLabel) {
-  if (ops.length === 0) return null;
-  const deletes = [];
-  const sets = [];
-  for (const op of ops) (op.delete ? deletes : sets).push(op);
-  let expr = base;
-  if (deletes.length > 0) {
-    const placeholders = deletes.map(() => "?").join(", ");
-    expr = `json_remove(${expr}, ${placeholders})`;
-    for (const op of deletes) {
-      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
-      params.push(`$.${op.path.join(".")}`);
-    }
-  }
-  if (sets.length > 0) {
-    const pieces = sets.map(() => "?, json(?)").join(", ");
-    expr = `json_set(${expr}, ${pieces})`;
-    for (const op of sets) {
-      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
-      params.push(`$.${op.path.join(".")}`);
-      params.push(jsonBind(op.value, backendLabel));
-    }
-  }
-  return expr;
-}
-
-// src/internal/sqlite-payload-guard.ts
-var FIRESTORE_TYPE_NAMES2 = /* @__PURE__ */ new Set([
-  "Timestamp",
-  "GeoPoint",
-  "VectorValue",
-  "DocumentReference",
-  "FieldValue"
-]);
-function assertJsonSafePayload(data, label) {
-  walk(data, [], label);
-}
-function walk(node, path, label) {
-  if (node === null || node === void 0) return;
-  if (isDeleteSentinel(node)) {
-    throw new FiregraphError(
-      `${label} backend cannot persist a deleteField() sentinel inside a full-data payload (replaceNode/replaceEdge or first-insert). The sentinel is only valid inside an updateNode/updateEdge dataOps patch. Path: ${formatPath(path)}.`,
-      "INVALID_ARGUMENT"
-    );
-  }
-  const t = typeof node;
-  if (t === "symbol" || t === "function") {
-    throw new FiregraphError(
-      `${label} backend cannot persist a value of type ${t}. JSON.stringify drops it silently. Path: ${formatPath(path)}.`,
-      "INVALID_ARGUMENT"
-    );
-  }
-  if (t === "bigint") {
-    throw new FiregraphError(
-      `${label} backend cannot persist a value of type bigint. JSON.stringify cannot serialize this type (throws TypeError). Path: ${formatPath(path)}.`,
-      "INVALID_ARGUMENT"
-    );
-  }
-  if (t !== "object") return;
-  if (Array.isArray(node)) {
-    for (let i = 0; i < node.length; i++) {
-      walk(node[i], [...path, String(i)], label);
-    }
-    return;
-  }
-  const obj = node;
-  if (Object.prototype.hasOwnProperty.call(obj, SERIALIZATION_TAG)) {
-    const tagValue = obj[SERIALIZATION_TAG];
-    throw new FiregraphError(
-      `${label} backend cannot persist an object with a \`${SERIALIZATION_TAG}\` key (value: ${formatTagValue(tagValue)}). Recognised tags are valid only on the Firestore backend (migration-sandbox output); a literal \`${SERIALIZATION_TAG}\` field in user data is reserved and not allowed. Path: ${formatPath(path)}.`,
-      "INVALID_ARGUMENT"
-    );
-  }
-  const proto = Object.getPrototypeOf(node);
-  if (proto !== null && proto !== Object.prototype) {
-    const ctor = node.constructor;
-    const ctorName = ctor && typeof ctor.name === "string" ? ctor.name : "<anonymous>";
-    if (FIRESTORE_TYPE_NAMES2.has(ctorName)) {
-      throw new FiregraphError(
-        `${label} backend cannot persist a Firestore ${ctorName} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp, \`{lat,lng}\` for GeoPoint). Path: ${formatPath(path)}.`,
-        "INVALID_ARGUMENT"
-      );
-    }
-    if (node instanceof Date) return;
-    throw new FiregraphError(
-      `${label} backend cannot persist a class instance of type ${ctorName}. Only plain objects, arrays, and primitives round-trip safely through JSON storage. Path: ${formatPath(path)}.`,
-      "INVALID_ARGUMENT"
-    );
-  }
-  for (const key of Object.keys(obj)) {
-    walk(obj[key], [...path, key], label);
-  }
-}
-function formatPath(path) {
-  return path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
-}
-function formatTagValue(value) {
-  if (value === null) return "null";
-  if (value === void 0) return "undefined";
-  if (typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-  return typeof value;
-}
-
-// src/timestamp.ts
-var GraphTimestampImpl = class _GraphTimestampImpl {
-  constructor(seconds, nanoseconds) {
-    this.seconds = seconds;
-    this.nanoseconds = nanoseconds;
-  }
-  toDate() {
-    return new Date(this.toMillis());
-  }
-  toMillis() {
-    return this.seconds * 1e3 + Math.floor(this.nanoseconds / 1e6);
-  }
-  toJSON() {
-    return { seconds: this.seconds, nanoseconds: this.nanoseconds };
-  }
-  static fromMillis(ms) {
-    const seconds = Math.floor(ms / 1e3);
-    const nanoseconds = (ms - seconds * 1e3) * 1e6;
-    return new _GraphTimestampImpl(seconds, nanoseconds);
-  }
-  static now() {
-    return _GraphTimestampImpl.fromMillis(Date.now());
-  }
-};
-
-export {
-  isFirestoreSpecialType,
-  validateJsonPathKey,
-  compileDataOpsExpr,
-  assertJsonSafePayload,
-  GraphTimestampImpl,
-  buildIndexDDL,
-  dedupeIndexSpecs
-};
-//# sourceMappingURL=chunk-4MMQ5W74.js.map

package/dist/chunk-4MMQ5W74.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/sqlite-index-ddl.ts","../src/internal/sqlite-data-ops.ts","../src/internal/sqlite-payload-guard.ts","../src/timestamp.ts"],"sourcesContent":["/**\n * Translator from `IndexSpec` to SQLite `CREATE INDEX` DDL.\n *\n * Shared between the DO SQLite backend (`src/cloudflare/schema.ts`) and the\n * legacy single-table SQLite backend (`src/internal/sqlite-schema.ts`). The\n * two backends differ only in:\n *\n *  1. Their field→column mapping (no `scope` column in the DO schema).\n *  2. Whether a fixed `scope` leading column is prepended to every index\n *     (legacy backend only — DO rows are scoped by DO-instance identity).\n *\n * Both differences are handled via the `fieldToColumn` and `leadingColumns`\n * options; the rest of the emission logic is identical.\n *\n * ## JSON path expression indexes\n *\n * Data-field specs (`data.foo`, `data.nested.bar`) compile to\n * `json_extract(\"data\", '$.foo')` expression indexes. The JSON path\n * literal is inlined — not parametrized — so the SQLite query planner can\n * match the index against the expression emitted by the query compiler\n * (which also inlines the literal after this PR). Path components are\n * validated against a safe identifier pattern so inlining is not an\n * injection risk.\n *\n * ## Index naming\n *\n * Names are `{table}_idx_{hash}` where `hash` is a short FNV-1a of a\n * canonicalized spec. This keeps names stable across runs (so\n * `CREATE INDEX IF NOT EXISTS` is idempotent) and prevents collisions\n * between similar specs. The hash includes the field list, per-field\n * direction, and the `where` predicate.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type { IndexFieldSpec, IndexSpec } from '../types.js';\n\n/**\n * Valid SQLite identifier pattern — used for table and column names.\n * Mirrors the validation in `sqlite-schema.ts` / `cloudflare/schema.ts` so\n * this module doesn't need to import one over the other.\n */\nconst IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Safe JSON path component. Must match `JSON_PATH_KEY_RE` in the SQLite\n * query compilers — an index is only useful if the query emits an\n * identical `json_extract` expression.\n */\nconst JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;\n\nfunction quoteIdent(name: string): string {\n  if (!IDENT_RE.test(name)) {\n    throw new FiregraphError(\n      `Invalid SQL identifier in index DDL: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,\n      'INVALID_INDEX',\n    );\n  }\n  return `\"${name}\"`;\n}\n\n/**\n * FNV-1a 32-bit hash, returned as 8-char hex. Non-cryptographic;\n * used only to produce short, stable index names.\n */\nfunction fnv1a32(str: string): string {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return (h >>> 0).toString(16).padStart(8, '0');\n}\n\nfunction normalizeFields(\n  fields: Array<string | IndexFieldSpec>,\n): Array<{ path: string; desc: boolean }> {\n  return fields.map((f) => {\n    if (typeof f === 'string') return { path: f, desc: false };\n    if (!f.path || typeof f.path !== 'string') {\n      throw new FiregraphError(\n        `IndexSpec field must be a string or { path: string, desc?: boolean }; got ${JSON.stringify(f)}`,\n        'INVALID_INDEX',\n      );\n    }\n    return { path: f.path, desc: !!f.desc };\n  });\n}\n\nfunction specFingerprint(spec: IndexSpec, leadingColumns: string[]): string {\n  // Canonical form: JSON of normalized fields + leading cols + where.\n  // Leading columns are part of the fingerprint so the same spec under\n  // two different backends gets distinct names (though in practice only\n  // one backend compiles a given spec).\n  const normalized = {\n    lead: leadingColumns,\n    fields: normalizeFields(spec.fields),\n    where: spec.where ?? '',\n  };\n  return fnv1a32(JSON.stringify(normalized));\n}\n\n/**\n * Compile one field path to its SQLite column expression.\n *\n *  - Firegraph top-level fields (`aType`, `createdAt`, …) → mapped column.\n *  - `data.foo` / `data.foo.bar` → `json_extract(\"data\", '$.foo.bar')`.\n *  - `data` alone → `json_extract(\"data\", '$')`.\n */\nfunction compileFieldExpr(path: string, fieldToColumn: Record<string, string>): string {\n  const col = fieldToColumn[path];\n  if (col) return quoteIdent(col);\n\n  if (path === 'data') {\n    return `json_extract(\"data\", '$')`;\n  }\n  if (path.startsWith('data.')) {\n    const suffix = path.slice(5);\n    const parts = suffix.split('.');\n    for (const part of parts) {\n      if (!JSON_PATH_KEY_RE.test(part)) {\n        throw new FiregraphError(\n          `IndexSpec data path \"${path}\" has invalid component \"${part}\". ` +\n            `Each component must match /^[A-Za-z_][A-Za-z0-9_-]*$/.`,\n          'INVALID_INDEX',\n        );\n      }\n    }\n    // Inline the path literal (no parameter). Validated components above\n    // are safe to embed — no quote or escape characters.\n    return `json_extract(\"data\", '$.${suffix}')`;\n  }\n\n  throw new FiregraphError(\n    `IndexSpec field \"${path}\" is not a known firegraph field. ` +\n      `Use a top-level field (aType, aUid, axbType, bType, bUid, createdAt, updatedAt, v) ` +\n      `or a dotted data path like 'data.status'.`,\n    'INVALID_INDEX',\n  );\n}\n\nexport interface SqliteIndexDDLOptions {\n  /** Target table. */\n  table: string;\n  /** Map from firegraph field name to SQLite column name. */\n  fieldToColumn: Record<string, string>;\n  /**\n   * Columns prepended to every index's field list (leading ASC). Used by\n   * the legacy shared-table SQLite backend to lead every index with\n   * `scope`, matching the predicate its query compiler emits.\n   *\n   * Identifier names only — no JSON paths or expressions.\n   */\n  leadingColumns?: string[];\n}\n\n/**\n * Emit the `CREATE INDEX IF NOT EXISTS` DDL for one `IndexSpec`.\n *\n * Returns a single SQL string. Name is deterministic (same spec → same\n * name across runs), so re-running the bootstrap is idempotent.\n */\nexport function buildIndexDDL(spec: IndexSpec, options: SqliteIndexDDLOptions): string {\n  const { table, fieldToColumn, leadingColumns = [] } = options;\n\n  if (!spec.fields || spec.fields.length === 0) {\n    throw new FiregraphError('IndexSpec.fields must be a non-empty array', 'INVALID_INDEX');\n  }\n\n  const normalized = normalizeFields(spec.fields);\n  const hash = specFingerprint(spec, leadingColumns);\n  const indexName = `${table}_idx_${hash}`;\n\n  const cols: string[] = [];\n  for (const col of leadingColumns) {\n    cols.push(quoteIdent(col));\n  }\n  for (const f of normalized) {\n    const expr = compileFieldExpr(f.path, fieldToColumn);\n    cols.push(f.desc ? `${expr} DESC` : expr);\n  }\n\n  let ddl = `CREATE INDEX IF NOT EXISTS ${quoteIdent(indexName)} ON ${quoteIdent(table)}(${cols.join(', ')})`;\n\n  if (spec.where) {\n    // The predicate is inlined verbatim. It comes from library/app\n    // configuration — never from user data — so we don't attempt to\n    // parse, rewrite, or validate it. Callers authoring partial indexes\n    // are responsible for writing a valid SQLite WHERE clause.\n    ddl += ` WHERE ${spec.where}`;\n  }\n\n  return ddl;\n}\n\n/**\n * Deduplicate index specs by their deterministic fingerprint. Same spec\n * declared twice (e.g., by core preset + registry entry) collapses to a\n * single DDL statement.\n */\nexport function dedupeIndexSpecs(\n  specs: ReadonlyArray<IndexSpec>,\n  leadingColumns: string[] = [],\n): IndexSpec[] {\n  const seen = new Set<string>();\n  const out: IndexSpec[] = [];\n  for (const spec of specs) {\n    const fp = specFingerprint(spec, leadingColumns);\n    if (seen.has(fp)) continue;\n    seen.add(fp);\n    out.push(spec);\n  }\n  return out;\n}\n","/**\n * Shared `dataOps` SQL compilation helpers used by both SQLite-style backends\n * (`internal/sqlite-sql.ts` for the shared-table backend and `cloudflare/sql.ts`\n * for the per-DO backend).\n *\n * The two backends differ in identifier quoting and scope handling, but the\n * `data` column lives in JSON in both, the deep-merge / replace contract is\n * identical, and the `json_set` / `json_remove` expression they emit for a\n * `DataPathOp[]` is byte-for-byte the same. Lifting the helpers here keeps\n * that shape in one place — the comment in `cloudflare/sql.ts` used to read\n * \"keep them in sync\"; this module is what they keep in sync against.\n *\n * The helpers take a `backendLabel` parameter so error messages still\n * distinguish `\"SQLite backend\"` (shared-table) from `\"DO SQLite backend\"`\n * (per-Durable-Object). Identifier quoting is the caller's job — the helpers\n * here only emit JSON-path expressions against an opaque `base` argument,\n * never bare column names.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type { DataPathOp } from './write-plan.js';\n\n/**\n * Constructor names of Firestore special types that don't survive a plain\n * `JSON.stringify` round-trip — they have non-enumerable accessors (e.g.\n * `Timestamp.seconds`) or class identity that JSON loses. Detection is by\n * `constructor.name` to keep this module dependency-free (importing\n * `@google-cloud/firestore` here would pollute the Cloudflare Workers bundle —\n * see tests/unit/bundle-pollution.test.ts).\n */\nexport const FIRESTORE_TYPE_NAMES = new Set([\n  'Timestamp',\n  'GeoPoint',\n  'VectorValue',\n  'DocumentReference',\n  'FieldValue',\n]);\n\nexport function isFirestoreSpecialType(value: object): string | null {\n  const ctorName = (value as { constructor?: { name?: string } }).constructor?.name;\n  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;\n  return null;\n}\n\n/**\n * Identifiers accepted in `data.<key>` paths and `dataOps` path segments.\n * The pattern (`/^[A-Za-z_][A-Za-z0-9_-]*$/`) covers code-style identifiers\n * (camel, snake, kebab). Silently quoting exotic keys would require symmetric\n * quoting at every read/write call site; any drift produces silent data\n * corruption. Failing loudly at compile time is safer — users with exotic\n * keys can use `replaceNode` / `replaceEdge` (full-data overwrite) instead.\n */\nexport const JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;\n\nexport function validateJsonPathKey(key: string, backendLabel: string): void {\n  if (key.length === 0) {\n    throw new FiregraphError(\n      `${backendLabel}: empty JSON path component is not allowed`,\n      'INVALID_QUERY',\n    );\n  }\n  if (!JSON_PATH_KEY_RE.test(key)) {\n    throw new FiregraphError(\n      `${backendLabel}: data field path component \"${key}\" is not a safe JSON-path identifier. ` +\n        `Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceNode/replaceEdge (full-data overwrite) ` +\n        `for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,\n      'INVALID_QUERY',\n    );\n  }\n}\n\n/**\n * Bind a value as a JSON-serializable string for `json(?)` placeholders in\n * the compiled `json_set` expression. `assertJsonSafePayload` already runs\n * eagerly at the write boundary, so the Firestore-special-type rejection\n * here is defense-in-depth — left in place per the team's preference for\n * symmetric guards across the SQLite compilers.\n */\nexport function jsonBind(value: unknown, backendLabel: string): string {\n  if (value === undefined) return 'null';\n  if (value !== null && typeof value === 'object') {\n    const firestoreType = isFirestoreSpecialType(value);\n    if (firestoreType) {\n      throw new FiregraphError(\n        `${backendLabel} cannot persist a Firestore ${firestoreType} value. ` +\n          `Convert to a primitive before writing (e.g. \\`ts.toMillis()\\` for Timestamp).`,\n        'INVALID_ARGUMENT',\n      );\n    }\n  }\n  return JSON.stringify(value);\n}\n\n/**\n * Build the SQL expression that applies a list of `DataPathOp`s onto an\n * existing JSON column reference (e.g. `\"data\"` or `COALESCE(\"data\", '{}')`).\n *\n * Returns the full expression (already parenthesised where needed) and pushes\n * the bound parameters onto `params` in left-to-right order. Returns `null`\n * when there are no ops at all — the caller picks a fallback expression.\n *\n * Strategy:\n *   1. `json_remove(<base>, '$.a.b', '$.c', …)` strips delete-ops.\n *   2. `json_set(<#1>, '$.x.y', json(?), '$.z', json(?), …)` writes value-ops.\n *      `json(?)` ensures non-string values bind as JSON (objects, arrays,\n *      numbers, booleans, null).\n */\nexport function compileDataOpsExpr(\n  ops: readonly DataPathOp[],\n  base: string,\n  params: unknown[],\n  backendLabel: string,\n): string | null {\n  if (ops.length === 0) return null;\n\n  const deletes: DataPathOp[] = [];\n  const sets: DataPathOp[] = [];\n  for (const op of ops) (op.delete ? deletes : sets).push(op);\n\n  let expr = base;\n\n  if (deletes.length > 0) {\n    const placeholders = deletes.map(() => '?').join(', ');\n    expr = `json_remove(${expr}, ${placeholders})`;\n    for (const op of deletes) {\n      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);\n      params.push(`$.${op.path.join('.')}`);\n    }\n  }\n\n  if (sets.length > 0) {\n    const pieces = sets.map(() => '?, json(?)').join(', ');\n    expr = `json_set(${expr}, ${pieces})`;\n    for (const op of sets) {\n      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);\n      params.push(`$.${op.path.join('.')}`);\n      params.push(jsonBind(op.value, backendLabel));\n    }\n  }\n\n  return expr;\n}\n","/**\n * Shared eager-validation helper for SQLite-style backends\n * (`internal/sqlite-sql.ts` and `cloudflare/sql.ts`).\n *\n * Both backends serialise `record.data` (and `update.replaceData`) as a raw\n * JSON blob via `JSON.stringify`. Two classes of value silently corrupt that\n * representation and the cross-backend contract:\n *\n *   1. **Firestore special types** (`Timestamp`, `GeoPoint`, `VectorValue`,\n *      `DocumentReference`, `FieldValue`). They have non-enumerable accessors\n *      or rely on class identity that JSON drops, so they round-trip as `{}`\n *      or garbage. Callers must convert to primitives before writing.\n *   2. **`DELETE_FIELD` sentinel.** A `Symbol` is invisible to\n *      `JSON.stringify`. If a caller embeds the sentinel in a `replaceNode`\n *      payload or in a fresh-insert (no existing row), the field would\n *      silently disappear instead of erroring loudly the way it does for the\n *      `dataOps` path — so we reject it eagerly here.\n *   3. **Tagged serialization payloads** (`__firegraph_ser__`). These are the\n *      sandbox migration boundary marshalling form. They are valid inside\n *      Firestore (the Firestore backend re-hydrates them via\n *      `deserializeFirestoreTypes`), but on SQLite they would persist as\n *      opaque tagged objects that no downstream reader knows how to interpret.\n *      Reject them at the boundary so the failure is loud.\n *\n * The Firestore backend does NOT call this — it accepts those types natively\n * and `deserializeFirestoreTypes` rebuilds tagged values into real Firestore\n * objects on its own write path.\n *\n * Detection avoids `instanceof` so this module stays free of\n * `@google-cloud/firestore`. Constructor-name + duck-type matches the\n * approach used by `bindValue`/`jsonBind` elsewhere in the SQLite compilers.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport { SERIALIZATION_TAG } from './serialization-tag.js';\nimport { isDeleteSentinel } from './write-plan.js';\n\nconst FIRESTORE_TYPE_NAMES = new Set([\n  'Timestamp',\n  'GeoPoint',\n  'VectorValue',\n  'DocumentReference',\n  'FieldValue',\n]);\n\n/**\n * Walk `data` and throw on any value that the SQLite-style raw-JSON\n * persistence path can't faithfully serialise. `label` distinguishes the\n * caller in error messages (e.g. `'shared-table SQLite'` vs `'DO SQLite'`).\n *\n * Plain objects recurse. Arrays recurse element-wise. Primitives, `null`,\n * and `undefined` are accepted (mirroring how `flattenPatch` treats them\n * during the merge path).\n */\nexport function assertJsonSafePayload(data: unknown, label: string): void {\n  walk(data, [], label);\n}\n\nfunction walk(node: unknown, path: readonly string[], label: string): void {\n  if (node === null || node === undefined) return;\n  if (isDeleteSentinel(node)) {\n    throw new FiregraphError(\n      `${label} backend cannot persist a deleteField() sentinel inside a ` +\n        `full-data payload (replaceNode/replaceEdge or first-insert). The ` +\n        `sentinel is only valid inside an updateNode/updateEdge dataOps patch. ` +\n        `Path: ${formatPath(path)}.`,\n      'INVALID_ARGUMENT',\n    );\n  }\n  const t = typeof node;\n  if (t === 'symbol' || t === 'function') {\n    throw new FiregraphError(\n      `${label} backend cannot persist a value of type ${t}. ` +\n        `JSON.stringify drops it silently. Path: ${formatPath(path)}.`,\n      'INVALID_ARGUMENT',\n    );\n  }\n  if (t === 'bigint') {\n    throw new FiregraphError(\n      `${label} backend cannot persist a value of type bigint. ` +\n        `JSON.stringify cannot serialize this type (throws TypeError). ` +\n        `Path: ${formatPath(path)}.`,\n      'INVALID_ARGUMENT',\n    );\n  }\n  if (t !== 'object') return;\n  if (Array.isArray(node)) {\n    for (let i = 0; i < node.length; i++) {\n      walk(node[i], [...path, String(i)], label);\n    }\n    return;\n  }\n  // Reject any object carrying the firegraph serialization tag — both legit\n  // tagged Firestore-type payloads (the migration-sandbox output that round-\n  // trips through Firestore) and bogus user data that happens to put a\n  // literal `__firegraph_ser__` key on a plain object. SQLite has no\n  // Timestamp class to rebuild the tag into, and silently writing the\n  // envelope would produce an unreadable column.\n  const obj = node as Record<string, unknown>;\n  if (Object.prototype.hasOwnProperty.call(obj, SERIALIZATION_TAG)) {\n    const tagValue = obj[SERIALIZATION_TAG];\n    throw new FiregraphError(\n      `${label} backend cannot persist an object with a \\`${SERIALIZATION_TAG}\\` ` +\n        `key (value: ${formatTagValue(tagValue)}). Recognised tags are valid only on ` +\n        `the Firestore backend (migration-sandbox output); a literal ` +\n        `\\`${SERIALIZATION_TAG}\\` field in user data is reserved and not allowed. ` +\n        `Path: ${formatPath(path)}.`,\n      'INVALID_ARGUMENT',\n    );\n  }\n  // Class instances: reject Firestore special types loudly; reject every\n  // other class instance generically (Map, Set, Date are caller's\n  // responsibility to convert — Date is allowed in filter binds via\n  // `bindValue` but not as a stored payload value because JSON.stringify\n  // produces a string, not a real Date).\n  const proto = Object.getPrototypeOf(node);\n  if (proto !== null && proto !== Object.prototype) {\n    const ctor = (node as { constructor?: { name?: string } }).constructor;\n    const ctorName = ctor && typeof ctor.name === 'string' ? ctor.name : '<anonymous>';\n    if (FIRESTORE_TYPE_NAMES.has(ctorName)) {\n      throw new FiregraphError(\n        `${label} backend cannot persist a Firestore ${ctorName} value. ` +\n          `Convert to a primitive before writing (e.g. \\`ts.toMillis()\\` for ` +\n          `Timestamp, \\`{lat,lng}\\` for GeoPoint). Path: ${formatPath(path)}.`,\n        'INVALID_ARGUMENT',\n      );\n    }\n    // Accept Date as an alias for its epoch-ms — it round-trips as an ISO\n    // string via JSON.stringify, which the caller chose; not our place to\n    // reject. Same for Buffer / typed arrays — they'll JSON-serialize as\n    // best they can. Reject only opaque exotic instances that JSON drops.\n    if (node instanceof Date) return;\n    throw new FiregraphError(\n      `${label} backend cannot persist a class instance of type ${ctorName}. ` +\n        `Only plain objects, arrays, and primitives round-trip safely through ` +\n        `JSON storage. Path: ${formatPath(path)}.`,\n      'INVALID_ARGUMENT',\n    );\n  }\n  for (const key of Object.keys(obj)) {\n    walk(obj[key], [...path, key], label);\n  }\n}\n\nfunction formatPath(path: readonly string[]): string {\n  return path.length === 0 ? '<root>' : path.map((p) => JSON.stringify(p)).join(' > ');\n}\n\nfunction formatTagValue(value: unknown): string {\n  if (value === null) return 'null';\n  if (value === undefined) return 'undefined';\n  if (typeof value === 'string') return JSON.stringify(value);\n  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {\n    return String(value);\n  }\n  return typeof value;\n}\n","/**\n * Backend-agnostic timestamp.\n *\n * Structurally compatible with `@google-cloud/firestore`'s `Timestamp` so\n * that records returned by either the Firestore or SQLite backend can be\n * consumed through the same `StoredGraphRecord` shape.\n *\n * Firestore's native `Timestamp` already satisfies this interface, so\n * existing Firestore consumers see no behavior change. The SQLite backend\n * returns instances of `GraphTimestampImpl` which also satisfies it.\n */\n\nexport interface GraphTimestamp {\n  readonly seconds: number;\n  readonly nanoseconds: number;\n  toDate(): Date;\n  toMillis(): number;\n}\n\n/**\n * Concrete `GraphTimestamp` implementation used by non-Firestore backends.\n * Mirrors the surface of Firestore's `Timestamp` enough for typical use.\n */\nexport class GraphTimestampImpl implements GraphTimestamp {\n  constructor(\n    public readonly seconds: number,\n    public readonly nanoseconds: number,\n  ) {}\n\n  toDate(): Date {\n    return new Date(this.toMillis());\n  }\n\n  toMillis(): number {\n    return this.seconds * 1000 + Math.floor(this.nanoseconds / 1e6);\n  }\n\n  toJSON(): { seconds: number; nanoseconds: number } {\n    return { seconds: this.seconds, nanoseconds: this.nanoseconds };\n  }\n\n  static fromMillis(ms: number): GraphTimestampImpl {\n    const seconds = Math.floor(ms / 1000);\n    const nanoseconds = (ms - seconds * 1000) * 1e6;\n    return new GraphTimestampImpl(seconds, nanoseconds);\n  }\n\n  static now(): GraphTimestampImpl {\n    return GraphTimestampImpl.fromMillis(Date.now());\n  }\n}\n\n/**\n * Sentinel returned by `StorageBackend.serverTimestamp()` when the backend\n * has no native server-time concept and just wants a placeholder that the\n * adapter resolves to a concrete time at write commit. SQLite backends\n * substitute the wall-clock millis at the moment of `setDoc`/`updateDoc`.\n */\nexport const SERVER_TIMESTAMP_SENTINEL = Symbol.for('firegraph.serverTimestamp');\nexport type ServerTimestampSentinel = typeof SERVER_TIMESTAMP_SENTINEL;\n\nexport function isServerTimestampSentinel(value: unknown): value is ServerTimestampSentinel {\n  return value === SERVER_TIMESTAMP_SENTINEL;\n}\n"],"mappings":"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","names":["JSON_PATH_KEY_RE","FIRESTORE_TYPE_NAMES"]}