@omgbase/oqx 0.1.0

package/README.md

@@ -0,0 +1,424 @@
+# oqx
+
+**Generic Object Query eXpression engine for JavaScript.**
+
+OQX is a small query language for querying ordinary in-memory JavaScript objects
+and collections — arrays of records, nested relations, recursive trees — with a
+readable, declarative syntax. This package is the **generic collection kernel**:
+the OQX language semantics separated from any particular data model, exposed as a
+JavaScript tagged template.
+
+```js
+import { oqx } from "oqx";
+
+const people = [
+  { name: "Bob", id: 124, title: "Engineer",
+    jobs: [{ employer: "Globocorp", start_date: "1984/05/01", end_date: "1990/01/01" },
+           { employer: "Globocorp", start_date: "2001/03/01" }] },
+  // …
+];
+const company = "Globocorp";
+
+const employees = oqx`
+  name, id, title
+  from ${people}
+  where jobs exists { employer == ${company} && !end_date }
+`;
+// → [{ name: "Bob", id: 124, title: "Engineer" }, …]  (current Globocorp employees)
+```
+
+## Why a tagged template
+
+Interpolations cross the host/OQX boundary as **typed value bindings, never as
+source text** — prepared-statement semantics. A `${…}` in `from` position is the
+collection being queried; a `${…}` in a predicate is an ordinary host value.
+Because values are never spliced into the query text, they cannot alter the
+grammar and there is no injection surface. The compiled query is cached by the
+template's identity and re-runs with fresh bindings each call.
+
+## Language tutorial
+
+A query has, in spirit, the shape below — but at the top level the clauses are
+**order-flexible**, so you can lead with the projection (SQL-style) or with
+`from`, whichever reads better:
+
+```
+[ [select] projection ]    name, id, title: label
+from <collection>          from ${people}
+[ where <predicate> ]      where age >= 18 && jobs exists { !end }
+[ order by <expr> … ]      order by age desc, name
+[ follow <relation> … ]    follow children { depth 4 }
+```
+
+The examples below all use this dataset:
+
+```js
+const people = [
+  { name: "Bob",   id: 124, title: "Engineer", active: true,  age: 41, city: "NYC",
+    jobs: [{ employer: "Globocorp", start: "1984", end: "1990" },
+           { employer: "Globocorp", start: "2001" }] },
+  { name: "Alice", id: 7,   title: "Director", active: true,  age: 52, city: "SF",
+    jobs: [{ employer: "Initech",   start: "1999", end: "2005" },
+           { employer: "Globocorp", start: "2010", end: "2015" }] },
+  { name: "Carol", id: 55,  title: "Analyst",  active: false, age: 29, city: "NYC",
+    jobs: [{ employer: "Globocorp", start: "2020" }] },
+];
+```
+
+### 1. Source: `from`
+
+Every query reads from a source collection. In the tagged template the source is
+normally an interpolated value; it may also be a named root or a navigation (see
+[data context](#data-context-string-queries-and-named-roots)).
+
+```js
+oqx`name from ${people}`;
+// [{ name: "Bob" }, { name: "Alice" }, { name: "Carol" }]
+```
+
+### 2. Projection (select)
+
+List the fields to keep. With **no** projection you get the raw rows unchanged.
+
+```js
+oqx`name, id from ${people}`;
+// [{ name: "Bob", id: 124 }, { name: "Alice", id: 7 }, { name: "Carol", id: 55 }]
+
+oqx`from ${people} where active`;                 // no projection → whole objects
+// [ <Bob>, <Alice> ]
+```
+
+A projection item can be:
+
+- a **bare field** — `name`;
+- a **dotted navigation**, keyed by its last segment — `meta.slug` produces
+  `{ slug: … }`;
+- an **alias / value expression** — `label: name`, `decade: age / 10`;
+- a **nested collection** — `current: jobs collect { … }` (see §6).
+
+```js
+oqx`label: name, decade: age / 10 from ${people} where name == "Bob"`;
+// [{ label: "Bob", decade: 4.1 }]
+```
+
+The `select` keyword is optional and works in any position — `select name from …`
+is identical to `name from …`. (It's the hook for a future `select distinct`.)
+
+### 3. Predicates (where)
+
+`where` filters rows. The predicate language has comparisons (`== != < <= > >=`),
+boolean operators (`&& || !`) with grouping `( )`, membership (`in`), arithmetic
+(`+ - * / %`), and bare truthiness. The `where` keyword is optional when the
+leading expression is clearly a predicate.
+
+```js
+const min = 40;
+oqx`name from ${people} where age >= ${min}`;      // → Bob, Alice
+oqx`name from ${people} where city in ${["SF", "LA"]}`;   // → Alice
+oqx`name from ${people} where !active`;            // → Carol
+```
+
+Equality is **typed and strict** (`5 == "5"` is false); a comparison against an
+absent (`null`/`undefined`) field is simply false rather than an error.
+
+**Interpolations are always values, never syntax.** `where name == ${x}` compares
+against the value of `x`; a string in `x` can't inject operators or identifiers.
+
+**Bindings & scoping.** A bare identifier resolves against the current row, and if
+absent it **climbs to enclosing rows** — lexical outer references, for free:
+
+```js
+const accounts = [
+  { owner: "x", budget: 100, orders: [{ amount: 50 }, { amount: 150 }] },
+  { owner: "y", budget: 200, orders: [{ amount: 250 }] },
+];
+oqx`owner from ${accounts} where orders exists { amount > budget }`;
+// [{ owner: "x" }, { owner: "y" }]   — `budget` climbs from the order to the account
+```
+
+A `.member` access does **not** climb — it always navigates the value on its left.
+
+**Explicit outer references (`^`).** Implicit climbing only reaches an outer field
+when the inner row *doesn't* have that name. When both scopes share a name, the
+inner one shadows the outer, and you reach past it with `^name` ("one scope out",
+`^^name` for two). This is what makes correlated subqueries work — e.g. each
+person's siblings, where both the person and the candidates have a `parent`:
+
+```js
+const family = [
+  { name: "Ada", parent: "Pat" },
+  { name: "Ben", parent: "Pat" },
+  { name: "Cy",  parent: "Sam" },
+];
+oqx`
+  name,
+  siblings: ${family} collect { name where parent == ^parent && name != ^name }
+  from ${family}
+`;
+// [{ name: "Ada", siblings: [{ name: "Ben" }] },
+//  { name: "Ben", siblings: [{ name: "Ada" }] },
+//  { name: "Cy",  siblings: [] }]
+```
+
+Here `parent` is the inner candidate's parent while `^parent` is the outer
+person's. (`^` in an expression *reads* one scope out; the same `^` as a
+select-item prefix — `^name: …` in §7 — *binds* one scope out. Both mean "one
+scope out.")
+
+### 4. Built-in functions
+
+Methods on a value: `contains`, `startsWith`, `endsWith`, `matches` (regex),
+`size`, `lower`, `upper`. Free functions: `list(x)` (coerce to an array), `size(x)`,
+`has(x)`.
+
+```js
+oqx`name from ${people} where title.startsWith("Eng")`;      // → Bob
+oqx`name from ${people} where title.lower() == "director"`;  // → Alice
+```
+
+### 5. Consumers
+
+A consumer shapes a result set. There are five:
+
+| Consumer  | Returns                        |
+| --------- | ------------------------------ |
+| `collect` | an array (the default)         |
+| `exists`  | a boolean                      |
+| `count`   | a number                       |
+| `first`   | one record, or `null`          |
+| `single`  | one record, or `null`; throws if more than one matches |
+
+The bare `from … ` form is always `collect`. To reduce the **whole** query with a
+different consumer, use the directive form `<source> <consumer> { <body> }` — note
+this is *not* SQL: `count from people` would project a field called `count`, whereas
+a real reduction is a directive:
+
+```js
+oqx`${people} exists { where active }`;            // true
+oqx`${people} count { where active }`;             // 2
+oqx`${people} first { name where age > 50 }`;      // { name: "Alice" }
+```
+
+(Inside a consumer block a bare identifier **projects** — `count { active }` selects
+a field named `active`; write `count { where active }` to filter.)
+
+### 6. Nested collections and relations
+
+The same consumers work as **postfix directives** over a relation of the current
+row — `<relation> <consumer> { <body> }` — both in `where` and in a projection.
+
+In `where`, an `exists { … }` tests non-emptiness and `count { … } <op> N` compares
+cardinality:
+
+```js
+oqx`name from ${people} where jobs exists { !end }`;   // has a current job → Bob, Carol
+oqx`name from ${people} where jobs count {} >= 2`;     // ≥2 jobs → Bob, Alice
+```
+
+In a projection, `collect` yields a nested array; `first` / `single` yield one
+nested record:
+
+```js
+oqx`name, current: jobs collect { employer where !end } from ${people} where name == "Bob"`;
+// [{ name: "Bob", current: [{ employer: "Globocorp" }] }]
+
+oqx`name, firstJob: jobs first { employer } from ${people} where name == "Alice"`;
+// [{ name: "Alice", firstJob: { employer: "Initech" } }]
+```
+
+A relation is just an expression evaluated on the row and coerced to a collection,
+so nested blocks compose to any depth and can navigate dotted paths
+(`author.books collect { … }`).
+
+### 7. Lifts (`^`)
+
+Sometimes you want to filter by a nested collection *and* keep a value from it.
+A `^name:` item inside a `collect { … }` that sits directly in the top-level
+`where` does both: it filters (non-empty) and binds `name` into the outer
+projection as a per-row array.
+
+```js
+oqx`
+  name, currentEmployers
+  from ${people}
+  where jobs collect { ^currentEmployers: employer where !end }
+`;
+// [{ name: "Bob", currentEmployers: ["Globocorp"] },
+//  { name: "Carol", currentEmployers: ["Globocorp"] }]
+```
+
+**Multi-level lifts (`^^`, `^^^`).** The caret count is how many scopes the value
+binds *out* — `^` to the immediate enclosing projection, `^^` two out, and so on
+(the mirror image of the `^`-read in §3). When a deeper lift fires repeatedly as
+an intermediate collection fans out, its values **flatten-append** into one flat
+list at the target scope — "every matching value from the subtree, N scopes out":
+
+```js
+const departments = [
+  { name: "Eng",   teams: [{ id: "t1", members: [{ name: "Ada" }, { name: "Ben" }] },
+                           { id: "t2", members: [{ name: "Cy" }] }] },
+  { name: "Sales", teams: [{ id: "t3", members: [{ name: "Dee" }] }] },
+];
+oqx`
+  name, teamIds, allMembers
+  from ${departments}
+  where teams collect { ^teamIds: id where members collect { ^^allMembers: name } }
+`;
+// [{ name: "Eng",   teamIds: ["t1", "t2"], allMembers: ["Ada", "Ben", "Cy"] },
+//  { name: "Sales", teamIds: ["t3"],       allMembers: ["Dee"] }]
+```
+
+`^teamIds` (one out) and `^^allMembers` (two out) bind to the same department row
+at once. Because accumulation happens as each intermediate collection is
+iterated, the intermediate scopes must be `collect`/`count` bodies (which iterate
+fully), not a short-circuiting `exists`.
+
+### 8. Ordering
+
+`order by <expr> [asc|desc]`, comma-separated for tie-breaks. Absent values sort
+last.
+
+```js
+oqx`name from ${people} where city == "NYC" order by age desc`;
+// [{ name: "Bob" }, { name: "Carol" }]
+```
+
+### 9. Recursion: `follow`
+
+`follow <relation>` turns a query into a bounded recursive traversal: the `where`
+selects the seed rows, and `follow` walks a relation from each reached row. It's
+fully duck-typed — the relation is any expression yielding successors; a row that
+lacks it is simply a leaf.
+
+```js
+const tree = [{ id: "root", children: [
+  { id: "a", children: [{ id: "a1", children: [] }] },
+  { id: "b", children: [] },
+]}];
+
+oqx`id, depth: $depth from ${tree} follow children order by $depth, id`;
+// [{ id: "root", depth: 1 }, { id: "a", depth: 2 }, { id: "b", depth: 2 }, { id: "a1", depth: 3 }]
+```
+
+Reached rows expose recursion **intrinsics** in `select` / `order by`:
+`$depth` (1-based), `$leaf` (no successors), `$frontier` (hit a boundary), and
+`$stop` (`"continue"` / `"leaf"` / `"depth"` / `"frontier"`). Options go in a
+trailing block:
+
+```js
+oqx`id, stop: $stop from ${tree} follow children { depth 2 } order by id`;
+// a1 is never reached; a and b report stop:"depth"
+```
+
+The block accepts: `where <succ>` (which successors keep participating),
+`frontier <pred>` (cut a relation that could continue), `depth <n>` (1–8), and
+`by <expr>` (the identity used for cycle/duplicate detection — default `.id` or the
+object reference). Reached rows are de-duplicated by that identity, so cycles
+terminate. Give `follow` a stable identity (`.id` or `by`) when your relation
+returns fresh objects rather than shared references.
+
+### Cheat-sheet
+
+```
+name, alias: expr, nested: rel collect { … }   projection (select optional)
+from ${source}                                  source collection
+where a == b && rel exists { … } || !c          predicate tree + nested ops
+^name / ^^name                                   read an outer row's field (N scopes out)
+^name: expr  /  ^^name: expr                     lift/export a value N scopes out (flatten-append)
+order by expr desc, expr2                        ordering
+follow rel { where … frontier … depth n by … }  recursion ($depth/$stop/$leaf/$frontier)
+${source} <collect|exists|count|first|single> { … }   whole-query consumer
+```
+
+## Data context: string queries and named roots
+
+When you don't need interpolation, `execute` runs a plain string query against a
+**data context** of named roots:
+
+```js
+import { execute } from "oqx";
+
+execute("name from people where age >= 18", { people });
+// `from people` resolves the `people` root
+```
+
+`parse(source)` returns a reusable AST and `run(query, { values, roots })` returns
+the full discriminated result (`{ consumer, … }`).
+
+## Architecture: adapting to other storage & query systems
+
+OQX is layered so it can be the front-end for query systems far beyond in-memory
+objects. The parsed `Query` AST is the host-agnostic IR; execution is pluggable.
+
+```
+Query AST  ─┬─ InMemoryEngine(DataContext)     tier 1/2 — drive any data model
+            └─ PlannedEngine(QueryPlanner)      tier 3   — push work into a store
+                   └─ finishes the residual on the in-memory engine
+```
+
+**Everything obeys one scalar-semantics contract** (`oqx.semantics`): typed/strict
+equality (`5 == "5"` is false), absent operands make ordering comparisons false,
+CEL-style `in`, absent-last sort order. Any backend that can't reproduce a rule
+in its native language must leave that fragment as an in-memory *residual* rather
+than approximate it. The conformance suite verifies this.
+
+### Tier 2 — a custom `DataContext` (bind any data model)
+
+The engine never touches host objects directly; it asks a `DataContext` to
+resolve named roots, read properties/relations, coerce results to rows, and
+compute identity. Implement it to query an ORM graph, a remote API, or lazily
+loaded relations — the query *semantics* stay in OQX:
+
+```js
+import { parse, run } from "oqx";
+
+const graph = {
+  root: (name) => name === "tree" ? [nodes.get(1)] : undefined,
+  get:  (row, key) => key === "children" ? row.childIds.map(id => nodes.get(id)) : row[key],
+  has:  (row, key) => key === "children" || key in row,   // declare computed relations
+  toRows: (v) => v == null ? [] : Array.isArray(v) ? v : [v],
+  identity: (row) => row.id,                                // for follow dedup
+};
+run(parse("id, depth: $depth from tree follow children"), { context: graph });
+```
+
+### Tier 3 — a `QueryPlanner` (pushdown + planning)
+
+A planner translates as much of a query as it can into its store's native query
+and returns the produced rows plus a **residual** `Query` for the rest. The
+in-memory engine finishes the residual, so a planner can be as partial as it
+likes and stay correct. Two adapters ship:
+
+- `IndexedCollection` — hash-indexes a collection and answers equality predicates
+  from the index instead of scanning, leaving other predicates as residual.
+- `oqx/sqlite` — real pushdown to a `node:sqlite` database: the flat query core
+  (scan + translatable conjunctive predicates, `LIMIT` for unordered
+  `first`/`single`) becomes SQL; `matches()`, nested consumer ops, `follow`, etc.
+  fall back to the in-memory residual.
+
+```js
+import { parse, PlannedEngine } from "oqx";
+import { SqliteTable } from "oqx/sqlite";
+
+const planner = new SqliteTable(db, "emp", { columns: ["id", "name", "dept", "level"] });
+new PlannedEngine(planner).run(parse('name from emp where dept == "eng" && level >= 5'), []);
+// → `dept`/`level` pushed to SQL; anything untranslatable finishes in-memory
+```
+
+This is the seam an omgbase adapter uses: its existing OQX→SQL compiler (docs/
+blocks/nodes, the relations table, `$` intrinsics, `WITH RECURSIVE` for `follow`)
+becomes a `QueryPlanner`, while oqx-js contributes the parser, IR, semantics
+contract, and residual executor.
+
+## Requirements
+
+Node 22.6+ (the sources are TypeScript, run natively via type-stripping — the
+package has **no runtime dependencies**). `npm test` runs the suite; `npm run
+typecheck` typechecks.
+
+## Relationship to omgbase
+
+This is tier 1 (the in-memory object/collection interpreter) of the OQX
+implementation tiers. The language kernel here is host-agnostic; richer hosts
+(e.g. omgbase's docs/blocks/nodes with index pushdown) layer data-model
+vocabulary and execution capabilities on top of the same surface syntax.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@omgbase/oqx",
+  "version": "0.1.0",
+  "description": "Generic Object Query eXpression engine for JavaScript",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./sqlite": "./src/adapters/sqlite.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "typescript": "^5.7.0"
+  }
+}

package/src/adapters/indexed.ts

@@ -0,0 +1,61 @@
+// An in-memory optimizing planner: it hash-indexes a named root collection on
+// chosen fields and, for a query whose where-clause contains equality predicates
+// on those fields, answers from the index (candidate intersection) instead of a
+// full scan. Everything it can't turn into an index probe is left as a residual
+// query the in-memory engine finishes over the candidate rows.
+//
+// This is the smallest honest demonstration of plan optimization: same answers
+// as a naive scan, far fewer rows examined, and partial-pushdown correctness via
+// the residual.
+
+import type { Query } from "../ast.ts";
+import type { Plan, QueryPlanner } from "../planner.ts";
+import { partitionPushable, residualQuery, asEquality, constValue } from "../plan.ts";
+
+export class IndexedCollection implements QueryPlanner {
+  private name: string;
+  private rows: readonly unknown[];
+  private indexes = new Map<string, Map<unknown, unknown[]>>();
+
+  /** Index `rows` (exposed as root `name`) on each field in `indexFields`. */
+  constructor(name: string, rows: readonly unknown[], indexFields: readonly string[]) {
+    this.name = name;
+    this.rows = rows;
+    for (const field of indexFields) {
+      const idx = new Map<unknown, unknown[]>();
+      for (const row of rows) {
+        const key = (row as Record<string, unknown>)?.[field];
+        let bucket = idx.get(key);
+        if (!bucket) idx.set(key, (bucket = []));
+        bucket.push(row);
+      }
+      this.indexes.set(field, idx);
+    }
+  }
+
+  plan(query: Query, params: readonly unknown[]): Plan | null {
+    if (query.source.kind !== "ident" || query.source.name !== this.name) return null;
+    if (query.from.length > 0 || query.follow) return null;
+
+    const { pushed, residual } = partitionPushable(query.where, (e) => {
+      const eq = asEquality(e);
+      return eq != null && this.indexes.has(eq.field);
+    });
+    if (pushed.length === 0) return null; // no index probe available — let the scan handle it
+
+    // Intersect the candidate sets from each indexed equality (smallest first).
+    let candidate: unknown[] | null = null;
+    for (const e of pushed) {
+      const eq = asEquality(e)!;
+      const bucket = this.indexes.get(eq.field)!.get(constValue(eq.value, params)) ?? [];
+      candidate = candidate === null ? bucket.slice() : intersect(candidate, bucket);
+    }
+    const rows = candidate ?? [];
+    return { rows: () => rows, residual: residualQuery(query, residual) };
+  }
+}
+
+function intersect(a: unknown[], b: unknown[]): unknown[] {
+  const set = new Set(b);
+  return a.filter((x) => set.has(x));
+}

package/src/adapters/sqlite.ts

@@ -0,0 +1,120 @@
+// A real storage adapter: pushes the flat core of an OQX query (source scan +
+// translatable conjunctive predicates, and a LIMIT for unordered first/single)
+// into SQL over Node's built-in `node:sqlite`, and leaves everything it can't
+// translate — nested consumer ops, `follow`, negation/disjunction, method calls
+// like matches(), custom functions — as a residual the in-memory engine finishes
+// over the rows SQL returned.
+//
+// This is imported on its own subpath (`oqx/sqlite`) so that plain consumers of
+// `oqx` never pull in the experimental `node:sqlite` module.
+//
+// Semantics note: OQX equality is typed and strict (see semantics.ts). SQL `=`
+// uses column affinity, so this adapter assumes a well-typed schema for the
+// columns it pushes; anything it cannot translate faithfully stays residual.
+
+import { DatabaseSync } from "node:sqlite";
+import type { Query, Expr } from "../ast.ts";
+import type { Plan, QueryPlanner } from "../planner.ts";
+import { partitionPushable, residualQuery } from "../plan.ts";
+
+export interface SqliteTableOptions {
+  /** Columns that map to bare OQX fields (only these are pushable). */
+  columns: readonly string[];
+  /** Columns whose stored text should be JSON.parse'd back into row values. */
+  jsonColumns?: readonly string[];
+  /** Custom mapper from a raw SQL row to a query row (overrides jsonColumns). */
+  map?: (raw: Record<string, unknown>) => unknown;
+}
+
+const RELOP_SQL: Record<string, string> = {
+  "==": "=", "!=": "<>", "<": "<", "<=": "<=", ">": ">", ">=": ">=",
+};
+const ARITH_SQL = new Set(["+", "-", "*", "/", "%"]);
+
+export class SqliteTable implements QueryPlanner {
+  private db: DatabaseSync;
+  private table: string;
+  private columns: Set<string>;
+  private opts: SqliteTableOptions;
+
+  constructor(db: DatabaseSync, table: string, opts: SqliteTableOptions) {
+    this.db = db;
+    this.table = table;
+    this.columns = new Set(opts.columns);
+    this.opts = opts;
+  }
+
+  plan(query: Query, params: readonly unknown[]): Plan | null {
+    if (query.source.kind !== "ident" || query.source.name !== this.table) return null;
+    if (query.from.length > 0 || query.follow) return null;
+
+    const { pushed, residual } = partitionPushable(query.where, (e) => this.translatable(e));
+    const sqlParams: unknown[] = [];
+    const whereSql = pushed.map((e) => this.translate(e, params, sqlParams)).join(" AND ");
+
+    // A LIMIT is only safe when nothing is left to filter in-memory and the
+    // result is unordered (first/single are "some row" without an order by).
+    let tail = "";
+    if (!residual && !query.orderBy) {
+      if (query.consumer === "first") tail = " LIMIT 1";
+      else if (query.consumer === "single") tail = " LIMIT 2";
+    }
+
+    const sql = `SELECT * FROM "${this.table}"${whereSql ? ` WHERE ${whereSql}` : ""}${tail}`;
+    const raw = this.db.prepare(sql).all(...sqlParams.map(toSqlParam)) as Record<string, unknown>[];
+    const rows = raw.map((r) => this.mapRow(r));
+    return { rows: () => rows, residual: residualQuery(query, residual) };
+  }
+
+  private translatable(e: Expr): boolean {
+    switch (e.kind) {
+      case "lit": case "binding": return true;
+      case "ident": return this.columns.has(e.name);
+      case "unary": return (e.op === "!" || e.op === "-") && this.translatable(e.expr);
+      case "logical": return this.translatable(e.left) && this.translatable(e.right);
+      case "binary":
+        return (e.op in RELOP_SQL || ARITH_SQL.has(e.op)) && this.translatable(e.left) && this.translatable(e.right);
+      default: return false; // member/index/call/in → residual
+    }
+  }
+
+  private translate(e: Expr, params: readonly unknown[], out: unknown[]): string {
+    switch (e.kind) {
+      case "lit": out.push(e.value); return "?";
+      case "binding": out.push(params[e.index]); return "?";
+      case "ident": return `"${e.name}"`;
+      case "unary": return e.op === "!" ? `(NOT ${this.translate(e.expr, params, out)})` : `(-${this.translate(e.expr, params, out)})`;
+      case "logical": {
+        const op = e.op === "&&" ? "AND" : "OR";
+        return `(${this.translate(e.left, params, out)} ${op} ${this.translate(e.right, params, out)})`;
+      }
+      case "binary": {
+        const op = e.op in RELOP_SQL ? RELOP_SQL[e.op]! : e.op;
+        return `(${this.translate(e.left, params, out)} ${op} ${this.translate(e.right, params, out)})`;
+      }
+      default: throw new Error(`sqlite: not translatable: ${e.kind}`);
+    }
+  }
+
+  private mapRow(raw: Record<string, unknown>): unknown {
+    if (this.opts.map) return this.opts.map(raw);
+    if (this.opts.jsonColumns) {
+      const out: Record<string, unknown> = { ...raw };
+      for (const c of this.opts.jsonColumns) {
+        if (typeof out[c] === "string") out[c] = JSON.parse(out[c] as string);
+      }
+      return out;
+    }
+    return raw;
+  }
+}
+
+// node:sqlite accepts null | number | bigint | string | Uint8Array. Map the
+// common host values that appear as bound params.
+function toSqlParam(v: unknown): null | number | bigint | string | Uint8Array {
+  if (v === undefined || v === null) return null;
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "number" || typeof v === "bigint" || typeof v === "string") return v;
+  if (v instanceof Uint8Array) return v;
+  return String(v);
+}