@kequtech/tenon-orm 0.2.1 → 0.3.0

package/docs/mutations.md

@@ -1,8 +1,18 @@
 # Mutation cookbook
 
-Keep SQL structure visible and let the official helpers handle object fields. See the
-[reference](reference.md#object-based-mutation-fragments) for the complete contract. Examples use
-application-owned inputs and clients; add the authorization predicates required by your product.
+Use `sql.insertValues` and `sql.assignments` for object fields while keeping SQL structure visible.
+The [reference](reference.md#object-based-mutation-fragments) defines the complete contract.
+Examples assume an existing `db` and this table, with generated `Rows` from the same schema:
+
+```sql
+CREATE TABLE profiles (
+  id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name text NOT NULL UNIQUE,
+  bio text DEFAULT 'unwritten',
+  score integer NOT NULL DEFAULT 0,
+  revision integer NOT NULL DEFAULT 0
+);
+```
 
 ## Defaults, undefined, and null in batches
 
@@ -12,36 +22,16 @@ await db.query(
     { name: 'Ada', bio: null },
     { name: 'Lin', score: 4, bio: undefined },
   ])} RETURNING id`,
+  { returns: 'many' },
 );
 ```
 
-The first row uses the score default. The second uses the bio default. Explicit null in the first
-row stays null. Columns are aligned across rows. Omit generated columns and let PostgreSQL enforce
-required fields and constraints.
-
-Use a column list to select and order fields in runtime-built rows:
-
-```ts
-import type { Rows } from './generated-schema.js';
-
-const rows: Rows.Insert['profiles'][] = buildRows();
-await db.query(sql`INSERT INTO profiles ${sql.insertValues(rows, ['name', 'bio', 'score'])}`);
-```
-
-This list selects and orders fields; unlisted fields are ignored. It does not assert that the
-entire input object contains only allowed keys. Keep narrower application input validation.
-
-`tenon generate` also provides `Rows.Update['profiles']`. Use `Pick` to limit a patch to fields
-the caller may edit, for example `Pick<Rows.Update['profiles'], 'name' | 'bio'>`. Generated inputs
-understand defaults, nullability, domains, and generated columns. They use write representations:
-timestamps accept `Date | string`, bigint accepts `string | bigint`, and JSON accepts native JavaScript values through Tenon's exported `JSONValue` type.
-See the [input-type reference](reference.md#insert-and-update-inputs) for the complete mapping.
+Ada gets the score default and SQL null for bio. Lin gets score 4 and the bio default. Columns stay
+aligned across heterogeneous rows. Empty batches fail; a single default-only object emits
+`DEFAULT VALUES` and still depends on the table's required-column rules.
 
 ## Input types and runtime validation
 
-Apply input types with an annotation, `satisfies`, or a helper generic argument. Generating the
-file alone does not check every write. Narrow the fields each operation accepts:
-
 ```ts
 import { sql, type QueryClient } from '@kequtech/tenon-orm';
 import type { Rows } from './generated-schema.js';
@@ -49,46 +39,44 @@ import type { Rows } from './generated-schema.js';
 type ProfileInput = Pick<Rows.Insert['profiles'], 'name' | 'score'>;
 
 function createProfile(client: QueryClient, input: ProfileInput) {
-  return client.query(sql<{ id: number }>`INSERT INTO profiles
-    ${sql.insertValues(input, ['name', 'score'])} RETURNING id`);
+  return client.query(
+    sql<{ id: number }>`INSERT INTO profiles
+    ${sql.insertValues(input, ['name', 'score'])} RETURNING id`,
+    { returns: 'one' },
+  );
 }
 ```
 
-Here `id` and `score` are assumed to be integers. TypeScript rejects an incompatible typed input
-such as `{ name: 'Ada', score: true }`. Inspect the completed SQL with `describeQuery` and test its
-returned rows and write effects against the database. Validate external inputs before calling this
-function and keep database constraints and application authorization in place.
+Annotations, `satisfies`, or helper generic arguments apply generated input types; merely generating
+the file does not check writes. Use `Pick` to narrow accepted fields and retain runtime validation.
+Generated inputs describe defaults and driver representations, not authorization or constraints.
 
-**Selected columns can discard required fields.** For a table requiring integer `id` and text
-`name` and `location`, this input is valid but the query fails:
+Selected columns choose and order fields, ignoring unlisted keys. They can discard a required field
+even when the original object is valid:
 
 ```ts
-const row: Rows.Insert['profiles'] = { id: 1, name: 'Ada', location: 'London' };
-const query = sql`INSERT INTO profiles ${sql.insertValues(row, ['id', 'name'])}`;
-// PostgreSQL rejects the insert: location was dropped and has no default.
+const input: Rows.Insert['profiles'] = { name: 'Ada' };
+const query = sql`INSERT INTO profiles ${sql.insertValues(input, ['bio', 'score'])}`;
+// Executing this fails: name was discarded and has no default.
 ```
 
-A column list selects fields; it does not prove that all required fields will be written.
-
-## Patches mixed with SQL expressions
+## Patches mixed with expressions
 
 ```ts
-await db.query(sql`UPDATE profiles
-  SET ${sql.assignments({ name, bio })}, revision = revision + 1, score = DEFAULT
+const patch: Pick<Rows.Update['profiles'], 'name' | 'bio'> = { bio: null };
+await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
   WHERE id = ${id}`);
 ```
 
-Undefined fields are omitted; null clears a field. Expressions, `DEFAULT`, and references to
-`excluded.column` belong in SQL, not in mutation objects.
+Missing/undefined fields are omitted; null clears a nullable field. Put arithmetic and
+`column = DEFAULT` in SQL. Helpers accept values, not SQL expression objects.
 
-An empty patch throws even if the surrounding statement has other assignments. Choose an
-expression-only query explicitly when that is the intended behavior:
+An empty patch fails even if the surrounding SQL has other assignments. Branch when an
+expression-only update is intended:
 
 ```ts
-const patch: { name?: string; bio?: string | null } = readPatch();
 if (patch.name !== undefined || patch.bio !== undefined) {
-  await db.query(sql`UPDATE profiles
-    SET ${sql.assignments(patch, ['name', 'bio'])}, revision = revision + 1
+  await db.query(sql`UPDATE profiles SET ${sql.assignments(patch)}, revision = revision + 1
     WHERE id = ${id}`);
 } else {
   await db.query(sql`UPDATE profiles SET revision = revision + 1 WHERE id = ${id}`);
@@ -97,44 +85,40 @@ if (patch.name !== undefined || patch.bio !== undefined) {
 
 ## Preserve an omitted field during an upsert
 
-Use separate queries when an option changes conflict behavior:
+Given validated `name`, `score`, and optional `bio`, choose conflict behavior explicitly:
 
 ```ts
-if (email !== undefined) {
-  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app, email })}
-    ON CONFLICT (profile_id) DO UPDATE
-    SET in_app = excluded.in_app, email = excluded.email`);
+if (bio !== undefined) {
+  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score, bio })}
+    ON CONFLICT (name) DO UPDATE SET score = excluded.score, bio = excluded.bio`);
 } else {
-  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app })}
-    ON CONFLICT (profile_id) DO UPDATE SET in_app = excluded.in_app`);
+  await db.query(sql`INSERT INTO profiles ${sql.insertValues({ name, score })}
+    ON CONFLICT (name) DO UPDATE SET score = excluded.score`);
 }
 ```
 
-The second query leaves an existing email value unchanged. Missing an insert field uses its
-database default; that alone does not decide what an upsert should overwrite.
+The second query preserves an existing bio. Omitting an insert value uses its database default; that
+alone does not decide which fields a conflict update overwrites.
 
-## JSONB arrays and PostgreSQL arrays
+## JSON and PostgreSQL arrays
 
-SQL context determines whether a bound JavaScript array is a PostgreSQL array or a JSON value.
-Pass native JavaScript values; Postgres.js serializes them for the target type:
+For a table with `payload jsonb` and `tags text[]`, encode JSON separately from the PostgreSQL
+array:
 
 ```ts
-const handles = ['ada', 'lin'];
+const tags = ['ada', 'lin'];
 await db.query(
-  sql`INSERT INTO deliveries ${sql.insertValues({
-    recipients_json: handles, // jsonb column
-    recipient_handles: handles, // text[] column
-  })}`,
+  sql`INSERT INTO deliveries ${sql.insertValues({ payload: JSON.stringify(tags), tags })}`,
 );
 ```
 
-Objects used as JSON values retain Postgres.js's ordinary JSON conversion. The helper does not need runtime schema metadata. Generated JSON input types use Tenon's exported
-`JSONValue` type, excluding SQL null for nonnullable columns. Pre-serialized text becomes a JSON
-string; use SQL such as `'null'::jsonb` when JSON null is required. Validate JSON contents in the application.
+Generated JSON writes accept encoded JSON strings. Use `JSON.stringify(value)` for objects, arrays,
+strings, and JSON null; a bound JavaScript null means SQL null. Arrays passed directly are
+PostgreSQL arrays. Tenon leaves serialization to pg.
 
 ## Batches in one transaction
 
-Choose the batch size in the caller and keep all writes on the transaction client:
+For an array `rows` of generated profile inputs:
 
 ```ts
 await db.transaction(async (tx) => {
@@ -145,8 +129,6 @@ await db.transaction(async (tx) => {
 });
 ```
 
-A failure rolls back all batches. The helper rejects an empty batch; this loop makes no insert
-calls for empty input. Each query accepts at most 65,533 bound parameters, including parameters outside
-the mutation fragment. An oversized query reports its actual count, for example
-`at most 65533 bound parameters; received 65534`. Defaults consume no parameters. Account for the
-selected columns and surrounding query when choosing a batch size; Tenon never splits queries automatically.
+A failure rolls back all batches. Empty input makes no insert calls. Choose a batch size below the
+query-wide 65,535-parameter limit, including surrounding parameters; default cells consume none.
+Tenon does not split batches or choose transaction boundaries for you.

package/docs/query-inspection.md

@@ -1,12 +1,10 @@
 # Inspect and test queries
 
-`describeQuery` asks PostgreSQL what a completed SQL statement accepts and returns, without
-binding its values or executing it. Use it while writing a query or in a database test. It handles
-the actual SQL produced by fragments, helpers, loops, and conditional filters.
-Its `postgres` driver installs with Tenon; no extra
-consumer dependency or configuration is needed. Calling inspection opens a separate connection.
+`describeQuery` asks PostgreSQL for a completed statement's parameter/result metadata without
+binding its values or executing it. Inspection is included with Tenon and opens a separate,
+short-lived connection. It works with SQL assembled from fragments and mutation helpers.
 
-## Inspect the query you will execute
+## Inspect completed SQL
 
 ```ts
 import { describeQuery, sql } from '@kequtech/tenon-orm';
@@ -18,111 +16,121 @@ const query = sql<{ id: number; total: string }>`
   SELECT ${42}::integer AS id, count(*) AS total FROM pg_catalog.pg_class
 `;
 const description = await describeQuery({ connection, query });
-// description.columns reports number/string read types; nullability remains unknown.
 ```
 
-For an application, pass the same query object that will go to `db.query`. Use representative inputs when calling its query-building
-function. Keep authorization policy centralized inside that builder or its fragments.
+`query` accepts SQL text or an object with `text`, including `SqlQuery`. Pass the same completed
+query to inspection and execution. Strings use PostgreSQL `$1` placeholders; templates use
+`${value}`. Cast standalone parameters so PostgreSQL can infer their types without runtime values.
+Inspection does not read `sql<Row>`, check `query.values`, or compare an annotation with SQL.
 
-`query` accepts a SQL string or an object with a `text` property, including a Tenon `SqlQuery`.
-For SQL strings, use PostgreSQL placeholders such as `$1`. PostgreSQL infers their types from SQL
-context; `SELECT $1::integer AS id` can be described without supplying a value. Ordinary Tenon
-templates bind values with `${value}`.
-
-Inspection does not read the type argument of `sql<Row>`, validate `query.values`, or compare an
-annotation with the result. A successful description is useful schema/type evidence, not proof
-that the query will execute or do the intended job.
-
-## Match the application's context
+## Session and timeouts
 
 ```ts
 const description = await describeQuery({
   connection,
   query,
-  session: { searchPath: 'mail,public', timeZone: 'UTC' },
+  session: { searchPath: 'app,public', timeZone: 'UTC' },
   timeouts: { connectMs: 3000, statementMs: 5000, lockMs: 1000 },
 });
 ```
 
-Reuse the application's connection URI and the source of its session settings. All overrides are
-optional. Connection URI startup options are preserved. `session.role` can assume a role when the
-connecting account has permission; omitted settings use the new connection's defaults. `SET ROLE`
-does not load that role's login defaults. Unknown options and invalid settings fail explicitly.
-
-The result's `context` reports the database, login/effective roles, configured and resolved search
-paths, timezone, and effective server timeouts. Compare these with the execution connection.
-Inspection reports `mode: 'separate-session'` and `readMappings: 'postgres'`. SQL NULL array
-elements are represented as JavaScript null.
-
-The default connection/authentication limit is 3 seconds. Every server statement, including
-metadata reads, has a 5-second limit, and each lock wait a 1-second limit. Cleanup is bounded to
-1 second. Timeout overrides are positive integer milliseconds; URI settings cannot disable these
-bounds. Limits apply to individual operations, not one overall deadline.
-
-The API owns and closes its connection. It does not borrow an application client or a Tenon transaction.
-Temporary tables, uncommitted changes, transaction-local settings, custom parsers, and other
-pool-only state are not inherited. `PGOPTIONS` environment settings are not automatically copied;
-use URI startup options or explicit session values. Standard read mappings describe Postgres.js
-values, so custom parser behavior needs a deliberate application decision.
-
-## Read the result
-
-| Field                   | Meaning                                                                                                                                                                     |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parameters`            | Parameter type OIDs, qualified PostgreSQL type names, and Postgres.js read representations. These are not accepted JavaScript input contracts.                              |
-| `columns`               | Ordered output names, PostgreSQL types, Postgres.js read representations, and source-column metadata where available.                                                       |
-| `columns[].nullability` | Always `"unknown"`. A source column's `notNull` constraint does not establish result nullability.                                                                           |
-| `rowType`               | A conservative `DescribedRow` TypeScript declaration. Fields include null; JSON/unmapped types stay unknown. Null when there are no output columns or names are duplicated. |
-| `issues`                | Findings with stable `code` fields, human-readable messages, and relevant column/type details.                                                                              |
-| `context`               | The separate inspection session's effective settings and read mapping profile.                                                                                              |
-
-Use issue codes for tooling; message text is descriptive:
-
-- `nullability-unknown`: result nullability has not been established.
-- `shape-unknown`: listed columns have unknown read types; JSON object structure is not inferred.
-- `unmapped-type`: the PostgreSQL type/OID lacks a verified Postgres.js mapping.
-- `duplicate-column`: repeated names would overwrite earlier values in object rows.
-
-Source `notNull` remains informational. Outer joins, grouping, and expressions can introduce nulls.
-An empty result set supplies no runtime samples. Unknown mappings and duplicate names are findings
-to handle explicitly, not a successful verification of a handwritten result type.
+Reuse the runtime URI and session settings. Optional `session.role` uses SET ROLE when permitted; it
+does not load that role's login defaults. Omitted settings use the inspection connection's defaults.
+Explicit undefined behaves like omission. Unknown keys and invalid settings fail.
+
+`context` reports login/effective roles, configured/resolved search paths, timezone, database, and
+effective statement/lock timeouts. Its mode is `separate-session` and read mapping profile is `pg`;
+reported read types assume pg's default parsers and do not infer application overrides. Temporary
+tables, uncommitted changes, and transaction-local settings are not inherited. pg reads its normal
+connection environment, including `PGOPTIONS` when URI options are absent. Use explicit URI/session
+settings for reproducibility.
+
+Defaults are a 3-second connection/authentication timeout, a 5-second limit per server statement,
+and a 1-second lock wait. Overrides are positive integer milliseconds, at most 2,147,483,647. URI
+settings cannot disable the statement/lock bounds. A URI `query_timeout` remains pg's separate
+client read timeout. The owned client closes after inspection. These are operation limits, not a
+single overall deadline.
+
+## Result fields
+
+| Field                   | Meaning                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `parameters`            | OIDs, qualified PostgreSQL names, and read representations; not JavaScript input contracts |
+| `columns`               | Ordered names, PostgreSQL types, read representations, and source metadata where available |
+| `columns[].nullability` | Always `"unknown"`; source `notNull` is informational                                      |
+| `rowType`               | Conservative `DescribedRow` declaration, or null for no columns/duplicate names            |
+| `issues`                | Findings with stable `code` fields and descriptive messages                                |
+| `context`               | Effective inspection-session settings                                                      |
+
+Known read types in `rowType` include null; unknown types already include it. Source constraints
+cannot establish result nullability through joins, expressions, or grouping. JSON structure stays
+unknown. Handle findings by code:
+
+| Code                  | Meaning                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `nullability-unknown` | Result nullability is unresolved                                |
+| `shape-unknown`       | Listed output columns have unknown shapes/read types            |
+| `unmapped-type`       | A parameter or result type has no verified driver mapping       |
+| `duplicate-column`    | Repeated result names would overwrite earlier object properties |
+
+## Test the same statement
+
+For the `public.users` table from the [human guide](human-guide.md), assume a dedicated test fixture
+has rows `{ id: 1, email: 'ada@example.test', active: true }` and
+`{ id: 2, email: 'lin@example.test', active: false }`, and `db` is its runtime connection:
+
+```ts
+import assert from 'node:assert/strict';
+
+function usersQuery(activeOnly: boolean) {
+  const filters = [sql.fragment`email LIKE ${'%@example.test'}`];
+  if (activeOnly) filters.push(sql.fragment`active = ${true}`);
+  return sql<{ id: number; email: string }>`SELECT id, email FROM public.users
+    WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
+}
+
+const ada = { id: 1, email: 'ada@example.test' };
+const lin = { id: 2, email: 'lin@example.test' };
+for (const activeOnly of [false, true]) {
+  const query = usersQuery(activeOnly);
+  const description = await describeQuery({ connection, query });
+  assert.deepEqual(
+    description.columns.map(({ name, readType }) => [name, readType]),
+    [
+      ['id', 'number'],
+      ['email', 'string'],
+    ],
+  );
+  assert.deepEqual(
+    description.issues.map(({ code }) => code),
+    ['nullability-unknown'],
+  );
+  assert.deepEqual(await db.query(query, { returns: 'many' }), activeOnly ? [ada] : [ada, lin]);
+}
+```
+
+Description and execution establish different facts. Describe can succeed for invalid bound values,
+a write that violates constraints, or an operation the runtime role cannot execute. Check actual
+rows/effects, JSON, permissions, and rollback in database tests, and run TypeScript. Inspect
+meaningful query variants; one instance does not cover unexercised branches. Expect only reviewed
+findings and keep unexpected ones visible.
 
 ## CLI
 
-Save the statement in `query.sql`, using `$1`, `$2`, and so on for parameters:
+Save SQL with PostgreSQL placeholders in `query.sql`:
 
 ```sql
 SELECT $1::integer AS id, count(*) AS total FROM pg_catalog.pg_class;
 ```
 
-Supply `DATABASE_URL` through the application's normal environment setup:
-
 ```sh
 npx tenon describe query.sql
-npx tenon describe query.sql --search-path mail,public --time-zone UTC
+npx tenon describe query.sql --search-path app,public --time-zone UTC
 ```
 
-The CLI prints the description as JSON. Options are `--role`, `--search-path`, `--time-zone`,
-`--connect-timeout-ms`, `--statement-timeout-ms`, and `--lock-timeout-ms`. Migration/generation
-options such as `--namespace` and `--check` are rejected. No environment files are loaded.
-
-Exit code 0 means PostgreSQL described the statement, even if the report contains unresolved
-issues. Exit code 1 means input, connection, timeout, or PostgreSQL analysis failed. No query values
-are bound and no inspected statement is executed, including writes and locking statements.
-
-## Keep execution assertions
-
-For each meaningful query-builder variant, describe the finished SQL and run it through the
-application's actual Tenon/Postgres.js connection against its test database. Assert complete relevant rows
-and effects: nulls, JSON contents, precision, ordering, empty results, ownership, and rollback.
-Include absent relationships, pagination ties, and empty aggregates where relevant. Keep those
-tests alongside the query and run the application's normal TypeScript compiler.
-
-Description can succeed for an invalid bound value, a write that violates a constraint, or an
-operation the runtime role may not execute. Execution tests establish behavior for the exercised
-inputs; they are not a proof for every possible input. Inspecting one variant does not cover
-other branches or detect stale TypeScript annotations elsewhere in the application.
+The CLI uses `DATABASE_URL` and prints JSON. Session flags are `--role`, `--search-path`, and
+`--time-zone`. Timeout flags are `--connect-timeout-ms`, `--statement-timeout-ms`, and
+`--lock-timeout-ms`. Migration/generation flags such as `--namespace` and `--check` are rejected.
 
-Describe does not bind runtime values. Cast standalone parameter projections, for example
-`SELECT $1::boolean AS enabled`, so SQL establishes their types. Execution can otherwise infer a
-type from a JavaScript value that an inspection without values cannot establish.
+Exit 0 means description succeeded, including reports with unresolved findings. Exit 1 means input,
+connection, timeout, or PostgreSQL analysis failed. The inspected statement is never executed.