@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/sqlite/index.js

@@ -0,0 +1,1164 @@
+import {
+  GraphTimestampImpl,
+  assertJsonSafePayload,
+  compileDataOpsExpr,
+  isFirestoreSpecialType,
+  validateJsonPathKey
+} from "../chunk-4MMQ5W74.js";
+import "../chunk-2DHMNTV6.js";
+import {
+  createCapabilities
+} from "../chunk-N5HFDWQX.js";
+import {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
+  NODE_RELATION,
+  buildEdgeQueryPlan,
+  computeEdgeDocId,
+  computeNodeDocId,
+  createGraphClient,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+} from "../chunk-WRTFC5NG.js";
+import {
+  FiregraphError,
+  assertUpdatePayloadExclusive,
+  flattenPatch
+} from "../chunk-TK64DNVK.js";
+import "../chunk-EQJUUVFG.js";
+
+// src/internal/sqlite-schema.ts
+var FIELD_TO_COLUMN = {
+  aType: "a_type",
+  aUid: "a_uid",
+  axbType: "axb_type",
+  bType: "b_type",
+  bUid: "b_uid",
+  v: "v",
+  createdAt: "created_at",
+  updatedAt: "updated_at"
+};
+function quoteIdent(name) {
+  validateTableName(name);
+  return `"${name}"`;
+}
+function validateTableName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid SQL identifier: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+  }
+}
+function quoteColumnAlias(label) {
+  return `"${label.replace(/"/g, '""')}"`;
+}
+
+// src/sqlite/sql.ts
+var SQLITE_BACKEND_LABEL = "shared-table SQLite";
+var SQLITE_BACKEND_ERR_LABEL = "SQLite backend";
+function compileFieldRef(field) {
+  const column = FIELD_TO_COLUMN[field];
+  if (column) {
+    return { expr: quoteIdent(column) };
+  }
+  if (field.startsWith("data.")) {
+    const suffix = field.slice(5);
+    for (const part of suffix.split(".")) {
+      validateJsonPathKey(part, SQLITE_BACKEND_ERR_LABEL);
+    }
+    return { expr: `json_extract("data", '$.${suffix}')` };
+  }
+  if (field === "data") {
+    return { expr: `json_extract("data", '$')` };
+  }
+  throw new FiregraphError(`SQLite backend cannot resolve filter field: ${field}`, "INVALID_QUERY");
+}
+function bindValue(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `SQLite backend cannot bind a Firestore ${firestoreType} value \u2014 JSON serialization would silently drop fields and the resulting bind would never match a stored row. Convert to a primitive (e.g. \`ts.toMillis()\` for Timestamp) before filtering or updating.`,
+        "INVALID_QUERY"
+      );
+    }
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function compileFilter(filter, params) {
+  const { expr } = compileFieldRef(filter.field);
+  switch (filter.op) {
+    case "==":
+      params.push(bindValue(filter.value));
+      return `${expr} = ?`;
+    case "!=":
+      params.push(bindValue(filter.value));
+      return `${expr} != ?`;
+    case "<":
+      params.push(bindValue(filter.value));
+      return `${expr} < ?`;
+    case "<=":
+      params.push(bindValue(filter.value));
+      return `${expr} <= ?`;
+    case ">":
+      params.push(bindValue(filter.value));
+      return `${expr} > ?`;
+    case ">=":
+      params.push(bindValue(filter.value));
+      return `${expr} >= ?`;
+    case "in": {
+      const values = asArray(filter.value, "in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} IN (${placeholders})`;
+    }
+    case "not-in": {
+      const values = asArray(filter.value, "not-in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} NOT IN (${placeholders})`;
+    }
+    case "array-contains": {
+      params.push(bindValue(filter.value));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value = ?)`;
+    }
+    case "array-contains-any": {
+      const values = asArray(filter.value, "array-contains-any");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value IN (${placeholders}))`;
+    }
+    default:
+      throw new FiregraphError(
+        `SQLite backend does not support filter operator: ${String(filter.op)}`,
+        "INVALID_QUERY"
+      );
+  }
+}
+function asArray(value, op) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new FiregraphError(`Operator "${op}" requires a non-empty array value`, "INVALID_QUERY");
+  }
+  return value;
+}
+function compileOrderBy(options, _params) {
+  if (!options?.orderBy) return "";
+  const { field, direction } = options.orderBy;
+  const { expr } = compileFieldRef(field);
+  const dir = direction === "desc" ? "DESC" : "ASC";
+  return ` ORDER BY ${expr} ${dir}`;
+}
+function compileLimit(options, params) {
+  if (options?.limit === void 0) return "";
+  params.push(options.limit);
+  return ` LIMIT ?`;
+}
+function compileSelect(table, scope, filters, options) {
+  const params = [];
+  const conditions = ['"scope" = ?'];
+  params.push(scope);
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  let sql = `SELECT * FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  const orderClause = compileOrderBy(options, params);
+  sql += orderClause;
+  sql += compileLimit(options, params);
+  return { sql, params };
+}
+function compileAggregate(table, scope, spec, filters) {
+  const aliases = Object.keys(spec);
+  if (aliases.length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const projections = [];
+  for (const alias of aliases) {
+    const { op, field } = spec[alias];
+    validateJsonPathKey(alias, SQLITE_BACKEND_ERR_LABEL);
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      projections.push(`COUNT(*) AS ${quoteIdent(alias)}`);
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    const { expr } = compileFieldRef(field);
+    const numeric = `CAST(${expr} AS REAL)`;
+    if (op === "sum") projections.push(`SUM(${numeric}) AS ${quoteIdent(alias)}`);
+    else if (op === "avg") projections.push(`AVG(${numeric}) AS ${quoteIdent(alias)}`);
+    else if (op === "min") projections.push(`MIN(${numeric}) AS ${quoteIdent(alias)}`);
+    else if (op === "max") projections.push(`MAX(${numeric}) AS ${quoteIdent(alias)}`);
+    else
+      throw new FiregraphError(
+        `SQLite backend does not support aggregate op: ${String(op)}`,
+        "INVALID_QUERY"
+      );
+  }
+  const params = [scope];
+  const conditions = ['"scope" = ?'];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  return { stmt: { sql, params }, aliases };
+}
+function compileSelectGlobal(table, filters, options, scopeNameFilter) {
+  if (filters.length === 0) {
+    throw new FiregraphError(
+      "compileSelectGlobal requires at least one filter \u2014 refusing to issue an unbounded SELECT.",
+      "INVALID_QUERY"
+    );
+  }
+  const params = [];
+  const conditions = [];
+  if (scopeNameFilter) {
+    if (scopeNameFilter.isRoot) {
+      conditions.push(`"scope" = ?`);
+      params.push("");
+    } else {
+      conditions.push(`"scope" LIKE ? ESCAPE '\\'`);
+      params.push(`%/${escapeLike(scopeNameFilter.name)}`);
+    }
+  }
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const sql = `SELECT * FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}` + compileOrderBy(options, params) + compileLimit(options, params);
+  return { sql, params };
+}
+function compileSelectByDocId(table, scope, docId) {
+  return {
+    sql: `SELECT * FROM ${quoteIdent(table)} WHERE "scope" = ? AND "doc_id" = ? LIMIT 1`,
+    params: [scope, docId]
+  };
+}
+function normalizeProjectionField(field) {
+  if (field in FIELD_TO_COLUMN) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function compileFindEdgesProjected(table, scope, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "compileFindEdgesProjected requires a non-empty select list \u2014 an empty projection has no SQL representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueFields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      uniqueFields.push(f);
+    }
+  }
+  const projections = [];
+  const columns = [];
+  for (let idx = 0; idx < uniqueFields.length; idx++) {
+    const field = uniqueFields[idx];
+    const canonical = normalizeProjectionField(field);
+    const { expr } = compileFieldRef(canonical);
+    const alias = quoteColumnAlias(field);
+    projections.push(`${expr} AS ${alias}`);
+    let kind;
+    let typeAliasName;
+    if (canonical === "data") {
+      kind = "data";
+    } else if (canonical.startsWith("data.")) {
+      kind = "json";
+      typeAliasName = `__fg_t_${idx}`;
+      const typeAlias = quoteColumnAlias(typeAliasName);
+      projections.push(`json_type("data", '$.${canonical.slice(5)}') AS ${typeAlias}`);
+    } else {
+      if (canonical === "v") kind = "builtin-int";
+      else if (canonical === "createdAt" || canonical === "updatedAt") kind = "builtin-timestamp";
+      else kind = "builtin-text";
+    }
+    columns.push({ field, kind, typeAlias: typeAliasName });
+  }
+  const params = [scope];
+  const conditions = ['"scope" = ?'];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  let sql = `SELECT ${projections.join(", ")} FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  sql += compileOrderBy(options, params);
+  sql += compileLimit(options, params);
+  return { stmt: { sql, params }, columns };
+}
+function decodeProjectedRow(row, columns) {
+  const out = {};
+  for (const c of columns) {
+    const raw = row[c.field];
+    switch (c.kind) {
+      case "builtin-text":
+        out[c.field] = raw === null || raw === void 0 ? null : String(raw);
+        break;
+      case "builtin-int":
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else if (typeof raw === "number") {
+          out[c.field] = raw;
+        } else {
+          out[c.field] = Number(raw);
+        }
+        break;
+      case "builtin-timestamp": {
+        const ms = toMillis(raw);
+        out[c.field] = GraphTimestampImpl.fromMillis(ms);
+        break;
+      }
+      case "data":
+        if (raw === null || raw === void 0 || raw === "") {
+          out[c.field] = {};
+        } else {
+          out[c.field] = JSON.parse(raw);
+        }
+        break;
+      case "json": {
+        const t = row[c.typeAlias];
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (t === "object" || t === "array") {
+          out[c.field] = typeof raw === "string" ? JSON.parse(raw) : raw;
+        } else if (t === "integer" && typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else {
+          out[c.field] = raw;
+        }
+        break;
+      }
+    }
+  }
+  return out;
+}
+function compileExpand(table, scope, params) {
+  if (params.sources.length === 0) {
+    throw new FiregraphError(
+      "compileExpand requires a non-empty sources list \u2014 empty IN () is invalid SQL. Callers should short-circuit empty input before reaching the compiler.",
+      "INVALID_QUERY"
+    );
+  }
+  const direction = params.direction ?? "forward";
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const aTypeCol = compileFieldRef("aType").expr;
+  const bTypeCol = compileFieldRef("bType").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  const sourceColumn = direction === "forward" ? aUidCol : bUidCol;
+  const sqlParams = [scope, params.axbType];
+  const conditions = ['"scope" = ?', `${axbTypeCol} = ?`];
+  const placeholders = params.sources.map(() => "?").join(", ");
+  conditions.push(`${sourceColumn} IN (${placeholders})`);
+  for (const uid of params.sources) sqlParams.push(uid);
+  if (params.aType !== void 0) {
+    conditions.push(`${aTypeCol} = ?`);
+    sqlParams.push(params.aType);
+  }
+  if (params.bType !== void 0) {
+    conditions.push(`${bTypeCol} = ?`);
+    sqlParams.push(params.bType);
+  }
+  if (params.axbType === NODE_RELATION) {
+    conditions.push(`${aUidCol} != ${bUidCol}`);
+  }
+  let sql = `SELECT * FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  if (params.orderBy) {
+    sql += compileOrderBy({ orderBy: params.orderBy }, sqlParams);
+  }
+  if (params.limitPerSource !== void 0) {
+    const totalLimit = params.sources.length * params.limitPerSource;
+    sql += ` LIMIT ?`;
+    sqlParams.push(totalLimit);
+  }
+  return { sql, params: sqlParams };
+}
+function compileExpandHydrate(table, scope, targetUids) {
+  if (targetUids.length === 0) {
+    throw new FiregraphError(
+      "compileExpandHydrate requires a non-empty target list \u2014 empty IN () is invalid SQL.",
+      "INVALID_QUERY"
+    );
+  }
+  const placeholders = targetUids.map(() => "?").join(", ");
+  const sqlParams = [scope, NODE_RELATION];
+  for (const uid of targetUids) sqlParams.push(uid);
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  return {
+    sql: `SELECT * FROM ${quoteIdent(table)} WHERE "scope" = ? AND ${axbTypeCol} = ? AND ${aUidCol} = ${bUidCol} AND ${bUidCol} IN (${placeholders})`,
+    params: sqlParams
+  };
+}
+function compileSet(table, scope, docId, record, nowMillis, mode) {
+  assertJsonSafePayload(record.data, SQLITE_BACKEND_LABEL);
+  if (mode === "replace") {
+    const sql2 = `INSERT OR REPLACE INTO ${quoteIdent(table)} (
+      doc_id, scope, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+    const params = [
+      docId,
+      scope,
+      record.aType,
+      record.aUid,
+      record.axbType,
+      record.bType,
+      record.bUid,
+      JSON.stringify(record.data ?? {}),
+      record.v ?? null,
+      nowMillis,
+      nowMillis
+    ];
+    return { sql: sql2, params };
+  }
+  const insertParams = [
+    docId,
+    scope,
+    record.aType,
+    record.aUid,
+    record.axbType,
+    record.bType,
+    record.bUid,
+    JSON.stringify(record.data ?? {}),
+    record.v ?? null,
+    nowMillis,
+    nowMillis
+  ];
+  const ops = flattenPatch(record.data ?? {});
+  const updateParams = [];
+  const dataExpr = compileDataOpsExpr(ops, `COALESCE("data", '{}')`, updateParams, SQLITE_BACKEND_ERR_LABEL) ?? `COALESCE("data", '{}')`;
+  const sql = `INSERT INTO ${quoteIdent(table)} (
+      doc_id, scope, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(scope, doc_id) DO UPDATE SET
+      "a_type" = excluded."a_type",
+      "a_uid" = excluded."a_uid",
+      "axb_type" = excluded."axb_type",
+      "b_type" = excluded."b_type",
+      "b_uid" = excluded."b_uid",
+      "data" = ${dataExpr},
+      "v" = COALESCE(excluded."v", "v"),
+      "created_at" = excluded."created_at",
+      "updated_at" = excluded."updated_at"`;
+  return { sql, params: [...insertParams, ...updateParams] };
+}
+function compileUpdate(table, scope, docId, update, nowMillis) {
+  assertUpdatePayloadExclusive(update);
+  const setClauses = [];
+  const params = [];
+  if (update.replaceData) {
+    assertJsonSafePayload(update.replaceData, SQLITE_BACKEND_LABEL);
+    setClauses.push(`"data" = ?`);
+    params.push(JSON.stringify(update.replaceData));
+  } else if (update.dataOps && update.dataOps.length > 0) {
+    for (const op of update.dataOps) {
+      if (!op.delete) assertJsonSafePayload(op.value, SQLITE_BACKEND_LABEL);
+    }
+    const expr = compileDataOpsExpr(
+      update.dataOps,
+      `COALESCE("data", '{}')`,
+      params,
+      SQLITE_BACKEND_ERR_LABEL
+    );
+    if (expr !== null) {
+      setClauses.push(`"data" = ${expr}`);
+    }
+  }
+  if (update.v !== void 0) {
+    setClauses.push(`"v" = ?`);
+    params.push(update.v);
+  }
+  setClauses.push(`"updated_at" = ?`);
+  params.push(nowMillis);
+  params.push(scope, docId);
+  return {
+    sql: `UPDATE ${quoteIdent(table)} SET ${setClauses.join(", ")} WHERE "scope" = ? AND "doc_id" = ?`,
+    params
+  };
+}
+function compileDelete(table, scope, docId) {
+  return {
+    sql: `DELETE FROM ${quoteIdent(table)} WHERE "scope" = ? AND "doc_id" = ?`,
+    params: [scope, docId]
+  };
+}
+function compileBulkDelete(table, scope, filters) {
+  const params = [scope];
+  const conditions = ['"scope" = ?'];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  return {
+    sql: `DELETE FROM ${quoteIdent(table)} WHERE ${conditions.join(" AND ")}`,
+    params
+  };
+}
+function compileBulkUpdate(table, scope, filters, patchData, nowMillis) {
+  const dataOps = flattenPatch(patchData);
+  if (dataOps.length === 0) {
+    throw new FiregraphError(
+      "bulkUpdate() patch.data must contain at least one leaf \u2014 an empty patch would only rewrite `updated_at`, which is almost certainly a bug. Use `setDoc` with merge mode if you want to stamp without editing data.",
+      "INVALID_QUERY"
+    );
+  }
+  for (const op of dataOps) {
+    if (!op.delete) assertJsonSafePayload(op.value, SQLITE_BACKEND_LABEL);
+  }
+  const setParams = [];
+  const expr = compileDataOpsExpr(
+    dataOps,
+    `COALESCE("data", '{}')`,
+    setParams,
+    SQLITE_BACKEND_ERR_LABEL
+  );
+  if (expr === null) {
+    throw new FiregraphError(
+      "bulkUpdate() patch produced no SQL operations \u2014 internal invariant violated.",
+      "INVALID_ARGUMENT"
+    );
+  }
+  const setClauses = [`"data" = ${expr}`, `"updated_at" = ?`];
+  setParams.push(nowMillis);
+  const whereParams = [scope];
+  const conditions = ['"scope" = ?'];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, whereParams));
+  }
+  return {
+    sql: `UPDATE ${quoteIdent(table)} SET ${setClauses.join(", ")} WHERE ${conditions.join(" AND ")}`,
+    params: [...setParams, ...whereParams]
+  };
+}
+function compileDeleteScopePrefix(table, scopePrefix) {
+  const escaped = escapeLike(scopePrefix);
+  return {
+    sql: `DELETE FROM ${quoteIdent(table)} WHERE "scope" LIKE ? ESCAPE '\\'`,
+    params: [`${escaped}/%`]
+  };
+}
+function compileCountScopePrefix(table, scopePrefix) {
+  const escaped = escapeLike(scopePrefix);
+  return {
+    sql: `SELECT COUNT(*) AS n FROM ${quoteIdent(table)} WHERE "scope" LIKE ? ESCAPE '\\'`,
+    params: [`${escaped}/%`]
+  };
+}
+function escapeLike(value) {
+  return value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+function rowToRecord(row) {
+  const dataString = row.data;
+  const data = dataString ? JSON.parse(dataString) : {};
+  const createdMs = toMillis(row.created_at);
+  const updatedMs = toMillis(row.updated_at);
+  const record = {
+    aType: row.a_type,
+    aUid: row.a_uid,
+    axbType: row.axb_type,
+    bType: row.b_type,
+    bUid: row.b_uid,
+    data,
+    createdAt: GraphTimestampImpl.fromMillis(createdMs),
+    updatedAt: GraphTimestampImpl.fromMillis(updatedMs)
+  };
+  if (row.v !== null && row.v !== void 0) {
+    record.v = Number(row.v);
+  }
+  return record;
+}
+function toMillis(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") return Number(value);
+  return 0;
+}
+
+// src/sqlite/backend.ts
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_RETRY_DELAY_MS = 200;
+var MAX_RETRY_DELAY_MS = 5e3;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function minDefined(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return Math.min(a, b);
+}
+function chunkStatements(statements, maxStatements, maxParams) {
+  const stmtCap = maxStatements && maxStatements > 0 && Number.isFinite(maxStatements) ? Math.floor(maxStatements) : Infinity;
+  const paramCap = maxParams && maxParams > 0 && Number.isFinite(maxParams) ? Math.floor(maxParams) : Infinity;
+  if (stmtCap === Infinity && paramCap === Infinity) {
+    return [statements];
+  }
+  const chunks = [];
+  let current = [];
+  let currentParamCount = 0;
+  for (const stmt of statements) {
+    const stmtParams = stmt.params.length;
+    const wouldExceedStmt = current.length + 1 > stmtCap;
+    const wouldExceedParam = currentParamCount + stmtParams > paramCap;
+    if (current.length > 0 && (wouldExceedStmt || wouldExceedParam)) {
+      chunks.push(current);
+      current = [];
+      currentParamCount = 0;
+    }
+    current.push(stmt);
+    currentParamCount += stmtParams;
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+var SqliteTransactionBackendImpl = class {
+  constructor(tx, tableName, storageScope) {
+    this.tx = tx;
+    this.tableName = tableName;
+    this.storageScope = storageScope;
+  }
+  async getDoc(docId) {
+    const stmt = compileSelectByDocId(this.tableName, this.storageScope, docId);
+    const rows = await this.tx.all(stmt.sql, stmt.params);
+    return rows.length === 0 ? null : rowToRecord(rows[0]);
+  }
+  async query(filters, options) {
+    const stmt = compileSelect(this.tableName, this.storageScope, filters, options);
+    const rows = await this.tx.all(stmt.sql, stmt.params);
+    return rows.map(rowToRecord);
+  }
+  async setDoc(docId, record, mode) {
+    const stmt = compileSet(this.tableName, this.storageScope, docId, record, Date.now(), mode);
+    await this.tx.run(stmt.sql, stmt.params);
+  }
+  async updateDoc(docId, update) {
+    const stmt = compileUpdate(this.tableName, this.storageScope, docId, update, Date.now());
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const rows = await this.tx.all(sqlWithReturning, stmt.params);
+    if (rows.length === 0) {
+      throw new FiregraphError(
+        `updateDoc: no document found for doc_id=${docId} (scope=${this.storageScope})`,
+        "NOT_FOUND"
+      );
+    }
+  }
+  async deleteDoc(docId) {
+    const stmt = compileDelete(this.tableName, this.storageScope, docId);
+    await this.tx.run(stmt.sql, stmt.params);
+  }
+};
+var SqliteBatchBackendImpl = class {
+  constructor(executor, tableName, storageScope) {
+    this.executor = executor;
+    this.tableName = tableName;
+    this.storageScope = storageScope;
+  }
+  statements = [];
+  setDoc(docId, record, mode) {
+    this.statements.push(
+      compileSet(this.tableName, this.storageScope, docId, record, Date.now(), mode)
+    );
+  }
+  updateDoc(docId, update) {
+    this.statements.push(
+      compileUpdate(this.tableName, this.storageScope, docId, update, Date.now())
+    );
+  }
+  deleteDoc(docId) {
+    this.statements.push(compileDelete(this.tableName, this.storageScope, docId));
+  }
+  async commit() {
+    if (this.statements.length === 0) return;
+    await this.executor.batch(this.statements);
+    this.statements.length = 0;
+  }
+};
+var SQLITE_CORE_CAPS = [
+  "core.read",
+  "core.write",
+  "core.batch",
+  "core.subgraph",
+  "query.aggregate",
+  "query.dml",
+  "query.join",
+  "query.select",
+  "raw.sql"
+];
+var SqliteBackendImpl = class _SqliteBackendImpl {
+  constructor(executor, tableName, storageScope, scopePath) {
+    this.executor = executor;
+    this.collectionPath = tableName;
+    this.storageScope = storageScope;
+    this.scopePath = scopePath;
+    const caps = new Set(SQLITE_CORE_CAPS);
+    if (typeof executor.transaction === "function") {
+      caps.add("core.transactions");
+    }
+    this.capabilities = createCapabilities(caps);
+  }
+  capabilities;
+  /** Logical table name (returned through `collectionPath` for parity with Firestore). */
+  collectionPath;
+  scopePath;
+  /** Materialized storage scope (interleaved parent UIDs + subgraph names). */
+  storageScope;
+  // --- Reads ---
+  async getDoc(docId) {
+    const stmt = compileSelectByDocId(this.collectionPath, this.storageScope, docId);
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    return rows.length === 0 ? null : rowToRecord(rows[0]);
+  }
+  async query(filters, options) {
+    const stmt = compileSelect(this.collectionPath, this.storageScope, filters, options);
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    return rows.map(rowToRecord);
+  }
+  // --- Writes ---
+  async setDoc(docId, record, mode) {
+    const stmt = compileSet(
+      this.collectionPath,
+      this.storageScope,
+      docId,
+      record,
+      Date.now(),
+      mode
+    );
+    await this.executor.run(stmt.sql, stmt.params);
+  }
+  async updateDoc(docId, update) {
+    const stmt = compileUpdate(this.collectionPath, this.storageScope, docId, update, Date.now());
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const rows = await this.executor.all(sqlWithReturning, stmt.params);
+    if (rows.length === 0) {
+      throw new FiregraphError(
+        `updateDoc: no document found for doc_id=${docId} (scope=${this.storageScope})`,
+        "NOT_FOUND"
+      );
+    }
+  }
+  async deleteDoc(docId) {
+    const stmt = compileDelete(this.collectionPath, this.storageScope, docId);
+    await this.executor.run(stmt.sql, stmt.params);
+  }
+  // --- Transactions / Batches ---
+  async runTransaction(fn) {
+    if (!this.executor.transaction) {
+      throw new FiregraphError(
+        "Interactive transactions are not supported by this SQLite driver. D1 in particular has no read-then-conditional-write transactions; use a Durable Object SQLite client instead, or rewrite the code path as a batch().",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    return this.executor.transaction(async (tx) => {
+      const txBackend = new SqliteTransactionBackendImpl(
+        tx,
+        this.collectionPath,
+        this.storageScope
+      );
+      return fn(txBackend);
+    });
+  }
+  createBatch() {
+    return new SqliteBatchBackendImpl(this.executor, this.collectionPath, this.storageScope);
+  }
+  // --- Subgraphs ---
+  subgraph(parentNodeUid, name) {
+    if (!parentNodeUid || parentNodeUid.includes("/")) {
+      throw new FiregraphError(
+        `Invalid parentNodeUid for subgraph: "${parentNodeUid}". Must be a non-empty string without "/".`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    if (!name || name.includes("/")) {
+      throw new FiregraphError(
+        `Subgraph name must not contain "/" and must be non-empty: got "${name}". Use chained .subgraph() calls for nested subgraphs.`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    const newStorageScope = this.storageScope ? `${this.storageScope}/${parentNodeUid}/${name}` : `${parentNodeUid}/${name}`;
+    const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _SqliteBackendImpl(this.executor, this.collectionPath, newStorageScope, newScope);
+  }
+  // --- Cascade & bulk ---
+  async removeNodeCascade(uid, reader, options) {
+    const [outgoingRaw, incomingRaw] = await Promise.all([
+      reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+      reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
+    ]);
+    const seen = /* @__PURE__ */ new Set();
+    const edgeDocIds = [];
+    for (const edge of [...outgoingRaw, ...incomingRaw]) {
+      if (edge.axbType === NODE_RELATION) continue;
+      const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
+      if (!seen.has(docId)) {
+        seen.add(docId);
+        edgeDocIds.push(docId);
+      }
+    }
+    const nodeDocId = computeNodeDocId(uid);
+    const shouldDeleteSubgraphs = options?.deleteSubcollections !== false;
+    let subgraphRowCount = 0;
+    if (shouldDeleteSubgraphs) {
+      const prefix = this.storageScope ? `${this.storageScope}/${uid}` : uid;
+      const countStmt = compileCountScopePrefix(this.collectionPath, prefix);
+      const countRows = await this.executor.all(countStmt.sql, countStmt.params);
+      const first = countRows[0];
+      const n = first?.n;
+      subgraphRowCount = typeof n === "bigint" ? Number(n) : Number(n ?? 0);
+    }
+    const writeStatements = edgeDocIds.map(
+      (id) => compileDelete(this.collectionPath, this.storageScope, id)
+    );
+    writeStatements.push(compileDelete(this.collectionPath, this.storageScope, nodeDocId));
+    if (shouldDeleteSubgraphs) {
+      const prefix = this.storageScope ? `${this.storageScope}/${uid}` : uid;
+      writeStatements.push(compileDeleteScopePrefix(this.collectionPath, prefix));
+    }
+    const {
+      deleted: stmtDeleted,
+      batches,
+      errors
+    } = await this.executeChunkedBatches(writeStatements, options);
+    const allOk = errors.length === 0;
+    const edgesDeleted = allOk ? edgeDocIds.length : 0;
+    const nodeDeleted = allOk;
+    const prefixStatementContribution = shouldDeleteSubgraphs && allOk ? 1 : 0;
+    const deleted = stmtDeleted - prefixStatementContribution + (allOk ? subgraphRowCount : 0);
+    return { deleted, batches, errors, edgesDeleted, nodeDeleted };
+  }
+  async bulkRemoveEdges(params, reader, options) {
+    const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+    const edges = await reader.findEdges(effectiveParams);
+    const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+    if (docIds.length === 0) {
+      return { deleted: 0, batches: 0, errors: [] };
+    }
+    const statements = docIds.map(
+      (id) => compileDelete(this.collectionPath, this.storageScope, id)
+    );
+    return this.executeChunkedBatches(statements, options);
+  }
+  /**
+   * Submit `statements` to the executor as one or more `batch()` calls,
+   * chunking by `executor.maxBatchSize` (e.g. D1's ~100-statement cap).
+   * Drivers that don't advertise a cap submit everything in one batch,
+   * preserving cross-batch atomicity.
+   *
+   * Each chunk is retried with exponential backoff up to `maxRetries`
+   * (default 3) before being recorded in `errors`. The loop continues past
+   * a permanently failed chunk so the caller still gets partial progress
+   * visibility — to halt on first failure, set `maxRetries: 0` and check
+   * `result.errors.length` after the call.
+   *
+   * Returns `BulkResult`-shaped fields. `deleted` reflects only the
+   * statement count of *successfully committed* batches — a prefix-delete
+   * statement contributes 1 to that total even though it may match many
+   * rows; `removeNodeCascade` patches that up with a pre-counted row total.
+   *
+   * **Atomicity caveat (D1):** when chunking kicks in, atomicity is lost
+   * across chunk boundaries — one chunk may commit while a later one fails.
+   * `removeNodeCascade` is idempotent (deleting the same docs again is a
+   * no-op) so a caller can simply retry on partial failure. `bulkRemoveEdges`
+   * is also idempotent for the same reason. DO SQLite leaves `maxBatchSize`
+   * unset, so everything funnels through one atomic `transactionSync` and
+   * this caveat does not apply.
+   */
+  async executeChunkedBatches(statements, options) {
+    if (statements.length === 0) {
+      return { deleted: 0, batches: 0, errors: [] };
+    }
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const callerBatchSize = options?.batchSize;
+    const stmtCap = minDefined(callerBatchSize, this.executor.maxBatchSize);
+    const chunks = chunkStatements(statements, stmtCap, this.executor.maxBatchParams);
+    const errors = [];
+    let deleted = 0;
+    let batches = 0;
+    const totalBatches = chunks.length;
+    const driverParamCap = this.executor.maxBatchParams;
+    for (let batchIndex = 0; batchIndex < chunks.length; batchIndex++) {
+      const chunk = chunks[batchIndex];
+      const isUnretriableOversize = chunk.length === 1 && driverParamCap !== void 0 && chunk[0].params.length > driverParamCap;
+      let committed = false;
+      let lastError = null;
+      const effectiveRetries = isUnretriableOversize ? 0 : maxRetries;
+      for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
+        try {
+          await this.executor.batch(chunk);
+          committed = true;
+          break;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+          if (attempt < effectiveRetries) {
+            const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+            await sleep(delay);
+          }
+        }
+      }
+      if (committed) {
+        deleted += chunk.length;
+        batches += 1;
+      } else if (lastError) {
+        errors.push({
+          batchIndex,
+          error: lastError,
+          operationCount: chunk.length
+        });
+      }
+      if (options?.onProgress) {
+        options.onProgress({
+          completedBatches: batches,
+          totalBatches,
+          deletedSoFar: deleted
+        });
+      }
+    }
+    return { deleted, batches, errors };
+  }
+  // --- Cross-scope (collection group) ---
+  async findEdgesGlobal(params, collectionName) {
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "findEdgesGlobal() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    const name = collectionName ?? this.collectionPath;
+    const scopeNameFilter = {
+      name,
+      isRoot: name === this.collectionPath
+    };
+    const stmt = compileSelectGlobal(
+      this.collectionPath,
+      plan.filters,
+      plan.options,
+      scopeNameFilter
+    );
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    return rows.map(rowToRecord);
+  }
+  // --- Aggregate ---
+  /**
+   * Run an aggregate query in a single SQL statement. Supports the full
+   * count/sum/avg/min/max set — the SQLite engine evaluates each aggregate
+   * function over the filtered row set and the executor returns one row
+   * with one column per alias. SUM/MIN/MAX of an empty set returns 0
+   * (SQLite's `SUM(NULL) = NULL` is mapped to a clean number for the
+   * cross-backend contract); AVG returns NaN, matching the mathematical
+   * convention and the Firestore Standard helper.
+   */
+  async aggregate(spec, filters) {
+    const { stmt, aliases } = compileAggregate(
+      this.collectionPath,
+      this.storageScope,
+      spec,
+      filters
+    );
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    const row = rows[0] ?? {};
+    const out = {};
+    for (const alias of aliases) {
+      const v = row[alias];
+      if (v === null || v === void 0) {
+        const op = spec[alias].op;
+        out[alias] = op === "avg" ? Number.NaN : 0;
+      } else if (typeof v === "bigint") {
+        out[alias] = Number(v);
+      } else if (typeof v === "number") {
+        out[alias] = v;
+      } else {
+        out[alias] = Number(v);
+      }
+    }
+    return out;
+  }
+  // --- Server-side DML ---
+  /**
+   * Delete every row matching `filters` in a single SQL DELETE statement.
+   *
+   * Uses `RETURNING "doc_id"` to count rows touched — the SQLite executor's
+   * `run` returns void, so RETURNING + `all()` is the portable way to learn
+   * how many rows the engine actually deleted. SQLite ≥ 3.35 supports
+   * `DELETE … RETURNING`; better-sqlite3, D1, and DO SQLite all run on a
+   * recent enough engine.
+   *
+   * Single-statement DML doesn't chunk: the engine handles N rows in one
+   * shot, so `BulkOptions.batchSize` is intentionally ignored. The retry
+   * loop here exists only for transient driver errors (e.g. D1 surface
+   * congestion); a permanent failure is surfaced via the `errors` array
+   * with `batchIndex: 0` so callers see the same shape as `bulkRemoveEdges`.
+   *
+   * Subgraph scoping is enforced inside `compileBulkDelete` (the leading
+   * `"scope" = ?` predicate) so this method, like every other backend
+   * surface, naturally honours subgraph isolation.
+   */
+  async bulkDelete(filters, options) {
+    const stmt = compileBulkDelete(this.collectionPath, this.storageScope, filters);
+    return this.executeDmlWithReturning(stmt, options);
+  }
+  /**
+   * Update every row matching `filters` with `patch.data` in a single SQL
+   * UPDATE statement. The patch is deep-merged into each row's `data`
+   * column via the same `flattenPatch` → `compileDataOpsExpr` pipeline that
+   * `compileUpdate` (single-row) uses.
+   *
+   * Same contract notes as `bulkDelete` apply: single-statement, no
+   * chunking, `RETURNING "doc_id"` for the affected count, retry loop for
+   * transient driver errors.
+   */
+  async bulkUpdate(filters, patch, options) {
+    const stmt = compileBulkUpdate(
+      this.collectionPath,
+      this.storageScope,
+      filters,
+      patch.data,
+      Date.now()
+    );
+    return this.executeDmlWithReturning(stmt, options);
+  }
+  /**
+   * Multi-source fan-out — `query.join` capability.
+   *
+   * Issues a single `SELECT … WHERE "aUid" IN (?, ?, …)` statement that
+   * matches every edge from every source UID in one round trip. When
+   * `params.hydrate === true`, follows up with a second statement that
+   * fetches the target node rows; both queries hit the same table so
+   * the executor amortises connection / parsing cost across them.
+   *
+   * Empty `params.sources` short-circuits to an empty result without
+   * touching the executor — `IN ()` is not valid SQL.
+   *
+   * Per-source ordering / strict per-source LIMIT enforcement is NOT
+   * implemented here; see the `ExpandParams.limitPerSource` JSDoc and
+   * `compileExpand` for the cap semantics. Strict per-source caps would
+   * require window functions and were judged out of scope for the
+   * round-trip-collapse goal.
+   */
+  async expand(params) {
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    const stmt = compileExpand(this.collectionPath, this.storageScope, params);
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    const edges = rows.map(rowToRecord);
+    if (!params.hydrate) {
+      return { edges };
+    }
+    const direction = params.direction ?? "forward";
+    const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+    const uniqueTargets = [...new Set(targetUids)];
+    if (uniqueTargets.length === 0) {
+      return { edges, targets: [] };
+    }
+    const hydrateStmt = compileExpandHydrate(this.collectionPath, this.storageScope, uniqueTargets);
+    const hydrateRows = await this.executor.all(hydrateStmt.sql, hydrateStmt.params);
+    const byUid = /* @__PURE__ */ new Map();
+    for (const row of hydrateRows) {
+      const node = rowToRecord(row);
+      byUid.set(node.bUid, node);
+    }
+    const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+    return { edges, targets };
+  }
+  /**
+   * Server-side projection — `query.select` capability.
+   *
+   * Issues a single `SELECT json_extract(data, '$.f1'), …` statement that
+   * returns only the requested fields. The compiler emits one column per
+   * unique field plus a paired `json_type` column for `data.*` projections
+   * so the decoder can recover JSON-encoded objects/arrays without a
+   * second round trip. Migrations are NOT applied — the caller asked for
+   * a partial shape, and rehydrating that into the migration pipeline
+   * would require synthesising every absent field.
+   *
+   * The wire-payload reduction is the entire reason this method exists:
+   * a list view that only needs `title` / `date` no longer drags the
+   * full `data` JSON across the network. Callers that need the full
+   * record should use `findEdges` (with migration support).
+   */
+  async findEdgesProjected(select, filters, options) {
+    const { stmt, columns } = compileFindEdgesProjected(
+      this.collectionPath,
+      this.storageScope,
+      select,
+      filters,
+      options
+    );
+    const rows = await this.executor.all(stmt.sql, stmt.params);
+    return rows.map((row) => decodeProjectedRow(row, columns));
+  }
+  /**
+   * Run a DML statement with `RETURNING "doc_id"` so we can count the
+   * rows the engine touched, with the same retry/backoff contract as
+   * `executeChunkedBatches`. Single statement, single batch.
+   */
+  async executeDmlWithReturning(stmt, options) {
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const rows = await this.executor.all(sqlWithReturning, stmt.params);
+        const deleted = rows.length;
+        if (options?.onProgress) {
+          options.onProgress({
+            completedBatches: 1,
+            totalBatches: 1,
+            deletedSoFar: deleted
+          });
+        }
+        return { deleted, batches: 1, errors: [] };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxRetries) {
+          const delay = Math.min(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), MAX_RETRY_DELAY_MS);
+          await sleep(delay);
+        }
+      }
+    }
+    return {
+      deleted: 0,
+      batches: 0,
+      errors: [
+        {
+          batchIndex: 0,
+          error: lastError ?? new Error("bulk DML failed for unknown reason"),
+          operationCount: 0
+        }
+      ]
+    };
+  }
+};
+function createSqliteBackend(executor, tableName, options = {}) {
+  const storageScope = options.storageScope ?? "";
+  const scopePath = options.scopePath ?? "";
+  return new SqliteBackendImpl(executor, tableName, storageScope, scopePath);
+}
+export {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
+  createGraphClient,
+  createMergedRegistry,
+  createRegistry,
+  createSqliteBackend,
+  generateId
+};
+//# sourceMappingURL=index.js.map