@typicalday/firegraph 0.10.0 → 0.11.0

package/dist/cloudflare/index.d.cts

@@ -1,5 +1,5 @@
-import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-73p5Blx7.cjs';
-import { i as QueryFilter, y as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, c as GraphRegistry, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-DOemdlVA.cjs';
+import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-np4gEVhB.cjs';
+import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.cjs';
 import '@google-cloud/firestore';
 
 /**
@@ -127,6 +127,24 @@ interface FiregraphDOOptions {
     table?: string;
     /** Run schema DDL on first boot. Default: `true`. */
     autoMigrate?: boolean;
+    /**
+     * Registry whose per-entry `indexes` get compiled into `CREATE INDEX`
+     * statements during schema bootstrap. Supply the same registry you pass
+     * to `createGraphClient` on the Worker side to keep DO and client in sync.
+     */
+    registry?: GraphRegistry;
+    /**
+     * Replaces the built-in core index preset
+     * (`DEFAULT_CORE_INDEXES`). Supply this when the default set of
+     * `(aUid, axbType)`, `(axbType, bUid)`, etc. composites doesn't fit your
+     * query shapes — e.g., you want descending timestamps or a reduced set.
+     * Entry-level `RegistryEntry.indexes` remain additive on top.
+     *
+     * Pass `[]` to disable core indexes entirely (advanced — only safe when
+     * the provided `registry`'s entries cover every query shape your app
+     * issues).
+     */
+    coreIndexes?: IndexSpec[];
 }
 declare class FiregraphDO {
     /** @internal — exposed for subclass access, not part of the public RPC. */
@@ -135,6 +153,10 @@ declare class FiregraphDO {
     protected readonly env: unknown;
     /** @internal — table name used by every compiled statement. */
     protected readonly table: string;
+    /** @internal — registry consulted by `runSchema` for per-entry indexes. */
+    protected readonly registry?: GraphRegistry;
+    /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
+    protected readonly coreIndexes?: IndexSpec[];
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
@@ -451,4 +473,57 @@ declare function createDOClient(namespace: FiregraphNamespace, rootKey: string,
 declare function createSiblingClient(client: GraphClient, siblingRootKey: string): GraphClient;
 declare function createSiblingClient(client: DynamicGraphClient, siblingRootKey: string): DynamicGraphClient;
 
-export { type BatchOp, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, createDOClient, createSiblingClient };
+/**
+ * Flat SQLite schema for a single firegraph DO.
+ *
+ * Each `FiregraphDO` instance owns its own SQLite database and holds exactly
+ * one subgraph's triples. Subgraph isolation is physical (one DO per
+ * subgraph), so there is no `scope` column — every row in this DO belongs to
+ * the same logical scope. This is the Cloudflare-native design: the scope
+ * discriminator used by the legacy shared-table SQLite backend
+ * (`src/internal/sqlite-schema.ts`) does not exist here.
+ *
+ * Document IDs:
+ *   - Nodes: the UID itself
+ *   - Edges: `shard:aUid:axbType:bUid`
+ *
+ * Indexes come from two sources and are appended to the DDL list:
+ *
+ *  1. The core preset (`DEFAULT_CORE_INDEXES`), overridable per-DO via
+ *     `FiregraphDOOptions.coreIndexes`.
+ *  2. Per-registry-entry `indexes` declared on `RegistryEntry` (from code or
+ *     `meta.json` via entity discovery).
+ *
+ * Both sets are deduplicated by canonical fingerprint, so declaring the same
+ * composite twice (e.g., by preset + registry entry) collapses to one
+ * `CREATE INDEX`.
+ */
+
+/**
+ * Options controlling DDL emission for `buildDOSchemaStatements`.
+ */
+interface BuildDOSchemaOptions {
+    /**
+     * Replaces the built-in core preset. Defaults to `DEFAULT_CORE_INDEXES`.
+     * Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+    /**
+     * Registry contributing per-triple `indexes` declarations. Entries with
+     * no `indexes` field are ignored; the rest are flattened and deduplicated
+     * against the core preset by canonical fingerprint.
+     */
+    registry?: GraphRegistry;
+}
+/**
+ * DDL statements that create the firegraph table and its indexes. Returned
+ * as separate statements because DO SQLite's `exec()` runs one statement per
+ * call. Run via `FiregraphDO.ensureSchema()` on DO boot.
+ *
+ * The CREATE TABLE statement is always first; index statements follow in
+ * deterministic order. Same specs across runs produce the same statements,
+ * so `CREATE INDEX IF NOT EXISTS` is idempotent.
+ */
+declare function buildDOSchemaStatements(table: string, options?: BuildDOSchemaOptions): string[];
+
+export { type BatchOp, type BuildDOSchemaOptions, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };

package/dist/cloudflare/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-BrqFkbid.js';
-import { i as QueryFilter, y as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, c as GraphRegistry, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-DOemdlVA.js';
+import { W as WritableRecord, U as UpdatePayload, S as StorageBackend, T as TransactionBackend, B as BatchBackend } from '../backend-U-MLShlg.js';
+import { c as GraphRegistry, I as IndexSpec, i as QueryFilter, z as QueryOptions, C as CascadeResult, F as FindEdgesParams, m as BulkOptions, o as BulkResult, a as GraphClient, D as DynamicGraphClient, S as StoredGraphRecord, d as GraphReader, G as GraphClientOptions, e as DynamicRegistryConfig } from '../types-BGWxcpI_.js';
 import '@google-cloud/firestore';
 
 /**
@@ -127,6 +127,24 @@ interface FiregraphDOOptions {
     table?: string;
     /** Run schema DDL on first boot. Default: `true`. */
     autoMigrate?: boolean;
+    /**
+     * Registry whose per-entry `indexes` get compiled into `CREATE INDEX`
+     * statements during schema bootstrap. Supply the same registry you pass
+     * to `createGraphClient` on the Worker side to keep DO and client in sync.
+     */
+    registry?: GraphRegistry;
+    /**
+     * Replaces the built-in core index preset
+     * (`DEFAULT_CORE_INDEXES`). Supply this when the default set of
+     * `(aUid, axbType)`, `(axbType, bUid)`, etc. composites doesn't fit your
+     * query shapes — e.g., you want descending timestamps or a reduced set.
+     * Entry-level `RegistryEntry.indexes` remain additive on top.
+     *
+     * Pass `[]` to disable core indexes entirely (advanced — only safe when
+     * the provided `registry`'s entries cover every query shape your app
+     * issues).
+     */
+    coreIndexes?: IndexSpec[];
 }
 declare class FiregraphDO {
     /** @internal — exposed for subclass access, not part of the public RPC. */
@@ -135,6 +153,10 @@ declare class FiregraphDO {
     protected readonly env: unknown;
     /** @internal — table name used by every compiled statement. */
     protected readonly table: string;
+    /** @internal — registry consulted by `runSchema` for per-entry indexes. */
+    protected readonly registry?: GraphRegistry;
+    /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
+    protected readonly coreIndexes?: IndexSpec[];
     constructor(ctx: DurableObjectStateLike, env: unknown, options?: FiregraphDOOptions);
     _fgGetDoc(docId: string): Promise<DORecordWire | null>;
     _fgQuery(filters: QueryFilter[], options?: QueryOptions): Promise<DORecordWire[]>;
@@ -451,4 +473,57 @@ declare function createDOClient(namespace: FiregraphNamespace, rootKey: string,
 declare function createSiblingClient(client: GraphClient, siblingRootKey: string): GraphClient;
 declare function createSiblingClient(client: DynamicGraphClient, siblingRootKey: string): DynamicGraphClient;
 
-export { type BatchOp, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, createDOClient, createSiblingClient };
+/**
+ * Flat SQLite schema for a single firegraph DO.
+ *
+ * Each `FiregraphDO` instance owns its own SQLite database and holds exactly
+ * one subgraph's triples. Subgraph isolation is physical (one DO per
+ * subgraph), so there is no `scope` column — every row in this DO belongs to
+ * the same logical scope. This is the Cloudflare-native design: the scope
+ * discriminator used by the legacy shared-table SQLite backend
+ * (`src/internal/sqlite-schema.ts`) does not exist here.
+ *
+ * Document IDs:
+ *   - Nodes: the UID itself
+ *   - Edges: `shard:aUid:axbType:bUid`
+ *
+ * Indexes come from two sources and are appended to the DDL list:
+ *
+ *  1. The core preset (`DEFAULT_CORE_INDEXES`), overridable per-DO via
+ *     `FiregraphDOOptions.coreIndexes`.
+ *  2. Per-registry-entry `indexes` declared on `RegistryEntry` (from code or
+ *     `meta.json` via entity discovery).
+ *
+ * Both sets are deduplicated by canonical fingerprint, so declaring the same
+ * composite twice (e.g., by preset + registry entry) collapses to one
+ * `CREATE INDEX`.
+ */
+
+/**
+ * Options controlling DDL emission for `buildDOSchemaStatements`.
+ */
+interface BuildDOSchemaOptions {
+    /**
+     * Replaces the built-in core preset. Defaults to `DEFAULT_CORE_INDEXES`.
+     * Pass `[]` to disable core indexes entirely.
+     */
+    coreIndexes?: IndexSpec[];
+    /**
+     * Registry contributing per-triple `indexes` declarations. Entries with
+     * no `indexes` field are ignored; the rest are flattened and deduplicated
+     * against the core preset by canonical fingerprint.
+     */
+    registry?: GraphRegistry;
+}
+/**
+ * DDL statements that create the firegraph table and its indexes. Returned
+ * as separate statements because DO SQLite's `exec()` runs one statement per
+ * call. Run via `FiregraphDO.ensureSchema()` on DO boot.
+ *
+ * The CREATE TABLE statement is always first; index statements follow in
+ * deterministic order. Same specs across runs produce the same statements,
+ * so `CREATE INDEX IF NOT EXISTS` is idempotent.
+ */
+declare function buildDOSchemaStatements(table: string, options?: BuildDOSchemaOptions): string[];
+
+export { type BatchOp, type BuildDOSchemaOptions, type DOClientOptions, DORPCBackend, type DORPCBackendOptions, type DOSqlCursor, type DOSqlExecutor, type DOStorage, type DurableObjectIdLike, type DurableObjectStateLike, FiregraphDO, type FiregraphDOOptions, type FiregraphNamespace, type FiregraphStub, buildDOSchemaStatements, createDOClient, createSiblingClient };

package/dist/cloudflare/index.js

@@ -1,10 +1,11 @@
 import {
+  DEFAULT_CORE_INDEXES,
   NODE_RELATION,
   buildEdgeQueryPlan,
   computeEdgeDocId,
   computeNodeDocId,
   createGraphClientFromBackend
-} from "../chunk-LZOIQHYN.js";
+} from "../chunk-6SB34IPQ.js";
 import {
   FiregraphError
 } from "../chunk-R7CRGYY4.js";
@@ -34,6 +35,104 @@ var GraphTimestampImpl = class _GraphTimestampImpl {
   }
 };
 
+// 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",
@@ -45,9 +144,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_]*$/.`);
   }
 }
@@ -55,9 +154,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,
@@ -69,13 +168,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
@@ -85,12 +186,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}`,
@@ -127,7 +230,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(
@@ -135,7 +238,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"
@@ -143,8 +246,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));
@@ -199,11 +301,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}`;
 }
@@ -607,12 +708,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 () => {
@@ -802,7 +909,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();
     }
   }
@@ -816,6 +927,7 @@ var FiregraphDO = class {
 export {
   DORPCBackend,
   FiregraphDO,
+  buildDOSchemaStatements,
   createDOClient,
   createSiblingClient
 };