@kequtech/tenon-orm 0.4.0 → 0.4.2

package/docs/connections.md

@@ -0,0 +1,185 @@
+# Connections and driver access
+
+`createTenon` uses a pgclear connection pool. Tenon includes the driver; a separate installation is
+needed only when your application imports native pgclear APIs directly.
+
+## Configure a database instance
+
+```ts
+import { createTenon } from '@kequtech/tenon-orm';
+
+const connection = process.env.DATABASE_URL;
+if (!connection) throw new Error('DATABASE_URL is required');
+
+export const db = createTenon({
+  connection: {
+    connectionString: connection,
+    maxConnections: 10,
+    connectTimeoutMs: 5000,
+    acquireTimeoutMs: 5000,
+    idleTimeoutMs: 30_000,
+    startupParameters: { search_path: 'app,public', TimeZone: 'UTC' },
+  },
+});
+```
+
+`connection` accepts a PostgreSQL URI, pgclear `PoolOptions`, or an existing pgclear `Pool`.
+`ConnectionOptions` is Tenon's alias for `PoolOptions`. Object fields override URI settings.
+Reuse an instance for each database configuration.
+
+The driver does not load environment variables, `.env`, pgpass, or service files. Tenon CLI commands
+read `DATABASE_URL`; application code passes its configuration explicitly. An empty options object
+uses localhost:5432, the current OS user and a database with that user's name.
+
+Use `tls: {}` for TLS with certificate and hostname verification using system trust. Supply the
+provider's CA or other required TLS settings through pgclear's `tls` options. Preserve the
+connection requirements of your deployment. The complete option list is in the installed driver's
+`docs/public-api.md`; unknown options reject.
+
+Qualify table names in SQL or set runtime `search_path`. Tooling `namespace` options select the
+schema to migrate or generate; they do not configure your application's queries. The example above
+assumes an `app` schema already exists.
+
+## Close resources
+
+For a short-lived script, use `try/finally`:
+
+```ts
+try {
+  // Await database work here.
+} finally {
+  await db.close();
+}
+```
+
+For a server, stop accepting work and finish requests before closing the database. A close call
+immediately rejects new Tenon work and gives an owned pool a default 5,000 ms grace period. Set
+`db.close({ timeoutMs: 1000 })` to change it; `0` requests immediate shutdown. Remaining driver work
+and checkouts expire at the deadline. This bounds database resources, not arbitrary JavaScript
+callbacks or proof that a remote rollback completed.
+
+The first valid close call fixes the timeout. Concurrent and later calls share its promise and
+outcome. Timeout must be an integer from 0 to 2,147,483,647 ms; invalid initial options reject
+without closing the instance.
+
+### Use an application-owned pool
+
+When another part of the application already owns a pgclear pool:
+
+```ts
+import { createPool } from '@kequtech/pgclear';
+import { createTenon } from '@kequtech/tenon-orm';
+
+const pool = createPool(connection);
+const db = createTenon({ connection: pool });
+// db.native === pool
+
+await db.close(); // Disables this wrapper; pool remains open.
+await pool.close(); // The application owns the pool's shutdown.
+```
+
+Tenon borrows the supplied pool by identity. Closing the wrapper does not cancel that pool's
+outstanding work. Tool APIs that accept `Connection` follow the same ownership rule.
+
+## Choose output conversions
+
+Outputs follow the pool's codec registry. For example, to read int8 as JavaScript bigint and
+`timestamptz` as Date:
+
+```ts
+import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+
+const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
+const db = createTenon({ connection: { connectionString: connection, codecs } });
+```
+
+These choices apply across the database instance, including callback transactions. Tenon's query
+options have no per-query codec override. Input encoders remain separate: a `param(value, codec)`
+carries its own encoder, and passing a Date does not select a Date output decoder.
+
+Use `db.generateTypes` with this instance to inherit its read mappings. Pass the same registry
+explicitly to `describeQuery` and `checkQueries`; their CLI forms use default codecs. See
+[schema types and values](schema-types.md#custom-codecs) for custom representations and Temporal.
+
+## Observe completed queries
+
+```ts
+const db = createTenon({
+  connection,
+  onQuery(event) {
+    console.log(event.label, event.durationMs, event.outcome, event.rowCount);
+  },
+});
+```
+
+Set `{ label: 'user-by-email' }` on a query to identify it. `onQuery` receives duration, outcome,
+and available command/count/error-code metadata, with no SQL text or bound values. Validation
+failures before execution are not observed. Native driver calls and tooling are outside this hook.
+
+Observers are not awaited. A thrown error or rejected observer promise emits a warning and leaves
+the query outcome unchanged. A successful query event inside a transaction does not mean the outer
+transaction committed. Guarded-call duration includes its commit or rollback work.
+
+## Use native driver features
+
+`db.native` is the actual pgclear pool. Use it for prepared statements, streams, COPY, or held
+sessions. For a finished SQL string:
+
+```ts
+const result = await db.native.queryClassic('SELECT $1::integer AS value', [42]);
+```
+
+Native calls bypass Tenon's result modes, affected-row guards, SQL boundary checks, and `onQuery`.
+They do not join a Tenon callback transaction. A callback's `tx` exposes only `query`.
+
+Use the public driver session APIs and release held leases. For example:
+
+```ts
+await db.native.withSession(async (session) => {
+  const prepared = await session.prepare('SELECT $1::integer AS value');
+  try {
+    await prepared.query<{ value: number }>([42]);
+  } finally {
+    await prepared.close();
+  }
+});
+```
+
+Native `query` accepts pgclear's own SQL tag. Tenon's `sql` and `unsafeSql` results belong in
+`db.query`; use `queryClassic` for text to avoid needing a second tag. When both tags are used,
+import the native one as `pgSql`.
+
+### Listen for notifications
+
+Import `listen` directly from pgclear for a dedicated connection:
+
+```ts
+import { listen } from '@kequtech/pgclear';
+
+const listener = await listen(connection, {
+  channels: ['users_changed'],
+  onNotification: ({ payload }) => console.log(payload),
+  reconnect: true,
+});
+// At shutdown:
+await listener.close();
+```
+
+A listener has a separate lifetime and is not closed by `db.close()`. Notifications are not replayed
+after a disconnection; the application owns its recovery policy.
+
+## Update the driver
+
+Tenon depends on `@kequtech/pgclear: ^0.3.0`, which permits compatible 0.3.x patch updates. With npm:
+
+```sh
+npm update @kequtech/pgclear
+npm ls @kequtech/pgclear
+```
+
+Review the resolved version and lockfile, regenerate affected declarations, and run application
+checks before committing. A lockfile keeps its chosen version until updated. Pgclear 0.4 is outside
+this range and requires an explicit Tenon compatibility update.
+
+If the application imports pgclear directly, declare it as a dependency with a compatible version
+so the package manager can share a copy. See the [changelog](../CHANGELOG.md) when updating Tenon.

package/docs/human-guide.md

@@ -1,26 +1,28 @@
-# Using Tenon: a human guide
+# Getting started
 
-Tenon lets you use PostgreSQL directly from TypeScript. You write SQL; Tenon binds its inputs and
-executes it through pgclear. This guide follows a small application from its first table to reusable
-queries, transactions, and result checking.
+This guide creates a table, inserts and reads a user, reuses a query in a transaction, and generates
+TypeScript types. You need an existing PostgreSQL database. If your application already has tables
+and a migration runner, keep them and start at [Write and read a row](#write-and-read-a-row).
 
-Use the [reference](reference.md) for exact contracts and [adoption](adoption-guide.md) when
-replacing an existing ORM. Code blocks build on the connection and table introduced below;
-query-function examples belong in their own module.
+## Install and connect
 
-## Connect to your database
-
-In an existing Node.js 24+ TypeScript project using ESM:
+Use Node.js 24+, PostgreSQL 16+, ESM, and TypeScript 6+ with Node.js development typings. In an
+existing TypeScript project:
 
 ```sh
 npm install @kequtech/tenon-orm
 ```
 
-Use PostgreSQL 16+ and TypeScript 6+. Keep your existing strict TypeScript configuration and Node
-typings. Tenon includes pgclear 0.3.x. Supply `DATABASE_URL` through your application's
-environment setup; Tenon does not load `.env` files. Import `sql`, `json`, `param`, and codec helpers
-from `@kequtech/tenon-orm` for application queries. See [driver updates](reference.md#driver-updates)
-when updating Pgclear independently.
+Keep the project's TypeScript configuration; a typical Node.js application uses `module: "NodeNext"`
+and `strict: true`. Tenon includes its PostgreSQL driver, pgclear.
+
+Supply `DATABASE_URL` through your environment setup. For a local example database:
+
+```sh
+export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/your_database
+```
+
+Tenon does not create the database or load `.env` files. Create one shared database module:
 
 ```ts
 // src/db.ts
@@ -31,19 +33,18 @@ if (!connection) throw new Error('DATABASE_URL is required');
 export const db = createTenon({ connection });
 ```
 
-Reuse this instance across the application and call `await db.close()` at shutdown. You can also
-supply an existing pgclear `Pool`; your application then owns its shutdown.
+Reuse `db` across requests. Call `await db.close()` when a standalone script finishes or a server
+shuts down. See [connections](connections.md) for pool options and application-owned pools.
 
-## Create a table
+## Create and apply a migration
 
-If you already have a schema and migration runner, keep them. For a fresh example database, create a
-migration:
+In a fresh migrations directory:
 
 ```sh
 npx tenon new create_users
 ```
 
-Fill the generated files:
+This creates two empty files. Put the table definition in the up file:
 
 ```sql
 -- migrations/0001_create_users.up.sql
@@ -54,91 +55,74 @@ CREATE TABLE public.users (
 );
 ```
 
+Put the reverse operation in the down file:
+
 ```sql
 -- migrations/0001_create_users.down.sql
 DROP TABLE public.users;
 ```
 
-For development, add a script to `package.json` that applies migrations and updates generated types:
-
-```json
-{
-  "scripts": {
-    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
-  }
-}
-```
+Apply it to the database selected by `DATABASE_URL`:
 
 ```sh
-npm run db:migrate
+npx tenon migrate
+npx tenon status
 ```
 
-Commit migrations and generated types together. In production, run only `npx tenon migrate`; deploy
-the already-built application. If you do not use generated table types, omit generation from the
-development script. For later schema changes, add a new migration instead of editing an applied one.
-If a change cannot be reversed, omit its down file. A down migration is not a backup.
-
-## Write a query
+For later changes, create a new migration. Applied files are checked against recorded checksums and
+must stay unchanged. If a migration cannot be reversed, remove its down file before applying it.
+See [migrations](migrations.md) for rollback and deployment behavior.
 
-Create a row, then read the fields you need:
+## Write and read a row
 
 ```ts
+// src/example.ts
 import { sql } from '@kequtech/tenon-orm';
 import { db } from './db.js';
 
-const email = 'reader@example.test';
-await db.query(sql`INSERT INTO public.users (email) VALUES (${email})`);
-const user = await db.query(
-  sql<{ id: number; email: string }>`
-    SELECT id, email FROM public.users WHERE email = ${email}
-  `,
-  { returns: 'oneOrNone' },
-);
-```
-
-`${email}` becomes a bound parameter. Do not put quotes around it: the driver passes the value
-separately from the SQL text, even when the value contains SQL.
-
-The type describes one selected row. `returns: 'oneOrNone'` gives you that row or `undefined`; it
-throws if the query returns more than one row. Use `'one'` when absence should also be an error,
-`'many'` for an array, or omit `returns` for the native result object with `.rows`, `.rowCount`, and
-`.fields`. These options do not change your SQL.
-
-`rowCount` is a number or null when the command has no count. SQL `count(*)` and bigint/bigserial
-column values are exact strings, including values beyond JavaScript's safe integer range. Use
-strings, bigint, or pgclear `param(text, builtin.int8)` for int8 parameters. Plain Date and supported
-Temporal inputs also work; they do not change the default string outputs. Date inputs encode in UTC.
-Opt-in codecs can return Date, bigint, or Temporal values when the application needs them.
-
-Generated table types can help describe projections without repeating every field:
-
-```ts
-import type { Database } from './generated-schema.js';
-type UserSummary = Pick<Database['users']['row'], 'id' | 'email'>;
+try {
+  const email = 'reader@example.test';
+  const created = await db.query(
+    sql<{ id: number }>`INSERT INTO public.users (email) VALUES (${email}) RETURNING id`,
+    { returns: 'one' },
+  );
+
+  const user = await db.query(
+    sql<{ id: number; email: string; active: boolean }>`
+      SELECT id, email, active FROM public.users WHERE id = ${created.id}
+    `,
+    { returns: 'oneOrNone' },
+  );
+  console.log(user);
+} finally {
+  await db.close();
+}
 ```
 
-For frequently used types, define [application aliases](reference.md#application-aliases) such as
-`UserRow`, `UserInsert`, and `UserUpdate` in a handwritten module.
+This inserts a new email; rerunning it with the same email will fail the unique constraint. Run it
+through your project's TypeScript runner or compile it with your application. The `.js` imports
+follow NodeNext's convention for compiled TypeScript modules.
 
-You can then write `sql<UserSummary>`. A table type describes the full table; a join or aggregate
-needs a type for what that particular query selects. An annotation is a declaration, not proof that
-the SQL matches. Without one, result fields are `unknown`. Use the inspection and database-test
-workflow below to check the declared contract against the query's behavior.
+The template binds `${email}` separately from the SQL. Do not put quotes around an interpolation.
+`sql<{ id: number }>` describes one returned row; `RETURNING id` asks PostgreSQL to return it.
+`returns: 'one'` requires exactly one row, while `oneOrNone` permits absence as `undefined`.
+Use `many` for an array or omit `returns` for the driver result with `.rows` and `.rowCount`.
 
-Keep storage types conservative and validate them when projecting domain values. The
-[persistence-to-domain example](reference.md#persistence-and-domain-values) shows validated JSON
-writes and reads, temporal strings, and an SQL predicate that rejects infinite session expiry.
+The annotation does not check SQL or validate the row at runtime. Without an annotation, field values
+are `unknown`. Bigint columns and SQL `count(*)` return strings by default; the integer ID in this
+example returns a number. See [value mappings](schema-types.md#value-mappings) for JSON, arrays,
+decimals, and dates.
 
-## Reuse a query with a function
+## Reuse a query
 
-Use an ordinary function when several callers need the same query. An object input makes the
-supplied values easy to read:
+Put reusable queries in ordinary functions. Accept `QueryClient` when a caller may supply either
+`db` or a transaction's `tx`:
 
 ```ts
+// src/queries.ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { Database } from './generated-schema.js';
 
-type UserSummary = Pick<Database['users']['row'], 'id' | 'email'>;
+type UserSummary = { id: number; email: string };
 
 export function userByEmail(client: QueryClient, { email }: { email: string }) {
   return client.query(sql<UserSummary>`SELECT id, email FROM public.users WHERE email = ${email}`, {
@@ -147,12 +131,15 @@ export function userByEmail(client: QueryClient, { email }: { email: string }) {
 }
 ```
 
-Call `userByEmail(db, { email: 'reader@example.test' })` at the call site, or pass a transaction's
-`tx`. Keep the SQL and execution options together in the function.
+Call `userByEmail(db, { email: 'reader@example.test' })`. Keep the SQL and result options together in
+the function. Joins and aggregates work the same way; see [writing queries](sql.md).
 
-## Change data in a transaction
+## Use a transaction and a write guard
+
+In code using the shared `db`:
 
 ```ts
+import { sql } from '@kequtech/tenon-orm';
 import { userByEmail } from './queries.js';
 
 await db.transaction(async (tx) => {
@@ -165,117 +152,86 @@ await db.transaction(async (tx) => {
 });
 ```
 
-Use `tx` for all work in the callback and await it. Tenon commits when the callback succeeds and
-rolls back when an error escapes.
+Run all participating queries through `tx` and await them. The callback commits on success and rolls
+back when an error escapes.
 
-`affectedRows: { exact: 1 }` requires exactly one affected row. `{ max: 1 }` permits zero or one.
-Tenon rolls back a write that violates the bound. You can also use these guards on `db.query`
-outside a callback transaction. The guard checks a count; you still need the correct `WHERE` clause
-and application authorization. Checking returned rows with `returns` alone does not undo an
-autocommitted write.
+The guard requires exactly one affected row and rolls back the update if the count differs. Use
+`{ max: 1 }` to allow zero or one. Guards also work with `db.query` outside a callback. Result modes
+such as `one` check returned rows; by themselves they do not undo an autocommitted write.
 
-## Write objects without building column lists by hand
+You still author the `WHERE` clause and application authorization. The
+[transaction reference](reference.md#transactions-guarded-writes-and-errors) covers caught errors,
+savepoints, and retry limits. For object-based inserts and patches, see [writing data](mutations.md).
 
-Use `sql.insertValues(rowOrRows)` inside an authored `INSERT` and `sql.assignments(patch)` after
-`SET`. Inserts use database defaults for missing/undefined fields; updates omit those fields.
-Explicit `null` stays null. Empty batches and updates throw. Heterogeneous insert rows remain
-aligned, with `DEFAULT` for missing cells.
+## Generate types
 
-```ts
-import type { Database } from './generated-schema.js';
+Generation is optional. It reads the migrated database and writes table read/insert/update types.
+Run it through the configured instance so the types use the same value conversions as your queries:
 
-const input: Database['users']['insert'] = { email: 'another@example.test' };
-await db.query(sql`INSERT INTO public.users ${sql.insertValues(input, ['email'])}`);
-
-const patch: Pick<Database['users']['update'], 'active'> = { active: false };
-await db.query(sql`UPDATE public.users SET ${sql.assignments(patch, ['active'])}
-  WHERE email = ${input.email}`);
+```ts
+// scripts/generate-types.ts
+import { parseArgs } from 'node:util';
+import { db } from '../src/db.ts';
+
+const { values } = parseArgs({ options: { check: { type: 'boolean', default: false } } });
+try {
+  await db.generateTypes({ out: 'src/generated-schema.d.ts', check: values.check });
+} finally {
+  await db.close();
+}
 ```
 
-Use `Pick` to limit editable fields. Keep expressions, predicates, conflict handling, and
-`RETURNING` in SQL. Selected columns choose fields; they do not validate the complete object. See
-[input types](reference.md#insert-and-update-inputs) for mappings and the
-[mutation cookbook](mutations.md) for defaults, batches, and upserts.
+This script runs directly on Node.js 24+ using its TypeScript support. For this execution path,
+`src/db.ts` must be runnable without build-time transformations or extension rewriting. If your
+project compiles scripts, use its normal runner and import conventions instead. To typecheck `.ts`
+imports with `noEmit`, enable `allowImportingTsExtensions`; emitting projects can use
+`rewriteRelativeImportExtensions`.
 
-## Check your SQL and result types
+Add these scripts to your existing `package.json`:
 
-The three database tools answer different questions: `tenon check` compares authored queries with
-their TypeScript contracts, `tenon describe` reports metadata for finished SQL, and
-`tenon generate --check` checks whether saved database declarations are current. See
-[validation tools](reference.md#choosing-a-validation-tool) for their limits.
-
-After migrating a development/test database, run the optional source-aware checker:
-
-```sh
-npx tenon check src/queries.ts
-npx tenon check src/queries.ts:23
+```json
+{
+  "scripts": {
+    "db:generate": "node scripts/generate-types.ts",
+    "db:check-types": "npm run db:generate -- --check",
+    "db:migrate": "tenon migrate && npm run db:generate"
+  }
+}
 ```
 
-A line selects one complete query. Omit the file to check the TypeScript project. The checker reads
-source and types without importing the application or executing SQL. It reports definite
-contradictions and unsupported composition; nullability, JSON members, and other inconclusive
-contracts receive the benefit of the declared type and remain unproven. See
-[query checking](query-checking.md) for supported fragments and explicit object expansion shapes.
-
-Use describeQuery on finished SQL, or tenon describe query.sql, when you only need metadata and a
-conservative row declaration. Match runtime role/session settings. Retain TypeScript and database
-tests for actual rows, effects, permissions, and rollback. The checker does not replace those tests.
-Generated patch types contain optional fields and can therefore be unchecked even when execution is
-valid. Keep optional patches when needed; see [responding to findings](query-checking.md#responding-to-findings).
-For rejected values, result-count errors, and other common failures, see
-[troubleshooting](reference.md#troubleshooting).
-
-## Reuse or assemble parts of SQL when needed
-
-A fragment is a piece of SQL that carries its bound values with it. It is useful when multiple
-queries share a condition. For example, a search can use the same predicate for its result page and
-its count:
+Run `npm run db:generate` now. The output exports a `Database` type:
 
 ```ts
-const pattern = '%example%';
-const limit = 20;
-const search = sql.fragment`active = ${true} AND email ILIKE ${pattern}`;
-const page = sql<UserSummary>`SELECT id, email FROM public.users
-  WHERE ${search} ORDER BY id LIMIT ${limit}`;
-const count = sql<{ count: string }>`SELECT count(*) AS count FROM public.users
-  WHERE ${search}`;
-```
+import type { Database } from './generated-schema.js';
 
-Execute each query with `db.query`. Validate application-supplied patterns and page sizes before
-building queries. The complete query supplies the result type.
-The SQL aggregate's `count` is a string; the native result's `rowCount` counts returned rows.
+type UserRow = Database['users']['row'];
+type UserSummary = Pick<UserRow, 'id' | 'email'>;
+type UserInsert = Database['users']['insert'];
+type UserUpdate = Database['users']['update'];
+```
 
-Use `sql.join` when the number of fragments varies, such as one search condition per word or a set
-of optional filters. It combines fragments with `'AND'`, `'OR'`, or `','` and preserves their bound
-values:
+Use `UserSummary` with `sql<UserSummary>` or `UserInsert` to type an insert input. These types
+follow table columns, defaults, nullability, and codec representations. They do not validate
+application inputs. Keep aliases in handwritten files and leave generated output unchanged.
+See [schema types](schema-types.md) for an output example and mapping details.
 
-```ts
-const terms = ['reader', 'example'];
-const filters = [sql.fragment`active = ${true}`];
-for (const term of terms) {
-  filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
-}
+## Keep schema and code in step
 
-const query = sql<UserSummary>`SELECT id, email FROM public.users
-  WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
-```
+During development, run `npm run db:migrate`, review the generated diff, and commit migrations and
+generated declarations together. Exclude the generated file from automatic formatting.
 
-This matches active users whose email contains every term. With no terms, the active condition still
-applies. For an entirely optional set of filters, omit the whole `WHERE` clause when the list is
-empty:
+In CI, migrate a dedicated test database and check committed output without rewriting it:
 
-```ts
-const optionalFilters = terms.map((term) => sql.fragment`email ILIKE ${'%' + term + '%'}`);
-const unfilteredOrMatching = optionalFilters.length
-  ? sql<UserSummary>`SELECT id, email FROM public.users WHERE ${sql.join(optionalFilters, 'AND')} ORDER BY id`
-  : sql<UserSummary>`SELECT id, email FROM public.users ORDER BY id`;
+```sh
+npx tenon migrate
+npm run db:check-types
+npx tsc --noEmit
 ```
 
-`sql.join` and fragments require nonempty input. Keep mandatory authorization predicates in the
-initial list when applicable; an empty optional-filter list must not remove them. Use parentheses
-when mixing `AND` and `OR`. See the [composition reference](reference.md#sql-fragments-and-joins).
+Do not run the regenerating `db:migrate` script before the freshness check: it would replace the file
+you meant to verify. Production runs migrations and deploys the already-built application.
 
-Use fixed SQL when composition is unnecessary. See the [reference](reference.md) for arrays,
-identifiers, value mappings, CLI options, and error behavior.
-Runtime loops and dynamic fragment lists work during execution but remain unchecked by `tenon check`;
-use database tests for those queries.
+Optionally run `npx tenon check src/queries.ts` against the migrated database to compare source query
+types with PostgreSQL metadata. Keep database tests for rows, permissions, and rollback. See
+[choosing a validation tool](reference.md#choosing-a-validation-tool) and
+[troubleshooting](reference.md#troubleshooting) as needed.