feat: core grammar, discovery and renderer; Postgres dialect; conformance suite

2026-11-02 01:11:38 +01:00
commit 4b276f21e3
54 changed files with 4103 additions and 0 deletions
@@ -0,0 +1,23 @@
+import { RestError } from '@crudy/restloom';
+
+const CODES: Record<string, [number, string]> = {
+    '42501': [403, 'forbidden'],
+    '23505': [409, 'duplicate'],
+    '23503': [409, 'reference_missing'],
+    '23502': [400, 'value_required'],
+    '23514': [400, 'value_rejected'],
+    '22P02': [400, 'invalid_value'],
+    '22007': [400, 'invalid_value'],
+    '22008': [400, 'invalid_value'],
+    '22003': [400, 'invalid_value'],
+    '22001': [400, 'invalid_value'],
+    '22023': [400, 'invalid_value'],
+    '57014': [503, 'timeout'],
+};
+
+/** A Postgres error the client caused, by SQLSTATE. The database's own message is never passed on. */
+export function mapError(err: unknown): RestError | null {
+    const code = (err as { code?: unknown })?.code;
+    const hit = typeof code === 'string' ? CODES[code] : undefined;
+    return hit ? new RestError(hit[0], hit[1]) : null;
+}
@@ -0,0 +1,49 @@
+import { SqlRenderer, type Dialect, type Tx } from '@crudy/restloom';
+import type { Pool } from 'pg';
+import { mapError } from './errors.js';
+import { introspect } from './introspect.js';
+
+export { mapError } from './errors.js';
+
+/** Postgres writes every primitive the core's defaults assume; subclass it to change one. */
+export class PostgresRenderer extends SqlRenderer {}
+
+export interface PostgresOptions {
+    renderer?: SqlRenderer;
+}
+
+/**
+ * The Postgres dialect over a `pg` Pool. Every request runs in one transaction
+ * with a local statement timeout, read-only for reads, so a `transaction` hook
+ * can set the role and session settings that row security reads.
+ */
+export function postgres(pool: Pool, options: PostgresOptions = {}): Dialect {
+    return {
+        name: 'postgres',
+        capabilities: { returning: true, estimatedCount: true, rowSecurity: true },
+        renderer: options.renderer ?? new PostgresRenderer(),
+        introspect: (scope) => introspect(pool, scope),
+        async transaction(fn, { timeoutMs, readOnly }) {
+            const client = await pool.connect();
+            try {
+                await client.query(readOnly ? 'BEGIN READ ONLY' : 'BEGIN');
+                await client.query(`SET LOCAL statement_timeout = ${Math.max(1, Math.floor(timeoutMs))}`);
+                const tx: Tx = { query: async (sql, params) => (await client.query(sql, params)).rows };
+                const out = await fn(tx);
+                await client.query('COMMIT');
+                return out;
+            } catch (err) {
+                await client.query('ROLLBACK').catch(() => undefined);
+                throw err;
+            } finally {
+                client.release();
+            }
+        },
+        mapError,
+        async estimate(tx, sql, params) {
+            const [row] = await tx.query(`EXPLAIN (FORMAT JSON) ${sql}`, params);
+            const plan = (row?.['QUERY PLAN'] as { Plan?: { 'Plan Rows'?: number } }[] | undefined)?.[0]?.Plan;
+            return typeof plan?.['Plan Rows'] === 'number' ? plan['Plan Rows'] : null;
+        },
+    };
+}
@@ -0,0 +1,96 @@
+import type { Catalog, CatalogColumn, CatalogTable } from '@crudy/restloom';
+import type { Pool } from 'pg';
+import { logical } from './types.js';
+
+const TABLES = `
+SELECT c.oid, n.nspname AS schema, c.relname AS name, c.relkind AS kind
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f')
+   AND (n.nspname = ANY($1::text[]) OR n.nspname || '.' || c.relname = ANY($2::text[]))`;
+
+const COLUMNS = `
+SELECT a.attrelid AS oid, a.attname AS name, format_type(a.atttypid, a.atttypmod) AS native,
+       b.typname, b.typtype, b.typcategory, a.attnotnull AS notnull,
+       (a.attgenerated <> '' OR a.attidentity = 'a') AS generated
+  FROM pg_attribute a
+  JOIN pg_type t ON t.oid = a.atttypid
+  JOIN pg_type b ON b.oid = CASE WHEN t.typtype = 'd' THEN t.typbasetype ELSE t.oid END
+ WHERE a.attrelid = ANY($1::oid[]) AND a.attnum > 0 AND NOT a.attisdropped
+ ORDER BY a.attrelid, a.attnum`;
+
+const PRIMARY_KEYS = `
+SELECT i.indrelid AS oid, array_agg(a.attname::text ORDER BY k.ord) AS columns
+  FROM pg_index i
+  CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
+  JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+ WHERE i.indisprimary AND i.indrelid = ANY($1::oid[])
+ GROUP BY i.indrelid`;
+
+const FOREIGN_KEYS = `
+SELECT con.conrelid AS oid, tn.nspname AS target_schema, tc.relname AS target_table,
+       (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(con.conkey) WITH ORDINALITY k(n, ord)
+          JOIN pg_attribute a ON a.attrelid = con.conrelid AND a.attnum = k.n) AS columns,
+       (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(con.confkey) WITH ORDINALITY k(n, ord)
+          JOIN pg_attribute a ON a.attrelid = con.confrelid AND a.attnum = k.n) AS target_columns
+  FROM pg_constraint con
+  JOIN pg_class tc ON tc.oid = con.confrelid
+  JOIN pg_namespace tn ON tn.oid = tc.relnamespace
+ WHERE con.contype = 'f' AND con.conrelid = ANY($1::oid[])
+ ORDER BY con.conname`;
+
+const FUNCTIONS = `
+SELECT n.nspname AS schema, p.proname AS name, p.proretset AS returns_set, p.pronargs AS nargs,
+       p.pronargdefaults AS ndefaults, coalesce(p.proargnames, '{}') AS argnames,
+       (SELECT array_agg(format_type(t, NULL) ORDER BY ord) FROM unnest(p.proargtypes) WITH ORDINALITY u(t, ord)) AS natives,
+       (SELECT array_agg(b.typname::text || ':' || b.typtype::text || ':' || b.typcategory::text ORDER BY ord)
+          FROM unnest(p.proargtypes) WITH ORDINALITY u(t, ord) JOIN pg_type b ON b.oid = u.t) AS types
+  FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+ WHERE p.prokind = 'f' AND n.nspname = ANY($1::text[])`;
+
+type Row = Record<string, unknown>;
+
+/** Reads the tables, views, keys, foreign keys and functions of the exposed schemas and tables. */
+export async function introspect(pool: Pool, scope: { schemas: string[]; tables: string[] }): Promise<Catalog> {
+    const { rows: tables } = await pool.query<Row>(TABLES, [scope.schemas, scope.tables]);
+    const oids = tables.map((t) => t.oid as number);
+    const [columns, keys, fks, fns] = await Promise.all([
+        pool.query<Row>(COLUMNS, [oids]), pool.query<Row>(PRIMARY_KEYS, [oids]),
+        pool.query<Row>(FOREIGN_KEYS, [oids]), pool.query<Row>(FUNCTIONS, [scope.schemas]),
+    ]);
+    const byOid = new Map<number, CatalogTable>();
+    for (const t of tables) {
+        byOid.set(t.oid as number, {
+            schema: t.schema as string, name: t.name as string,
+            kind: t.kind === 'v' || t.kind === 'm' ? 'view' : 'table',
+            columns: [], primaryKey: [], foreignKeys: [],
+        });
+    }
+    for (const c of columns.rows) {
+        const col: CatalogColumn = {
+            name: c.name as string, nativeType: c.native as string, nullable: !c.notnull, generated: c.generated as boolean,
+            type: logical(c.typname as string, c.typtype as string, c.typcategory as string),
+        };
+        byOid.get(c.oid as number)?.columns.push(col);
+    }
+    for (const k of keys.rows) byOid.get(k.oid as number)!.primaryKey = k.columns as string[];
+    for (const f of fks.rows) {
+        byOid.get(f.oid as number)!.foreignKeys.push({
+            columns: f.columns as string[], targetColumns: f.target_columns as string[],
+            target: { schema: f.target_schema as string, table: f.target_table as string },
+        });
+    }
+    const functions = fns.rows.map((f) => {
+        const names = f.argnames as string[];
+        const types = (f.types as string[] | null) ?? [];
+        const natives = (f.natives as string[] | null) ?? [];
+        const nargs = f.nargs as number;
+        return {
+            schema: f.schema as string, name: f.name as string, returnsSet: f.returns_set as boolean,
+            args: types.map((t, i) => {
+                const [typname, typtype, category] = t.split(':');
+                return { name: names[i] ?? '', type: logical(typname, typtype, category), nativeType: natives[i], hasDefault: i >= nargs - (f.ndefaults as number) };
+            }),
+        };
+    });
+    return { tables: [...byOid.values()], functions };
+}
@@ -0,0 +1,18 @@
+import type { LogicalType } from '@crudy/restloom';
+
+const BY_NAME: Record<string, LogicalType> = {
+    int2: 'integer', int4: 'integer', int8: 'integer', oid: 'integer',
+    numeric: 'number', float4: 'number', float8: 'number', money: 'number',
+    bool: 'boolean', uuid: 'uuid',
+    date: 'date', timestamp: 'timestamp', timestamptz: 'timestamp', time: 'time', timetz: 'time',
+    text: 'text', varchar: 'text', bpchar: 'text', name: 'text', citext: 'text', inet: 'text', cidr: 'text',
+    json: 'json', jsonb: 'json', bytea: 'binary',
+};
+
+/** A Postgres type (after resolving a domain to its base) as a logical type. Enums read as text. */
+export function logical(typname: string, typtype: string, category: string): LogicalType {
+    if (BY_NAME[typname]) return BY_NAME[typname];
+    if (typtype === 'e') return 'text';
+    if (category === 'A') return 'array';
+    return 'other';
+}