@kequtech/tenon-orm 0.0.0-stage → 0.1.1

package/dist/generate.d.ts

@@ -0,0 +1,9 @@
+import type { Connection } from './connection.js';
+export interface GenerateOptions {
+    readonly connection: Connection;
+    readonly namespace?: string;
+    /** Receives generation warnings; defaults to console.warn. */
+    readonly onWarning?: (message: string) => void;
+}
+/** Read-only introspection. Output needs no runtime imports or schema registration. */
+export declare function generateDefinitions(options: GenerateOptions): Promise<string>;

package/dist/generate.js

@@ -0,0 +1,34 @@
+import { readTables } from './generation/catalog.js';
+import { renderRowTypes } from './generation/row-types.js';
+import { domainSummaries, schemaSummary, tableSummary } from './generation/schema-summary.js';
+import { withMigrationLock } from './migrations/connection.js';
+import { quote } from './sql.js';
+/** Read-only introspection. Output needs no runtime imports or schema registration. */
+export async function generateDefinitions(options) {
+    const onWarning = options.onWarning ?? ((message) => console.warn(`Warning: ${message}`));
+    return withMigrationLock(options, 'shared', async (client, namespace) => {
+        await client.query('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
+        const schema = await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
+            namespace,
+        ]);
+        if (!schema.rows.length)
+            throw new Error(`Schema ${quote(namespace)} does not exist.`);
+        // Keep catalog deparsing stable across connection settings and replay schemas.
+        // Transaction-local settings are restored before returning a borrowed client.
+        await client.query(`SET LOCAL search_path TO pg_catalog, ${quote(namespace)}`);
+        await client.query('SET LOCAL quote_all_identifiers TO off');
+        await client.query('SET LOCAL standard_conforming_strings TO on');
+        const definitions = await readTables(client, namespace);
+        const summaries = [];
+        for (const table of definitions) {
+            summaries.push(await tableSummary(client, table.oid, table.name));
+        }
+        const domains = await domainSummaries(client, definitions.flatMap((table) => table.columns.map((column) => column.declaredOid)));
+        const types = renderRowTypes(definitions, namespace, onWarning);
+        await client.query('COMMIT');
+        return `// Generated by Tenon from the PostgreSQL schema. Do not edit.
+// Commit this file and regenerate it after changing the schema.
+
+${schemaSummary([...domains, ...summaries])}${types}`;
+    });
+}

package/dist/generation/catalog.d.ts

@@ -0,0 +1,19 @@
+import type { PoolClient } from 'pg';
+export interface ColumnRow {
+    name: string;
+    oid: string;
+    type: string;
+    typeSchema: string;
+    typeKind: string;
+    declaredOid: string;
+    declaredType: string;
+    declaredSchema: string;
+    nullable: boolean;
+    choices: string[] | null;
+}
+export interface TableRow {
+    oid: string;
+    name: string;
+    columns: ColumnRow[];
+}
+export declare function readTables(client: PoolClient, namespace: string): Promise<TableRow[]>;

package/dist/generation/catalog.js

@@ -0,0 +1,35 @@
+import { migrationTable } from '../migrations/history.js';
+export async function readTables(client, namespace) {
+    const tables = await client.query(`
+      SELECT c.oid::text AS oid, c.relname AS name
+      FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = $1 AND c.relname <> $2 AND c.relkind IN ('r', 'p')
+        AND NOT c.relispartition
+      ORDER BY c.relname COLLATE "C"`, [namespace, migrationTable]);
+    const definitions = [];
+    for (const table of tables.rows) {
+        // Attached descendants are storage details, not separate generated models.
+        const columns = await client.query(`
+        WITH RECURSIVE resolved AS (
+          SELECT a.attnum, t.oid, t.typbasetype
+          FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+          WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
+          UNION ALL
+          SELECT r.attnum, t.oid, t.typbasetype
+          FROM resolved r JOIN pg_catalog.pg_type t ON t.oid = r.typbasetype
+        )
+        SELECT a.attname AS name, t.oid::text AS oid, t.typname AS type, tn.nspname AS "typeSchema", t.typtype AS "typeKind",
+          declared.oid::text AS "declaredOid", declared.typname AS "declaredType", dn.nspname AS "declaredSchema",
+          NOT a.attnotnull AS nullable,
+          (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder) FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS choices
+        FROM pg_catalog.pg_attribute a
+          JOIN resolved r ON r.attnum = a.attnum AND r.typbasetype = 0
+          JOIN pg_catalog.pg_type t ON t.oid = r.oid
+          JOIN pg_catalog.pg_namespace tn ON tn.oid = t.typnamespace
+          JOIN pg_catalog.pg_type declared ON declared.oid = a.atttypid
+          JOIN pg_catalog.pg_namespace dn ON dn.oid = declared.typnamespace
+        WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [table.oid]);
+        definitions.push({ ...table, columns: columns.rows });
+    }
+    return definitions;
+}

package/dist/generation/row-types.d.ts

@@ -0,0 +1,2 @@
+import type { TableRow } from './catalog.js';
+export declare function renderRowTypes(tables: readonly TableRow[], namespace: string, onWarning: (message: string) => void): string;

package/dist/generation/row-types.js

@@ -0,0 +1,115 @@
+// Every generated table remains accessible through Rows["exact SQL name"].
+const reservedTypeNames = new Set(`
+  as await break case catch class const continue debugger default delete do else enum
+  export extends false finally for function if implements import in instanceof
+  interface let new null package private protected public return static super
+  switch this throw true try typeof var void while with yield any bigint boolean
+  intrinsic never number object string symbol undefined unknown
+  Rows globalThis PgArray
+`
+    .trim()
+    .split(/\s+/));
+function canExportRowName(name) {
+    return (/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(name) && !reservedTypeNames.has(name));
+}
+// Exact built-in OIDs with verified default pg text parsers. Array parsers do
+// not necessarily use their scalar type's representation (notably numeric[]).
+const arrayTypes = {
+    '1000': 'boolean',
+    '1001': 'import("node:buffer").Buffer',
+    '1005': 'number',
+    '1007': 'number',
+    '1021': 'number',
+    '1022': 'number',
+    '1028': 'number',
+    '1016': 'string',
+    '1231': 'number',
+    '1009': 'string',
+    '1014': 'string',
+    '1015': 'string',
+    '1183': 'string',
+    '1270': 'string',
+    '2951': 'string',
+    '1182': 'globalThis.Date | number',
+    '1115': 'globalThis.Date | number',
+    '1185': 'globalThis.Date | number',
+    '199': 'unknown',
+    '3807': 'unknown',
+};
+const scalarTypes = {
+    int2: 'number',
+    int4: 'number',
+    oid: 'number',
+    float4: 'number',
+    float8: 'number',
+    bool: 'boolean',
+    text: 'string',
+    varchar: 'string',
+    bpchar: 'string',
+    time: 'string',
+    timetz: 'string',
+    uuid: 'string',
+    // pg returns +/-Infinity as numbers. TypeScript has no infinity literal type.
+    date: 'globalThis.Date | number',
+    timestamp: 'globalThis.Date | number',
+    timestamptz: 'globalThis.Date | number',
+    int8: 'string',
+    numeric: 'string',
+    json: 'unknown',
+    jsonb: 'unknown',
+    bytea: 'import("node:buffer").Buffer',
+};
+function isSupportedArray(value) {
+    return Object.hasOwn(arrayTypes, value.oid);
+}
+function columnType(value, column, onWarning) {
+    let scalar;
+    if (isSupportedArray(value)) {
+        scalar = `PgArray<${arrayTypes[value.oid]}>`;
+    }
+    else if (value.typeKind === 'e') {
+        scalar = value.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+    }
+    else {
+        const type = value.typeSchema === 'pg_catalog' && Object.hasOwn(scalarTypes, value.type)
+            ? scalarTypes[value.type]
+            : undefined;
+        if (type) {
+            scalar = type;
+        }
+        else {
+            const underlying = value.declaredOid === value.oid
+                ? ''
+                : ` with underlying type ${JSON.stringify(value.typeSchema)}.${JSON.stringify(value.type)} (OID ${value.oid})`;
+            onWarning(`Column ${column} uses PostgreSQL type ${JSON.stringify(value.declaredSchema)}.${JSON.stringify(value.declaredType)} (OID ${value.declaredOid})${underlying} without a verified pg mapping; generated as unknown.`);
+            scalar = 'unknown';
+        }
+    }
+    // unknown already includes null, including for nullable JSON and unmapped types.
+    return `${scalar}${value.nullable && scalar !== 'unknown' ? ' | null' : ''}`;
+}
+export function renderRowTypes(tables, namespace, onWarning) {
+    const rows = tables.map((table) => {
+        const tableName = JSON.stringify(table.name);
+        const columns = table.columns.map((column) => {
+            const columnName = JSON.stringify(column.name);
+            const path = `${JSON.stringify(namespace)}.${tableName}.${columnName}`;
+            return `    ${columnName}: ${columnType(column, path, onWarning)};`;
+        });
+        return `  ${tableName}: {
+${columns.join('\n')}
+  };`;
+    });
+    const aliases = tables
+        .filter((table) => canExportRowName(table.name))
+        .map((table) => `export type ${table.name} = Rows[${JSON.stringify(table.name)}];`);
+    const arrays = tables.some((table) => table.columns.some(isSupportedArray))
+        ? 'export type PgArray<T> = (T | null | PgArray<T>)[];\n\n'
+        : '';
+    return `${arrays}// Full database rows. Compose query types with Pick, indexed access, and intersections.
+export type Rows = {
+${rows.join('\n')}
+};
+${aliases.join('\n')}
+`;
+}

package/dist/generation/schema-summary.d.ts

@@ -0,0 +1,6 @@
+import type { PoolClient } from 'pg';
+/** Include only domains reached through selected columns, base domains or arrays. */
+export declare function domainSummaries(client: PoolClient, typeOids: readonly string[]): Promise<string[]>;
+/** Called inside generation's read-only snapshot, with a fixed local search_path. */
+export declare function tableSummary(client: PoolClient, oid: string, name: string): Promise<string>;
+export declare function schemaSummary(summaries: readonly string[]): string;

package/dist/generation/schema-summary.js

@@ -0,0 +1,114 @@
+import { quote } from '../sql.js';
+/** Include only domains reached through selected columns, base domains or arrays. */
+export async function domainSummaries(client, typeOids) {
+    const domains = await client.query(`
+    WITH RECURSIVE referenced(oid) AS (
+      SELECT unnest($1::oid[])
+      UNION
+      SELECT child.oid FROM referenced r JOIN pg_catalog.pg_type t ON t.oid = r.oid
+        CROSS JOIN LATERAL (VALUES (t.typbasetype), (t.typelem)) child(oid)
+      WHERE child.oid <> 0
+    )
+    SELECT t.oid::text AS oid, pg_catalog.format_type(t.oid, NULL) AS name,
+      pg_catalog.format_type(t.typbasetype, t.typtypmod) AS base,
+      NOT t.typnotnull AS nullable, pg_catalog.pg_get_expr(t.typdefaultbin, 0, false) AS expression,
+      CASE WHEN t.typcollation <> base.typcollation THEN t.typcollation::pg_catalog.regcollation::text END AS collation
+    FROM referenced r JOIN pg_catalog.pg_type t ON t.oid = r.oid
+      JOIN pg_catalog.pg_type base ON base.oid = t.typbasetype
+    WHERE t.typtype = 'd'
+    ORDER BY pg_catalog.format_type(t.oid, NULL) COLLATE "C"`, [typeOids]);
+    const summaries = [];
+    for (const domain of domains.rows) {
+        const constraints = await client.query(`
+      SELECT conname AS name, pg_catalog.pg_get_constraintdef(oid, false) AS definition
+      FROM pg_catalog.pg_constraint WHERE contypid = $1::oid
+      ORDER BY conname COLLATE "C"`, [domain.oid]);
+        summaries.push([
+            `DOMAIN ${domain.name} AS ${domain.base}` +
+                (domain.collation === null ? '' : ` COLLATE ${domain.collation}`) +
+                (domain.expression === null ? '' : ` DEFAULT ${domain.expression}`) +
+                (domain.nullable ? '' : ' NOT NULL'),
+            ...constraints.rows.map((constraint) => `  CONSTRAINT ${quote(constraint.name)} ${constraint.definition}`),
+        ].join('\n'));
+    }
+    return summaries;
+}
+/** Called inside generation's read-only snapshot, with a fixed local search_path. */
+export async function tableSummary(client, oid, name) {
+    const columns = await client.query(`
+    SELECT a.attname AS name,
+      pg_catalog.format_type(a.atttypid, a.atttypmod)
+      || CASE WHEN a.attnotnull THEN ' NOT NULL' ELSE '' END
+      || CASE
+        WHEN a.attidentity <> '' THEN
+          ' GENERATED ' || CASE a.attidentity WHEN 'a' THEN 'ALWAYS' ELSE 'BY DEFAULT' END
+          || ' AS IDENTITY' || pg_catalog.format(
+            ' (START WITH %s INCREMENT BY %s MINVALUE %s MAXVALUE %s CACHE %s %s)',
+            s.seqstart, s.seqincrement, s.seqmin, s.seqmax, s.seqcache,
+            CASE WHEN s.seqcycle THEN 'CYCLE' ELSE 'NO CYCLE' END)
+        WHEN a.attgenerated <> '' THEN
+          ' GENERATED ALWAYS AS (' || pg_catalog.pg_get_expr(d.adbin, d.adrelid, false)
+          || ')' || CASE a.attgenerated WHEN 's' THEN ' STORED' WHEN 'v' THEN ' VIRTUAL' ELSE '' END
+        WHEN d.oid IS NOT NULL THEN ' DEFAULT ' || pg_catalog.pg_get_expr(d.adbin, d.adrelid, false)
+        ELSE ''
+      END AS definition
+    FROM pg_catalog.pg_attribute a
+      LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+      LEFT JOIN pg_catalog.pg_depend dep ON a.attidentity <> ''
+        AND dep.refclassid = 'pg_catalog.pg_class'::pg_catalog.regclass
+        AND dep.refobjid = a.attrelid AND dep.refobjsubid = a.attnum
+        AND dep.classid = 'pg_catalog.pg_class'::pg_catalog.regclass AND dep.deptype = 'i'
+      LEFT JOIN pg_catalog.pg_sequence s ON s.seqrelid = dep.objid
+    WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
+    ORDER BY a.attnum`, [oid]);
+    // Column definitions already describe NOT NULL; PostgreSQL 18 also stores it
+    // as a table constraint, which would duplicate every required column here.
+    const constraints = await client.query(`
+    SELECT conname AS name, pg_catalog.pg_get_constraintdef(oid, false) AS definition
+    FROM pg_catalog.pg_constraint
+    WHERE conrelid = $1::oid AND conparentid = 0 AND contype IN ('p', 'u', 'f', 'c', 'x')
+    ORDER BY conname COLLATE "C"`, [oid]);
+    const indexes = await client.query(`
+    SELECT pg_catalog.pg_get_indexdef(i.indexrelid, 0, false) AS definition,
+      pg_catalog.format('CREATE %sINDEX %I ON %s',
+        CASE WHEN i.indisunique THEN 'UNIQUE ' ELSE '' END, ic.relname,
+        CASE WHEN t.relkind = 'p' THEN 'ONLY ' ELSE '' END) AS prefix,
+      pg_catalog.quote_ident(n.nspname) || '.' AS qualification,
+      i.indisvalid AS valid, i.indisready AS ready
+    FROM pg_catalog.pg_index i
+      JOIN pg_catalog.pg_class ic ON ic.oid = i.indexrelid
+      JOIN pg_catalog.pg_class t ON t.oid = i.indrelid
+      JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
+    WHERE i.indrelid = $1::oid
+    ORDER BY ic.relname COLLATE "C"`, [oid]);
+    const lines = [
+        `TABLE ${quote(name)}`,
+        ...columns.rows.map((column) => `  ${quote(column.name)} ${column.definition}`),
+        ...constraints.rows.map((constraint) => `  CONSTRAINT ${quote(constraint.name)} ${constraint.definition}`),
+        ...indexes.rows.map((index) => {
+            // pg_get_indexdef always qualifies its target table. Remove only that
+            // known prefix, never matching/replacing namespace text inside SQL literals.
+            const qualifiedPrefix = index.prefix + index.qualification;
+            if (!index.definition.startsWith(qualifiedPrefix)) {
+                throw new Error(`Unexpected PostgreSQL index definition for ${quote(name)}.`);
+            }
+            const definition = index.prefix + index.definition.slice(qualifiedPrefix.length);
+            return `  ${definition}${index.valid ? '' : ' [INVALID]'}${index.ready ? '' : ' [NOT READY]'}`;
+        }),
+    ];
+    return lines.join('\n');
+}
+export function schemaSummary(summaries) {
+    const text = [
+        'Schema summary — same database checkpoint as the row types below.',
+        'Unqualified application names use the selected namespace; pg_catalog is also in the search path.',
+        'Descriptive catalog output, not a migration script. Includes constraint-backed indexes.',
+        ...summaries.map((summary) => `\n${summary}`),
+    ].join('\n');
+    // Identifiers and SQL literals can contain any JavaScript line terminator.
+    // Prefix every physical line so catalog text always remains a comment.
+    return (text
+        .split(/\r\n|[\n\r\u2028\u2029]/u)
+        .map((line) => `//${line ? ` ${line}` : ''}`)
+        .join('\n') + '\n\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export type { QueryResult } from 'pg';
+export type { AffectedRowsConstraint } from './affected-rows.js';
+export { createTenon } from './database.js';
+export type { TenonOptions } from './database.js';
+export { AffectedRowsError } from './errors.js';
+export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
+export { identifier, sql, unsafeSql } from './query.js';
+export type { SqlFragment, SqlQuery, UnknownRow } from './query.js';
+export type { Database, QueryClient, QueryEvent, Transaction } from './types.js';
+export { adoptBaseline, captureBaseline } from './baseline.js';
+export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
+export { generateDefinitions } from './generate.js';
+export type { GenerateOptions } from './generate.js';
+export { migrate, migrationStatus, rollback } from './migrations.js';
+export type { MigrationStatus } from './migrations.js';
+export type { DatabaseToolOptions } from './migrations/connection.js';
+export { createMigration, readMigrations } from './migrations/files.js';
+export type { CreateMigrationOptions, CreatedMigration, SqlMigration } from './migrations/files.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createTenon } from './database.js';
+export { AffectedRowsError } from './errors.js';
+export { identifier, sql, unsafeSql } from './query.js';
+export { adoptBaseline, captureBaseline } from './baseline.js';
+export { generateDefinitions } from './generate.js';
+export { migrate, migrationStatus, rollback } from './migrations.js';
+export { createMigration, readMigrations } from './migrations/files.js';

package/dist/migrations/baseline-sql.d.ts

@@ -0,0 +1,3 @@
+export declare const baselineHeader = "-- Tenon baseline captured by pg_dump.\n";
+/** Bridge pg_dump's plain-text script to pg's transactional SQL execution. */
+export declare function prepareBaselineSql(dump: string, namespace: string): string;

package/dist/migrations/baseline-sql.js

@@ -0,0 +1,38 @@
+import { quote } from '../sql.js';
+export const baselineHeader = '-- Tenon baseline captured by pg_dump.\n';
+/** Bridge pg_dump's plain-text script to pg's transactional SQL execution. */
+export function prepareBaselineSql(dump, namespace) {
+    // Recent pg_dump versions bracket psql scripts with a random restrict key.
+    // Remove only the outer pair; SQL bodies containing similar text stay intact.
+    const opening = /^\\restrict ([A-Za-z0-9]+)\r?$/m.exec(dump);
+    if (opening) {
+        const closing = dump.lastIndexOf(`\\unrestrict ${opening[1]}`);
+        if (closing < opening.index) {
+            throw new Error('pg_dump output has an incomplete psql wrapper.');
+        }
+        dump =
+            dump.slice(0, closing) + dump.slice(closing).replace(/^\\unrestrict [A-Za-z0-9]+\r?\n?/, '');
+        dump = dump.slice(0, opening.index) + dump.slice(opening.index + opening[0].length);
+    }
+    // Only the native preamble and bookkeeping schema declaration need adapting. Never
+    // rewrite SET/CREATE text inside functions or other captured object bodies.
+    const start = dump.indexOf('\n-- Name:');
+    const preamble = start === -1 ? dump : dump.slice(0, start);
+    let objects = start === -1 ? '' : dump.slice(start);
+    const declaration = `\nCREATE SCHEMA ${quote(namespace)};`;
+    const position = objects.indexOf(declaration);
+    const section = objects.lastIndexOf('\n-- Name:', position);
+    const isSchemaDeclaration = position !== -1 &&
+        objects
+            .slice(Math.max(section, 0), position)
+            .split('\n')
+            .every((line) => !line.trim() || line.startsWith('--'));
+    if (isSchemaDeclaration) {
+        objects = objects.replace(declaration, `\nCREATE SCHEMA IF NOT EXISTS ${quote(namespace)};`);
+    }
+    return (baselineHeader +
+        preamble
+            .replace(/^SET /gm, 'SET LOCAL ')
+            .replace("SELECT pg_catalog.set_config('search_path', '', false);", "SELECT pg_catalog.set_config('search_path', '', true);") +
+        objects);
+}

package/dist/migrations/connection.d.ts

@@ -0,0 +1,9 @@
+import type { PoolClient } from 'pg';
+import type { Connection } from '../connection.js';
+export interface DatabaseToolOptions {
+    readonly connection: Connection;
+    readonly namespace?: string;
+    readonly directory?: string;
+}
+/** Coordinate tools independently of application sessions; PostgreSQL owns the wait. */
+export declare function withMigrationLock<T>(options: DatabaseToolOptions, mode: 'shared' | 'exclusive', work: (client: PoolClient, namespace: string) => Promise<T>): Promise<T>;

package/dist/migrations/connection.js

@@ -0,0 +1,65 @@
+import { createPool, watchClient } from '../connection.js';
+import { validateName } from '../sql.js';
+/** Coordinate tools independently of application sessions; PostgreSQL owns the wait. */
+export async function withMigrationLock(options, mode, work) {
+    const namespace = options.namespace ?? 'public';
+    validateName(namespace);
+    const { pool, owned } = createPool(options.connection);
+    const suffix = mode === 'shared' ? '_shared' : '';
+    const lockKey = `tenon:migrations:${namespace}`;
+    const errors = [];
+    let client;
+    let connection;
+    let locked = false;
+    let result;
+    try {
+        client = await pool.connect();
+        connection = watchClient(client);
+        await client.query(`SELECT pg_advisory_lock${suffix}(hashtextextended($1, 0))`, [lockKey]);
+        locked = true;
+        result = await work(client, namespace);
+        connection.check();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    finally {
+        if (client) {
+            let releaseError;
+            try {
+                await client.query('ROLLBACK');
+                if (locked) {
+                    await client.query(`SELECT pg_advisory_unlock${suffix}(hashtextextended($1, 0))`, [
+                        lockKey,
+                    ]);
+                }
+            }
+            catch (error) {
+                errors.push(error);
+                releaseError =
+                    error instanceof Error ? error : new Error('Tool connection cleanup failed.');
+            }
+            try {
+                connection.release(releaseError);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (owned) {
+            try {
+                await pool.end();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+    }
+    if (errors.length === 1) {
+        throw errors[0];
+    }
+    if (errors.length > 1) {
+        throw new AggregateError(errors, 'Database operation and cleanup failed.');
+    }
+    return result;
+}

package/dist/migrations/files.d.ts

@@ -0,0 +1,21 @@
+export interface SqlMigration {
+    readonly id: string;
+    readonly name: string;
+    readonly up: string;
+    readonly down?: string;
+    readonly checksum: string;
+}
+export interface CreateMigrationOptions {
+    readonly name: string;
+    readonly directory?: string;
+}
+export interface CreatedMigration {
+    readonly id: string;
+    readonly upPath: string;
+    readonly downPath: string;
+}
+/** Serialize offline scaffolding and baseline capture in one directory. */
+export declare function withMigrationCreationLock<T>(directory: string, work: (directory: string) => Promise<T>): Promise<T>;
+/** Scaffold empty SQL files offline; authors supply both migration bodies. */
+export declare function createMigration(options: CreateMigrationOptions): Promise<CreatedMigration>;
+export declare function readMigrations(directory?: string): Promise<readonly SqlMigration[]>;

package/dist/migrations/files.js

@@ -0,0 +1,131 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { baselineHeader } from './baseline-sql.js';
+import { validateMigrationSql } from './sql.js';
+const migrationFilename = /^(\d+)_([A-Za-z0-9_-]+)\.(up|down)\.sql$/;
+/** Serialize offline scaffolding and baseline capture in one directory. */
+export async function withMigrationCreationLock(directory, work) {
+    directory = resolve(directory);
+    await mkdir(directory, { recursive: true });
+    const lockPath = join(directory, '.tenon-create.lock');
+    // Serialize local numbering even when two processes choose different names.
+    const lock = await open(lockPath, 'wx').catch((error) => {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+            throw new Error(`Migration creation lock exists at ${lockPath}; another creator may be running. Remove a stale lock only after that process has stopped.`);
+        }
+        throw error;
+    });
+    try {
+        return await work(directory);
+    }
+    finally {
+        try {
+            await lock.close();
+        }
+        finally {
+            await unlink(lockPath);
+        }
+    }
+}
+/** Scaffold empty SQL files offline; authors supply both migration bodies. */
+export async function createMigration(options) {
+    if (typeof options.name !== 'string' || !/^[A-Za-z0-9_-]+$/.test(options.name)) {
+        throw new Error('Migration names must contain only letters, digits, underscores or hyphens.');
+    }
+    return withMigrationCreationLock(options.directory ?? 'migrations', async (directory) => {
+        let latest = 0n;
+        let width = 4;
+        for (const file of await readdir(directory, { withFileTypes: true })) {
+            if (!file.isFile() || !file.name.endsWith('.sql')) {
+                continue;
+            }
+            const match = migrationFilename.exec(file.name);
+            if (!match) {
+                throw new Error(`Invalid migration filename: ${file.name}`);
+            }
+            const id = BigInt(match[1]);
+            if (id > latest) {
+                latest = id;
+            }
+            width = Math.max(width, match[1].length);
+        }
+        const id = (latest + 1n).toString().padStart(width, '0');
+        const upPath = join(directory, `${id}_${options.name}.up.sql`);
+        const downPath = join(directory, `${id}_${options.name}.down.sql`);
+        await writeFile(upPath, '', { flag: 'wx' });
+        try {
+            await writeFile(downPath, '', { flag: 'wx' });
+        }
+        catch (error) {
+            try {
+                await unlink(upPath);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], 'Migration creation and cleanup failed.');
+            }
+            throw error;
+        }
+        return { id, upPath, downPath };
+    });
+}
+export async function readMigrations(directory = 'migrations') {
+    const files = await readdir(directory, { withFileTypes: true });
+    const groups = new Map();
+    for (const file of files) {
+        if (!file.isFile() || !file.name.endsWith('.sql')) {
+            continue;
+        }
+        const match = migrationFilename.exec(file.name);
+        if (!match) {
+            throw new Error(`Invalid migration filename: ${file.name}; use 0001_description.up.sql and optional .down.sql.`);
+        }
+        const id = match[1];
+        const name = match[2];
+        const direction = match[3];
+        const group = groups.get(id) ?? { name };
+        if (group.name !== name || group[direction] !== undefined) {
+            throw new Error(`Duplicate migration version: ${id}`);
+        }
+        const sql = await readFile(join(directory, file.name), 'utf8');
+        if (!sql.trim()) {
+            throw new Error(`Empty migration: ${file.name}`);
+        }
+        // The filename/header opts into native pg_dump SQL, including SQL-standard
+        // function bodies our guard cannot parse. This is an explicit trust convention,
+        // not proof of provenance: baseline SQL must be reviewed before execution.
+        if (!(file.name === '0001_baseline.up.sql' && sql.startsWith(baselineHeader))) {
+            validateMigrationSql(sql, file.name);
+        }
+        group[direction] = sql;
+        groups.set(id, group);
+    }
+    const sorted = [...groups].sort(([left], [right]) => {
+        const a = BigInt(left);
+        const b = BigInt(right);
+        if (a < b) {
+            return -1;
+        }
+        if (a > b) {
+            return 1;
+        }
+        return 0;
+    });
+    return sorted.map(([id, group], i) => {
+        if (i && BigInt(sorted[i - 1][0]) === BigInt(id)) {
+            throw new Error(`Duplicate migration version: ${id}`);
+        }
+        if (group.up === undefined) {
+            throw new Error(`Migration ${id} has a down file without an up file.`);
+        }
+        return {
+            id,
+            name: group.name,
+            up: group.up,
+            ...(group.down === undefined ? {} : { down: group.down }),
+            checksum: createHash('sha256')
+                .update(JSON.stringify([group.up, group.down ?? null]))
+                .digest('hex'),
+        };
+    });
+}

package/dist/migrations/history.d.ts

@@ -0,0 +1,12 @@
+import type { PoolClient } from 'pg';
+import type { SqlMigration } from './files.js';
+export declare const migrationTable = "__tenon_migrations";
+interface AppliedMigration {
+    id: string;
+    name: string;
+    checksum: string;
+}
+export declare function migrationState(client: PoolClient, namespace: string, migrations: readonly SqlMigration[]): Promise<readonly AppliedMigration[]>;
+export declare function createHistoryTable(client: PoolClient, namespace: string): Promise<void>;
+export declare function recordMigration(client: PoolClient, namespace: string, migration: SqlMigration): Promise<void>;
+export {};