@kequtech/tenon-orm 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.0
+
+- **Breaking:** `pg@8.23.1` replaces Postgres.js. Use pg `PoolConfig` (`connectionString` for a URI)
+  or `pg.Pool`; removed `{ url, options }` and `ConnectionUri`. `db.native` is the actual pool;
+  results use `rows`, `rowCount`, and `fields`, and error fields use pg names (`table`,
+  `constraint`). Native LISTEN uses checked-out clients with application-owned resubscription.
+- Driver defaults apply, including no acquisition timeout and SQL null for bound `undefined`. The
+  parameter ceiling now matches PostgreSQL's 65,535 limit.
+- Regenerate types: temporal reads include numeric infinities, date-only values use Node's local
+  timezone, and numeric arrays contain numbers that can lose precision. JSON write inputs are
+  encoded strings; use `JSON.stringify`, especially for arrays and strings. Removed `JSONValue`.
+
+## 0.2.2
+
+- Closing a Tenon-owned client through `db.close()` prevents native LISTEN reconnects from restoring
+  connections after shutdown, including pending subscription setup. Borrowed clients retain
+  application ownership.
+- Added `connection: { url, options? }` to preserve a deployment URI while configuring the native
+  driver. `ConnectionUri` is exported; `ConnectionOptions` includes the pinned driver's constructor
+  `onnotify` callback. Internally created clients remain Tenon-owned.
+- Inspection accepts explicit `undefined` for optional session and timeout settings, including in
+  strict TypeScript configurations; unknown keys and invalid defined values still fail.
+- `db.close({ timeoutMs? })` now shares one shutdown outcome across concurrent/later callers and
+  defaults to a 5,000 ms grace period before requesting owned driver termination; `0` skips the
+  wait.
+- Added `CardinalityError` for `one`/`oneOrNone` mismatches, with code `TENON_CARDINALITY_MISMATCH`,
+  expected mode, actual count, and optional label.
+
 ## 0.2.1
 
 - Added readonly `db.native` access to Tenon's existing Postgres.js client for LISTEN, cursors,
@@ -14,29 +42,29 @@ 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.
+- 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.
+  `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).
+  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.
 
@@ -44,21 +72,9 @@ Changes since 0.1.0, including improvements shipped in 0.1.1–0.1.4.
 
 - 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.
+- Transactions and migration locks reject work after connection loss. Failed recovery discards the
+  affected session, and accepted pending work finishes before transaction cleanup.
+- 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.

package/README.md

@@ -2,21 +2,16 @@
 
 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, 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
-connection configuration and validation. Tenon includes its pinned Postgres.js driver.
+Write SQL directly, bind values with a template tag, and reuse queries through ordinary functions.
+Tenon provides transactions, affected-row guards, SQL migrations, generated database types, and
+query inspection. It includes its pinned pg driver.
 
 ```sh
 npm install @kequtech/tenon-orm
 ```
 
-Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and
-Node development typings.
+Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
+development typings.
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
@@ -39,70 +34,32 @@ try {
 }
 ```
 
-This standalone example assumes the table exists. In a server, reuse an instance per database and
-close it at shutdown, not after each request. Use `returns: 'many'` for an array, `'one'` when a row
-must exist, or omit the option for the driver's full result.
-
-Use [`db.native`](docs/reference.md#native-driver-access) to access the underlying Postgres.js client
-for LISTEN, cursors, COPY, and other native features without installing another driver. Native calls
-use the pool directly and bypass Tenon's query and transaction guards.
-
-Tenon also provides:
-
-- Transactions and affected-row limits that roll back rejected writes.
-- 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
-performance remain application concerns. You can keep an existing migration runner; Tenon's
-migrations and table type generation are independent conveniences.
-
-## Here's what a coding agent says about it
+The example assumes `public.users` exists. In a server, reuse the instance and close it at shutdown.
+`oneOrNone` rejects multiple rows; use `one` for exactly one row, `many` for an array, or omit
+`returns` for the driver's result object and metadata.
 
-> "The appeal is that I can read the query, see where the transaction starts and ends, and put
-> reusable logic in a function. There isn't much framework machinery to learn. The tradeoff is that
-> someone still has to write the SQL and check the result types. I'm happy to do that part. Please
-> still review my SQL."
->
-> — Codex, after working on Tenon. An interested party, to put it mildly.
+Joins, relationships, aggregates, and upserts use PostgreSQL SQL. Object-based writes can use
+`sql.insertValues` and `sql.assignments` while keeping the surrounding statement explicit.
+`db.native` exposes the underlying `pg.Pool` for LISTEN, cursors, COPY, and other driver features;
+those calls bypass Tenon's query and transaction guards.
 
-## Object-based writes
-
-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.
-Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
-against your schema.
-
-## Checking query results
-
-The type in `sql<{ id: number; email: string }>` describes what you expect back. TypeScript alone
-cannot verify that your SQL actually selects those columns.
-
-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).
+`sql<Row>` declares an expected result type. `describeQuery` inspects the finished SQL through
+PostgreSQL without executing it; it does not verify that annotation. Keep database tests for actual
+rows and write effects. Validation, authorization, and retry policy belong to the application.
+Existing migration runners can be retained; Tenon's migrations and type generation are optional.
 
 ## 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, query inspection, type mappings, and
-  limitations.
-- **[Adoption guide](docs/adoption-guide.md)** — replace an existing ORM and, if needed, transfer
-  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 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
-bundled.
+- **[Human guide](docs/human-guide.md)** — a table, queries, transactions, and generated types.
+- **[Agent guide](docs/agent-guide.md)** — implementation contracts and upgrade workflow.
+- **[Reference](docs/reference.md)** — API options, value mappings, CLI, and limitations.
+- **[Adoption guide](docs/adoption-guide.md)** — replace an ORM and transfer migration ownership.
+- **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, and batching.
+- **[Query inspection](docs/query-inspection.md)** — Describe reports and database tests.
+- **[Changelog](CHANGELOG.md)** — versioned changes and upgrade instructions.
+
+These documents all ship with the npm package, including the changelog so an agent upgrading a
+project can read the relevant release entries locally. Repository maintenance instructions are in
+[CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md).
 
 [ISC licensed](LICENSE). Maintained by [Kequtech](https://github.com/kequtech).

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.count === null ||
-        !Number.isSafeInteger(result.count) ||
-        result.count < 0) {
-        throw new AffectedRowsError(constraint, result.count, result.command, false);
+        result.rowCount === null ||
+        !Number.isSafeInteger(result.rowCount) ||
+        result.rowCount < 0) {
+        throw new AffectedRowsError(constraint, result.rowCount, result.command, false);
     }
     const expected = constraint.exact ?? constraint.max;
-    const matches = constraint.exact === undefined ? result.count <= expected : result.count === expected;
+    const matches = constraint.exact === undefined ? result.rowCount <= expected : result.rowCount === expected;
     if (!matches) {
-        throw new AffectedRowsError(constraint, result.count, result.command, true);
+        throw new AffectedRowsError(constraint, result.rowCount, result.command, true);
     }
 }

package/dist/baseline.js

@@ -82,16 +82,16 @@ export async function adoptBaseline(options) {
         if (applied.length) {
             return [];
         }
-        const schema = await client.unsafe('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
+        const schema = await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
             namespace,
         ]);
-        if (!schema.length) {
+        if (!schema.rows.length) {
             throw new Error('The baseline namespace does not exist. Use migrate to initialize a fresh database.');
         }
-        await client.unsafe('BEGIN');
+        await client.query('BEGIN');
         await createHistoryTable(client, namespace);
         await recordMigration(client, namespace, baseline);
-        const result = await client.unsafe('COMMIT');
+        const result = await client.query('COMMIT');
         if (result.command !== 'COMMIT') {
             throw new Error('Baseline adoption was rolled back.');
         }

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.count;
+                rowCount = result.rowCount;
                 if (options.affectedRows)
                     checkAffectedRows(options.affectedRows, result);
                 return queryOutput(options, result);

package/dist/connection.d.ts

@@ -1,20 +1,19 @@
-import postgres from 'postgres';
+import { Pool, type PoolClient, type PoolConfig, type QueryResult as PgResult } from 'pg';
 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 ConnectionOptions = PoolConfig;
+export type Connection = string | ConnectionOptions | Pool;
+export type QueryResult<Row extends object = UnknownRow> = PgResult<Row>;
 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. */
+/** Own constructed pools; supplied pools retain their application's ownership and error policy. */
 export declare function createConnection(connection: Connection): {
-    sql: postgres.Sql;
-    owned: boolean;
+    pool: Pool;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    close(timeoutMs: number): Promise<void>;
 };
-export declare function executeSql(sql: SqlConnection, text: string, input?: readonly unknown[]): Promise<QueryResult>;
+/** A checked-out pg client remains tied to its session and is discarded after a failure. */
+export declare function watchClient(client: PoolClient): {
+    check(): void;
+    release(error?: Error): void;
+};
+/** Unnamed extended protocol enforces a single statement, even without parameters. */
+export declare function executeSql(connection: Pool | PoolClient, text: string, input?: readonly unknown[]): Promise<PgResult<UnknownRow>>;

package/dist/connection.js

@@ -1,22 +1,132 @@
-import postgres from 'postgres';
+import { Pool, } from 'pg';
 import { plainObject } from './validation.js';
-/** Own clients created from a URI/config; borrow explicitly supplied Postgres.js clients. */
+/** A supplied pool may come from another installed copy of pg. */
+function isPool(connection) {
+    return (connection !== null &&
+        typeof connection === 'object' &&
+        'connect' in connection &&
+        typeof connection.connect === 'function' &&
+        'query' in connection &&
+        typeof connection.query === 'function' &&
+        'totalCount' in connection &&
+        typeof connection.totalCount === 'number' &&
+        'end' in connection &&
+        typeof connection.end === 'function');
+}
+/** Own constructed pools; supplied pools retain their application's ownership and error policy. */
 export function createConnection(connection) {
-    if (typeof connection === 'function' && typeof connection.unsafe === 'function') {
-        return { sql: connection, owned: false };
-    }
+    if (isPool(connection))
+        return { pool: connection, run: (work) => work(), close: async () => { } };
+    let config;
     if (typeof connection === 'string') {
         if (!connection.trim())
             throw new Error('Connection string must not be empty.');
-        return { sql: postgres(connection), owned: true };
+        config = { connectionString: connection };
     }
-    plainObject(connection, 'Connection configuration');
-    return { sql: postgres(connection), owned: true };
+    else {
+        plainObject(connection, 'Connection configuration');
+        if ('url' in connection) {
+            throw new Error('Use pg connectionString in the connection configuration instead of url/options.');
+        }
+        config = connection;
+    }
+    const pool = new Pool(config);
+    const clients = new Set();
+    const pending = new Map();
+    let terminating = false;
+    const terminate = (client) => {
+        void client.end().catch(() => { });
+    };
+    // pool.end handles idle clients; the deadline also ends native checkouts.
+    pool.on('acquire', (client) => {
+        clients.add(client);
+        if (terminating)
+            terminate(client);
+    });
+    pool.on('release', (_error, client) => clients.delete(client));
+    pool.on('error', (error) => process.emitWarning(error));
+    return {
+        pool,
+        run(work) {
+            let expire;
+            const task = new Promise((resolve, reject) => {
+                expire = reject;
+                void Promise.resolve().then(work).then(resolve, reject);
+            });
+            pending.set(task, expire);
+            const forget = () => {
+                pending.delete(task);
+            };
+            void task.then(forget, forget);
+            return task;
+        },
+        async close(timeoutMs) {
+            let timer;
+            let ending;
+            const end = () => (ending ??= pool.end());
+            try {
+                await Promise.race([
+                    (async () => {
+                        await Promise.allSettled([...pending.keys()]);
+                        await end();
+                    })(),
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, timeoutMs);
+                    }).then(async () => {
+                        // Native callbacks must reject close on failure, not escape a timer callback.
+                        terminating = true;
+                        const error = new Error('The database shutdown deadline expired.');
+                        for (const reject of pending.values())
+                            reject(error);
+                        try {
+                            void end().catch(() => { });
+                        }
+                        finally {
+                            // Attempt every checkout even when one native end call throws.
+                            await Promise.all([...clients].map(async (client) => terminate(client)));
+                        }
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+/** A checked-out pg client remains tied to its session and is discarded after a failure. */
+export function watchClient(client) {
+    let failure;
+    const onError = (error) => {
+        failure ??= error;
+    };
+    const onEnd = () => {
+        failure ??= new Error('The PostgreSQL connection closed.');
+    };
+    client.on('error', onError);
+    client.on('end', onEnd);
+    return {
+        check() {
+            if (failure)
+                throw failure;
+        },
+        release(error) {
+            try {
+                client.release(error ?? failure);
+            }
+            finally {
+                client.removeListener('error', onError);
+                client.removeListener('end', onEnd);
+            }
+        },
+    };
 }
-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);
+/** Unnamed extended protocol enforces a single statement, even without parameters. */
+export function executeSql(connection, text, input = []) {
+    const config = {
+        text,
+        values: [...input],
+        queryMode: 'extended',
+    };
+    return connection.query(config);
 }

package/dist/database.js

@@ -1,8 +1,22 @@
 import { createClient } from './client.js';
 import { createConnection, executeSql } from './connection.js';
-import { prepareArrays } from './driver/array.js';
 import { withTransaction } from './transaction.js';
 import { plainObject } from './validation.js';
+function closeTimeout(options) {
+    const settings = plainObject(options === undefined ? {} : options, 'Close options');
+    for (const key of Object.keys(settings)) {
+        if (key !== 'timeoutMs')
+            throw new Error(`Unknown close option: ${key}`);
+    }
+    const timeoutMs = settings.timeoutMs === undefined ? 5000 : settings.timeoutMs;
+    if (typeof timeoutMs !== 'number' ||
+        !Number.isInteger(timeoutMs) ||
+        timeoutMs < 0 ||
+        timeoutMs > 2147483647) {
+        throw new Error('Close timeoutMs must be an integer from 0 to 2147483647 milliseconds.');
+    }
+    return timeoutMs;
+}
 export function createTenon(options) {
     for (const key of Object.keys(plainObject(options, 'Tenon options'))) {
         if (key !== 'connection' && key !== 'onQuery') {
@@ -12,35 +26,40 @@ export function createTenon(options) {
     if (options.onQuery !== undefined && typeof options.onQuery !== 'function') {
         throw new Error('onQuery must be a function.');
     }
-    const { sql: pool, owned } = createConnection(options.connection);
-    let closed = false;
+    const { pool, run, close } = createConnection(options.connection);
+    let closing;
     function checkOpen() {
-        if (closed) {
+        if (closing) {
             throw new Error('This database instance is closed.');
         }
     }
-    const query = async (text, input, readResult, guarded) => {
+    const query = (text, input, readResult, guarded) => {
         checkOpen();
-        if (guarded) {
-            return withTransaction(pool, (query) => query(text, input, readResult, false));
-        }
-        await prepareArrays(pool);
-        return readResult(await executeSql(pool, text, input));
+        return run(async () => {
+            if (guarded) {
+                return withTransaction(pool, (query) => query(text, input, readResult, false));
+            }
+            return readResult(await executeSql(pool, text, input));
+        });
     };
     return {
         ...createClient(query, options.onQuery),
         native: pool,
         async transaction(callback) {
             checkOpen();
-            return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));
+            return run(() => withTransaction(pool, (query) => callback(createClient(query, options.onQuery))));
         },
-        async close() {
-            if (closed) {
-                return;
+        close(options) {
+            if (closing)
+                return closing;
+            try {
+                const timeoutMs = closeTimeout(options);
+                // Cache before invoking driver callbacks, so reentrant/concurrent callers share shutdown.
+                closing = Promise.resolve().then(() => close(timeoutMs));
+                return closing;
             }
-            closed = true;
-            if (owned) {
-                await pool.end();
+            catch (error) {
+                return Promise.reject(error);
             }
         },
     };

package/dist/driver/types.d.ts

@@ -1,4 +1,4 @@
-/** Postgres.js default representations (with SQL NULL array elements preserved), shared by generation and query inspection. */
+/** pg default representations, shared by generation and query inspection. */
 export type ValueTypes = Readonly<{
     read: string;
     write: string;

package/dist/driver/types.js

@@ -8,18 +8,18 @@ export const arrayTypes = {
     '1022': 'number',
     '1028': 'number',
     '1016': { read: 'string', write: 'string | bigint' },
-    '1231': { read: 'string', write: 'string | number' },
+    '1231': { read: 'number', 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>' },
+    '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' },
 };
 export const scalarTypes = {
     int2: 'number',
@@ -35,13 +35,13 @@ export const scalarTypes = {
     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' },
+    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: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
-    jsonb: { read: 'unknown', write: 'Exclude<import("@kequtech/tenon-orm").JSONValue, null>' },
+    json: { read: 'unknown', write: 'string' },
+    jsonb: { read: 'unknown', write: 'string' },
     bytea: 'import("node:buffer").Buffer',
 };
 export function valueTypes(mapping) {

package/dist/errors.d.ts

@@ -1,4 +1,12 @@
 import type { AffectedRowsConstraint } from './affected-rows.js';
+export declare class CardinalityError extends Error {
+    name: string;
+    readonly code = "TENON_CARDINALITY_MISMATCH";
+    readonly expected: 'one' | 'oneOrNone';
+    readonly actual: number;
+    readonly label?: string;
+    constructor(expected: 'one' | 'oneOrNone', actual: number, label?: string);
+}
 export declare class AffectedRowsError extends Error {
     name: string;
     readonly code: 'TENON_AFFECTED_ROWS_MISMATCH' | 'TENON_AFFECTED_ROWS_UNSUPPORTED';

package/dist/errors.js

@@ -1,3 +1,18 @@
+export class CardinalityError extends Error {
+    name = 'CardinalityError';
+    code = 'TENON_CARDINALITY_MISMATCH';
+    expected;
+    actual;
+    label;
+    constructor(expected, actual, label) {
+        const count = expected === 'one' ? 'exactly one row' : 'at most one row';
+        super(`${label ?? 'Query'} expected ${count}, but returned ${actual} rows.`);
+        this.expected = expected;
+        this.actual = actual;
+        if (label !== undefined)
+            this.label = label;
+    }
+}
 export class AffectedRowsError extends Error {
     name = 'AffectedRowsError';
     code;