@spooky-sync/core 0.0.1-canary.133 → 0.0.1-canary.134

package/src/services/database/sqlite-select.ts

@@ -0,0 +1,113 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { resolveRelations, stableKey } from './relation-resolver';
+import { renderOrderSql, renderWhereSql, reviveRow, project } from './sqlite-plan-sql';
+import type { OrderBy, RelationFetch, Row, RowFetcher } from './cache-engine';
+
+/**
+ * Worker-side execution of a whole {@link QueryPlan} — table creation, base
+ * select (either the `ids` window or where/order/limit), projection, and the
+ * full `.related()` tree via the SHARED `resolveRelations` — against an
+ * injected DB handle. Runs inside `sqlite-worker.ts` so the engine pays ONE
+ * postMessage round-trip per select instead of one per table/relation level;
+ * extracted into its own module so the logic is unit-testable off-worker
+ * (parity with the engine's legacy multi-hop path).
+ *
+ * Semantics mirror `SqliteCacheEngine.selectLegacy` exactly: same SQL, same
+ * ordering rules, same projection, same resolver.
+ */
+
+/** The slice of the worker's DB surface `executeSelect` needs. */
+export interface SelectDb {
+  /** Run a row-returning statement; rows come back as `{ data: <json> }`. */
+  exec(sql: string, bind?: unknown[]): { data: string }[];
+  /** Run a statement for effect only (CREATE TABLE). */
+  run(sql: string, bind?: unknown[]): void;
+  /** Tables already CREATEd on this handle (caller owns the lifecycle). */
+  knownTables: Set<string>;
+}
+
+function ensureTable(db: SelectDb, table: string): void {
+  if (db.knownTables.has(table)) return;
+  db.run(`CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+  db.knownTables.add(table);
+}
+
+function execRows(db: SelectDb, sql: string, bind: unknown[]): Row[] {
+  return db.exec(sql, bind).map((r) => reviveRow(r.data));
+}
+
+/** Mirrors the engine's `selectByIds`: fetch by primary id, preserving `ids`
+ *  order unless an ORDER BY overrides it. */
+function selectByIds(
+  db: SelectDb,
+  table: string,
+  ids: unknown[],
+  opts?: { select?: string[]; orderBy?: OrderBy }
+): Row[] {
+  if (ids.length === 0) return [];
+  ensureTable(db, table);
+  const keys = ids.map(stableKey);
+  const placeholders = keys.map(() => '?').join(', ');
+  let sql = `SELECT data FROM "${table}" WHERE id IN (${placeholders})`;
+  if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+  let rows = execRows(db, sql, keys);
+  if (!opts?.orderBy || opts.orderBy.length === 0) {
+    const pos = new Map(keys.map((k, i) => [k, i]));
+    rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+  }
+  return opts?.select ? rows.map((r) => project(r, opts.select!)) : rows;
+}
+
+/** Mirrors the engine's `fetchRelation` SQL exactly. */
+function fetchRelation(db: SelectDb, req: RelationFetch): Row[] {
+  ensureTable(db, req.table);
+  const keys = req.keys.map(stableKey);
+  const placeholders = keys.map(() => '?').join(', ');
+  const bind: unknown[] = [...keys];
+  const lhs = req.matchField === 'id' ? 'id' : `json_extract(data, '$.${req.matchField}')`;
+  let sql = `SELECT data FROM "${req.table}" WHERE ${lhs} IN (${placeholders})`;
+  if (req.where && req.where.length > 0) {
+    sql += ` AND ${renderWhereSql(req.where, bind, {})}`;
+  }
+  if (req.orderBy && req.orderBy.length > 0) sql += renderOrderSql(req.orderBy);
+  const rows = execRows(db, sql, bind);
+  return req.select ? rows.map((r) => project(r, req.select!)) : rows;
+}
+
+export async function executeSelect(
+  plan: QueryPlan,
+  params: Record<string, unknown>,
+  db: SelectDb
+): Promise<{ rows: Row[]; relationFetches: number }> {
+  // Per-call fetch counter (the engine folds it into `__sqliteStats`).
+  const counter = { n: 0 };
+  const fetcher: RowFetcher = {
+    fetchRelation: (req) => {
+      counter.n++;
+      return Promise.resolve(fetchRelation(db, req));
+    },
+  };
+  // Window materialization: base rows are exactly `plan.ids`, ordered.
+  if (plan.ids) {
+    const rows = selectByIds(db, plan.table, plan.ids, {
+      select: plan.select,
+      orderBy: plan.orderBy,
+    });
+    await resolveRelations(rows, plan.relations, fetcher);
+    return { rows, relationFetches: counter.n };
+  }
+  ensureTable(db, plan.table);
+  const bind: unknown[] = [];
+  let sql = `SELECT data FROM "${plan.table}"`;
+  if (plan.where && plan.where.length > 0) {
+    sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
+  }
+  if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
+  if (plan.limit !== undefined) sql += ` LIMIT ${Number(plan.limit)}`;
+  if (plan.offset !== undefined) sql += ` OFFSET ${Number(plan.offset)}`;
+  const rows = execRows(db, sql, bind);
+  // Optional projection trimming to match `SELECT <fields>`.
+  const projected = plan.select ? rows.map((r) => project(r, plan.select!)) : rows;
+  await resolveRelations(projected, plan.relations, fetcher);
+  return { rows: projected, relationFetches: counter.n };
+}

package/src/services/database/sqlite-worker.ts

@@ -9,13 +9,20 @@
  * to an in-memory DB when OPFS is unavailable.
  *
  * Message protocol (request/response keyed by `id`):
- *   { id, type: 'open',  payload: { dbName, useOpfs } }
- *   { id, type: 'exec',  payload: { sql, bind } }  -> { id, ok, rows }
- *   { id, type: 'run',   payload: { sql, bind } }  -> { id, ok }
- *   { id, type: 'batch', payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+ *   { id, type: 'open',   payload: { dbName, useOpfs } }
+ *   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
+ *   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
+ *   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+ *   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
  *   { id, type: 'close' }
+ *
+ * `select` executes a whole QueryPlan — table creation, base select, the full
+ * `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
+ * round-trip, returning structured-clone row objects. This is the first-load
+ * hot path; the per-statement ops remain for the write/shim paths.
  */
 import sqlite3InitModule from '@sqlite.org/sqlite-wasm';
+import { executeSelect, type SelectDb } from './sqlite-select';
 
 interface Stmt {
   sql: string;
@@ -78,14 +85,32 @@ function batch(stmts: Stmt[]): void {
   }
 }
 
+// ==================== worker-side plan execution ('select') ====================
+
+/** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
+ *  plan executor). `knownTables` is cleared on open/close — a bucket switch
+ *  spawns a fresh worker anyway. */
+const selectDb: SelectDb = {
+  exec: (sql, bind) => exec(sql, bind) as { data: string }[],
+  run,
+  knownTables: new Set<string>(),
+};
+
 self.onmessage = async (ev: MessageEvent) => {
   const { id, type, payload } = ev.data ?? {};
+  // `wt` (worker time) lets the main thread split a round-trip into actual DB
+  // work vs postMessage/queue overhead (see `__sqliteStats`).
+  const t0 = performance.now();
   try {
     let result: unknown;
     switch (type) {
       case 'open':
+        selectDb.knownTables.clear();
         result = await open(payload.dbName, payload.useOpfs);
         break;
+      case 'select':
+        result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);
+        break;
       case 'exec':
         result = { rows: exec(payload.sql, payload.bind) };
         break;
@@ -100,12 +125,18 @@ self.onmessage = async (ev: MessageEvent) => {
       case 'close':
         db?.close();
         db = null;
+        selectDb.knownTables.clear();
         result = {};
         break;
       default:
         throw new Error(`sqlite worker: unknown message ${type}`);
     }
-    (self as unknown as Worker).postMessage({ id, ok: true, ...(result as object) });
+    (self as unknown as Worker).postMessage({
+      id,
+      ok: true,
+      wt: performance.now() - t0,
+      ...(result as object),
+    });
   } catch (err) {
     (self as unknown as Worker).postMessage({
       id,

package/src/types.ts

@@ -117,6 +117,13 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
     store?: StoreType;
     /** Authentication token. */
     token?: string;
+    /**
+     * SQLite engine only: execute `select` plans (base rows + relation tree +
+     * row parsing) inside the worker as ONE round-trip instead of one hop per
+     * table/relation level. Defaults to true; set false to force the legacy
+     * multi-hop path (escape hatch while the worker-side path beds in).
+     */
+    workerSelect?: boolean;
   };
   /** The schema definition. */
   schema: S;