API index and search · Build metadata

Source snapshot

packages/query-compiler/src/index.ts

1// @rindle/query-compiler — compile a Rindle query `Ast` into one SQL `SELECT` whose single2// column `"rindle_result"` is the entire nested result tree as JSON, run on a live SQL3// backend inside the caller's open transaction (POSTGRES-READ-COMPILER-DESIGN.md §4).4//5// Dialect-parametric, with BOTH dialects product targets:6// - `postgres` — the BYO-Postgres server mutator read, with the §6.2 `::text::<type>` cast7//   discipline (PG is a second type system whose driver parsing must be pinned + reconciled).8// - `sqlite` — the daemon-backend mutator read, ridden through an interactive mutation9//   session (DAEMON-INTERACTIVE-TXN-DESIGN.md §5.4). NO casts, by design: SQLite IS the10//   canonical store and results return as raw storage classes over Rindle's own value11//   encoding, so there is no second representation to reconcile — every value binds as a12//   native parameter (`rindle-d2s`, the Rust twin, states the same principle: "Values13//   (minimal — no casting)"). It doubles as the offline differential oracle (§9, §11),14//   which is what proves the shared walker end-to-end against `node:sqlite`.1516export type {17  Aggregate,18  Ast,19  Bound,20  Condition,21  CorrelatedSubquery,22  Correlation,23  Dir,24  ExistsOp,25  LitValue,26  OrderPart,27  SimpleOp,28  ValuePosition,29} from "./ast.ts";30export type { Cardinality, Catalog, ColumnType, TableSchema } from "./catalog.ts";31export type { Dialect } from "./dialect.ts";32export { sqliteDialect } from "./dialect.ts";33export { postgresDialect } from "./postgres.ts";3435import type { Ast } from "./ast.ts";36import type { Catalog } from "./catalog.ts";37import { sqliteDialect } from "./dialect.ts";38import { postgresDialect } from "./postgres.ts";39import { compileWith } from "./walker.ts";4041/** Which SQL dialect to emit. Both are product targets: `postgres` for the BYO-PG backend,42 *  `sqlite` for the daemon backend's session reads (and the offline oracle, §9). */43export type DialectName = "postgres" | "sqlite";4445export interface CompileOptions {46  dialect: DialectName;47}4849/**50 * A compiled query: one SQL `SELECT` plus its positional bound parameters. `sql` returns a51 * single row with a single column `"rindle_result"` — the whole nested result as JSON52 * (`jsonb` on Postgres, `json` text on SQLite). No runtime value is ever interpolated into53 * `sql`; every filter/paging value is a bound parameter (Invariant 4).54 */55export interface CompiledQuery {56  sql: string;57  /** In order: `$1..$n` for Postgres, `?` for SQLite. */58  params: unknown[];59}6061/**62 * Compile `ast` against `catalog` into `{ sql, params }` (§4). A pure function of its63 * inputs — no database access (Invariant 2). The root is **singular** when `ast.one` is set64 * (a single JSON object or `null`), else **plural** (a JSON array).65 */66export function compile(ast: Ast, catalog: Catalog, opts: CompileOptions): CompiledQuery {67  const singular = ast.one === true;68  switch (opts.dialect) {69    case "sqlite":70      return compileWith(ast, catalog, sqliteDialect, singular);71    case "postgres":72      return compileWith(ast, catalog, postgresDialect, singular);73  }74}75