@kequtech/tenon-orm 0.2.2 → 0.3.1

package/docs/reference.md

@@ -1,14 +1,14 @@
 # Tenon reference
 
-Exact API contracts and limitations. The [human guide](human-guide.md) introduces the workflow;
-the [agent guide](agent-guide.md) covers routine implementation. Examples below use the
-`public.users` table from the human guide and an existing `db` instance, unless stated otherwise.
+Exact API contracts and limitations. The [human guide](human-guide.md) introduces the workflow; the
+[agent guide](agent-guide.md) covers routine implementation. Examples below use the `public.users`
+table from the human guide and an existing `db` instance, unless stated otherwise.
 
 ## Installation and connection
 
 Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
-development typings. Tenon includes `postgres@3.4.9`; no driver peer or special compiler plugin is
-required. A usual Node TypeScript setup uses `module: "NodeNext"`.
+development typings. Tenon includes `pg@8.23.1` and its TypeScript declarations; no driver peer or
+special compiler plugin is required. A usual Node TypeScript setup uses `module: "NodeNext"`.
 
 ```sh
 npm install @kequtech/tenon-orm
@@ -18,71 +18,147 @@ npm install @kequtech/tenon-orm
 and `close`. The required `connection` accepts:
 
 - A PostgreSQL URI string.
-- `{ url: string, options?: ConnectionOptions }` to combine a URI with driver settings.
-- A Postgres.js options object; an explicit `{}` uses the driver's environment defaults.
-- An existing Postgres.js client, borrowed by identity.
+- A pg `PoolConfig` object; an explicit `{}` uses the driver's environment defaults.
+- An existing `pg.Pool`, borrowed by identity.
 
 ```ts
 const db = createTenon({
   connection: {
-    url: connection,
-    options: { connect_timeout: 5, idle_timeout: 10, connection: { search_path: 'app,public' } },
+    connectionString: connection,
+    max: 10,
+    idleTimeoutMillis: 30_000,
+    connectionTimeoutMillis: 30_000,
+    options: '-c search_path=app,public',
   },
 });
 ```
 
-Tenon forwards `{ url, options }` to `postgres(url, options)`. Explicit driver options override
-corresponding URI pool/transport options. URI startup parameters such as `search_path` and
-`application_name` override `options.connection`. Timeouts above are seconds; preserve the
-deployment's credentials and TLS requirements. `ConnectionUri` and `ConnectionOptions` are
-exported. The latter includes `onnotify(channel, payload)` for native notification handling;
-configure callbacks at construction.
-
-Reuse an instance for each database configuration. `db.close({ timeoutMs? })` rejects new Tenon
-work immediately and gives owned connections a 5,000 ms grace period by default before requesting
-driver termination. Use `0` for immediate termination. The timeout must be an integer from 0 to
-2,147,483,647 milliseconds; `CloseOptions` is exported. Finish outstanding work before closing
-when possible. The timeout bounds the shutdown wait and rejects pending client queries; it is not
-a PostgreSQL cancellation request. Server work can complete afterward, including an autocommitted
-write, and JavaScript inside a transaction callback is not canceled.
-
-The first valid close call chooses the timeout. Concurrent and later calls return the same promise,
-including the same shutdown failure; later options do not change it. Invalid initial options reject
-without closing the instance. For a borrowed client, close only disables the Tenon wrapper and
-leaves the driver pool and its work to the caller. Tenon does not load environment files.
-
-Qualify SQL names or configure runtime `search_path`. CLI `--namespace` selects tooling scope;
-it does not configure application queries. Baseline capture and Describe accept connection
-strings rather than the runtime connection union.
+Strings become pg's `connectionString`; configuration objects pass to `new Pool(config)`.
+`ConnectionOptions` is an alias for pg's `PoolConfig`. Driver options and defaults are unchanged,
+including no acquisition timeout unless `connectionTimeoutMillis` is configured. Pool timeouts use
+milliseconds. pg parses the URI for connection fields; matching URI values override client
+configuration, including an `options` URI parameter overriding the configuration's `options` string.
+The pool sizes and timeouts above are application choices. Configure pool policy in `PoolConfig`;
+old driver-specific URI settings such as `idle_timeout` do not configure pg's idle timeout. Preserve
+existing URI startup options when appending settings such as UTC and `search_path`.
+Preserve deployment credentials and TLS requirements; see
+[pg connection configuration](https://node-postgres.com/features/connecting).
+
+Reuse an instance for each database configuration. `db.close({ timeoutMs? })` immediately rejects
+new Tenon work. For owned pools, accepted Tenon operations can drain for up to 5,000 ms by default;
+at the deadline, remaining operations reject and Tenon requests driver termination. `0` skips the
+grace period. The timeout must be an integer from 0 to 2,147,483,647 milliseconds; `CloseOptions` is
+exported. This bounds Tenon's wait, not every native transport's teardown or server execution. It
+sends no PostgreSQL cancellation request and does not cancel JavaScript callbacks. An unbounded
+authentication attempt can keep a connection open after close resolves. Configure pg's
+`connectionTimeoutMillis` when connection establishment also needs a deadline.
+
+The first valid close call chooses the timeout. Concurrent and later calls share the same promise
+and outcome. Invalid initial options reject without closing the instance. For borrowed pools, close
+only disables the Tenon wrapper; the application retains the pool and outstanding work. Tenon does
+not load environment files.
+
+Qualify SQL names or configure runtime `search_path`. CLI `--namespace` selects tooling scope; it
+does not configure application queries. Baseline capture and Describe accept connection strings
+rather than the runtime connection union.
 
 ## Native driver access
 
-`db.native` is the actual pool-level Postgres.js client, readonly in TypeScript. Use it for LISTEN,
-cursors, COPY, and other [native APIs](https://github.com/porsager/postgres/tree/v3.4.9#usage).
-Native calls bypass Tenon's result modes, affected-row guards, SQL checks, and `onQuery`. They use
-native preparation defaults and do not join a Tenon transaction; callback clients expose only
-`tx.query`.
+`db.native` is the actual `pg.Pool`, readonly in TypeScript. Native calls bypass Tenon's result
+modes, affected-row guards, SQL checks, and `onQuery`. They follow pg's query configuration and do
+not join a Tenon transaction; callback clients expose only `tx.query`.
 
-Native access alone does not install Tenon's array correction. The first Tenon query or transaction
-installs it on the shared client; native statements prepared earlier may retain their old parsers.
+Use pg's [native APIs](https://node-postgres.com/apis/pool) and compatible cursor/COPY packages when
+needed. For LISTEN, check out a client with `await db.native.connect()`, attach `notification`,
+`error`, and `end` listeners, and issue `LISTEN` on that client. Keep it checked out while listening;
+release it after `UNLISTEN`. Native queued acquisitions follow pg's shutdown behavior and must be
+settled by their caller before closing. A disconnected client does not reconnect. The application owns
+resubscription and catch-up; notifications are not replayed.
 
-Native `.listen(channel, onPayload, onReady?)` uses a dedicated physical connection. `onReady`
-runs after subscription and resubscription. Missed notifications are not replayed; the application
-owns catch-up and callback errors. That dedicated client installs its own close handler, so a
-constructor `onclose` does not report its outages. Explicit LISTEN on a dedicated reserved native
-connection can use constructor callbacks when disconnect detection is required. Subscription
-cancellation follows the pinned driver; known reconnect limitations are recorded in
-[maintainer considerations](https://github.com/kequtech/tenon-orm/blob/main/CONSIDERATIONS.md#native-driver-access-and-listen-lifecycle).
+Close owned pools through `db.close()` for bounded shutdown, including checked-out native clients.
+Borrowed pools and their listeners remain usable after wrapper close until their owner ends them.
 
-Close owned clients through `db.close()` to prevent queued LISTEN reconnects from reopening them.
-Direct `db.native.end()` bypasses that protection. Borrowed clients and their listeners remain
-usable after wrapper close until their owner ends them.
+### LISTEN lifecycle example
+
+This helper owns a dedicated single-client pool. It returns an intentional-close function only
+after LISTEN is ready. Callbacks are synchronous; notification exceptions are isolated, and an
+unexpected disconnect invalidates this generation once before notifying its consumer. Failed
+connection acquisition or LISTEN setup closes the owned resources and rejects the setup promise.
+
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+
+async function listenForChanges(
+  connectionString: string,
+  onChange: (payload: string | undefined) => void,
+  onDisconnect: (error: Error) => void,
+) {
+  const db = createTenon({
+    connection: { connectionString, max: 1, idleTimeoutMillis: 0, connectionTimeoutMillis: 30_000 },
+  });
+  const client = await db.native.connect().catch(async (error: unknown) => {
+    await db.close();
+    throw error;
+  });
+  let active = true;
+  let closing: Promise<void> | undefined;
+
+  function stop(error?: Error): Promise<void> {
+    if (closing) return closing;
+    active = false;
+    closing = Promise.resolve().then(async () => {
+      try {
+        if (error) onDisconnect(error);
+      } finally {
+        client.release(true);
+        await db.close();
+      }
+    });
+    return closing;
+  }
+
+  const failed = (error: Error) => {
+    if (active) void stop(error).catch(console.error);
+  };
+  client.on('error', failed);
+  client.on('end', () => failed(new Error('The notification connection ended.')));
+  client.on('notification', (event) => {
+    if (!active || event.channel !== 'app_changes') return;
+    try {
+      onChange(event.payload);
+    } catch (error) {
+      console.error(error);
+    }
+  });
+  try {
+    await client.query('LISTEN "app_changes"');
+    if (!active) throw new Error('The notification connection closed during setup.');
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+  return () => stop();
+}
+```
+
+Both failure and intentional close discard the dedicated checkout with `release(true)` before
+closing its pool, so no UNLISTEN is needed and normal shutdown does not wait for Tenon's deadline.
+The active flag suppresses duplicate error/end callbacks and intentional-close notifications.
+Create a new helper instance to recover, and reconcile missed events through persistent data.
+
+This helper's close function is available after readiness. A manager that also supports replacement
+or shutdown while setup is pending must assign a generation token before awaiting setup. Only the
+current generation may change shared readiness/subscription state or notify its consumers. If stale
+setup later succeeds, close that setup's own listener; if it fails or finishes cleanup, leave the
+replacement alone. Invalidate the current token before intentional shutdown. Keep those guards in
+the application's subscription manager. The fixed channel above is trusted; validate and quote
+application-selected channel names before placing them in native SQL.
 
 ## Queries and result modes
 
 `sql<Row>` creates a detached `SqlQuery<Row>` with SQL `text` and ordered `values`; it does not
-execute. `Row` declares one selected row. Without an annotation, fields are `unknown`. An
-annotation does not verify the SQL or validate returned data.
+execute. `Row` declares one selected row. Without an annotation, fields are `unknown`. An annotation
+does not verify the SQL or validate returned data.
 
 ```ts
 const user = await db.query(
@@ -94,27 +170,47 @@ const user = await db.query(
 `query` options are `{ returns?, affectedRows?, label? }`; unknown keys fail. A supplied `label`
 must be a nonempty string.
 
-| `returns`          | Output                          | Allowed returned rows |
-| ------------------ | ------------------------------- | --------------------- |
-| `native` (default) | `QueryResult<Row>` driver array | Any                   |
-| `many`             | Plain `Row[]`                   | Any                   |
-| `oneOrNone`        | `Row \| undefined`              | Zero or one           |
-| `one`              | `Row`                           | Exactly one           |
+| `returns`          | Output                           | Allowed returned rows |
+| ------------------ | -------------------------------- | --------------------- |
+| `native` (default) | `QueryResult<Row>` driver object | Any                   |
+| `many`             | Plain `Row[]`                    | Any                   |
+| `oneOrNone`        | `Row \| undefined`               | Zero or one           |
+| `one`              | `Row`                            | Exactly one           |
 
-Native arrays carry `command`, `count`, `columns`, `statement`, and `state` metadata. `count` is
-the command's affected-row count, independent of `RETURNING`; it can be null for commands without
-a count. Result modes never add `LIMIT` or `RETURNING`. A returned-row mismatch alone does not
-undo an autocommitted write; use `affectedRows` for write bounds that roll back on failure.
+Native results expose `rows`, `rowCount`, `command`, and `fields`, following pg's `QueryResult`.
+`rowCount` is the command's affected-row count, independent of `RETURNING`; it can be null for
+commands without a count. Result modes never add `LIMIT` or `RETURNING`. A returned-row mismatch
+alone does not undo an autocommitted write; use `affectedRows` for write bounds that roll back.
 
 Functions accepting `QueryClient` can use either `Database` or `Transaction`. Public types also
 include `QueryOptions`, `QueryReturnMode`, and `QueryOutput<Row, Mode>`.
 
+### Adapting transactional results
+
+For a job library or other adapter expecting `{ rows }`, extract the native result's row array:
+
+```ts
+import { unsafeSql, type QueryClient } from '@kequtech/tenon-orm';
+
+async function queryRows(tx: QueryClient, text: string, values: readonly unknown[]) {
+  const result = await tx.query(unsafeSql(text, values));
+  return { rows: result.rows };
+}
+```
+
+Alternatively, request `{ returns: 'many' }` and wrap the returned array in `{ rows }`. Supply the
+callback's `tx` when the adapter's work must commit with application writes. A native pool query
+uses a separate checkout and does not join that transaction. Await adapter calls before returning
+from the callback, retain commit/rollback tests, and make recording helpers return pg-shaped native
+results. The adapter's SQL text must be trusted and values must remain separately bound.
+
 ## SQL parameters and identifiers
 
 Ordinary `sql` interpolations bind values. Do not quote them or write manual `$n` placeholders
-inside templates. `undefined` bound parameters fail; `null` means SQL null. Pass JSON objects and
-arrays directly. SQL context distinguishes PostgreSQL arrays from JSON; cast standalone parameters
-when that context is absent.
+inside templates. Values follow pg serialization: `null` and `undefined` bind as SQL null, arrays
+bind as PostgreSQL arrays, and objects use pg's JSON serialization. For JSON input, use
+`JSON.stringify(value)`, including for JSON arrays, strings, and JSON null. Generated JSON write
+types accept encoded strings. Cast standalone parameters when SQL must establish their type.
 
 ```ts
 const ids = [1, 2, 3];
@@ -122,26 +218,27 @@ const query = sql<{ id: number }>`SELECT id FROM public.users
   WHERE id = ANY(${ids}::integer[])`;
 ```
 
-`identifier(schema, table)` quotes components separately. Names must contain 1–63 UTF-8 bytes and
-no NUL. Choose application-approved names; quoting does not authorize access. SQL syntax such as
-`DESC` belongs in fixed query alternatives or fragments, not a string parameter.
+`identifier(schema, table)` quotes components separately. Names must contain 1–63 UTF-8 bytes and no
+NUL. Choose application-approved names; quoting does not authorize access. SQL syntax such as `DESC`
+belongs in fixed query alternatives or fragments, not a string parameter.
 
 `unsafeSql<Row>(text, values)` accepts trusted external SQL and an explicit values array, including
 `[]`. Never concatenate request input into its text. Full `sql` and `unsafeSql` queries cannot be
 nested; use fragments for partial SQL.
 
-Each Tenon query executes one statement through the extended protocol. Application execution
-explicitly disables prepared-statement caching, including on supplied clients with `prepare: true`.
-Values remain bound separately. Migrations deliberately support multi-statement scripts.
+Each Tenon query executes one statement through the extended protocol. Application execution uses
+unnamed queries without a `name` or prepared-statement cache. Values remain bound separately.
+Migrations deliberately support multi-statement scripts.
 
 ## SQL fragments and joins
 
 `sql.fragment` creates immutable partial SQL with bound values. It has no row type, cannot execute
 alone, and rejects blank SQL. Insert it into a complete `sql<Row>` query.
 
-`sql.join(fragments, separator)` requires a nonempty list. Separators are `'AND'`, `'OR'`, and `','`.
-It does not add parentheses or change SQL precedence. Each fragment use receives correctly ordered
-parameters, including repeated and nested uses; literal `$1` text in strings/comments is unchanged.
+`sql.join(fragments, separator)` requires a nonempty list. Separators are `'AND'`, `'OR'`, and
+`','`. It does not add parentheses or change SQL precedence. Each fragment use receives correctly
+ordered parameters, including repeated and nested uses; literal `$1` text in strings/comments is
+unchanged.
 
 ```ts
 const email: string | undefined = 'reader@example.test';
@@ -178,10 +275,10 @@ fragment construction; nested objects retain ordinary driver serialization behav
 | SQL fragment, identifier, or query as a cell | Rejected               | Rejected        |
 
 Inserts accept one object or an array. Without `columns`, they infer the union of enumerable keys
-with defined values in first-seen order. Heterogeneous rows stay aligned. A single default-only
-row emits `DEFAULT VALUES`. Empty batches fail; multiple default-only rows need explicit columns.
-Assignments omit undefined values and fail when no assignments remain, even if surrounding SQL
-has other assignments.
+with defined values in first-seen order. Heterogeneous rows stay aligned. A single default-only row
+emits `DEFAULT VALUES`. Empty batches fail; multiple default-only rows need explicit columns.
+Assignments omit undefined values and fail when no assignments remain, even if surrounding SQL has
+other assignments.
 
 A supplied column list must be nonempty, unique, and valid. It selects and orders fields, ignoring
 unlisted keys. Missing insert cells use defaults; missing update fields are omitted. TypeScript
@@ -190,7 +287,7 @@ Helpers have no schema metadata; PostgreSQL enforces identity, generated-column,
 rules. Use [generated inputs](#insert-and-update-inputs) and application validation.
 
 Write arithmetic, `column = DEFAULT`, and `excluded.column` in the surrounding SQL. There is no
-expression/default sentinel. A complete query accepts at most 65,533 bound parameters, including
+expression/default sentinel. A complete query accepts at most 65,535 bound parameters, including
 surrounding interpolations; Tenon does not split batches. See the [mutation cookbook](mutations.md).
 
 ## Transactions, guarded writes, and errors
@@ -221,8 +318,8 @@ Sequence advances and external effects are not reversible. A lost commit acknowl
 the outcome unknown; applications own retry and idempotency policy.
 
 Set isolation before data queries with `SET TRANSACTION ISOLATION LEVEL SERIALIZABLE`, and use
-`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction. Manual savepoints are supported;
-reserve names beginning with `tenon_affected_rows_` for Tenon.
+`SET LOCAL statement_timeout = '5s'` to bound statements in that transaction. Manual savepoints are
+supported; reserve names beginning with `tenon_affected_rows_` for Tenon.
 
 SQL errors retain native driver details. Invalid inputs throw ordinary `Error` objects.
 `CardinalityError` has code `TENON_CARDINALITY_MISMATCH`, `expected` (`one` or `oneOrNone`),
@@ -233,59 +330,134 @@ produce `AggregateError`.
 
 Optional `onQuery` observes completed calls with `label`, `durationMs`, `outcome`, and available
 `command`, `rowCount`, and `errorCode`. It receives no SQL or values. Validation failures before
-execution are not observed. Observers are not awaited; failures emit warnings without changing
-the query outcome. Query success inside a callback does not establish outer commit.
+execution are not observed. Observers are not awaited; failures emit warnings without changing the
+query outcome. Query success inside a callback does not establish outer commit.
 
 ## Generated types and checking
 
-`generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript declarations
-from a consistent read-only snapshot; it does not need migration files or history. The CLI writes
-them atomically. Default namespace is `public`; default output is `src/generated-schema.ts`.
-Both `.ts` and `.d.ts` outputs are supported. Commit exact output and exclude it from formatting.
+`generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript declarations from a
+consistent read-only snapshot; it does not need migration files or history. The CLI writes them
+atomically. Default namespace is `public`; default output is `src/generated-schema.ts`. Both `.ts`
+and `.d.ts` outputs are supported. Commit exact output and exclude it from formatting.
 
 ```sh
 npx tenon generate --out src/generated-schema.d.ts
 npx tenon generate --out src/generated-schema.d.ts --check
 ```
 
-`--check` never rewrites the file. Missing/stale output fails with a diagnostic and a short diff
-for changes. It compares the generated representation, not pending migrations or every database
-object. Output includes relation/constraint/index summaries and referenced domains, not function
-bodies, grants, or a complete schema fingerprint.
+`--check` never rewrites the file. Missing/stale output fails with a diagnostic and a short diff for
+changes. It compares the generated representation, not pending migrations or every database object.
+Output includes relation/constraint/index summaries and referenced domains, not function bodies,
+grants, or a complete schema fingerprint.
+
+**Generated declarations are not a version-stable schema fingerprint.** TypeScript mappings can
+change without schema drift. The schema-summary comments describe SQL column types, defaults,
+constraints, indexes, and referenced domains independently of those mappings, but their formatting
+and PostgreSQL's rendering of definitions are not a versioned comparison contract either. Preserve
+reviewed generator-specific references if an existing guard hashes this output; see
+[baseline verification](adoption-guide.md#check-and-adopt-an-existing-database).
 
 Generation covers ordinary tables and partitioned roots. Views, foreign tables, and attached
 partitions need query-specific types. A missing namespace fails; an existing empty schema is valid.
 Exact table names are available through `Rows['users']`; valid nonreserved identifiers also receive
 named aliases. Use `Pick` for projections; a join or aggregate needs its actual selected shape.
 
-| PostgreSQL type                                | Read representation  | Generated write input                                        |
-| ---------------------------------------------- | -------------------- | ------------------------------------------------------------ |
-| smallint, integer, oid, real, double precision | `number`             | `number`                                                     |
-| bigint                                         | `string`             | `string \| bigint`                                           |
-| numeric                                        | `string`             | `string \| number`                                           |
-| boolean                                        | `boolean`            | `boolean`                                                    |
-| text, name, varchar, char, uuid, time, timetz  | `string`             | `string`                                                     |
-| date, timestamp, timestamptz                   | `Date`               | `Date \| string`                                             |
-| enum                                           | String literal union | Same union; `never` for an empty enum                        |
-| json, jsonb                                    | `unknown`            | `Exclude<JSONValue, null>`; `JSONValue` is exported by Tenon |
-| bytea                                          | `Buffer`             | `Buffer`                                                     |
-
-Nullable columns add null; `unknown` already includes it. Domains retain verified base mappings
-and the column's read nullability. Verified arrays use `PgArray<T> = (T | null | PgArray<T>)[]` for
-null elements and multiple dimensions. Numeric arrays contain strings; enum arrays and arrays of
-domains are unverified. Unmapped types warn and use `unknown` reads / `never` non-null writes.
+| PostgreSQL type                                | Read representation  | Generated write input                 |
+| ---------------------------------------------- | -------------------- | ------------------------------------- |
+| smallint, integer, oid, real, double precision | `number`             | `number`                              |
+| bigint                                         | `string`             | `string \| bigint`                    |
+| numeric                                        | `string`             | `string \| number`                    |
+| boolean                                        | `boolean`            | `boolean`                             |
+| text, name, varchar, char, uuid, time, timetz  | `string`             | `string`                              |
+| date, timestamp, timestamptz                   | `Date \| number`     | `Date \| string`                      |
+| enum                                           | String literal union | Same union; `never` for an empty enum |
+| json, jsonb                                    | `unknown`            | `string` containing encoded JSON      |
+| bytea                                          | `Buffer`             | `Buffer`                              |
+
+Nullable columns add null; `unknown` already includes it. Domains retain verified base mappings and
+the column's read nullability. Verified arrays use `PgArray<T> = (T | null | PgArray<T>)[]` for null
+elements and multiple dimensions. Numeric arrays contain numbers and can lose precision; select/cast
+them as text when exact values are required. Bigint arrays contain strings; enum arrays and arrays
+of domains are unverified. Unmapped types warn and use `unknown` reads / `never` non-null writes.
 Custom parsers need matching application types.
 
-Date-only parsing uses UTC; timestamps without time zone use Node's local timezone. Infinite
-temporal reads become invalid dates: check `Number.isFinite(value.getTime())` before date methods.
-Bound temporal values require finite dates; use SQL literals for PostgreSQL infinity.
+Date-only values and timestamps without time zone use Node's local timezone. Infinite temporal reads
+are numbers (`Infinity` or `-Infinity`); narrow with `value instanceof Date` before date methods.
+Temporal write inputs accept `Date | string`; use PostgreSQL's text `infinity` or `-infinity` when
+needed.
 
 ### Persistence and domain values
 
-Generated types describe storage representations. Text `CHECK` constraints do not become unions,
-and JSON reads remain unknown; validate before narrowing to domain types. Convert third-party
-payloads into validated native JSON-compatible objects rather than asserting compatibility or
-pre-serializing them. A bound null means SQL null; use `'null'::jsonb` for JSON null.
+Generated types describe storage representations. Text `CHECK` constraints do not become unions, and
+JSON reads remain unknown. Validate values before narrowing to application domain types.
+
+For example, assume this additional table and regenerate `Rows` from the resulting schema:
+
+```sql
+CREATE TABLE public.sessions (
+  id text PRIMARY KEY,
+  data jsonb NOT NULL,
+  expires_at timestamptz NOT NULL
+);
+```
+
+Use the same application validator before encoding a write and when restoring a domain value:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+import type { Rows } from './generated-schema.js';
+
+function sessionData(value: unknown): { userId: string } {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    Array.isArray(value) ||
+    !('userId' in value) ||
+    typeof value.userId !== 'string' ||
+    value.userId.length === 0
+  ) {
+    throw new Error('Expected session data with a nonempty userId');
+  }
+  return { userId: value.userId };
+}
+
+function finiteDate(value: Date | number): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new Error('Expected a finite database timestamp');
+  }
+  return value;
+}
+
+const input = {
+  id: 'example-session',
+  data: JSON.stringify(sessionData({ userId: 'user-42' })),
+  expires_at: new Date(Date.now() + 60_000),
+} satisfies Rows.Insert['sessions'];
+await db.query(sql`INSERT INTO public.sessions ${sql.insertValues(input)}`);
+
+const row = await db.query(
+  sql<Rows['sessions']>`SELECT id, data, expires_at FROM public.sessions
+    WHERE id = ${input.id} AND isfinite(expires_at) AND expires_at > now()`,
+  { returns: 'oneOrNone' },
+);
+const session =
+  row === undefined
+    ? undefined
+    : {
+        id: row.id,
+        data: sessionData(row.data),
+        expiresAt: finiteDate(row.expires_at),
+      };
+```
+
+The generated JSON read remains `unknown` and the timestamp remains `Date | number`. The projection
+validates both without assertions or edits to generated types. Preserve null separately for nullable
+columns. For an authentication policy requiring finite expiry, `isfinite(expires_at)` excludes both
+infinities before the expiry comparison; `expires_at > now()` alone would accept positive infinity.
+Include such predicates in expiry-sensitive updates/deletes too, and test infinite and expired
+values. This example illustrates representation validation; applications must also retain their
+token verification, revocation, and authorization checks. See
+[JSON and PostgreSQL arrays](mutations.md#json-and-postgresql-arrays) for array write boundaries.
 
 Bigint and `count(*)` reads are decimal strings. Use SQL or BigInt for exact arithmetic and decimal
 strings at JSON boundaries; convert to number only when bounded or approximate values are intended.
@@ -303,14 +475,14 @@ sql.assignments(patch);
 
 Insert fields are required when nonnullable, writable, and without a default. Other writable insert
 fields and all writable update fields are optional and accept explicit undefined, including with
-`exactOptionalPropertyTypes`. Explicit null requires both column and domain-chain permission.
-Domain defaults count; column defaults take precedence.
+`exactOptionalPropertyTypes`. Explicit null requires both column and domain-chain permission. Domain
+defaults count; column defaults take precedence.
 
 Computed and `GENERATED ALWAYS` identity columns use optional `never` fields. Serial and
-`GENERATED BY DEFAULT` identities are optional on insert and writable on update; other primary
-keys remain writable. Use `Pick`/`Omit` for application restrictions. Apply the generated types
-through annotations, `satisfies`, or helper generic arguments; they do not validate constraints,
-JSON structure, authorization, or nonempty input.
+`GENERATED BY DEFAULT` identities are optional on insert and writable on update; other primary keys
+remain writable. Use `Pick`/`Omit` for application restrictions. Apply the generated types through
+annotations, `satisfies`, or helper generic arguments; they do not validate constraints, JSON
+structure, authorization, or nonempty input.
 
 For unverified write mappings, provide a reviewed application-owned replacement, for example
 `Omit<Rows.Insert['events'], 'delay'> & { delay: string }` for interval text input. Selected columns
@@ -319,19 +491,20 @@ can discard required fields; see [the cookbook](mutations.md#input-types-and-run
 ## Query inspection
 
 `describeQuery({ connection, query, session?, timeouts? })` accepts a PostgreSQL URI and a finished
-SQL string or `{ text }` object. It returns PostgreSQL metadata, conservative read mappings and
-row declaration, session context, and coded findings. It does not bind values, execute the
-statement, or verify `sql<Row>`.
+SQL string or `{ text }` object. It returns PostgreSQL metadata, conservative read mappings and row
+declaration, session context, and coded findings. It does not bind values, execute the statement, or
+verify `sql<Row>`.
 
 Inspection owns a separate session with bounded timeouts. Match runtime settings; temporary tables,
-uncommitted changes, and custom parsers are not inherited. Nullability stays unknown. See
+and uncommitted changes are not inherited. Reported mappings assume pg's default parsers; parser
+overrides need matching application types. Nullability stays unknown. See
 [query inspection](query-inspection.md) for settings, result fields, issue codes, and testing.
 
 ## Command reference
 
-Database commands require `DATABASE_URL`. `new` and `--help` work offline. No environment files
-are loaded. Paths are relative to the working directory. Explicit flags unsupported by a command
-are rejected; `--check` is only a generation check, not a migration dry run.
+Database commands require `DATABASE_URL`. `new` and `--help` work offline. No environment files are
+loaded. Paths are relative to the working directory. Explicit flags unsupported by a command are
+rejected; `--check` is only a generation check, not a migration dry run.
 
 ```text
 tenon new <name> [--directory migrations]
@@ -356,10 +529,10 @@ file has down SQL before executing any; `steps` is a positive safe integer. Use
 function bodies and explicit `E'...'` backslash escapes. Nontransactional DDL such as
 `CREATE INDEX CONCURRENTLY` requires a separate procedure.
 
-Migration/status/rollback/adoption use session advisory locks per database and namespace;
-generation uses the same lock in shared mode. Use direct or session-pooled connections and server
-timeouts to bound waits. Baseline capture uses a local creation lock and native `pg_dump`;
-it does not acquire the runner's database advisory lock. See [adoption](adoption-guide.md).
+Migration/status/rollback/adoption use session advisory locks per database and namespace; generation
+uses the same lock in shared mode. Use direct or session-pooled connections and server timeouts to
+bound waits. Baseline capture uses a local creation lock and native `pg_dump`; it does not acquire
+the runner's database advisory lock. See [adoption](adoption-guide.md).
 
 Programmatic `migrate`, `migrationStatus`, and `rollback` accept
 `{ connection, directory?, namespace? }`; rollback also accepts `steps`. Migration/rollback return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",
@@ -54,7 +54,8 @@
     "benchmark": "npm run build && node scripts/benchmark.mjs"
   },
   "dependencies": {
-    "postgres": "3.4.9"
+    "pg": "8.23.1",
+    "@types/pg": "8.23.1"
   },
   "devDependencies": {
     "@types/node": "^24.19.2",

package/dist/driver/array.d.ts

@@ -1,5 +0,0 @@
-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[];