@spooky-sync/core 0.0.1-canary.15 → 0.0.1-canary.151

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

@@ -0,0 +1,160 @@
+/// <reference lib="webworker" />
+/**
+ * Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+ * funnelled through here (the main thread never touches the wasm module), which
+ * is also what the OPFS VFS requires — file access must happen off the main
+ * thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+ * classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+ * headers, so host apps embedding the client need no server changes. Falls back
+ * 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: '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;
+  bind?: unknown[];
+}
+
+let db: {
+  exec: (opts: { sql: string; bind?: unknown[]; rowMode?: string; returnValue?: string }) => unknown;
+  close: () => void;
+} | null = null;
+
+async function open(
+  dbName: string,
+  useOpfs: boolean,
+  systemTables: readonly string[] = []
+): Promise<{ persisted: boolean }> {
+  const sqlite3: any = await sqlite3InitModule();
+  let persisted = false;
+  if (useOpfs && sqlite3.installOpfsSAHPoolVfs) {
+    try {
+      const pool = await sqlite3.installOpfsSAHPoolVfs({ name: `sp00ky-${dbName}` });
+      db = new pool.OpfsSAHPoolDb(`/${dbName}.sqlite3`);
+      persisted = true;
+    } catch {
+      // fall through to in-memory
+    }
+  }
+  if (!db) db = new sqlite3.oo1.DB(':memory:', 'c');
+  // Physically create the internal `_00_*` tables the client reads before any
+  // write (DEFINE is a noop on this engine, so the migrator can't). Prevents
+  // "no such table: _00_query" on a fresh bucket right after signup.
+  for (const t of systemTables) {
+    db!.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+  }
+  // Retry (rather than instantly failing with SQLITE_BUSY=5) if a lock is held.
+  // Combined with the engine's single-flight op queue, overlap is avoided.
+  // `cache_size` is negated → KiB (here 32 MiB) so SQLite's page cache can't
+  // grow unbounded and starve a wasm-heavy renderer.
+  try {
+    db!.exec({ sql: 'PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;' });
+  } catch {
+    /* pragma best-effort */
+  }
+  return { persisted };
+}
+
+function exec(sql: string, bind?: unknown[]): unknown[] {
+  if (!db) throw new Error('sqlite: DB not open');
+  return db.exec({ sql, bind, rowMode: 'object', returnValue: 'resultRows' }) as unknown[];
+}
+
+function run(sql: string, bind?: unknown[]): void {
+  if (!db) throw new Error('sqlite: DB not open');
+  db.exec({ sql, bind });
+}
+
+function batch(stmts: Stmt[]): void {
+  if (!db) throw new Error('sqlite: DB not open');
+  db.exec({ sql: 'BEGIN' });
+  try {
+    for (const s of stmts) db.exec({ sql: s.sql, bind: s.bind });
+    db.exec({ sql: 'COMMIT' });
+  } catch (e) {
+    try {
+      db.exec({ sql: 'ROLLBACK' });
+    } catch {
+      /* ignore */
+    }
+    throw e;
+  }
+}
+
+// ==================== 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, payload.systemTables);
+        // The freshly seeded system tables exist — record them so the select
+        // path doesn't redundantly re-issue CREATE TABLE for each.
+        for (const t of (payload.systemTables ?? []) as string[]) selectDb.knownTables.add(t);
+        break;
+      case 'select':
+        result = await executeSelect(payload.plan, payload.params ?? {}, selectDb);
+        break;
+      case 'exec':
+        result = { rows: exec(payload.sql, payload.bind) };
+        break;
+      case 'run':
+        run(payload.sql, payload.bind);
+        result = {};
+        break;
+      case 'batch':
+        batch(payload as Stmt[]);
+        result = {};
+        break;
+      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,
+      wt: performance.now() - t0,
+      ...(result as object),
+    });
+  } catch (err) {
+    (self as unknown as Worker).postMessage({
+      id,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+};

package/src/services/database/surql-translate.ts

@@ -0,0 +1,291 @@
+import type { WhereNode } from '@spooky-sync/query-builder';
+import type { OrderBy, Row } from './cache-engine';
+import { stableKey } from './relation-resolver';
+
+/**
+ * Translate the BOUNDED set of SurrealQL statements the client actually emits
+ * into engine-neutral operations the SQLite backend executes. This is NOT a
+ * general SurrealQL parser — it recognizes exactly the shapes produced by the
+ * `surql` helper and the handful of literal queries in the codebase. Anything
+ * unrecognized throws (with the offending SQL) so gaps surface loudly during a
+ * trial rather than silently returning wrong data.
+ *
+ * The arbitrary user SELECT (`config.surql`, with nested `.related()`
+ * subqueries) is intentionally NOT handled here — it flows through
+ * `engine.select(plan)` instead, so the translator never faces an unbounded
+ * query shape.
+ */
+
+export type SqlOp =
+  | { kind: 'getById'; id: unknown; select?: string[]; value?: string }
+  | { kind: 'selectByIds'; ids: unknown[]; select?: string[]; orderBy?: OrderBy; value?: string }
+  | { kind: 'selectTable'; table: string; where?: WhereNode[]; orderBy?: OrderBy; select?: string[]; value?: string }
+  | { kind: 'upsert'; id: unknown; data: Row; mode: 'replace' | 'merge' }
+  | { kind: 'updateSet'; id: unknown; sets: SetClause[]; returnNone: boolean }
+  | { kind: 'delete'; id: unknown }
+  | { kind: 'deleteAll'; table: string }
+  | { kind: 'let'; var: string; inner: SqlOp }
+  | { kind: 'return'; entries: { key: string; var: string }[] }
+  | { kind: 'noop' };
+
+export interface SetClause {
+  path: string;
+  op: '=' | '+=' | '-=';
+  value: unknown;
+}
+
+export interface TranslatedQuery {
+  /** True for a `BEGIN TRANSACTION … COMMIT` block — the engine prepends a
+   *  `null` begin-result so `surql.seal`'s `idx+1` extraction still lines up. */
+  transaction: boolean;
+  ops: SqlOp[];
+}
+
+const rid = (v: unknown): unknown => v;
+
+/** Table name from a record id value (`table:id` string or RecordId). */
+export function tableOf(id: unknown): string {
+  return stableKey(id).split(':')[0];
+}
+
+export function translateSurql(sql: string, vars: Record<string, unknown>): TranslatedQuery {
+  const trimmed = sql.trim().replace(/;\s*$/, '');
+
+  if (/^BEGIN\s+TRANSACTION/i.test(trimmed)) {
+    const inner = trimmed
+      .replace(/^BEGIN\s+TRANSACTION\s*;?/i, '')
+      .replace(/;?\s*COMMIT\s+TRANSACTION\s*$/i, '');
+    const ops = splitStatements(inner).map((s) => translateStatement(s, vars));
+    return { transaction: true, ops };
+  }
+
+  // A plain multi-statement string (e.g. `DEFINE DATABASE x; USE DB x`) — split
+  // and translate each. Single statement is just the one-element case.
+  const parts = splitStatements(trimmed);
+  return { transaction: false, ops: parts.map((s) => translateStatement(s, vars)) };
+}
+
+function splitStatements(block: string): string[] {
+  // Statements in the client's tx blocks never contain a bare `;` inside a
+  // string/paren, so a simple split is sufficient for this bounded vocabulary.
+  return block
+    .split(';')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function translateStatement(stmt: string, vars: Record<string, unknown>): SqlOp {
+  const s = stmt.trim();
+
+  // LET $var = ( <inner statement> ) — bind the inner result into query scope.
+  let mLet = /^LET\s+\$(\w+)\s*=\s*\(([\s\S]+)\)$/i.exec(s);
+  if (mLet) {
+    return { kind: 'let', var: mLet[1], inner: translateStatement(mLet[2].trim(), vars) };
+  }
+
+  // RETURN { key: $var, ... } — build an object from scope/vars.
+  let mRet = /^RETURN\s+\{([\s\S]+)\}$/i.exec(s);
+  if (mRet) {
+    const entries = splitTopLevel(mRet[1], ',').map((pair) => {
+      const c = pair.indexOf(':');
+      const key = pair.slice(0, c).trim();
+      const v = pair.slice(c + 1).trim();
+      return { key, var: v.startsWith('$') ? v.slice(1) : v };
+    });
+    return { kind: 'return', entries };
+  }
+
+  // ---- schema / session DDL: no-ops on a schemaless engine --------------
+  // SQLite creates tables lazily and has no namespaces/DB DDL, so DEFINE /
+  // REMOVE / USE / INFO / RETURN statements are safely ignored.
+  if (/^(DEFINE|REMOVE|USE|INFO|RETURN|CANCEL|COMMIT|BEGIN)\b/i.test(s)) {
+    return { kind: 'noop' };
+  }
+
+  // ---- writes -----------------------------------------------------------
+  let m =
+    /^CREATE\s+ONLY\s+\$(\w+)\s+CONTENT\s+\$(\w+)$/i.exec(s) ||
+    /^UPSERT\s+ONLY\s+\$(\w+)\s+REPLACE\s+\$(\w+)$/i.exec(s);
+  if (m) {
+    return { kind: 'upsert', id: rid(vars[m[1]]), data: asRow(vars[m[2]]), mode: 'replace' };
+  }
+
+  m =
+    /^UPSERT\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s) ||
+    /^UPDATE\s+ONLY\s+\$(\w+)\s+MERGE\s+\$(\w+)$/i.exec(s);
+  if (m) {
+    return { kind: 'upsert', id: rid(vars[m[1]]), data: asRow(vars[m[2]]), mode: 'merge' };
+  }
+
+  // CREATE ONLY $id SET a = ..., b = ...  (createSet / createMutation)
+  m = /^CREATE\s+ONLY\s+\$(\w+)\s+SET\s+(.+)$/i.exec(s);
+  if (m) {
+    const data: Row = {};
+    for (const { path, value } of parseSetClauses(m[2], vars)) setPath(data, path, value);
+    return { kind: 'upsert', id: rid(vars[m[1]]), data, mode: 'replace' };
+  }
+
+  // UPDATE $id SET a.b = $x, c = $y [RETURN NONE]
+  m = /^UPDATE\s+\$(\w+)\s+SET\s+(.+?)(\s+RETURN\s+NONE)?$/i.exec(s);
+  if (m) {
+    return {
+      kind: 'updateSet',
+      id: rid(vars[m[1]]),
+      sets: parseSetClauses(m[2], vars),
+      returnNone: !!m[3],
+    };
+  }
+
+  m = /^DELETE\s+\$(\w+)$/i.exec(s);
+  if (m) return { kind: 'delete', id: rid(vars[m[1]]) };
+
+  m = /^DELETE\s+([A-Za-z_]\w*)$/i.exec(s); // DELETE <table>
+  if (m) return { kind: 'deleteAll', table: m[1] };
+
+  // ---- reads ------------------------------------------------------------
+  // SELECT [VALUE] <proj> FROM ONLY $id
+  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+ONLY\s+\$(\w+)$/i.exec(s);
+  if (m) {
+    const value = m[1] ? m[2].trim() : undefined;
+    return { kind: 'getById', id: rid(vars[m[3]]), select: projFields(m[2], !!m[1]), value };
+  }
+
+  // SELECT [VALUE] <proj> FROM $arrayParam
+  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+\$(\w+)$/i.exec(s);
+  if (m) {
+    const value = m[1] ? m[2].trim() : undefined;
+    return {
+      kind: 'selectByIds',
+      ids: (vars[m[3]] as unknown[]) ?? [],
+      select: projFields(m[2], !!m[1]),
+      value,
+    };
+  }
+
+  // SELECT <proj> FROM <table> [WHERE ...] [ORDER BY ...]
+  m = /^SELECT\s+(VALUE\s+)?(.+?)\s+FROM\s+([A-Za-z_]\w*)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?$/i.exec(
+    s
+  );
+  if (m) {
+    return {
+      kind: 'selectTable',
+      table: m[3],
+      where: m[4] ? parseWhere(m[4], vars) : undefined,
+      orderBy: m[5] ? parseOrderBy(m[5]) : undefined,
+      select: projFields(m[2], !!m[1]),
+      value: m[1] ? m[2].trim() : undefined,
+    };
+  }
+
+  throw new Error(`SqliteCacheEngine: unsupported SurrealQL for translation: ${stmt}`);
+}
+
+// ==================== clause parsers ====================
+
+function projFields(proj: string, isValue: boolean): string[] | undefined {
+  const p = proj.trim();
+  if (isValue) return undefined; // VALUE returns a scalar, no projection object
+  if (p === '*') return undefined;
+  return p.split(',').map((f) => f.trim());
+}
+
+function asRow(v: unknown): Row {
+  return (v && typeof v === 'object' ? v : {}) as Row;
+}
+
+/** Parse `a = $x, b.c = 'lit', _00_rv += 1` into path/op/value triples. */
+function parseSetClauses(clause: string, vars: Record<string, unknown>): SetClause[] {
+  return splitTopLevel(clause, ',').map((part) => {
+    const m = /^(.+?)\s*(\+=|-=|=)\s*([\s\S]+)$/.exec(part.trim());
+    if (!m) throw new Error(`SqliteCacheEngine: cannot parse SET clause: ${part}`);
+    return { path: m[1].trim(), op: m[2] as SetClause['op'], value: literalOrVar(m[3], vars) };
+  });
+}
+
+function literalOrVar(token: string, vars: Record<string, unknown>): unknown {
+  const t = token.trim();
+  if (t.startsWith('$')) return vars[t.slice(1)];
+  if (/^'.*'$/.test(t) || /^".*"$/.test(t)) return t.slice(1, -1);
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (t === 'NONE' || t === 'NULL' || t === 'null') return null;
+  return t;
+}
+
+function parseWhere(clause: string, vars: Record<string, unknown>): WhereNode[] {
+  // Only simple AND-of-equality/comparison is emitted by the client's raw
+  // queries; OR/nested go through plan-based select().
+  return splitTopLevel(clause, 'AND').map((cond) => {
+    const m = /^(\S+)\s*(=|!=|>=|<=|>|<)\s*(.+)$/.exec(cond.trim());
+    if (!m) throw new Error(`SqliteCacheEngine: cannot parse WHERE condition: ${cond}`);
+    return { field: m[1], op: m[2] as WhereComparisonOp, value: literalOrVar(m[3], vars) };
+  });
+}
+
+type WhereComparisonOp = '=' | '!=' | '>=' | '<=' | '>' | '<';
+
+function parseOrderBy(clause: string): OrderBy {
+  return clause.split(',').map((c) => {
+    const [f, dir] = c.trim().split(/\s+/);
+    return [f, (dir ?? 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'];
+  });
+}
+
+/** Split on a top-level separator, ignoring parens/quotes (bounded inputs). */
+function splitTopLevel(input: string, sep: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let inStr: string | null = null;
+  let cur = '';
+  const isWord = /[A-Za-z]/.test(sep);
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (inStr) {
+      cur += ch;
+      if (ch === inStr) inStr = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      inStr = ch;
+      cur += ch;
+      continue;
+    }
+    if (ch === '(') depth++;
+    if (ch === ')') depth--;
+    const matches = isWord
+      ? depth === 0 && input.slice(i, i + sep.length).toUpperCase() === sep && /\s/.test(input[i - 1] ?? ' ')
+      : depth === 0 && ch === sep;
+    if (matches) {
+      out.push(cur.trim());
+      cur = '';
+      i += sep.length - 1;
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}
+
+/** Read a possibly-dotted path (`a.b.c`) from an object. */
+export function getPath(obj: Row, path: string): unknown {
+  let cur: unknown = obj;
+  for (const k of path.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Row)[k];
+  }
+  return cur;
+}
+
+/** Set a possibly-dotted path (`a.b.c`) on an object. */
+export function setPath(obj: Row, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let cur: Row = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (typeof cur[k] !== 'object' || cur[k] === null) cur[k] = {};
+    cur = cur[k] as Row;
+  }
+  cur[parts[parts.length - 1]] = value;
+}