@kequtech/tenon-orm 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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,

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 Postgres.js 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 array 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 driver for LISTEN, cursors, COPY, and other native 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/connection.d.ts

@@ -1,7 +1,13 @@
 import postgres from 'postgres';
 import type { UnknownRow } from './query.js';
-export type ConnectionOptions = postgres.Options<{}>;
-export type Connection = string | ConnectionOptions | postgres.Sql;
+export type ConnectionOptions = postgres.Options<{}> & {
+    readonly onnotify?: ((channel: string, payload: string) => void) | undefined;
+};
+export interface ConnectionUri {
+    readonly url: string;
+    readonly options?: ConnectionOptions | undefined;
+}
+export type Connection = string | ConnectionOptions | ConnectionUri | postgres.Sql;
 export type QueryResult<Row extends object = UnknownRow> = postgres.RowList<Row[]>;
 /** The driver operations shared by ordinary and reserved connections. */
 export interface SqlConnection {

package/dist/connection.js

@@ -11,6 +11,19 @@ export function createConnection(connection) {
         return { sql: postgres(connection), owned: true };
     }
     plainObject(connection, 'Connection configuration');
+    if ('url' in connection) {
+        for (const key of Object.keys(connection)) {
+            if (key !== 'url' && key !== 'options') {
+                throw new Error(`Unknown URI connection option: ${key}`);
+            }
+        }
+        if (typeof connection.url !== 'string' || !connection.url.trim()) {
+            throw new Error('Connection string must not be empty.');
+        }
+        if (connection.options !== undefined)
+            plainObject(connection.options, 'Connection options');
+        return { sql: postgres(connection.url, connection.options), owned: true };
+    }
     return { sql: postgres(connection), owned: true };
 }
 export function executeSql(sql, text, input = []) {

package/dist/database.js

@@ -1,8 +1,24 @@
 import { createClient } from './client.js';
 import { createConnection, executeSql } from './connection.js';
 import { prepareArrays } from './driver/array.js';
+import { guardListenerShutdown } from './driver/listener.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') {
@@ -13,9 +29,10 @@ export function createTenon(options) {
         throw new Error('onQuery must be a function.');
     }
     const { sql: pool, owned } = createConnection(options.connection);
-    let closed = false;
+    const stopListeners = owned ? guardListenerShutdown(pool) : undefined;
+    let closing;
     function checkOpen() {
-        if (closed) {
+        if (closing) {
             throw new Error('This database instance is closed.');
         }
     }
@@ -34,13 +51,22 @@ export function createTenon(options) {
             checkOpen();
             return 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(() => {
+                    if (owned) {
+                        stopListeners();
+                        return pool.end({ timeout: timeoutMs / 1000 });
+                    }
+                });
+                return closing;
             }
-            closed = true;
-            if (owned) {
-                await pool.end();
+            catch (error) {
+                return Promise.reject(error);
             }
         },
     };

package/dist/driver/listener.d.ts

@@ -0,0 +1,3 @@
+import type postgres from 'postgres';
+/** Prevent an owned LISTEN client's queued reconnect from reopening it after shutdown. */
+export declare function guardListenerShutdown(sql: postgres.Sql): () => void;

package/dist/driver/listener.js

@@ -0,0 +1,63 @@
+import { createConnection } from 'node:net';
+function closedError() {
+    return Object.assign(new Error('The owned PostgreSQL listener is closed.'), {
+        code: 'CONNECTION_ENDED',
+    });
+}
+/** Prevent an owned LISTEN client's queued reconnect from reopening it after shutdown. */
+export function guardListenerShutdown(sql) {
+    const options = sql.options;
+    const listen = sql.listen;
+    const sockets = new Set();
+    let closed = false;
+    let hostIndex = 0;
+    function track(socket) {
+        // TLS adoption removes raw socket listeners; prune those closed transports on reconnect.
+        for (const previous of sockets)
+            if (previous.destroyed)
+                sockets.delete(previous);
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+        if (closed) {
+            socket.destroy();
+            throw closedError();
+        }
+        return socket;
+    }
+    sql.listen = (...args) => {
+        if (closed)
+            return Promise.reject(closedError());
+        const previous = options.socket;
+        // Postgres.js synchronously clones these options for its dedicated max:1 listener.
+        // Restore immediately so ordinary queries retain their native transport configuration.
+        options.socket = (settings) => {
+            if (closed)
+                throw closedError();
+            if (previous)
+                return Promise.resolve(previous(settings)).then(track);
+            const host = settings.host[hostIndex];
+            const port = settings.port[hostIndex];
+            const socket = createConnection(settings.path ? { path: settings.path } : { host, port });
+            if (!settings.path) {
+                hostIndex = (hostIndex + 1) % settings.port.length;
+                // The driver's TLS negotiation uses this metadata for SNI and verification.
+                Object.assign(socket, { host, port });
+            }
+            // Node buffers startup writes while connecting; the driver retains its connect timeout,
+            // authentication, TLS negotiation and reconnect handling.
+            return track(socket);
+        };
+        try {
+            return listen(...args);
+        }
+        finally {
+            options.socket = previous;
+        }
+    };
+    return () => {
+        closed = true;
+        for (const socket of sockets)
+            socket.destroy();
+        sockets.clear();
+    };
+}

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;

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 export type { JSONValue } from 'postgres';
-export type { Connection, ConnectionOptions, QueryResult } from './connection.js';
+export type { Connection, ConnectionOptions, ConnectionUri, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
 export type { TenonOptions } from './database.js';
-export { AffectedRowsError } from './errors.js';
+export { AffectedRowsError, CardinalityError } from './errors.js';
 export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 export { identifier, sql, unsafeSql } from './query.js';
 export type { SqlFragment, SqlQuery, UnknownRow } from './query.js';
-export type { Database, QueryClient, QueryEvent, Transaction } from './types.js';
+export type { CloseOptions, 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';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { createTenon } from './database.js';
-export { AffectedRowsError } from './errors.js';
+export { AffectedRowsError, CardinalityError } from './errors.js';
 export { identifier, sql, unsafeSql } from './query.js';
 export { describeQuery } from './describe.js';
 export { adoptBaseline, captureBaseline } from './baseline.js';

package/dist/inspection/cli.js

@@ -14,9 +14,9 @@ export async function runDescribe(filename, connection, values) {
         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'] } : {}),
+            role: values.role,
+            searchPath: values['search-path'],
+            timeZone: values['time-zone'],
         },
         timeouts: {
             ...(values['connect-timeout-ms'] !== undefined

package/dist/inspection/options.d.ts

@@ -8,8 +8,8 @@ export declare function inspectionOptions(options: Pick<DescribeOptions, 'connec
         lockMs: number;
     };
     session: {
-        role?: string;
-        searchPath?: string;
-        timeZone?: string;
+        role?: string | undefined;
+        searchPath?: string | undefined;
+        timeZone?: string | undefined;
     };
 };

package/dist/inspection/options.js

@@ -10,6 +10,8 @@ export function inspectionOptions(options) {
         if (!['role', 'searchPath', 'timeZone'].includes(key)) {
             throw new Error(`Unknown inspection session option: ${key}`);
         }
+        if (value === undefined)
+            continue;
         if (typeof value !== 'string' || !value.trim() || value.includes('\0')) {
             throw new Error(`Inspection session ${key} requires a nonempty string without NUL.`);
         }
@@ -20,11 +22,17 @@ export function inspectionOptions(options) {
     for (const [key, value] of Object.entries(timeouts)) {
         if (!Object.hasOwn(defaults, key))
             throw new Error(`Unknown inspection timeout: ${key}`);
+        if (value === undefined)
+            continue;
         if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 2147483647) {
             throw new Error(`Inspection timeout ${key} must be a positive integer in milliseconds.`);
         }
     }
-    const limits = { ...defaults, ...timeouts };
+    const limits = {
+        connectMs: timeouts.connectMs ?? defaults.connectMs,
+        statementMs: timeouts.statementMs ?? defaults.statementMs,
+        lockMs: timeouts.lockMs ?? defaults.lockMs,
+    };
     // URL startup options must not disable the inspection's server-side bounds.
     let url;
     try {

package/dist/inspection/types.d.ts

@@ -1,14 +1,14 @@
 import type { SqlQuery } from '../query.js';
 export interface InspectionSession {
-    readonly role?: string;
+    readonly role?: string | undefined;
     /** PostgreSQL's search_path setting, as used in the application's connection options. */
-    readonly searchPath?: string;
-    readonly timeZone?: string;
+    readonly searchPath?: string | undefined;
+    readonly timeZone?: string | undefined;
 }
 export interface InspectionTimeouts {
-    readonly connectMs?: number;
-    readonly statementMs?: number;
-    readonly lockMs?: number;
+    readonly connectMs?: number | undefined;
+    readonly statementMs?: number | undefined;
+    readonly lockMs?: number | undefined;
 }
 export interface InspectionContext {
     readonly mode: 'separate-session';
@@ -27,8 +27,8 @@ export interface DescribeOptions {
     readonly connection: string;
     /** Finished SQL; query values are neither bound nor executed. */
     readonly query: string | Pick<SqlQuery, 'text'>;
-    readonly session?: InspectionSession;
-    readonly timeouts?: InspectionTimeouts;
+    readonly session?: InspectionSession | undefined;
+    readonly timeouts?: InspectionTimeouts | undefined;
 }
 export type DescriptionIssue = {
     readonly code: 'nullability-unknown';

package/dist/query-options.js

@@ -1,5 +1,6 @@
 import { validateAffectedRows } from './affected-rows.js';
 import { plainObject } from './validation.js';
+import { CardinalityError } from './errors.js';
 export function validateOptions(options) {
     const config = options === undefined ? {} : plainObject(options, 'Query options');
     for (const key of Object.keys(config)) {
@@ -27,9 +28,8 @@ export function queryOutput(options, result) {
         return result;
     if (options.returns === 'many')
         return [...result];
-    const expected = options.returns === 'oneOrNone' ? 'at most one row' : 'exactly one row';
     if (result.length > 1 || (options.returns === 'one' && result.length === 0)) {
-        throw new Error(`${options.label ?? 'Query'} expected ${expected}, but returned ${result.length} rows.`);
+        throw new CardinalityError(options.returns === 'oneOrNone' ? 'oneOrNone' : 'one', result.length, options.label);
     }
     return result[0];
 }

package/dist/types.d.ts

@@ -12,12 +12,16 @@ export interface QueryClient {
     query<Row extends object>(query: SqlQuery<Row>, options: QueryOptions | undefined): NoInfer<Promise<QueryOutput<Row, QueryReturnMode>>>;
 }
 export type Transaction = QueryClient;
+export interface CloseOptions {
+    /** Grace period before requesting owned driver termination; milliseconds, default 5000. */
+    readonly timeoutMs?: number | undefined;
+}
 export type Database = Transaction & {
     /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
     readonly native: postgres.Sql;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
-    close(): Promise<void>;
+    close(options?: CloseOptions): Promise<void>;
 };
 /** One completed public query call, including rollback/commit time for guarded calls. */
 export interface QueryEvent {