API index and search · Build metadata

Source snapshot

packages/query-compiler/src/catalog.ts

1// The static, declared type catalog (POSTGRES-READ-COMPILER-DESIGN.md §7) — the second2// input to the compiler, beside the `Ast`. Compilation is a pure function of3// `(Ast, Catalog)`; the catalog carries the facts the AST does not: column order, primary4// key, relationship cardinality, and — for the Postgres dialect — the per-column native5// type detail the `::text::<type>` cast strategy (§6.2) branches on.67/** Whether a relationship yields a single child object (`one`) or an array (`many`). */8export type Cardinality = "one" | "many";910/**11 * Per-column type detail the Postgres compiler needs for value-model↔native-type12 * reconciliation (§6.2). Mirrors z2s's `ServerColumnSchema`: the raw Postgres type name13 * plus the two flags the cast switch branches on. The extension over what14 * `rindle-pg-source` derives today (§7, review decision 2): enums and arrays are carried15 * distinctly instead of collapsing into a text fallback.16 *17 * - `type` — the native Postgres type name: `"int4"`, `"text"`, `"bool"`, `"float8"`,18 *   `"numeric"`, `"timestamptz"`, `"timestamp"`, `"date"`, `"timetz"`, `"time"`, `"uuid"`,19 *   `"json"`/`"jsonb"`, or an **enum type name** (paired with `isEnum: true`).20 * - `isEnum` — `type` names a Postgres enum ⇒ cast via `$N::text::"<type>"`.21 * - `isArray` — the column is an array ⇒ unnest via `jsonb_array_elements_text`.22 *23 * The SQLite oracle dialect ignores this entirely: it binds native values (no casts).24 */25export interface ColumnType {26  type: string;27  isEnum: boolean;28  isArray: boolean;29}3031/**32 * Per-table metadata the compiler needs beyond the `Ast`:33 * - `columns` — the projected column list, **in projection order** (the order34 *   `json_object`/`jsonb_build_object` enumerates), matching the View's `Schema`.35 * - `primaryKey` — the PK columns, for ordering-completion (§8): the compiler appends the36 *   full PK to every `orderBy` at every level for a total order, exactly as the engine's37 *   builder does (`rindle::complete_ordering`).38 * - `columnTypes` — per-column native type detail, keyed by column name (§6.2; Postgres39 *   dialect only).40 * - `relationships` — declared relationships → cardinality. This is the one structural41 *   fact not carried by the `Ast` (the relationship *shape* — correlation keys, nesting,42 *   where/order/limit — lives in the `Ast`'s `related` subqueries).43 */44export interface TableSchema {45  columns: string[];46  primaryKey: string[];47  columnTypes: Record<string, ColumnType>;48  relationships: Record<string, Cardinality>;49}5051/**52 * The catalog: every table the compiler may reference, keyed by table name. Produced53 * statically by `rindle pg prepare` from an ephemeral migration-built Postgres (§7,54 * Phase B); hand-authored for tests. A pure input — the compiler never touches a database55 * to obtain it.56 */57export interface Catalog {58  tables: Record<string, TableSchema>;59}60