@rindle/query-compiler 0.4.3

package/src/errors.ts

@@ -0,0 +1,30 @@
+// Why a query could not be compiled. Mirrors `rindle-d2s`'s `CompileError` (lib.rs:133) so
+// the two compilers reject the same shapes with the same reasons.
+
+export class CompileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CompileError";
+  }
+}
+
+/** A referenced table is not in the catalog. */
+export function unknownTable(table: string): CompileError {
+  return new CompileError(`unknown table \`${table}\``);
+}
+
+/** A `related`/EXISTS relationship's cardinality is not declared in the catalog. */
+export function unknownRelationship(table: string, rel: string): CompileError {
+  return new CompileError(`unknown relationship \`${rel}\` on table \`${table}\``);
+}
+
+/** A `related` subquery is missing an alias (every child must be named). */
+export function missingAlias(table: string): CompileError {
+  return new CompileError(`related subquery on \`${table}\` has no alias`);
+}
+
+/** An AST feature the compiler does not lower in the position it appears — rejected loudly
+ *  rather than emitting silently-wrong SQL (e.g. a `start` paging bound inside EXISTS). */
+export function unsupported(what: string): CompileError {
+  return new CompileError(`unsupported AST feature: ${what}`);
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+// @rindle/query-compiler — compile a Rindle query `Ast` into one SQL `SELECT` whose single
+// column `"rindle_result"` is the entire nested result tree as JSON, run on a live SQL
+// backend inside the caller's open transaction (POSTGRES-READ-COMPILER-DESIGN.md §4).
+//
+// Dialect-parametric, with BOTH dialects product targets:
+// - `postgres` — the BYO-Postgres server mutator read, with the §6.2 `::text::<type>` cast
+//   discipline (PG is a second type system whose driver parsing must be pinned + reconciled).
+// - `sqlite` — the daemon-backend mutator read, ridden through an interactive mutation
+//   session (DAEMON-INTERACTIVE-TXN-DESIGN.md §5.4). NO casts, by design: SQLite IS the
+//   canonical store and results return as raw storage classes over Rindle's own value
+//   encoding, so there is no second representation to reconcile — every value binds as a
+//   native parameter (`rindle-d2s`, the Rust twin, states the same principle: "Values
+//   (minimal — no casting)"). It doubles as the offline differential oracle (§9, §11),
+//   which is what proves the shared walker end-to-end against `node:sqlite`.
+
+export type {
+  Aggregate,
+  Ast,
+  Bound,
+  Condition,
+  CorrelatedSubquery,
+  Correlation,
+  Dir,
+  ExistsOp,
+  LitValue,
+  OrderPart,
+  SimpleOp,
+  ValuePosition,
+} from "./ast.ts";
+export type { Cardinality, Catalog, ColumnType, TableSchema } from "./catalog.ts";
+export type { Dialect } from "./dialect.ts";
+export { sqliteDialect } from "./dialect.ts";
+export { postgresDialect } from "./postgres.ts";
+
+import type { Ast } from "./ast.ts";
+import type { Catalog } from "./catalog.ts";
+import { sqliteDialect } from "./dialect.ts";
+import { postgresDialect } from "./postgres.ts";
+import { compileWith } from "./walker.ts";
+
+/** Which SQL dialect to emit. Both are product targets: `postgres` for the BYO-PG backend,
+ *  `sqlite` for the daemon backend's session reads (and the offline oracle, §9). */
+export type DialectName = "postgres" | "sqlite";
+
+export interface CompileOptions {
+  dialect: DialectName;
+}
+
+/**
+ * A compiled query: one SQL `SELECT` plus its positional bound parameters. `sql` returns a
+ * single row with a single column `"rindle_result"` — the whole nested result as JSON
+ * (`jsonb` on Postgres, `json` text on SQLite). No runtime value is ever interpolated into
+ * `sql`; every filter/paging value is a bound parameter (Invariant 4).
+ */
+export interface CompiledQuery {
+  sql: string;
+  /** In order: `$1..$n` for Postgres, `?` for SQLite. */
+  params: unknown[];
+}
+
+/**
+ * Compile `ast` against `catalog` into `{ sql, params }` (§4). A pure function of its
+ * inputs — no database access (Invariant 2). The root is **singular** when `ast.one` is set
+ * (a single JSON object or `null`), else **plural** (a JSON array).
+ */
+export function compile(ast: Ast, catalog: Catalog, opts: CompileOptions): CompiledQuery {
+  const singular = ast.one === true;
+  switch (opts.dialect) {
+    case "sqlite":
+      return compileWith(ast, catalog, sqliteDialect, singular);
+    case "postgres":
+      return compileWith(ast, catalog, postgresDialect, singular);
+  }
+}

package/src/pg-types.ts

@@ -0,0 +1,119 @@
+// Postgres type classification — the predicates that decide which `::text::<type>` cast a
+// value gets (§6.2). Ported verbatim from mono's `zero-cache/src/types/pg-data-type.ts` (the
+// maps + `formatTypeForLookup`), plus the temporal helpers the projection reconciliation needs.
+// Keeping these faithful to z2s is what keeps the filter-side casts bug-for-bug aligned.
+
+// The map *values* are irrelevant to the predicates (they test key membership); kept as in
+// mono for fidelity and in case the value-type mapping is needed later.
+const pgToZqlNumericTypeMap: Record<string, string> = Object.freeze({
+  smallint: "number",
+  integer: "number",
+  int: "number",
+  int2: "number",
+  int4: "number",
+  int8: "number",
+  bigint: "number",
+  smallserial: "number",
+  serial: "number",
+  serial2: "number",
+  serial4: "number",
+  serial8: "number",
+  bigserial: "number",
+  decimal: "number",
+  numeric: "number",
+  real: "number",
+  "double precision": "number",
+  float: "number",
+  float4: "number",
+  float8: "number",
+});
+
+const pgToZqlNativeStringTypeMap: Record<string, string> = Object.freeze({
+  bpchar: "string",
+  character: "string",
+  "character varying": "string",
+  text: "string",
+  varchar: "string",
+});
+
+const pgToZqlTextRepresentedTypeMap: Record<string, string> = Object.freeze({
+  cidr: "string",
+  ean13: "string",
+  inet: "string",
+  isbn: "string",
+  isbn13: "string",
+  ismn: "string",
+  ismn13: "string",
+  issn: "string",
+  issn13: "string",
+  macaddr: "string",
+  macaddr8: "string",
+  pg_lsn: "string",
+  upc: "string",
+  uuid: "string",
+});
+
+const pgToZqlStringTypeMap: Record<string, string> = Object.freeze({
+  ...pgToZqlNativeStringTypeMap,
+  ...pgToZqlTextRepresentedTypeMap,
+});
+
+/** Strips args (the `(32)` in `char(32)`) and lowercases — mono's `formatTypeForLookup`.
+ *  Every predicate normalizes through this, so `VARCHAR(255)` / `UUID` classify correctly. */
+export function formatTypeForLookup(pgType: string): string {
+  const startOfArgs = pgType.indexOf("(");
+  if (startOfArgs === -1) return pgType.toLowerCase();
+  return pgType.toLowerCase().substring(0, startOfArgs);
+}
+
+export function isPgNumberType(pgType: string): boolean {
+  return Object.hasOwn(pgToZqlNumericTypeMap, formatTypeForLookup(pgType));
+}
+
+export function isPgNativeStringType(pgType: string): boolean {
+  return Object.hasOwn(pgToZqlNativeStringTypeMap, formatTypeForLookup(pgType));
+}
+
+export function isPgTextRepresentedType(pgType: string): boolean {
+  return Object.hasOwn(pgToZqlTextRepresentedTypeMap, formatTypeForLookup(pgType));
+}
+
+export function isPgStringType(pgType: string): boolean {
+  return Object.hasOwn(pgToZqlStringTypeMap, formatTypeForLookup(pgType));
+}
+
+// ── temporal helpers (projection reconciliation, §6.2) ──────────────────────────────────────
+
+const TEMPORAL_TYPES = new Set([
+  "date",
+  "time",
+  "time without time zone",
+  "time with time zone",
+  "timetz",
+  "timestamp",
+  "timestamp without time zone",
+  "timestamp with time zone",
+  "timestamptz",
+]);
+
+/** A temporal type projected as epoch-ms (outbound) and reconciled via `to_timestamp`/interval
+ *  (inbound). Everything else projects raw. */
+export function isTemporalType(pgType: string): boolean {
+  return TEMPORAL_TYPES.has(formatTypeForLookup(pgType));
+}
+
+// Offset-bearing time-of-day types: `EXTRACT(EPOCH FROM …)` can go negative (e.g. 01:00+02 =
+// 23:00 UTC prev day = -3600s), so the outbound projection normalizes into 0..86_400_000 ms.
+const TIME_OF_DAY_TZ_TYPES = new Set(["timetz", "time with time zone"]);
+
+/**
+ * Whether an outbound temporal projection needs the `mod 1 day` normalization. **Deliberately
+ * narrower than z2s's `selectIdent`**, which (via a switch fall-through) also normalizes
+ * `timestamptz` — that would collapse a full timestamp to time-of-day. The design (§6.2) is
+ * explicit that `timestamptz` projects as plain epoch-ms and only the offset-bearing
+ * *time-of-day* types are modular-normalized; the §9 parity harness against the engine's value
+ * model is the check that keeps this honest.
+ */
+export function needsTimeOfDayNormalization(pgType: string): boolean {
+  return TIME_OF_DAY_TZ_TYPES.has(formatTypeForLookup(pgType));
+}

package/src/postgres.ts

@@ -0,0 +1,152 @@
+// The Postgres dialect leaf (§6.1/§6.2) — the product target. The walker is shared with the
+// SQLite oracle; this file supplies only the Postgres-specific leaves:
+//
+//  - JSON assembly via `jsonb_build_object` / `jsonb_agg` / `'[]'::jsonb` (the design's §6.1
+//    choice — the direct analogue of `rindle-d2s`'s `json_object`, NOT z2s's `row_to_json`);
+//  - explicit `ASC NULLS FIRST` / `DESC NULLS LAST` (§8 — Postgres's default is the opposite
+//    of the engine's null-low order);
+//  - the outbound projection reconciliation (temporal → epoch-ms);
+//  - the inbound filter/paging cast strategy `$N::text::<type>`, ported verbatim from z2s's
+//    `sql.ts` — the `::text` intermediate pins the driver's parameter description to text, and
+//    the `::<type>` half is value-model↔native reconciliation (§6.2). Values are parameterized.
+//
+// NOTE: `$N` numbering is per-occurrence (no de-duplication of repeated values). z2s reuses a
+// placeholder for a repeated (value,type); that is a plan-cache optimization, not correctness —
+// deferred (203 §7 posture).
+
+import type { Dir } from "./ast.ts";
+import type { ColumnType } from "./catalog.ts";
+import type { Dialect, LitScalar } from "./dialect.ts";
+import {
+  formatTypeForLookup,
+  isPgNativeStringType,
+  isPgNumberType,
+  isPgStringType,
+  isPgTextRepresentedType,
+  isTemporalType,
+  needsTimeOfDayNormalization,
+} from "./pg-types.ts";
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** The Postgres cast for a literal whose type is inferred from its JS value (no column). */
+function pgTypeForLiteralType(litType: "boolean" | "number" | "string"): string {
+  // `double precision` is IEEE-754 like a JS number, so it round-trips any zql number exactly.
+  return litType === "boolean" ? "boolean" : litType === "number" ? "double precision" : "text";
+}
+
+/**
+ * The inbound value↔native cast for a filter/paging value against a known column type — the
+ * verbatim port of z2s's `formatCommonToSingularAndPlural` (`sql.ts:194`). `vp` is the value
+ * placeholder (`$N`, or `value` inside an array unnest). `isComparison` widens strings to bare
+ * `text` and numbers to `double precision` so neither is forced to the column's width/precision.
+ */
+function pgCast(vp: string, type: string, isEnum: boolean, isComparison: boolean): string {
+  const t = formatTypeForLookup(type);
+  // Temporal: epoch-ms ↔ native. The zone-naive spellings get `AT TIME ZONE 'UTC'`.
+  if (t === "timestamptz" || t === "timestamp with time zone") {
+    return `to_timestamp(${vp}::text::numeric / 1000.0)`;
+  }
+  if (t === "date" || t === "timestamp" || t === "timestamp without time zone") {
+    return `to_timestamp(${vp}::text::numeric / 1000.0) AT TIME ZONE 'UTC'`;
+  }
+  if (t === "timetz" || t === "time with time zone") {
+    return `(${vp}::text::int * interval'1ms')::time`;
+  }
+  if (t === "time" || t === "time without time zone") {
+    return `(${vp}::text::int * interval'1ms')::time AT TIME ZONE 'UTC'`;
+  }
+  if (t === "uuid") return `${vp}::text::uuid`;
+  if (isEnum) return `${vp}::text::"${type}"`;
+  if (isPgNativeStringType(type)) return isComparison ? `${vp}::text` : `${vp}::text::${type}`;
+  if (isPgTextRepresentedType(type)) return `${vp}::text::${type}`;
+  if (isPgNumberType(type)) {
+    return isComparison ? `${vp}::text::double precision` : `${vp}::text::${type}`;
+  }
+  return `${vp}::text::${type}`;
+}
+
+/** The text-pinned serialization of a bound value — z2s's `stringify` (`sql.ts:120`). Strings
+ *  and enum/string columns bind their raw text; everything else binds its JSON text form so the
+ *  `$N::text::…` cast re-parses it authoritatively. */
+function stringifyForColumn(value: LitScalar, col: ColumnType): string | null {
+  if (value === null) return null;
+  if (col.isArray) return JSON.stringify(value);
+  if (col.isEnum || isPgStringType(col.type)) return String(value);
+  return JSON.stringify(value);
+}
+
+function bindValue(
+  params: unknown[],
+  value: LitScalar,
+  col: ColumnType | null,
+  isComparison: boolean,
+): string {
+  const idx = params.length + 1;
+
+  // Free literal (no column context): infer the cast from the JS type.
+  if (col === null) {
+    if (value === null) {
+      params.push(null);
+      return `$${idx}`;
+    }
+    const litType = typeof value as "boolean" | "number" | "string";
+    params.push(litType === "string" ? value : JSON.stringify(value));
+    return `$${idx}::text::${pgTypeForLiteralType(litType)}`;
+  }
+
+  params.push(stringifyForColumn(value, col));
+  if (value === null && col.isArray) return `$${idx}`;
+  if (col.isArray) {
+    // Unnest a JSON array param, casting each element (z2s's `formatPlural`, `sql.ts:260`).
+    return `ARRAY(SELECT ${pgCast("value", col.type, col.isEnum, isComparison)} FROM jsonb_array_elements_text($${idx}::text::jsonb))`;
+  }
+  return pgCast(`$${idx}`, col.type, col.isEnum, isComparison);
+}
+
+/**
+ * Project a stored column into the value model's representation (§6.2 outbound half). Temporal
+ * columns become **integer epoch-ms** — the value model always snaps to whole milliseconds, so
+ * `::bigint` rounds off the native µs resolution (unlike z2s, which projects the non-normalized
+ * path as an unsnapped float). Time-of-day-with-offset types additionally wrap `mod 1 day`.
+ * Enums (their label), uuid, numeric, json, and the scalar types project raw. See
+ * `needsTimeOfDayNormalization` for the deliberate divergence from z2s on `timestamptz`.
+ *
+ * The rounding mode (`::bigint` = round-half-to-even) must match pg-source's projector for exact
+ * parity — it is the one shared value-model contract (§10), not an independent choice here.
+ */
+function projectColumn(colRef: string, col: ColumnType | null): string {
+  if (!col || col.isEnum || !isTemporalType(col.type)) return colRef;
+  const normalize = needsTimeOfDayNormalization(col.type);
+  const toMs = (epoch: string): string =>
+    normalize ? `((${epoch})::bigint + 86400000) % 86400000` : `(${epoch})::bigint`;
+  if (col.isArray) {
+    return `CASE WHEN ${colRef} IS NULL THEN NULL ELSE ARRAY(SELECT ${toMs(`EXTRACT(EPOCH FROM unnest(${colRef})) * 1000`)}) END`;
+  }
+  return toMs(`EXTRACT(EPOCH FROM ${colRef}) * 1000`);
+}
+
+function orderDir(dir: Dir): string {
+  // Engine order is null-low; Postgres's default is the opposite, so make it explicit (§8).
+  return dir === "asc" ? "ASC NULLS FIRST" : "DESC NULLS LAST";
+}
+
+/**
+ * The Postgres dialect — the BYO-Postgres server-mutator read target. Emits `(sql, params)`
+ * with `$N::text::<type>` parameters and never imports a driver (Invariant 7).
+ */
+export const postgresDialect: Dialect = {
+  name: "postgres",
+  objectBuild: (parts) => `jsonb_build_object(${parts.join(", ")})`,
+  groupArray: (elem, orderSql) => `jsonb_agg(${elem}${orderSql})`,
+  emptyArray: "'[]'::jsonb",
+  reassertJson: (x) => x, // jsonb is a real type; no re-assert needed
+  trueLit: "TRUE",
+  falseLit: "FALSE",
+  orderDir,
+  projectColumn,
+  bindValue,
+  quoteIdent,
+};

package/src/reject.ts

@@ -0,0 +1,71 @@
+// Reject AST features the compiler does not lower, anywhere in the tree — so an unhandled
+// field fails loudly rather than producing silently-wrong SQL. Faithful port of
+// `rindle-d2s`'s `reject_unsupported` family (lib.rs:194).
+//
+// `start` (a paging bound) is lowered as a keyset predicate, but only on the **materialized
+// collections** the compiler emits (the root and each `related` child). It is *not* honored
+// inside an EXISTS/NOT EXISTS subquery, nor inside a `count(child)` aggregate — a `start`
+// there is rejected here rather than silently dropped.
+
+import type { Ast, Condition } from "./ast.ts";
+import { unsupported } from "./errors.ts";
+
+export function rejectUnsupported(ast: Ast): void {
+  for (const rel of ast.related ?? []) {
+    if (rel.subquery.aggregate) {
+      // A `count(child)` aggregate reduces its rows away: a `start`/`limit`/nested `related`
+      // would change the IVM count but `count_expr` ignores them — reject rather than diverge.
+      rejectAggregateSubquery(rel.subquery);
+    } else {
+      rejectUnsupported(rel.subquery); // collection: start honored, recurse
+    }
+  }
+  if (ast.where) {
+    rejectUnsupportedCond(ast.where);
+  }
+}
+
+function rejectAggregateSubquery(ast: Ast): void {
+  if (ast.start) throw unsupported("start inside a count aggregate");
+  if (ast.limit !== undefined) throw unsupported("limit inside a count aggregate");
+  if (ast.related && ast.related.length > 0) {
+    throw unsupported("nested related inside a count aggregate");
+  }
+  if (ast.where) rejectUnsupportedCond(ast.where);
+}
+
+function rejectUnsupportedCond(cond: Condition): void {
+  switch (cond.type) {
+    case "simple":
+      return;
+    case "correlatedSubquery":
+      rejectStartAnywhere(cond.related.subquery); // EXISTS: its `start` is not honored
+      return;
+    case "and":
+    case "or":
+      for (const c of cond.conditions) rejectUnsupportedCond(c);
+      return;
+  }
+}
+
+/** Reject a `start` bound *anywhere* in `ast` (the EXISTS subtrees the compiler does not
+ *  page). Conservative: rejects even positions a clever lowering might honor. */
+function rejectStartAnywhere(ast: Ast): void {
+  if (ast.start) throw unsupported("start (paging) inside an EXISTS subquery");
+  for (const rel of ast.related ?? []) rejectStartAnywhere(rel.subquery);
+  if (ast.where) rejectStartAnywhereCond(ast.where);
+}
+
+function rejectStartAnywhereCond(cond: Condition): void {
+  switch (cond.type) {
+    case "simple":
+      return;
+    case "correlatedSubquery":
+      rejectStartAnywhere(cond.related.subquery);
+      return;
+    case "and":
+    case "or":
+      for (const c of cond.conditions) rejectStartAnywhereCond(c);
+      return;
+  }
+}