@kequtech/tenon-orm 0.1.1 → 0.1.3

package/docs/agent-guide.md

@@ -1,7 +1,7 @@
 # Tenon agent guide
 
 Tenon executes PostgreSQL SQL through `pg`, with parameter binding, transactions, optional write
-limits, SQL migrations, and generated table row types. Use ordinary functions for reusable queries.
+limits, SQL migrations, and generated row and mutation input types. Use ordinary functions for reusable queries.
 This guide contains the setup and contracts needed for routine implementation; the
 [reference](reference.md) covers additional options.
 
@@ -88,11 +88,9 @@ is an optional nonempty diagnostic string.
   as `'DESC'` remain bound values, not SQL syntax.
 - `sql.fragment` carries SQL and bound values without a row type. Use it for shared predicates or
   partial SQL. Fragments cannot execute alone; full `sql` and `unsafeSql` queries cannot be nested.
-- `sql.join(fragments, separator)` requires a nonempty array of fragments and exactly `'AND'`,
-  `'OR'`, or `','`. No fragment or arbitrary-string separator is accepted. Empty lists and blank
-  fragments throw. Choose empty-filter behavior explicitly.
-- Joins add no parentheses. Group mixed `AND`/`OR` predicates explicitly and preserve authorization
-  conditions when adding optional filters.
+- `sql.join(fragments, separator)` combines a variable-length list of fragments using `'AND'`,
+  `'OR'`, or `','`. Use it for optional filters, search terms, or lists of SQL expressions. The list
+  must be nonempty; group mixed `AND`/`OR` predicates with parentheses.
 - `unsafeSql<Row>(text, values)` accepts trusted external SQL with an explicit values array. Never
   concatenate request input into its text. Each query executes one statement.
 
@@ -106,13 +104,8 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
   WHERE ${search}`;
 ```
 
-`pattern` and `limit` are validated application inputs. To compose existing predicates, use
-`sql.join([first, second], 'AND')`. The checker supports literal join arrays, constant fragments,
-literal/const-string separators, and [official mutation helpers](reference.md#object-based-mutation-fragments).
-It rejects mutable or runtime-dependent SQL structure. Prefer fixed SQL for simple optional filters, e.g.
-`(${email}::text IS NULL OR email = ${email})`. If runtime composition is required, retain an
-explicit result type, suppress `tenon/check-composition` only on that query with a reason, and test
-each branch. Parameter binding alone does not establish result correctness.
+`pattern` and `limit` are validated application inputs. See the
+[composition reference](reference.md#sql-fragments-and-joins) for grouping and list examples.
 
 ## Object-based writes
 
@@ -124,11 +117,14 @@ batches/updates throw; a single default-only insert works. Omit generated column
 writes explicitly below the query-wide limit of 65,535 parameters. Expressions and queries are
 rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
 
-SafeQL reads inline object/array literals directly. Runtime inputs, spreads and data-builder results
-need explicit inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`. Checking
-uses all selected columns conservatively, without interpreting application JavaScript. It verifies
-SQL and result annotations, not input values, constraints, or nonempty runtime input. See the
-[mutation contract](reference.md#object-based-mutation-fragments) and [cookbook](mutations.md).
+Use generated `Rows.Insert['table']` and `Rows.Update['table']` for mutation inputs when available;
+narrow editable fields with `Pick`. They account for defaults, nullability, domains, and generated
+columns. Write mappings differ from returned rows: timestamps use `Date | string`, bigint uses
+`string | bigint`, and JSON uses serialized text. See the [input types](reference.md#insert-and-update-inputs).
+
+Selected columns choose and order fields, e.g. `sql.insertValues(rows, ['name', 'score'])`. Unlisted
+fields are ignored. See the [mutation contract](reference.md#object-based-mutation-fragments) and
+[cookbook](mutations.md).
 
 ## Configure and run SQL checking
 
@@ -140,10 +136,8 @@ Configure it normally and add both exports from `@kequtech/tenon-orm/safeql`:
 - `eslintPlugin` goes in ESLint's `plugins`, with `tenon/check-composition` enabled. It reports
   unsupported forms that the adapter skips. It does not wrap SafeQL's rule.
 
-These tools are optional development tooling; the database runtime does not import them. SafeQL,
-ESLint, and TypeScript are optional peers. The application owns the TypeScript parser configuration
-and imports SafeQL and typescript-eslint itself. Use a TypeScript version supported by the lint
-toolchain. Generated table types are optional and not required by SafeQL.
+These tools run during development and CI. Reuse the application's TypeScript parser settings and
+use a TypeScript version supported by the lint toolchain. Generated table types are optional.
 
 Reuse existing configuration and scripts. For a new setup:
 
@@ -202,6 +196,18 @@ Reuse existing lint scripts or add:
 SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composition errors come from
 `tenon/check-composition`. Keep both rules enabled.
 
+The checker supports constant fragments and `sql.join` with inline nonempty arrays and literal or
+const-string separators. It does not follow runtime-built lists or fragment-returning functions.
+For tested runtime variants, keep an explicit result type and suppress `tenon/check-composition`
+only on the particular query with a reason.
+
+Mutation helpers accept inline object literals for checking. Runtime inputs, spreads, and
+data-builder results need inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`.
+The check uses all selected columns; it does not validate runtime input values or omission decisions.
+
+For existing applications, use the [incremental audit workflow](adoption-guide.md#adopt-sql-checking-incrementally)
+to preview fixes and review database types versus application refinements.
+
 1. Run the development `db:migrate` script below against the intended development/test database.
 2. Run `npm run lint`. Fix SQL mistakes before accepting generated types.
 3. Run `npm run lint:fix` for missing/stale annotations. It can add
@@ -209,38 +215,14 @@ SQL and annotation errors come from `@ts-safeql/check-sql`; unsupported composit
    enabled ESLint rules may also fix files.
 4. Run the application's typecheck and database tests. CI runs `lint` without `--fix`.
 
-For multiple databases, replace the connection object with an array. Each connection has its own
-URL, `plugins: [safeqlPlugin]`, and distinct `targets`, for example `{ tag: 'usersSql' }` and
-`{ tag: 'billingSql' }`. Import `sql as usersSql` and `sql as billingSql` to select them, even
-within one file. Alternatively, scope separate SafeQL configurations with non-overlapping ESLint
-`files` patterns and keep the `sql` tag. Runtime connections remain independent: execute each query
-with the right database instance. The checker does not trace `db.query` destinations.
-
-Qualify tables with their schema when names repeat across schemas in a database. SafeQL can infer
-the wrong type for an unqualified table despite the connection's `search_path`; explicit schema
-names avoid that ambiguity.
-
-The checker recognizes Tenon imports, aliases, and typed object properties. It resolves constant
-fragments and literal/const identifier names without executing application code. Imported
-fragments need inspectable source initializers. It recognizes the official mutation helpers
-directly; it never inspects function bodies or substitutes helper arguments/defaults. Conditional
-fragments, function-generated fragments, and runtime filter lists require narrow explained
-suppressions and database tests. Ordinary functions containing complete `sql` templates remain
-checkable. Keep reusable authorization policy centralized even when it is test-owned rather than
-statically checked. Use literal newlines and bound string values: outer-template JavaScript escapes
-are rejected because SafeQL reads raw text while Tenon executes decoded text. Bound values and
-constant fragments are decoded consistently.
-
-Checking verifies SQL and result annotations, not JavaScript input compatibility, authorization, or
-JSON contents. PostgreSQL owns parameter inference; the checker adds no casts based on JavaScript
-types. `unsafeSql` is unchecked. Never use `any` to hide an unsupported query.
-
-Default scalar mappings: bigint/numeric are strings; JSON is `unknown`; temporal values are
-`Date | number` because infinities are numbers. Generated `PgArray<T>` supports recursive dimensions
-and null elements. Numeric arrays contain numbers and can lose precision. Custom pg parsers and
-recursive array projections need matching checker overrides and tests, for example
-`overrides: { columns: { 'User.tags': 'PgArray<string>' } }` on the SafeQL connection. Import
-`PgArray` from the generated definitions when using that annotation.
+For multiple databases, give each connection distinct tag targets or ESLint file scopes. Qualify
+same-named tables with their schemas. See the [connection reference](reference.md#configuration-choices-and-multiple-databases).
+
+Checking verifies SQL and result annotations. Input validation, authorization, JSON contents, and
+runtime query variants still need application checks and database tests. Keep shared policy in
+ordinary functions even when its fragments cannot be checked statically. Use literal newlines in
+SQL templates and bind string values. The [reference](reference.md#supported-sql-and-limitations)
+covers supported composition and parser overrides.
 
 ## Transactions and writes
 
@@ -273,7 +255,7 @@ development script in `package.json`:
 ```json
 {
   "scripts": {
-    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.ts"
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
   }
 }
 ```
@@ -282,7 +264,7 @@ development script in `package.json`:
 npx tenon new create_users
 # Fill the generated up/down SQL before migrating.
 npm run db:migrate
-npx tenon generate --out src/generated-schema.ts --check
+npx tenon generate --out src/generated-schema.d.ts --check
 npx tenon status
 npx tenon rollback --steps 1
 ```

package/docs/human-guide.md

@@ -59,12 +59,12 @@ CREATE TABLE public."User" (
 DROP TABLE public."User";
 ```
 
-For development, add a script to `package.json` that applies migrations and updates table row types:
+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.ts"
+    "db:migrate": "tenon migrate && tenon generate --out src/generated-schema.d.ts"
   }
 }
 ```
@@ -170,15 +170,23 @@ Explicit `null` stays null. Empty batches and updates throw. Heterogeneous inser
 aligned, with `DEFAULT` for missing cells.
 
 ```ts
-await db.query(sql`INSERT INTO users ${sql.insertValues({ email, active: true })}`);
-await db.query(sql`UPDATE users SET ${sql.assignments({ email, active })} WHERE id = ${id}`);
+import type { Rows } from './generated-schema.js';
+
+const input: Rows.Insert['User'] = { email: 'another@example.test' };
+await db.query(sql`INSERT INTO public."User" ${sql.insertValues(input, ['email'])}`);
+
+const patch: Pick<Rows.Update['User'], 'active'> = { active: false };
+await db.query(sql`UPDATE public."User" SET ${sql.assignments(patch, ['active'])}
+  WHERE email = ${input.email}`);
 ```
 
-These helpers bind values only. Keep expressions, authorization, conflict handling and `RETURNING`
-in SQL. For SafeQL checking of runtime-built objects or batches, supply literal selected columns,
-for example `sql.assignments(patch, ['email', 'active'])`. The checker validates all selected columns
-without inspecting the code that built the patch. See the
-[mutation contract and checking limits](reference.md#object-based-mutation-fragments).
+Generated insert types distinguish required fields from defaults and nullable fields. Update types
+make writable fields optional; use `Pick` to limit what an action may edit. See the
+[input-type reference](reference.md#insert-and-update-inputs) for write-value mappings.
+
+Keep expressions, authorization, conflict handling and `RETURNING` in SQL. Selected column lists
+choose which fields to write; they do not validate the complete object. See the
+[mutation cookbook](mutations.md) for batches and upserts.
 
 ## Check your SQL and result types
 
@@ -188,13 +196,9 @@ There are three different jobs here:
 - TypeScript checks the application code and the result types you declare.
 - SafeQL checks the SQL against your database and verifies or generates those types.
 
-SafeQL is optional development tooling run by ESLint. Configure it normally, with Tenon's
-`safeqlPlugin` adapter to translate queries, constant fragments, and official mutation helpers. A small
-companion ESLint rule, `tenon/check-composition`, flags queries that cannot be checked statically. SafeQL performs the
-database analysis and annotation fixes. Your application's ESLint configuration imports these tools;
-Tenon's database runtime does not need them. Generated table types are a separate convenience and
-are not required by SafeQL. Follow the one-time
-[SQL checking setup](reference.md#sql-checking-with-safeql).
+SafeQL is optional development tooling run by ESLint. Tenon's adapter supports queries, constant
+fragments, and mutation helpers; `tenon/check-composition` reports queries it cannot inspect.
+Follow the one-time [SQL checking setup](reference.md#sql-checking-with-safeql).
 
 Use the application's existing lint commands. If it has none, the setup shows `lint` and `lint:fix`.
 They run ESLint, including all other enabled rules. Once configured, the normal workflow is:
@@ -211,6 +215,12 @@ an incorrect declared result type before the query runs.
 Input validation and database tests still matter. Checking a query does not prove that a request is
 authorized, that its values are valid, or that returned JSON has an application-specific shape.
 
+The checker supports constant fragments and `sql.join` with inline arrays. Runtime-built lists and
+fragment-returning functions remain outside static analysis. Keep result annotations and database
+tests for those queries; when using the checker, suppress `tenon/check-composition` only on the
+tested query with a reason. Runtime-built mutation inputs need inline selected columns for SQL
+checking. See the [checking reference](reference.md#supported-sql-and-limitations) for details.
+
 ## Reuse or assemble parts of SQL when needed
 
 For fixed conditions, write them directly:
@@ -235,36 +245,26 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
 ```
 
 Here `pattern` is an application-supplied search pattern and `limit` is a validated page size.
-Execute each query with `db.query`. A fragment cannot execute alone; the complete query supplies the
-result type. The checker can inspect these constant fragments.
-
-For a simple optional filter, a fixed SQL predicate often suffices:
+Execute each query with `db.query`. The complete query supplies the result type.
 
-```ts
-// email is string | null; null means no email filter.
-const query = sql<UserSummary>`SELECT id, email FROM public."User"
-  WHERE active = ${true} AND (${email}::text IS NULL OR email = ${email})`;
-```
-
-If you need a variable list of conditions, `sql.join` combines fragments using `'AND'`, `'OR'`, or
-`','`. **SafeQL cannot check runtime-built lists.** Keep an explicit result type and test each
-variant; if you use SafeQL, suppress only this query with an explanation. Parameter binding still
-works, but it does not prove that every variant is valid SQL or returns the declared columns.
+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:
 
 ```ts
+const terms = ['reader', 'example'];
 const filters = [sql.fragment`active = ${true}`];
-if (email !== undefined) filters.push(sql.fragment`email = ${email}`);
+for (const term of terms) {
+  filters.push(sql.fragment`email ILIKE ${'%' + term + '%'}`);
+}
 
-// eslint-disable-next-line tenon/check-composition -- Runtime filters are covered by database tests.
 const query = sql<UserSummary>`SELECT id, email FROM public."User"
   WHERE ${sql.join(filters, 'AND')} ORDER BY id`;
 ```
 
-The initial condition keeps this list nonempty. Empty lists throw so that missing filters cannot
-silently remove a condition. `join` adds separators, not parentheses; wrap groups explicitly when
-mixing `AND` and `OR`. Full queries cannot be used as fragments. See the
-[composition reference](reference.md#sql-fragments-and-joins) for static checking rules and other
-details.
+This matches active users whose email contains every term. With no terms, the active condition
+still applies. The list must be nonempty; `join` inserts separators, so use parentheses as usual
+when mixing `AND` and `OR`. See the [composition reference](reference.md#sql-fragments-and-joins).
 
 For arrays, identifiers, type mappings, CLI options, and error behavior, use the
 [reference](reference.md). You do not need fragments or a query builder to use PostgreSQL joins,

package/docs/mutations.md

@@ -19,16 +19,57 @@ The first row uses the score default. The second uses the bio default. Explicit
 row stays null. Columns are aligned across rows. Omit generated columns and let PostgreSQL enforce
 required fields and constraints.
 
-For runtime-built rows, supply an inline column list for SafeQL:
+Use a column list to select and order fields in runtime-built rows:
 
 ```ts
-const rows: { name: string; bio?: string | null; score?: number }[] = buildRows();
+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 uses serialized text.
+See the [input-type reference](reference.md#insert-and-update-inputs) for the complete mapping.
+
+## Input types, SQL checking, 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';
+
+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`);
+}
+```
+
+Here `id` and `score` are assumed to be integers. TypeScript rejects an incompatible typed input
+such as `{ name: 'Ada', score: true }`. SafeQL checks selected columns and `RETURNING`; it does not
+inspect runtime values. Validate external inputs before calling this function and keep database
+constraints and application authorization in place.
+
+**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:
+
+```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.
+```
+
+A column list selects fields; it does not prove that all required fields will be written.
+
 ## Patches mixed with SQL expressions
 
 ```ts
@@ -56,8 +97,7 @@ if (patch.name !== undefined || patch.bio !== undefined) {
 
 ## Preserve an omitted field during an upsert
 
-Use complete query variants when an option changes conflict behavior. Both templates can be
-checked independently; the checker need not choose a JavaScript branch:
+Use separate queries when an option changes conflict behavior:
 
 ```ts
 if (email !== undefined) {
@@ -89,8 +129,8 @@ await db.query(
 ```
 
 Objects used as JSON values retain pg's ordinary JSON conversion. The helper does not infer JSON
-versus array encoding from the table schema. SafeQL's projection checks do not validate stored JSON
-contents or runtime input values.
+versus array encoding from the table schema. Generated JSON input types use serialized text for
+consistent handling of objects and arrays. Validate JSON contents in the application.
 
 ## Batches in one transaction
 
@@ -107,9 +147,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. The query-wide limit is 65,535 bound parameters, including parameters outside
-the mutation fragment. Defaults consume no parameters. Account for your selected column count and
-surrounding query when choosing a batch size; Tenon never splits queries automatically.
-
-Reusable authorization fragments remain valid at runtime. Keep shared policy in application
-functions and test it rather than duplicating it for static coverage. Function-generated SQL,
-conditional fragments, and dynamic filter lists remain outside static checking.
+the mutation fragment. An oversized query reports its actual count, for example
+`at most 65535 bound parameters; received 65536`. Defaults consume no parameters. Account for the
+selected columns and surrounding query when choosing a batch size; Tenon never splits queries automatically.