@typicalday/firegraph 0.10.0 → 0.11.1

package/dist/cloudflare/index.cjs

@@ -159,6 +159,7 @@ var cloudflare_exports = {};
 __export(cloudflare_exports, {
   DORPCBackend: () => DORPCBackend,
   FiregraphDO: () => FiregraphDO,
+  buildDOSchemaStatements: () => buildDOSchemaStatements,
   createDOClient: () => createDOClient,
   createSiblingClient: () => createSiblingClient
 });
@@ -258,6 +259,116 @@ var GraphTimestampImpl = class _GraphTimestampImpl {
   }
 };
 
+// src/default-indexes.ts
+var DEFAULT_CORE_INDEXES = Object.freeze([
+  { fields: ["aUid"] },
+  { fields: ["bUid"] },
+  { fields: ["aType"] },
+  { fields: ["bType"] },
+  { fields: ["aUid", "axbType"] },
+  { fields: ["axbType", "bUid"] },
+  { fields: ["aType", "axbType"] },
+  { fields: ["axbType", "bType"] }
+]);
+
+// 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/cloudflare/schema.ts
 var DO_FIELD_TO_COLUMN = {
   aType: "a_type",
@@ -269,9 +380,9 @@ var DO_FIELD_TO_COLUMN = {
   createdAt: "created_at",
   updatedAt: "updated_at"
 };
-var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var IDENT_RE2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validateDOTableName(name) {
-  if (!IDENT_RE.test(name)) {
+  if (!IDENT_RE2.test(name)) {
     throw new Error(`Invalid SQL identifier: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
   }
 }
@@ -279,9 +390,9 @@ function quoteDOIdent(name) {
   validateDOTableName(name);
   return `"${name}"`;
 }
-function buildDOSchemaStatements(table) {
+function buildDOSchemaStatements(table, options = {}) {
   const t = quoteDOIdent(table);
-  return [
+  const statements = [
     `CREATE TABLE IF NOT EXISTS ${t} (
       doc_id      TEXT NOT NULL PRIMARY KEY,
       a_type      TEXT NOT NULL,
@@ -293,13 +404,15 @@ function buildDOSchemaStatements(table) {
       v           INTEGER,
       created_at  INTEGER NOT NULL,
       updated_at  INTEGER NOT NULL
-    )`,
-    `CREATE INDEX IF NOT EXISTS ${quoteDOIdent(`${table}_idx_a_uid`)} ON ${t}(a_uid)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteDOIdent(`${table}_idx_b_uid`)} ON ${t}(b_uid)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteDOIdent(`${table}_idx_axb_type_b_uid`)} ON ${t}(axb_type, b_uid)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteDOIdent(`${table}_idx_a_type`)} ON ${t}(a_type)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteDOIdent(`${table}_idx_b_type`)} ON ${t}(b_type)`
+    )`
   ];
+  const core = options.coreIndexes ?? [...DEFAULT_CORE_INDEXES];
+  const fromRegistry = options.registry?.entries().flatMap((e) => e.indexes ?? []) ?? [];
+  const deduped = dedupeIndexSpecs([...core, ...fromRegistry]);
+  for (const spec of deduped) {
+    statements.push(buildIndexDDL(spec, { table, fieldToColumn: DO_FIELD_TO_COLUMN }));
+  }
+  return statements;
 }
 
 // src/cloudflare/sql.ts
@@ -309,12 +422,14 @@ function compileFieldRef(field) {
     return { expr: quoteDOIdent(column) };
   }
   if (field.startsWith("data.")) {
-    const key = field.slice(5);
-    validateJsonPathKey(key);
-    return { expr: 'json_extract("data", ?)', pathParam: `$.${key}` };
+    const suffix = field.slice(5);
+    for (const part of suffix.split(".")) {
+      validateJsonPathKey(part);
+    }
+    return { expr: `json_extract("data", '$.${suffix}')` };
   }
   if (field === "data") {
-    return { expr: 'json_extract("data", ?)', pathParam: "$" };
+    return { expr: `json_extract("data", '$')` };
   }
   throw new FiregraphError(
     `DO SQLite backend cannot resolve filter field: ${field}`,
@@ -351,7 +466,7 @@ function bindValue(value) {
   }
   return String(value);
 }
-var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 function validateJsonPathKey(key) {
   if (key.length === 0) {
     throw new FiregraphError(
@@ -359,7 +474,7 @@ function validateJsonPathKey(key) {
       "INVALID_QUERY"
     );
   }
-  if (!JSON_PATH_KEY_RE.test(key)) {
+  if (!JSON_PATH_KEY_RE2.test(key)) {
     throw new FiregraphError(
       `DO SQLite backend: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceData (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
       "INVALID_QUERY"
@@ -367,8 +482,7 @@ function validateJsonPathKey(key) {
   }
 }
 function compileFilter(filter, params) {
-  const { expr, pathParam } = compileFieldRef(filter.field);
-  if (pathParam !== void 0) params.push(pathParam);
+  const { expr } = compileFieldRef(filter.field);
   switch (filter.op) {
     case "==":
       params.push(bindValue(filter.value));
@@ -423,11 +537,10 @@ function asArray(value, op) {
   }
   return value;
 }
-function compileOrderBy(options, params) {
+function compileOrderBy(options, _params) {
   if (!options?.orderBy) return "";
   const { field, direction } = options.orderBy;
-  const { expr, pathParam } = compileFieldRef(field);
-  if (pathParam !== void 0) params.push(pathParam);
+  const { expr } = compileFieldRef(field);
   const dir = direction === "desc" ? "DESC" : "ASC";
   return ` ORDER BY ${expr} ${dir}`;
 }
@@ -915,9 +1028,7 @@ async function migrateRecord(record, registry, globalWriteBack = "off") {
   };
 }
 async function migrateRecords(records, registry, globalWriteBack = "off") {
-  return Promise.all(
-    records.map((r) => migrateRecord(r, registry, globalWriteBack))
-  );
+  return Promise.all(records.map((r) => migrateRecord(r, registry, globalWriteBack)));
 }
 
 // src/scope.ts
@@ -1125,7 +1236,8 @@ function discoveryToEntries(discovery) {
       subtitleField: entity.subtitleField,
       allowedIn: entity.allowedIn,
       migrations: entity.migrations,
-      migrationWriteBack: entity.migrationWriteBack
+      migrationWriteBack: entity.migrationWriteBack,
+      indexes: entity.indexes
     });
   }
   for (const [axbType, entity] of discovery.edges) {
@@ -1153,7 +1265,8 @@ function discoveryToEntries(discovery) {
           allowedIn: entity.allowedIn,
           targetGraph: resolvedTargetGraph,
           migrations: entity.migrations,
-          migrationWriteBack: entity.migrationWriteBack
+          migrationWriteBack: entity.migrationWriteBack,
+          indexes: entity.indexes
         });
       }
     }
@@ -2321,12 +2434,18 @@ var FiregraphDO = class {
   env;
   /** @internal — table name used by every compiled statement. */
   table;
+  /** @internal — registry consulted by `runSchema` for per-entry indexes. */
+  registry;
+  /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
+  coreIndexes;
   constructor(ctx, env, options = {}) {
     this.ctx = ctx;
     this.env = env;
     const table = options.table ?? DEFAULT_OPTIONS.table;
     validateDOTableName(table);
     this.table = table;
+    this.registry = options.registry;
+    this.coreIndexes = options.coreIndexes;
     const autoMigrate = options.autoMigrate ?? DEFAULT_OPTIONS.autoMigrate;
     if (autoMigrate) {
       void this.ctx.blockConcurrencyWhile(async () => {
@@ -2516,7 +2635,11 @@ var FiregraphDO = class {
   // Internals
   // ---------------------------------------------------------------------------
   runSchema() {
-    for (const sql of buildDOSchemaStatements(this.table)) {
+    const statements = buildDOSchemaStatements(this.table, {
+      coreIndexes: this.coreIndexes,
+      registry: this.registry
+    });
+    for (const sql of statements) {
       this.ctx.storage.sql.exec(sql).toArray();
     }
   }
@@ -2531,6 +2654,7 @@ var FiregraphDO = class {
 0 && (module.exports = {
   DORPCBackend,
   FiregraphDO,
+  buildDOSchemaStatements,
   createDOClient,
   createSiblingClient
 });