@kequtech/tenon-orm 0.1.4 → 0.2.0

package/dist/driver/session.d.ts

@@ -0,0 +1,8 @@
+import type postgres from 'postgres';
+import type { SqlConnection } from '../connection.js';
+/** Pin a healthy session for transactions and advisory locks, with explicit failure cleanup. */
+export declare function reserveConnection(sql: postgres.Sql, initial?: 'SELECT 1' | 'BEGIN'): Promise<{
+    sql: SqlConnection;
+    check: () => void;
+    release(discard?: boolean): Promise<void>;
+}>;

package/dist/driver/session.js

@@ -0,0 +1,92 @@
+import { prepareArrays } from './array.js';
+import { observeConnections } from './lifecycle.js';
+let nextLease = 0;
+/** Pin a healthy session for transactions and advisory locks, with explicit failure cleanup. */
+export async function reserveConnection(sql, initial = 'SELECT 1') {
+    await prepareArrays(sql);
+    const state = observeConnections(sql);
+    // Warm a connection before reserve(): 3.4.9 can strand a cold reserve after reconnect.
+    await sql `SELECT 1`;
+    let abandoned = false;
+    let rejectAcquisition;
+    const closed = new Promise((_, reject) => {
+        rejectAcquisition = reject;
+    });
+    state.acquiring.add(rejectAcquisition);
+    const pending = sql.reserve();
+    void pending.then((client) => {
+        if (abandoned)
+            client.release();
+    }, () => { });
+    let client;
+    try {
+        client = await Promise.race([pending, closed]);
+    }
+    catch (error) {
+        abandoned = true;
+        throw error;
+    }
+    finally {
+        state.acquiring.delete(rejectAcquisition);
+    }
+    let rejectClosed;
+    const closedSession = new Promise((_, reject) => {
+        rejectClosed = reject;
+    });
+    void closedSession.catch(() => { });
+    const watch = {
+        closed: closedSession,
+        reject: rejectClosed,
+        check() {
+            if (watch.failure)
+                throw watch.failure;
+        },
+    };
+    const safe = {
+        async unsafe(text, input = [], options) {
+            watch.check();
+            // Driver dispatch runs in the next microtask, before another socket event.
+            const query = client.unsafe(text, input, options).execute();
+            return Promise.race([query, watch.closed]);
+        },
+        array: client.array,
+        typed: client.typed,
+    };
+    const connection = {
+        sql: safe,
+        check: watch.check,
+        async release(discard = false) {
+            for (const [id, active] of state.active)
+                if (active === watch)
+                    state.active.delete(id);
+            if (watch.failure)
+                return; // The driver already removed the closed session.
+            if (discard) {
+                // Failed recovery must not return an unknown transaction/lock state to the pool.
+                try {
+                    await client.unsafe('SELECT pg_terminate_backend(pg_backend_pid())').execute();
+                }
+                catch {
+                    /* The backend closes itself. */
+                }
+                return;
+            }
+            client.release();
+        },
+    };
+    // Capture the connection on BEGIN itself when opening a transaction.
+    const marker = `${initial} /* tenon_session_${++nextLease} */`;
+    const stopCapture = state.capture(marker, watch);
+    try {
+        await safe.unsafe(marker, [], { simple: false, prepare: false });
+        watch.check();
+        return connection;
+    }
+    catch (error) {
+        await connection.release(true);
+        throw error;
+    }
+    finally {
+        stopCapture();
+    }
+}

package/dist/driver/types.d.ts

@@ -0,0 +1,10 @@
+/** Postgres.js default representations (with SQL NULL array elements preserved), shared by generation and query inspection. */
+export type ValueTypes = Readonly<{
+    read: string;
+    write: string;
+}>;
+type TypeMapping = string | ValueTypes;
+export declare const arrayTypes: Readonly<Record<string, TypeMapping>>;
+export declare const scalarTypes: Readonly<Record<string, TypeMapping>>;
+export declare function valueTypes(mapping: TypeMapping): ValueTypes;
+export {};

package/dist/driver/types.js

@@ -0,0 +1,49 @@
+// Arrays use verified built-in OIDs: their parsers can differ from scalar parsers.
+export const arrayTypes = {
+    '1000': 'boolean',
+    '1001': 'import("node:buffer").Buffer',
+    '1005': 'number',
+    '1007': 'number',
+    '1021': 'number',
+    '1022': 'number',
+    '1028': 'number',
+    '1016': { read: 'string', write: 'string | bigint' },
+    '1231': { read: 'string', write: 'string | number' },
+    '1009': 'string',
+    '1014': 'string',
+    '1015': 'string',
+    '1183': 'string',
+    '1270': 'string',
+    '2951': 'string',
+    '1182': { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    '1115': { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    '1185': { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    '199': { read: 'unknown', write: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
+    '3807': { read: 'unknown', write: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
+};
+export const scalarTypes = {
+    int2: 'number',
+    int4: 'number',
+    oid: 'number',
+    float4: 'number',
+    float8: 'number',
+    bool: 'boolean',
+    text: 'string',
+    name: 'string',
+    varchar: 'string',
+    bpchar: 'string',
+    time: 'string',
+    timetz: 'string',
+    uuid: 'string',
+    date: { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    timestamp: { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    timestamptz: { read: 'globalThis.Date', write: 'globalThis.Date | string' },
+    int8: { read: 'string', write: 'string | bigint' },
+    numeric: { read: 'string', write: 'string | number' },
+    json: { read: 'unknown', write: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
+    jsonb: { read: 'unknown', write: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
+    bytea: 'import("node:buffer").Buffer',
+};
+export function valueTypes(mapping) {
+    return typeof mapping === 'string' ? { read: mapping, write: mapping } : mapping;
+}

package/dist/generate.js

@@ -7,17 +7,17 @@ import { quote } from './sql.js';
 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', [
+        await client.unsafe('BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY');
+        const schema = await client.unsafe('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
             namespace,
         ]);
-        if (!schema.rows.length)
+        if (!schema.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');
+        await client.unsafe(`SET LOCAL search_path TO pg_catalog, ${quote(namespace)}`);
+        await client.unsafe('SET LOCAL quote_all_identifiers TO off');
+        await client.unsafe('SET LOCAL standard_conforming_strings TO on');
         const definitions = await readTables(client, namespace);
         const summaries = [];
         for (const table of definitions) {
@@ -25,7 +25,7 @@ export async function generateDefinitions(options) {
         }
         const domains = await domainSummaries(client, definitions.flatMap((table) => table.columns.map((column) => column.declaredOid)));
         const types = renderTableTypes(definitions, namespace, onWarning);
-        await client.query('COMMIT');
+        await client.unsafe('COMMIT');
         return `// Generated by Tenon from the PostgreSQL schema. Do not edit.
 // Commit this file and regenerate it after changing the schema.
 

package/dist/generation/catalog.d.ts

@@ -1,4 +1,4 @@
-import type { PoolClient } from 'pg';
+import type { SqlConnection } from '../connection.js';
 export interface ColumnRow {
     name: string;
     oid: string;
@@ -19,4 +19,4 @@ export interface TableRow {
     name: string;
     columns: ColumnRow[];
 }
-export declare function readTables(client: PoolClient, namespace: string): Promise<TableRow[]>;
+export declare function readTables(client: SqlConnection, namespace: string): Promise<TableRow[]>;

package/dist/generation/catalog.js

@@ -1,15 +1,15 @@
 import { migrationTable } from '../migrations/history.js';
 export async function readTables(client, namespace) {
-    const tables = await client.query(`
+    const tables = await client.unsafe(`
       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) {
+    for (const table of tables) {
         // Attached descendants are storage details, not separate generated models.
-        const columns = await client.query(`
+        const columns = await client.unsafe(`
         WITH RECURSIVE resolved AS (
           SELECT a.attnum, t.oid, t.typbasetype, t.typnotnull AS domain_not_null
           FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
@@ -32,7 +32,7 @@ export async function readTables(client, namespace) {
           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 });
+        definitions.push({ ...table, columns: columns });
     }
     return definitions;
 }

package/dist/generation/output.d.ts

@@ -0,0 +1,2 @@
+/** Check without writing, or replace the complete generated file atomically. */
+export declare function writeDefinitions(source: string, filename: string, check: boolean): Promise<void>;

package/dist/generation/output.js

@@ -0,0 +1,35 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { definitionDiff } from './diff.js';
+/** Check without writing, or replace the complete generated file atomically. */
+export async function writeDefinitions(source, filename, check) {
+    const output = resolve(filename);
+    if (check) {
+        let existing;
+        try {
+            existing = await readFile(output, 'utf8');
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+                throw error;
+            }
+            throw new Error(`Generated definitions file is missing: ${output}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
+        }
+        if (existing !== source) {
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
+        }
+        process.stdout.write('Generated definitions are current.\n');
+        return;
+    }
+    await mkdir(dirname(output), { recursive: true });
+    const temporary = `${output}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, source, 'utf8');
+        await rename(temporary, output);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    process.stdout.write(`Generated ${output}\n`);
+}

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

@@ -1,6 +1,6 @@
-import type { PoolClient } from 'pg';
+import type { SqlConnection } from '../connection.js';
 /** Include only domains reached through selected columns, base domains or arrays. */
-export declare function domainSummaries(client: PoolClient, typeOids: readonly string[]): Promise<string[]>;
+export declare function domainSummaries(client: SqlConnection, 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 tableSummary(client: SqlConnection, oid: string, name: string): Promise<string>;
 export declare function schemaSummary(summaries: readonly string[]): string;

package/dist/generation/schema-summary.js

@@ -1,7 +1,7 @@
 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(`
+    const domains = await client.unsafe(`
     WITH RECURSIVE referenced(oid) AS (
       SELECT unnest($1::oid[])
       UNION
@@ -16,10 +16,10 @@ export async function domainSummaries(client, typeOids) {
     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]);
+    ORDER BY pg_catalog.format_type(t.oid, NULL) COLLATE "C"`, [client.array([...typeOids])]);
     const summaries = [];
-    for (const domain of domains.rows) {
-        const constraints = await client.query(`
+    for (const domain of domains) {
+        const constraints = await client.unsafe(`
       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]);
@@ -28,14 +28,14 @@ export async function domainSummaries(client, typeOids) {
                 (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}`),
+            ...constraints.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(`
+    const columns = await client.unsafe(`
     SELECT a.attname AS name,
       pg_catalog.format_type(a.atttypid, a.atttypmod)
       || CASE WHEN a.attnotnull THEN ' NOT NULL' ELSE '' END
@@ -63,12 +63,12 @@ export async function tableSummary(client, oid, name) {
     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(`
+    const constraints = await client.unsafe(`
     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(`
+    const indexes = await client.unsafe(`
     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,
@@ -83,9 +83,9 @@ export async function tableSummary(client, oid, name) {
     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) => {
+        ...columns.map((column) => `  ${quote(column.name)} ${column.definition}`),
+        ...constraints.map((constraint) => `  CONSTRAINT ${quote(constraint.name)} ${constraint.definition}`),
+        ...indexes.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;

package/dist/generation/table-types.js

@@ -1,3 +1,4 @@
+import { arrayTypes, scalarTypes, valueTypes } from '../driver/types.js';
 // 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
@@ -12,57 +13,6 @@ const reservedTypeNames = new Set(`
 function canExportRowName(name) {
     return (/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(name) && !reservedTypeNames.has(name));
 }
-// A string means the read and write representations match. Arrays use verified
-// built-in OIDs because their parsers can differ from scalar parsers (numeric[]).
-const arrayTypes = {
-    '1000': 'boolean',
-    '1001': 'import("node:buffer").Buffer',
-    '1005': 'number',
-    '1007': 'number',
-    '1021': 'number',
-    '1022': 'number',
-    '1028': 'number',
-    '1016': { read: 'string', write: 'string | bigint' },
-    '1231': { read: 'number', write: 'string | number' },
-    '1009': 'string',
-    '1014': 'string',
-    '1015': 'string',
-    '1183': 'string',
-    '1270': 'string',
-    '2951': 'string',
-    '1182': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    '1115': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    '1185': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    '199': { read: 'unknown', write: 'string' },
-    '3807': { read: 'unknown', write: 'string' },
-};
-const scalarTypes = {
-    int2: 'number',
-    int4: 'number',
-    oid: 'number',
-    float4: 'number',
-    float8: 'number',
-    bool: 'boolean',
-    text: 'string',
-    name: 'string',
-    varchar: 'string',
-    bpchar: 'string',
-    time: 'string',
-    timetz: 'string',
-    uuid: 'string',
-    // pg returns +/-Infinity as numbers. TypeScript has no infinity literal type.
-    date: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    timestamp: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    timestamptz: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
-    int8: { read: 'string', write: 'string | bigint' },
-    numeric: { read: 'string', write: 'string | number' },
-    json: { read: 'unknown', write: 'string' },
-    jsonb: { read: 'unknown', write: 'string' },
-    bytea: 'import("node:buffer").Buffer',
-};
-function valueTypes(mapping) {
-    return typeof mapping === 'string' ? { read: mapping, write: mapping } : mapping;
-}
 function isSupportedArray(value) {
     return Object.hasOwn(arrayTypes, value.oid);
 }
@@ -87,7 +37,7 @@ function columnTypes(value, column, onWarning) {
             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 for reads and never for non-null writes.`);
+            onWarning(`Column ${column} uses PostgreSQL type ${JSON.stringify(value.declaredSchema)}.${JSON.stringify(value.declaredType)} (OID ${value.declaredOid})${underlying} without a verified Postgres.js mapping; generated as unknown for reads and never for non-null writes.`);
             types = { read: 'unknown', write: 'never' };
         }
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export type { QueryResult } from 'pg';
+export type { JSONValue } from 'postgres';
+export type { Connection, ConnectionOptions, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
 export type { TenonOptions } from './database.js';
@@ -7,6 +8,8 @@ export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options
 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 { describeQuery } from './describe.js';
+export type { DescribeOptions, DescribedColumn, DescribedType, DescriptionIssue, InspectionContext, InspectionSession, InspectionTimeouts, QueryDescription, } from './inspection/types.js';
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';

package/dist/index.js

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

package/dist/inspection/catalog.d.ts

@@ -0,0 +1,25 @@
+import type postgres from 'postgres';
+interface CatalogType {
+    oid: number;
+    schema: string;
+    name: string;
+    kind: string;
+    base: number;
+    choices: string[] | null;
+}
+interface ColumnSource {
+    oid: number;
+    number: number;
+    schema: string;
+    table: string;
+    column: string;
+    notNull: boolean;
+}
+export interface StatementMetadata {
+    statement: postgres.Statement;
+    types: readonly CatalogType[];
+    sources: readonly ColumnSource[];
+}
+/** Describe the statement and read its type and source-column catalog records. */
+export declare function readStatementMetadata(client: postgres.Sql, text: string): Promise<StatementMetadata>;
+export {};

package/dist/inspection/catalog.js

@@ -0,0 +1,29 @@
+/** Describe the statement and read its type and source-column catalog records. */
+export async function readStatementMetadata(client, text) {
+    const statement = await client.unsafe(text, [], { prepare: true }).describe();
+    const oids = [...new Set([...statement.types, ...statement.columns.map((c) => c.type)])];
+    const types = await client `
+    WITH RECURSIVE wanted(oid) AS (
+      SELECT unnest(string_to_array(${oids.join(',')}, ',')::oid[])
+      UNION
+      SELECT t.typbasetype FROM pg_catalog.pg_type t JOIN wanted w ON w.oid = t.oid
+        WHERE t.typbasetype <> 0
+    )
+    SELECT t.oid, n.nspname AS schema, t.typname AS name,
+      t.typtype AS kind, t.typbasetype AS base,
+      (SELECT to_json(array_agg(e.enumlabel::text ORDER BY e.enumsortorder))
+        FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS choices
+    FROM wanted w JOIN pg_catalog.pg_type t ON t.oid = w.oid
+      JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+  `;
+    const tables = [...new Set(statement.columns.map((c) => c.table).filter(Boolean))];
+    const sources = await client `
+    SELECT c.oid, a.attnum AS number, n.nspname AS schema,
+      c.relname AS table, a.attname AS column, a.attnotnull AS "notNull"
+    FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+      JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.oid = ANY(string_to_array(${tables.join(',')}, ',')::oid[])
+      AND a.attnum > 0 AND NOT a.attisdropped
+  `;
+    return { statement, types, sources };
+}

package/dist/inspection/cli.d.ts

@@ -0,0 +1,22 @@
+export declare const describeFlags: {
+    readonly role: {
+        readonly type: "string";
+    };
+    readonly 'search-path': {
+        readonly type: "string";
+    };
+    readonly 'time-zone': {
+        readonly type: "string";
+    };
+    readonly 'connect-timeout-ms': {
+        readonly type: "string";
+    };
+    readonly 'statement-timeout-ms': {
+        readonly type: "string";
+    };
+    readonly 'lock-timeout-ms': {
+        readonly type: "string";
+    };
+};
+/** Translate CLI flags; validation and defaults belong to the public API. */
+export declare function runDescribe(filename: string, connection: string, values: Partial<Record<keyof typeof describeFlags, string | undefined>>): Promise<void>;

package/dist/inspection/cli.js

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { describeQuery } from '../describe.js';
+export const describeFlags = {
+    role: { type: 'string' },
+    'search-path': { type: 'string' },
+    'time-zone': { type: 'string' },
+    'connect-timeout-ms': { type: 'string' },
+    'statement-timeout-ms': { type: 'string' },
+    'lock-timeout-ms': { type: 'string' },
+};
+/** Translate CLI flags; validation and defaults belong to the public API. */
+export async function runDescribe(filename, connection, values) {
+    const result = await describeQuery({
+        connection,
+        query: await readFile(filename, 'utf8'),
+        session: {
+            ...(values.role !== undefined ? { role: values.role } : {}),
+            ...(values['search-path'] !== undefined ? { searchPath: values['search-path'] } : {}),
+            ...(values['time-zone'] !== undefined ? { timeZone: values['time-zone'] } : {}),
+        },
+        timeouts: {
+            ...(values['connect-timeout-ms'] !== undefined
+                ? { connectMs: Number(values['connect-timeout-ms']) }
+                : {}),
+            ...(values['statement-timeout-ms'] !== undefined
+                ? { statementMs: Number(values['statement-timeout-ms']) }
+                : {}),
+            ...(values['lock-timeout-ms'] !== undefined
+                ? { lockMs: Number(values['lock-timeout-ms']) }
+                : {}),
+        },
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/dist/inspection/connection.d.ts

@@ -0,0 +1,4 @@
+import postgres from 'postgres';
+import type { DescribeOptions, InspectionContext } from './types.js';
+/** Bound every database statement, including bootstrap and metadata queries. */
+export declare function withInspectionConnection<T>(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>, work: (client: postgres.Sql, context: InspectionContext) => Promise<T>): Promise<T>;

package/dist/inspection/connection.js

@@ -0,0 +1,44 @@
+import postgres from 'postgres';
+import { prepareArrays } from '../driver/array.js';
+import { inspectionOptions } from './options.js';
+/** Bound every database statement, including bootstrap and metadata queries. */
+export async function withInspectionConnection(options, work) {
+    const { url, limits, session } = inspectionOptions(options);
+    const client = postgres(url.toString(), {
+        max: 1,
+        connect_timeout: limits.connectMs / 1000,
+        // The inspector reads its own metadata; avoid an implicit array-catalog fetch.
+        fetch_types: false,
+        onnotice() { },
+    });
+    try {
+        await client `SELECT
+      set_config('statement_timeout', ${String(limits.statementMs)}, false),
+      set_config('lock_timeout', ${String(limits.lockMs)}, false)`;
+        await prepareArrays(client);
+        for (const [key, name] of [
+            ['role', 'role'],
+            ['searchPath', 'search_path'],
+            ['timeZone', 'TimeZone'],
+        ]) {
+            const value = session[key];
+            if (value !== undefined)
+                await client `SELECT set_config(${name}, ${value}, false)`;
+        }
+        const [context] = await client `
+      SELECT current_database() AS database, session_user AS "sessionUser",
+        current_user AS "currentUser", current_setting('search_path') AS "searchPath",
+        to_json(current_schemas(true)) AS "resolvedSearchPath",
+        current_setting('TimeZone') AS "timeZone",
+        (SELECT setting::integer FROM pg_catalog.pg_settings WHERE name='statement_timeout') AS "statementTimeoutMs",
+        (SELECT setting::integer FROM pg_catalog.pg_settings WHERE name='lock_timeout') AS "lockTimeoutMs"
+    `;
+        if (!context)
+            throw new Error('Inspection context was not returned.');
+        return await work(client, { mode: 'separate-session', readMappings: 'postgres', ...context });
+    }
+    finally {
+        // Bound cleanup as well; never leave an unbounded end() after a server/network failure.
+        await client.end({ timeout: 1 });
+    }
+}

package/dist/inspection/options.d.ts

@@ -0,0 +1,15 @@
+import type { DescribeOptions } from './types.js';
+/** Validate and capture caller-owned settings before opening a connection. */
+export declare function inspectionOptions(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>): {
+    url: URL;
+    limits: {
+        connectMs: number;
+        statementMs: number;
+        lockMs: number;
+    };
+    session: {
+        role?: string;
+        searchPath?: string;
+        timeZone?: string;
+    };
+};