@kequtech/tenon-orm 0.3.1 → 0.4.2

package/docs/agent-guide.md

@@ -1,167 +1,114 @@
-# Tenon agent guide
+# Agent guide
 
-Tenon executes explicit PostgreSQL SQL through pg. Use ordinary functions for reusable queries. This
-guide covers routine implementation; the [reference](reference.md) defines the full API and the
-[human guide](human-guide.md) gives a step-by-step introduction.
+Use this as a short workflow for changing an existing Tenon application. For first setup, follow
+[Getting started](human-guide.md). Exact contracts are in the [reference](reference.md).
 
-## Start with the existing project
+## Read the project first
 
-Inspect its connection configuration, migration runner, generated types, query functions, and check
-commands. Preserve those conventions. Tenon queries and type generation do not require Tenon
-migration history. Keep input validation, authorization, domain conversion, and retry policy in the
-application.
+Inspect the database module, nearby query functions, migration runner, generated types, and check
+commands. Reuse the application's package manager, connection configuration, namespace, and
+conventions. Read the docs shipped with the installed Tenon version.
 
-For an upgrade, record the previous resolved Tenon version from the lockfile or installed package
-and read the [Changelog](../CHANGELOG.md) entries through the target version before changing code.
-It ships with the package alongside this guide. Follow its upgrade instructions, regenerate types
-when mappings change, and run the project's typechecks and relevant database tests. Use the
-[adoption guide](adoption-guide.md) when replacing another ORM or transferring migration ownership.
+For an upgrade, find the previous resolved version in the lockfile and read the
+[changelog](../CHANGELOG.md) through the target version and follow its API and driver upgrade
+instructions. Check both Tenon and pgclear versions before changing native
+calls or representations.
 
-## Connect
-
-Requires Node.js 24+, PostgreSQL 16+, ESM, TypeScript 6+, and Node development typings. Install with
-`npm install @kequtech/tenon-orm`; retain the project's package manager and TypeScript
-configuration.
-
-```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 });
-```
-
-`connection` accepts a URI string, pg `PoolConfig` (including `connectionString`), or an existing
-`pg.Pool`. Reuse an instance for each database configuration. `db.close()` ends internally created
-pools with a default 5,000 ms grace period; supplied pools remain application-owned. Configure
-shutdown with `db.close({ timeoutMs })`; concurrent callers share its outcome. Finish outstanding
-work before closing. Tenon loads no environment files. Qualify table names or set runtime
-`search_path`; CLI `--namespace` selects tooling scope, not runtime query names. See
-[connection options](reference.md#installation-and-connection).
-
-## Query and result contracts
+## Write a query function
 
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
-import type { Rows } from './generated-schema.js';
+import type { Database } from './generated-schema.js';
 
-type Summary = Pick<Rows['users'], 'id' | 'email'>;
+type Summary = Pick<Database['users']['row'], 'id' | 'email'>;
 
-function userById(client: QueryClient, { id }: { id: number }) {
+export function userById(client: QueryClient, { id }: { id: number }) {
   return client.query(sql<Summary>`SELECT id, email FROM public.users WHERE id = ${id}`, {
     returns: 'oneOrNone',
   });
 }
 ```
 
-`QueryClient` accepts either `db` or a transaction's `tx`. Keep SQL and execution options together.
-`sql<Row>` declares one selected row; it does not verify SQL or validate data. Unannotated fields
-are `unknown`. Generated table types can describe full rows or `Pick` projections; joins and
-aggregates need types for their actual output.
-
-| `returns`          | Result                                             | Required returned rows |
-| ------------------ | -------------------------------------------------- | ---------------------- |
-| `native` (default) | Driver object with `.rows`, `.rowCount`, `.fields` | Any                    |
-| `many`             | Plain `Row[]`                                      | Any                    |
-| `oneOrNone`        | `Row \| undefined`                                 | Zero or one            |
-| `one`              | `Row`                                              | Exactly one            |
-
-Options are `{ returns?, affectedRows?, label? }`; unknown keys fail. Modes do not add SQL limits or
-`RETURNING`. A returned-row mismatch throws `CardinalityError` with code
-`TENON_CARDINALITY_MISMATCH`; it alone does not undo an autocommitted write.
-
-## Parameters and composition
-
-- Interpolate values without quotes. Do not author `$n` placeholders inside templates. `undefined`
-  and `null` bind as SQL null, following pg.
-- Use `id = ANY(${ids}::integer[])` for a set of IDs. Cast standalone parameters such as
-  `SELECT ${value}::integer AS value` when SQL must establish the type for inspection.
-- `identifier(schema, table)` quotes separate approved names. Strings such as `'DESC'` remain bound
-  values; choose SQL syntax through fixed query alternatives or fragments.
-- `sql.fragment` creates partial SQL with bound values; `sql.join(parts, 'AND' | 'OR' | ',')`
-  combines a nonempty list. Blank fragments fail. Group mixed conditions with parentheses.
-- Full `sql` or `unsafeSql` queries cannot be nested. `unsafeSql<Row>(text, values)` is for trusted
-  external SQL with an explicit values array. Each Tenon query executes one statement.
-
-Use fragments for actual reuse or variable composition. Keep fixed structure in SQL, and retain
-mandatory authorization predicates when optional filters are absent.
-
-## Writes and generated values
-
-`sql.insertValues(rowOrRows, columns?)` builds column/value fragments;
-`sql.assignments(patch, columns?)` builds assignments. Missing/undefined insert fields use defaults;
-update fields are omitted. Explicit null stays null. Empty batches and empty assignments fail.
-Selected columns ignore unlisted fields and can discard required inputs. Put expressions, conflict
-policy, and `RETURNING` in the surrounding SQL. Batch in the caller below the query-wide
-65,535-parameter limit.
-
-Use generated `Rows.Insert['users']` and `Rows.Update['users']` inputs; narrow editable fields with
-`Pick`. These types account for defaults, writable columns, domains, and driver representations.
-They do not validate constraints or JSON contents. See [mutation examples](mutations.md).
-
-Use `JSON.stringify(value)` for JSON write inputs; arrays otherwise bind as PostgreSQL arrays.
-Bigint and numeric scalars read as strings, while numeric arrays read as numbers and can lose
-precision. Temporal reads use `Date | number` for finite dates and infinities. SQL NULL array
-elements remain JavaScript null. Keep domain validation at the persistence boundary. See
-[value mappings](reference.md#generated-types-and-checking) and the
-[JSON/finite-date projection](reference.md#persistence-and-domain-values). For authentication policy
-requiring finite expiry, include `isfinite(expires_at)` alongside the SQL expiry comparison.
-
-## Transactions and native access
-
-For an existing user with id 42:
+Use a `QueryClient` parameter when callers may pass `db` or `tx`. Keep SQL and execution options
+together. Qualify table names or follow the configured runtime search path.
+
+- Bind values without quotes. Do not mix manual `$n` placeholders into templates.
+- Declare the actual projection with `sql<Row>`. Generated table rows do not describe arbitrary
+  joins/aggregates, and annotations do not validate runtime output.
+- Choose `many`, `oneOrNone`, `one`, or default `native` deliberately. Modes add no SQL limits.
+  A cardinality error alone does not undo an autocommitted write.
+- Use approved `identifier(...)` names and fixed fragments for SQL syntax. Keep mandatory
+  authorization predicates in every branch.
+- Use fragments for real reuse/composition. Runtime loops work but may remain unchecked by the
+  optional checker. See [writing queries](sql.md).
+
+## Preserve representations and validate inputs
+
+Bigint/bigserial and `count(*)` read as exact strings by default; command `rowCount` is a number or
+null. Decimals and temporal values default to strings, bytes to Uint8Array, and JSON to unknown.
+Built-in arrays preserve scalar representations and null elements.
+
+Plain bigint, valid Date, and supported Temporal inputs are accepted; inputs do not change output
+decoders. Plain arrays/objects require `json`, `param`, or encoded text. Direct undefined rejects.
+JSON encoding still rejects bigint. Import parameter/codec helpers from Tenon.
+
+Use the application's registry for queries and generation, and pass it explicitly to programmatic
+inspection/checking. Retain application validation, authorization, domain conversion, and retry
+policy. See [schema types and values](schema-types.md).
+
+## Change data deliberately
+
+Use `sql.insertValues` and `sql.assignments` for object fields while keeping table, predicates,
+expressions, conflicts, and `RETURNING` in SQL. Apply generated insert/update types and narrow
+editable fields with `Pick`.
+
+Missing/undefined insert fields use defaults; assignment fields are omitted; null remains null.
+Empty batches and assignments reject. Explicit column lists select/order fields and can discard
+required inputs. Batch below the complete query's 65,535-parameter limit. See [writing data](mutations.md).
+
+For work that commits together, use `db.transaction` and await every operation through `tx`. A
+callback client expires when it finishes; root/native pool queries do not join it. Tenon owns
+transaction boundaries and provides no automatic retries.
+
+Use `affectedRows: { exact: n }` or `{ max: n }` for write bounds. A root guard uses a transaction;
+a callback guard uses a savepoint. A rejected guarded operation rolls back before throwing, so a
+caught guard failure permits continued work. An unguarded server error normally aborts the
+transaction. Counts exclude additional trigger/cascade/CTE effects. A lost commit response can
+leave an unknown outcome. See [transactions](reference.md#transactions-guarded-writes-and-errors).
+
+## Make schema changes
+
+Keep an existing migration runner. With Tenon's runner, create a new numbered SQL pair, fill both
+files or omit an irreversible down file, and apply it. Never change applied SQL; checksums include
+both directions. Each file commits separately. Use direct or session pooling for tooling advisory
+locks. See [migrations](migrations.md).
+
+Generate with the configured database instance, after migrations commit:
 
 ```ts
-await db.transaction(async (tx) => {
-  await tx.query(sql`UPDATE public.users SET active = false WHERE id = ${42}`, {
-    affectedRows: { exact: 1 },
-  });
-});
+await db.generateTypes({ out: 'src/generated-schema.d.ts', namespace: 'public' });
 ```
 
-Use `tx` for every operation in the callback and await the work. Tenon commits on success and rolls
-back on an escaping error; the callback client expires when the callback finishes. Direct
-BEGIN/COMMIT/ROLLBACK boundaries, nested callback transactions, and automatic retries are not
-provided. Transactions belong to one database instance.
-
-`affectedRows: { exact: n }` or `{ max: n }` checks the final INSERT/UPDATE/DELETE/MERGE count.
-Bounds are nonnegative safe integers. A guarded `db.query` uses a transaction; a guarded `tx.query`
-uses a savepoint. Rejection rolls back that operation. A caught guarded failure permits continued
-work; an unguarded SQL error normally aborts the transaction. Counts exclude extra trigger/cascade
-and CTE effects. Reserve `tenon_affected_rows_` savepoint names for Tenon. A lost commit
-acknowledgment can leave the outcome unknown.
-
-`db.native` exposes the existing pool for driver features. Native calls bypass Tenon's guards and
-`onQuery`; they do not join a Tenon transaction. Close owned pools through `db.close()`. Follow the
-[native access contract](reference.md#native-driver-access) for resource ownership and LISTEN.
-Optional `onQuery` reports completion metadata without SQL or values; success inside a callback does
-not establish that the outer transaction committed.
-
-## Inspect and validate
-
-Use `describeQuery({ connection, query })` on completed SQL or `tenon describe query.sql` on a file.
-Inspection owns a separate connection. Match the runtime role, search path, and timezone. Temporary
-tables and transaction-local state are not inherited; reported mappings assume pg's default parsers.
-Result nullability is unknown and JSON structure is unchecked. A successful description does not
-verify `sql<Row>`, bound values, execution permission, or effects.
-
-Pair inspection with database assertions for complete relevant rows, meaningful query variants, and
-rollback. A small query-building function can share the same statement with inspection and
-execution; keep simple queries inline when that is sufficient. See
-[query inspection](query-inspection.md).
-
-## Schema changes
-
-With Tenon's runner, development can use
-`tenon migrate && tenon generate --out src/generated-schema.d.ts`. Commit migrations and exact
-generated output together; exclude the generated file from automatic formatting. Production runs
-migrations and deploys committed types. `generate --check` detects representation drift, not pending
-migrations or every schema change.
-
-All database CLI commands require `DATABASE_URL`. `tenon new <name>` creates empty up/down files
-offline; fill them before migrating. Migration commands use `--directory migrations` and
-`--namespace public` by default; generation also accepts `--namespace`. Pass a custom namespace to
-both migration and generation. Omit the down file for an irreversible migration; never edit applied
-history. Each file commits independently with its history entry. Tools use session advisory locks,
-so use a direct or session-pooled connection. Nontransactional DDL needs a separate procedure. See
-the [command reference](reference.md#command-reference).
+Use the project's [generation script](human-guide.md#generate-types), review the diff, and commit
+migrations with exact generated output. Keep handwritten aliases separate and generated files out
+of formatting. In CI, migrate the test database and use `check: true` without first regenerating.
+Production consumes committed declarations.
+
+## Verify the changed workflow
+
+Run the project's typecheck and database tests for actual rows, effects, permissions, and rollback.
+Use `tenon check` for source contracts and `tenon describe` for finished SQL metadata when useful.
+See [validation tools](reference.md#choosing-a-validation-tool).
+
+The checker fails on definite mismatches and unchecked sites; unproven properties remain notes.
+Fixed composition is supported within bounded variants. Object expansion needs an explicit finite
+shape with required, defined selected fields; optional generated patches may be unchecked. Keep
+intentional omission behavior and test it. Narrow to required fields only when application validation
+establishes that contract; do not cast merely to silence a diagnostic. See
+[responding to findings](query-checking.md#responding-to-findings).
+
+Match the runtime role, search path, timezone, and codecs. Describe uses a separate session and
+cannot establish result nullability, JSON members, cardinality, or execution permissions. Native
+calls bypass Tenon's guards/observations and need explicit resource ownership; see
+[connections and driver access](connections.md). For common failures, use
+[troubleshooting](reference.md#troubleshooting).

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.