@kequtech/tenon-orm 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.2.0
+
+Changes since 0.1.0, including improvements shipped in 0.1.1–0.1.4.
+
+### Breaking changes
+
+- Tenon includes `postgres@3.4.9` as its only runtime dependency. Removed `pg`, `@types/pg`,
+  and driver peer requirements. Connections accept a PostgreSQL URI, Postgres.js options, or
+  an existing Postgres.js client.
+- Native results are row arrays with `count`, `command`, and `columns` metadata. Replace
+  `result.rows` with the result itself, `rowCount` with `count`, and `fields` with `columns`.
+  The `many`, `oneOrNone`, and `one` result modes remain available. Native error fields use
+  Postgres.js names such as `table_name` and `constraint_name`.
+- Value conversions follow Postgres.js defaults: undefined parameters reject, JSON inputs use
+  native JavaScript values, numeric arrays return strings, and timestamp infinities return
+  invalid `Date` objects. Pre-serialized JSON text becomes a JSON string.
+- Removed the `/safeql` entry point, `safeqlPlugin`, `eslintPlugin`, and their dependencies and
+  peer requirements. Tenon no longer checks or fixes SQL result annotations automatically.
+
+### Added
+
+- `describeQuery({ connection, query, session?, timeouts? })` and `tenon describe <query.sql>`
+  report PostgreSQL parameter/result types, source columns, a conservative row declaration,
+  and unresolved findings. Inspection accepts completed dynamic SQL, uses a separate session,
+  and supports explicit role, search path, timezone, and timeouts. It does not execute the query
+  or verify its TypeScript annotation. See [query inspection](docs/query-inspection.md).
+- `sql.insertValues(input, columns?)` builds inserts with database defaults for missing or
+  undefined cells. `sql.assignments(input, columns?)` builds updates that omit undefined fields.
+  Both preserve explicit null. See the [mutation cookbook](docs/mutations.md).
+- Generated `Rows.Insert['table']` and `Rows.Update['table']` types account for defaults,
+  nullability, domains, generated columns, and driver input representations.
+
+### Fixes and improvements
+
+- SQL NULL array elements remain JavaScript null; quoted `"NULL"`, escapes, nesting, and custom
+  parsers retain their meanings.
+- Transactions and migration locks reject work after connection loss. Failed recovery discards
+  the affected session, and accepted pending work finishes before transaction cleanup.
+- Transactions and standalone guarded writes issue one fewer bootstrap query by registering
+  their connection during BEGIN. Cold-start regressions cover concurrent reservations and tooling locks.
+- Large fragment composition avoids argument-spread failures. Queries reject more than 65,533
+  bound parameters before execution; batching remains application-controlled.
+- PostgreSQL `name` columns generate string types. `tenon generate --check` reports missing
+  files and a short diff for stale definitions without modifying the saved file.
+
+### Upgrading
+
+1. Remove Tenon's SafeQL imports and plugin configuration, and unused checking dependencies.
+2. Install Tenon and remove `pg`/`@types/pg` when no other code needs them. Replace pg-specific
+   connection configuration and pools with Postgres.js equivalents.
+3. Update native result/error access, pass JSON values directly, and regenerate table definitions.
+   Review numeric arrays and date validity. Use generated insert/update types for write inputs.
+4. Inspect meaningful query variants and keep database tests for complete rows, permissions,
+   ordering, write effects, and rollback. Match inspection settings to the execution session.

package/README.md

@@ -3,20 +3,20 @@
 A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
 Your coding agent already knows SQL. Tenon gives it a small API for parameterized queries,
-transactions, and migrations, with optional tooling to check SQL and generate database types. Queries
+transactions, migrations, query inspection, and generated database types. Queries
 stay readable, reusable operations are ordinary functions, and humans can review exactly what will
 run against the database.
 
 Tenon takes the place of an ORM without hiding PostgreSQL behind a query builder. You or your agent
 write the SQL; Tenon handles binding values and returning results. Your application controls the
-`pg` driver, connection configuration, and validation.
+connection configuration and validation. Tenon includes its pinned Postgres.js driver.
 
 ```sh
-npm install @kequtech/tenon-orm pg
+npm install @kequtech/tenon-orm
 ```
 
 Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and
-development typings for Node and `pg`.
+Node development typings.
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
@@ -49,6 +49,7 @@ Tenon also provides:
 - SQL migration files and a CLI to apply, inspect, and roll back migrations.
 - TypeScript row, insert, and update types generated from your database.
 - SQL fragments for sharing query parts or assembling variable conditions.
+- Query descriptions from PostgreSQL, including parameter/result types and session context.
 
 Joins, relationships, aggregates, and upserts use ordinary PostgreSQL SQL. Tenon does not introduce
 model classes or automatically load related records. Input validation, authorization, and database
@@ -68,7 +69,7 @@ migrations and table type generation are independent conveniences.
 
 For object-based writes, `sql.insertValues(rows)` preserves database defaults across heterogeneous
 rows and `sql.assignments(patch)` omits undefined fields. Keep the surrounding SQL explicit. Both
-support selected columns and [SafeQL checking](docs/reference.md#checking-mutation-fragments).
+support selected columns.
 Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
 against your schema.
 
@@ -77,29 +78,24 @@ against your schema.
 The type in `sql<{ id: number; email: string }>` describes what you expect back. TypeScript alone
 cannot verify that your SQL actually selects those columns.
 
-For that, Tenon provides an optional integration with [SafeQL](https://safeql.dev/). SafeQL checks
-SQL against your development database and can write or repair the result annotation. ESLint runs the
-check during development and CI; it is not part of query execution.
-
-Configure SafeQL in your application's ESLint setup with Tenon's `safeqlPlugin` adapter and
-`eslintPlugin` companion rule. The adapter supports queries, constant fragments, and mutation
-helpers; the rule reports queries it cannot inspect. See the
-[SQL checking setup](docs/reference.md#sql-checking-with-safeql).
-
-Checking complements typed inputs and database tests. It does not validate request values or
-arbitrary JSON, and runtime-built query variants need their own tests.
+Use `describeQuery({ connection, query })` to inspect the finished SQL, including dynamic fragments,
+or `npx tenon describe query.sql` for a SQL file. It reports PostgreSQL types, Postgres.js values,
+session context, and unresolved findings without executing the statement. No checking packages or
+compiler API are required. Keep database tests for actual values, nullability, authorization, and
+write effects; descriptions do not verify `sql<Row>`. See [query inspection](docs/query-inspection.md).
 
 ## Documentation
 
+- **[Changelog](CHANGELOG.md)** — release changes and upgrade notes.
 - **[Human guide](docs/human-guide.md)** — learn the workflow through practical examples.
 - **[Agent guide](docs/agent-guide.md)** — self-contained setup, API contracts, and implementation
   conventions.
-- **[Reference](docs/reference.md)** — complete options, SQL checking setup, type mappings, and
+- **[Reference](docs/reference.md)** — complete options, query inspection, type mappings, and
   limitations.
 - **[Adoption guide](docs/adoption-guide.md)** — replace an existing ORM and, if needed, transfer
-  migration ownership; upgrade local write helpers and adopt SQL checking incrementally.
+  migration ownership, update local write helpers, and validate converted queries.
 - **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, batching, and
-  the boundaries between input typing and SQL checking.
+  the boundaries between input typing and database validation.
 
 The complete `docs/` folder ships with the npm package. Maintainer instructions are in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md), which is not

package/dist/affected-rows.d.ts

@@ -1,4 +1,4 @@
-import type { QueryResult } from 'pg';
+import type { QueryResult } from './connection.js';
 /** PostgreSQL's final command count, independent of RETURNING. */
 export type AffectedRowsConstraint = {
     readonly max: number;

package/dist/affected-rows.js

@@ -17,14 +17,14 @@ export function validateAffectedRows(value) {
 }
 export function checkAffectedRows(constraint, result) {
     if (!['INSERT', 'UPDATE', 'DELETE', 'MERGE'].includes(result.command) ||
-        result.rowCount === null ||
-        !Number.isSafeInteger(result.rowCount) ||
-        result.rowCount < 0) {
-        throw new AffectedRowsError(constraint, result.rowCount, result.command, false);
+        result.count === null ||
+        !Number.isSafeInteger(result.count) ||
+        result.count < 0) {
+        throw new AffectedRowsError(constraint, result.count, result.command, false);
     }
     const expected = constraint.exact ?? constraint.max;
-    const matches = constraint.exact === undefined ? result.rowCount <= expected : result.rowCount === expected;
+    const matches = constraint.exact === undefined ? result.count <= expected : result.count === expected;
     if (!matches) {
-        throw new AffectedRowsError(constraint, result.rowCount, result.command, true);
+        throw new AffectedRowsError(constraint, result.count, result.command, true);
     }
 }

package/dist/baseline.d.ts

@@ -13,7 +13,7 @@ export interface CapturedBaseline {
     readonly id: string;
     readonly upPath: string;
 }
-/** Capture schema only. No source history writes, comparisons or ORM cleanup. */
+/** Capture a portable schema; deployment provisioning owns role-specific security. */
 export declare function captureBaseline(options: CaptureBaselineOptions): Promise<CapturedBaseline>;
 /** Acknowledge the saved baseline on an existing database; never execute its SQL. */
 export declare function adoptBaseline(options: DatabaseToolOptions): Promise<readonly string[]>;

package/dist/baseline.js

@@ -8,7 +8,7 @@ import { readMigrations, withMigrationCreationLock } from './migrations/files.js
 import { createHistoryTable, migrationState, migrationTable, recordMigration, } from './migrations/history.js';
 import { qualified, quote } from './sql.js';
 const run = promisify(execFile);
-/** Capture schema only. No source history writes, comparisons or ORM cleanup. */
+/** Capture a portable schema; deployment provisioning owns role-specific security. */
 export async function captureBaseline(options) {
     if (typeof options.connection !== 'string' || !options.connection.trim()) {
         throw new Error('Baseline capture requires an explicit nonempty connection string.');
@@ -82,16 +82,16 @@ export async function adoptBaseline(options) {
         if (applied.length) {
             return [];
         }
-        const schema = await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
+        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('The baseline namespace does not exist. Use migrate to initialize a fresh database.');
         }
-        await client.query('BEGIN');
+        await client.unsafe('BEGIN');
         await createHistoryTable(client, namespace);
         await recordMigration(client, namespace, baseline);
-        const result = await client.query('COMMIT');
+        const result = await client.unsafe('COMMIT');
         if (result.command !== 'COMMIT') {
             throw new Error('Baseline adoption was rolled back.');
         }

package/dist/cli.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
-import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { adoptBaseline, captureBaseline } from './baseline.js';
 import { generateDefinitions } from './generate.js';
-import { definitionDiff } from './generation/diff.js';
+import { writeDefinitions } from './generation/output.js';
+import { describeFlags, runDescribe } from './inspection/cli.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
 const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
@@ -13,43 +11,15 @@ tenon baseline capture|adopt [--directory migrations] [--namespace public]
 baseline capture: [--schema name ...] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
 tenon generate [--namespace public] [--out src/generated-schema.ts] [--check]
+tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
+describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
+describe emits JSON metadata; it does not execute the query or verify result annotations.
 rollback: --steps 1
 Connection: DATABASE_URL
 `;
 function warn(message) {
     process.stderr.write(`Warning: ${message}\n`);
 }
-/** Check without writing, or replace the complete generated file atomically. */
-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`);
-}
 async function runBaseline(action, options) {
     warn("Capture one shared baseline at the old ORM's final schema checkpoint. Each existing database must be at that checkpoint before adoption. Tenon does not compare schemas or remove the old ORM.");
     if (action === 'capture') {
@@ -74,6 +44,7 @@ async function main() {
             check: { type: 'boolean', default: false },
             steps: { type: 'string', default: '1' },
             help: { type: 'boolean', default: false },
+            ...describeFlags,
         },
     });
     if (values.help) {
@@ -84,9 +55,9 @@ async function main() {
     // Validate explicitly supplied flags, not defaults. Silently ignoring --check
     // on migrate, for example, would turn an intended dry run into a schema change.
     const allowed = new Set(['help']);
-    if (command !== 'generate')
+    if (command !== 'generate' && command !== 'describe')
         allowed.add('directory');
-    if (command !== 'new') {
+    if (command !== 'new' && command !== 'describe') {
         allowed.add('namespace');
     }
     if (command === 'generate') {
@@ -99,6 +70,10 @@ async function main() {
     if (command === 'baseline' && argument === 'capture') {
         allowed.add('schema');
     }
+    if (command === 'describe') {
+        for (const name of Object.keys(describeFlags))
+            allowed.add(name);
+    }
     for (const token of tokens) {
         if (token.kind === 'option' && !allowed.has(token.name)) {
             throw new Error(`--${token.name} is not supported by ${command ?? 'this command'}.`);
@@ -113,17 +88,21 @@ async function main() {
         return;
     }
     const baseline = command === 'baseline' && (argument === 'capture' || argument === 'adopt');
-    const valid = baseline
+    const valid = baseline || command === 'describe'
         ? positionals.length === 2
         : positionals.length === 1 &&
             ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose new, baseline capture|adopt, migrate, generate, status, or rollback. Use --help for options.');
+        throw new Error('Choose new, baseline capture|adopt, migrate, generate, describe <query.sql>, status, or rollback. Use --help for options.');
     }
     const connection = process.env.DATABASE_URL;
     if (!connection) {
         throw new Error('DATABASE_URL is required.');
     }
+    if (command === 'describe') {
+        await runDescribe(argument, connection, values);
+        return;
+    }
     const options = { connection, directory: values.directory, namespace: values.namespace };
     if (baseline) {
         await runBaseline(argument, {

package/dist/client.js

@@ -16,7 +16,7 @@ export function createClient(query, onQuery) {
         try {
             const value = await query(statement.text, statement.values, (result) => {
                 command = result.command;
-                rowCount = result.rowCount;
+                rowCount = result.count;
                 if (options.affectedRows)
                     checkAffectedRows(options.affectedRows, result);
                 return queryOutput(options, result);

package/dist/connection.d.ts

@@ -1,15 +1,20 @@
-import type { PoolClient, PoolConfig, QueryResult } from 'pg';
-import { Pool } from 'pg';
-export type Connection = string | PoolConfig | Pool;
-export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult<Record<string, unknown>>) => T, guarded: boolean) => Promise<T>;
-/** Borrow application pools; own pools created from a connection string or config. */
-export declare function createPool(connection: Connection): {
-    pool: Pool;
+import postgres from 'postgres';
+import type { UnknownRow } from './query.js';
+export type ConnectionOptions = postgres.Options<{}>;
+export type Connection = string | ConnectionOptions | postgres.Sql;
+export type QueryResult<Row extends object = UnknownRow> = postgres.RowList<Row[]>;
+/** The driver operations shared by ordinary and reserved connections. */
+export interface SqlConnection {
+    unsafe<Rows extends object[] = UnknownRow[]>(text: string, input?: postgres.ParameterOrJSON<never>[], options?: postgres.UnsafeQueryOptions & {
+        simple?: boolean;
+    }): Promise<postgres.RowList<Rows>>;
+    array: postgres.Sql['array'];
+    typed: postgres.Sql['typed'];
+}
+export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult) => T, guarded: boolean) => Promise<T>;
+/** Own clients created from a URI/config; borrow explicitly supplied Postgres.js clients. */
+export declare function createConnection(connection: Connection): {
+    sql: postgres.Sql;
     owned: boolean;
 };
-/** Observe failures between queries until ownership returns to the pool. */
-export declare function watchClient(client: PoolClient): {
-    check(): void;
-    release(error?: Error): void;
-};
-export declare function executeSql(connection: Pool | PoolClient, text: string, input: readonly unknown[]): Promise<QueryResult<Record<string, unknown>>>;
+export declare function executeSql(sql: SqlConnection, text: string, input?: readonly unknown[]): Promise<QueryResult>;

package/dist/connection.js

@@ -1,51 +1,22 @@
-import { Pool } from 'pg';
+import postgres from 'postgres';
 import { plainObject } from './validation.js';
-/** Borrow application pools; own pools created from a connection string or config. */
-export function createPool(connection) {
-    if (connection instanceof Pool) {
-        return { pool: connection, owned: false };
+/** Own clients created from a URI/config; borrow explicitly supplied Postgres.js clients. */
+export function createConnection(connection) {
+    if (typeof connection === 'function' && typeof connection.unsafe === 'function') {
+        return { sql: connection, owned: false };
     }
-    // Missing configuration must not silently select pg's environment defaults.
-    // An explicit config object (including {}) may still use those defaults.
     if (typeof connection === 'string') {
         if (!connection.trim())
             throw new Error('Connection string must not be empty.');
+        return { sql: postgres(connection), owned: true };
     }
-    else {
-        plainObject(connection, 'Connection configuration');
-    }
-    const config = typeof connection === 'string' ? { connectionString: connection } : connection;
-    const pool = new Pool(config);
-    // pg removes broken idle clients itself, but an unhandled pool error would
-    // still terminate Node. Borrowed pools keep their application's error policy.
-    pool.on('error', (error) => process.emitWarning(error));
-    return { pool, owned: true };
-}
-/** Observe failures between queries until ownership returns to the pool. */
-export function watchClient(client) {
-    let failure;
-    const onError = (error) => {
-        failure ??= error;
-    };
-    client.on('error', onError);
-    return {
-        check() {
-            if (failure) {
-                throw failure;
-            }
-        },
-        release(error) {
-            try {
-                client.release(error ?? failure);
-            }
-            finally {
-                client.removeListener('error', onError);
-            }
-        },
-    };
+    plainObject(connection, 'Connection configuration');
+    return { sql: postgres(connection), owned: true };
 }
-export function executeSql(connection, text, input) {
-    // Extended protocol makes even a zero-parameter call one SQL statement.
-    const config = { text, values: [...input], queryMode: 'extended' };
-    return connection.query(config);
+export function executeSql(sql, text, input = []) {
+    // Tenon compiles SQL separately from values; let PostgreSQL infer array/JSON types from the surrounding SQL.
+    const values = input.map((value) => (Array.isArray(value) ? sql.typed(value, 0) : value));
+    // Keep preparation off; CONSIDERATIONS.md records parser-cache and pipeline safety constraints.
+    const options = { simple: false, prepare: false };
+    return sql.unsafe(text, values, options);
 }

package/dist/database.js

@@ -1,5 +1,6 @@
 import { createClient } from './client.js';
-import { createPool, executeSql } from './connection.js';
+import { createConnection, executeSql } from './connection.js';
+import { prepareArrays } from './driver/array.js';
 import { withTransaction } from './transaction.js';
 import { plainObject } from './validation.js';
 export function createTenon(options) {
@@ -11,7 +12,7 @@ export function createTenon(options) {
     if (options.onQuery !== undefined && typeof options.onQuery !== 'function') {
         throw new Error('onQuery must be a function.');
     }
-    const { pool, owned } = createPool(options.connection);
+    const { sql: pool, owned } = createConnection(options.connection);
     let closed = false;
     function checkOpen() {
         if (closed) {
@@ -23,6 +24,7 @@ export function createTenon(options) {
         if (guarded) {
             return withTransaction(pool, (query) => query(text, input, readResult, false));
         }
+        await prepareArrays(pool);
         return readResult(await executeSql(pool, text, input));
     };
     return {

package/dist/describe.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeOptions, QueryDescription } from './inspection/types.js';
+/** Describe finished SQL without binding values or executing the inspected statement. */
+export declare function describeQuery(options: DescribeOptions): Promise<QueryDescription>;

package/dist/describe.js

@@ -0,0 +1,21 @@
+import { readStatementMetadata } from './inspection/catalog.js';
+import { withInspectionConnection } from './inspection/connection.js';
+import { queryDescription } from './inspection/result.js';
+import { plainObject } from './validation.js';
+/** Describe finished SQL without binding values or executing the inspected statement. */
+export async function describeQuery(options) {
+    const input = plainObject(options, 'Describe options');
+    for (const key of Object.keys(input)) {
+        if (!['connection', 'query', 'session', 'timeouts'].includes(key)) {
+            throw new Error(`Unknown Describe option: ${key}`);
+        }
+    }
+    let text = input.query;
+    if (text !== null && typeof text === 'object' && 'text' in text)
+        text = text.text;
+    if (typeof text !== 'string' || !text.trim()) {
+        throw new Error('Describe query requires nonempty SQL text or a query object with text.');
+    }
+    const query = text;
+    return withInspectionConnection(options, async (client, context) => queryDescription(await readStatementMetadata(client, query), context));
+}

package/dist/driver/array.d.ts

@@ -0,0 +1,5 @@
+import type postgres from 'postgres';
+/** Preserve driver scalar parsers and serializers; replace only lossy array parsing. */
+export declare function prepareArrays(sql: postgres.Sql): Promise<void>;
+/** PostgreSQL text arrays: only unquoted NULL is null; quoted values use the scalar parser. */
+export declare function parseArray(text: string, parse: (value: string) => unknown, delimiter?: string): unknown[];

package/dist/driver/array.js

@@ -0,0 +1,70 @@
+const initialization = new WeakMap();
+/** Preserve driver scalar parsers and serializers; replace only lossy array parsing. */
+export function prepareArrays(sql) {
+    const existing = initialization.get(sql);
+    if (existing)
+        return existing;
+    const ready = (async () => {
+        const customArrays = new Set(Object.values(sql.options.types).flatMap((type) => type.from));
+        const arrays = await sql `
+      SELECT t.typarray AS oid, t.oid AS element, t.typdelim AS delimiter
+      FROM pg_catalog.pg_type t WHERE t.typarray <> 0`;
+        for (const type of arrays) {
+            if (customArrays.has(type.oid))
+                continue;
+            const scalar = sql.options.parsers[type.element] ?? ((value) => value);
+            sql.options.parsers[type.oid] = (value) => parseArray(value, scalar, type.delimiter);
+        }
+    })();
+    initialization.set(sql, ready);
+    void ready.catch(() => initialization.delete(sql));
+    return ready;
+}
+/** PostgreSQL text arrays: only unquoted NULL is null; quoted values use the scalar parser. */
+export function parseArray(text, parse, delimiter = ',') {
+    let position = text.startsWith('[') ? text.indexOf('=') + 1 : 0;
+    function array() {
+        if (text[position++] !== '{')
+            throw new Error('Invalid PostgreSQL array.');
+        const values = [];
+        while (position < text.length && text[position] !== '}') {
+            if (text[position] === '{')
+                values.push(array());
+            else {
+                let value = '';
+                const quoted = text[position] === '"';
+                if (quoted)
+                    position++;
+                while (position < text.length) {
+                    const char = text[position];
+                    if (char === '\\') {
+                        position++;
+                        value += text[position++] ?? '';
+                    }
+                    else if (quoted && char === '"') {
+                        position++;
+                        break;
+                    }
+                    else if (!quoted && (char === delimiter || char === '}'))
+                        break;
+                    else {
+                        value += char;
+                        position++;
+                    }
+                }
+                values.push(!quoted && value === 'NULL' ? null : parse(value));
+            }
+            if (text[position] === delimiter)
+                position++;
+            else if (text[position] !== '}')
+                throw new Error('Invalid PostgreSQL array separator.');
+        }
+        if (text[position++] !== '}')
+            throw new Error('Unterminated PostgreSQL array.');
+        return values;
+    }
+    const result = array();
+    if (position !== text.length)
+        throw new Error('Unexpected PostgreSQL array suffix.');
+    return result;
+}

package/dist/driver/lifecycle.d.ts

@@ -0,0 +1,15 @@
+import type postgres from 'postgres';
+export interface Watch {
+    failure?: Error;
+    check(): void;
+    closed: Promise<never>;
+    reject(error: Error): void;
+}
+interface State {
+    acquiring: Set<(error: Error) => void>;
+    active: Map<number, Watch>;
+    capture(marker: string, watch: Watch): () => void;
+}
+/** Observe the driver's public connection callbacks; never reuse a reconnected transaction. */
+export declare function observeConnections(sql: postgres.Sql): State;
+export {};

package/dist/driver/lifecycle.js

@@ -0,0 +1,57 @@
+const states = new WeakMap();
+function disconnected() {
+    return Object.assign(new Error('The reserved PostgreSQL connection closed.'), {
+        code: 'CONNECTION_CLOSED',
+    });
+}
+/** Observe the driver's public connection callbacks; never reuse a reconnected transaction. */
+export function observeConnections(sql) {
+    const previous = states.get(sql);
+    if (previous)
+        return previous;
+    const markers = new Map();
+    let debug = sql.options.debug;
+    // Capture the bootstrap connection ID, then restore debug before application work.
+    // Leaving it enabled would make the driver include SQL and values in enumerable errors.
+    const captureDebug = (id, text, values, types) => {
+        const watch = markers.get(text);
+        if (watch) {
+            state.active.set(id, watch);
+            markers.delete(text);
+        }
+        if (!markers.size)
+            sql.options.debug = debug;
+        if (typeof debug === 'function')
+            debug(id, text, values, types);
+    };
+    const state = {
+        acquiring: new Set(),
+        active: new Map(),
+        capture(marker, watch) {
+            if (!markers.size) {
+                debug = sql.options.debug;
+                sql.options.debug = captureDebug;
+            }
+            markers.set(marker, watch);
+            return () => {
+                markers.delete(marker);
+                if (!markers.size)
+                    sql.options.debug = debug;
+            };
+        },
+    };
+    const onclose = sql.options.onclose;
+    sql.options.onclose = (id) => {
+        const error = disconnected();
+        const watch = state.active.get(id);
+        if (watch) {
+            watch.failure ??= error;
+            watch.reject(watch.failure);
+        }
+        for (const reject of state.acquiring)
+            reject(error);
+        onclose?.(id);
+    };
+    states.set(sql, state);
+    return state;
+}