@kequtech/tenon-orm 0.1.0 → 0.1.2

package/docs/reference.md

@@ -131,12 +131,105 @@ const query = sql<{ id: number }>`SELECT id FROM public."User" WHERE ${condition
 Each fragment use receives correctly ordered parameters, including repeated and nested uses. SQL
 strings and comments containing literal `$1` text are left intact.
 
-Static checking supports constant fragments, literal join arrays, and literal or const-string
-separators. Runtime-built lists and selected fragments execute safely with respect to parameter
-binding, but the checker cannot verify their SQL or result types. Prefer fixed SQL when it fits.
+Static checking supports constant fragments, literal join arrays, literal or const-string
+separators, and [official mutation helpers](#object-based-mutation-fragments). Runtime-built lists
+and selected fragments execute safely with respect to parameter binding, but the checker cannot
+verify their SQL or result types. Prefer fixed SQL when it fits.
 Otherwise keep an explicit result annotation, use a narrow explained lint suppression, and test
 every variant.
 
+## Object-based mutation fragments
+
+`sql.insertValues(input, columns?)` and `sql.assignments(input, columns?)` return fragments. Keep the
+operation, table, authorization predicate, conflict policy, expressions, and `RETURNING` in SQL:
+
+```ts
+const created = await db.query(
+  sql<{ id: number }>`
+  INSERT INTO profiles ${sql.insertValues([
+    { name: 'Ada', bio: null },
+    { name: 'Lin', score: 4 },
+  ])}
+  ON CONFLICT (name) DO NOTHING
+  RETURNING id
+`,
+  { returns: 'many' },
+);
+
+await db.query(sql`
+  UPDATE profiles SET ${sql.assignments({ name: input.name, bio: input.bio })},
+    revision = revision + 1
+  WHERE id = ${id} AND owner_id = ${viewer}
+`);
+```
+
+Both helpers accept plain objects (including null-prototype objects), quote each column as one
+identifier, and bind cell values as data. Inputs are read when the fragment is created; replacing a
+field afterward does not change its captured value. Nested values retain the driver's usual
+serialization behavior. Only own data properties are read; accessors are rejected.
+
+| Input                                        | Insert behavior                    | Assignment behavior                     |
+| -------------------------------------------- | ---------------------------------- | --------------------------------------- |
+| Missing or `undefined` field                 | PostgreSQL `DEFAULT` for that cell | Omitted; the stored column is unchanged |
+| Explicit `null`                              | Bound SQL null                     | Bound SQL null                          |
+| Other value                                  | Bound parameter                    | Bound parameter                         |
+| SQL fragment, identifier, or query as a cell | Rejected                           | Rejected                                |
+
+Without `columns`, inserts infer the union of enumerable keys with defined values across all rows,
+in first-seen order. Heterogeneous rows stay aligned; missing cells use `DEFAULT`. One object or a
+one-row batch with no defined fields emits `DEFAULT VALUES`. An empty batch throws. A multi-row
+batch with no inferred columns throws; supply explicit columns to emit multiple default rows.
+
+Assignments infer enumerable keys and omit undefined values. An empty object or a selection with
+no defined values throws, so the helper never emits an empty `SET` clause. This also applies when
+the surrounding statement contains arithmetic or other assignments: branch explicitly when the
+intended update consists only of those expressions.
+
+An optional nonempty column list selects and orders fields. It does not validate that the input
+object has no additional keys. Unlisted fields are ignored; missing insert cells use `DEFAULT`,
+while missing update fields are omitted. Duplicate or invalid column
+names throw. TypeScript checks selected names against the input's known keys. The list is also the
+way to make runtime objects and batches available to static SQL checking:
+
+```ts
+const rows: { name: string; bio?: string | null }[] = buildRows();
+const insert = sql`INSERT INTO profiles ${sql.insertValues(rows, ['name', 'bio'])} RETURNING id`;
+
+const patch: { name?: string; bio?: string | null } = readPatch();
+const update = sql`UPDATE profiles SET ${sql.assignments(patch, ['name', 'bio'])} WHERE id = ${id}`;
+```
+
+The helpers have no runtime schema metadata. Use [generated input types](#insert-and-update-inputs)
+or application-owned contracts to check JavaScript values; PostgreSQL enforces identity,
+generation, required-column, and constraint rules. Retain application validation.
+To reset an update field to its default, write `column = DEFAULT` in the
+surrounding SQL. Put arithmetic and `excluded.column` expressions there too; these helpers accept
+values only, with no expression/default sentinel.
+
+A compiled query, including surrounding interpolations, is limited to 65,535 bound parameters.
+Tenon rejects larger queries and does not split them automatically. Choose batch sizes and
+transaction boundaries in the caller. Helper validation errors identify invalid rows/columns
+without printing cell values.
+
+### Checking mutation fragments
+
+SafeQL recognizes these official helpers directly through their Tenon function declarations,
+including aliases. It never analyzes their implementation or executes application data builders.
+Without an explicit column list, checking accepts inline object literals and inline insert arrays
+of object literals. Keys must be literal names; object spreads, computed keys, methods, accessors,
+and objects stored in variables require an explicit inline column list. Existing constant string
+resolution works for entries of that list; column arrays stored in variables are unsupported.
+
+For runtime inputs with explicit columns, the checker analyzes a representative nonempty insert
+row or assignment list containing **all selected columns**. This checks column references, SQL
+composition, conflict clauses, and `RETURNING` annotations. Runtime omission/default decisions and
+batch length do not require interpreting JavaScript. The check is conservative: an optional
+selected column is checked even when a particular runtime call omits it. It does not establish
+nonempty input, valid runtime values, successful constraints, or every default's behavior; runtime
+validation and database tests cover those contracts. Unknown inputs without explicit columns
+produce `tenon/check-composition` diagnostics. See the [mutation cookbook](mutations.md) for
+empty patches, conditional upserts, arrays, and batching.
+
 ## Transactions, guarded writes, and errors
 
 ```ts
@@ -184,42 +277,84 @@ transaction has committed.
 
 `generateDefinitions({ connection, namespace?, onWarning? })` returns TypeScript source for the
 connected schema. It does not need migration files or history. Table type generation is optional.
-SafeQL reads the database directly and does not require these generated files; they are useful when
-reusing table row shapes. The CLI writes that source atomically. This command checks the existing
-file without rewriting it:
+SafeQL reads the database directly and does not require these generated files; they provide
+reusable row and mutation input types. The CLI writes that source atomically. This command checks
+the existing file without rewriting it:
 
 ```sh
-npx tenon generate --out src/generated-schema.ts --check
+npx tenon generate --out src/generated-schema.d.ts --check
 ```
 
 `--check` compares the generated representation with the current database. Pending migration files
 are a separate concern. The representation includes table columns, constraints, indexes, and
 referenced domains, not every PostgreSQL object.
 
-Generation reads a consistent snapshot of ordinary tables and partitioned roots. Use the generated
-named type in queries, for example `sql<User>`. For other table names, define an alias such as
-`type AuditRow = Rows['audit-log']` and use `sql<AuditRow>`; SafeQL resolves named aliases but not
-indexed access directly in `sql<Rows['audit-log']>`. Views, foreign tables, and attached partitions
-use query-specific types. A missing namespace fails; an existing empty schema is valid.
-
-| PostgreSQL type                                | Default pg value                                |
-| ---------------------------------------------- | ----------------------------------------------- |
-| smallint, integer, oid, real, double precision | `number`                                        |
-| bigint, numeric                                | `string`                                        |
-| boolean                                        | `boolean`                                       |
-| text, varchar, char, uuid, time, timetz        | `string`                                        |
-| date, timestamp, timestamptz                   | `Date \| number` (numbers represent infinities) |
-| enum                                           | String literal union; `never` for an empty enum |
-| json, jsonb                                    | `unknown`                                       |
-| bytea                                          | `Buffer`                                        |
-
-Nullable columns add null. Domains use verified underlying mappings and the column's own
-nullability. Unverified types warn and become `unknown`. Verified arrays use
+Generation reads a consistent snapshot of ordinary tables and partitioned roots. `Rows['User']`
+describes one returned row; the generated `User` alias means the same thing. Use `sql<User>` for a
+full row or `Pick<User, 'id' | 'email'>` for a projection. Table keys preserve exact SQL names;
+`type AuditRow = Rows['audit-log']` works for names that cannot be exported as identifiers.
+Views, foreign tables, and attached partitions use query-specific types. A missing namespace
+fails; an existing empty schema is valid.
+
+| PostgreSQL type                                | Returned value                                | Generated write input                 |
+| ---------------------------------------------- | --------------------------------------------- | ------------------------------------- |
+| smallint, integer, oid, real, double precision | `number`                                      | `number`                              |
+| bigint                                         | `string`                                      | `string \| bigint`                    |
+| numeric                                        | `string`                                      | `string \| number`                    |
+| boolean                                        | `boolean`                                     | `boolean`                             |
+| text, name, varchar, char, uuid, time, timetz  | `string`                                      | `string`                              |
+| date, timestamp, timestamptz                   | `Date \| number` (numbers include infinities) | `Date \| string`                      |
+| enum                                           | String literal union                          | Same union; `never` for an empty enum |
+| json, jsonb                                    | `unknown`                                     | Serialized JSON text (`string`)       |
+| bytea                                          | `Buffer`                                      | `Buffer`                              |
+
+For returned rows, nullable columns add null. Domains use verified underlying mappings and the
+column's own nullability. Unverified types warn and become `unknown`. Verified arrays use
 `PgArray<T> = (T | null | PgArray<T>)[]` for null elements and multiple dimensions. Numeric arrays
 contain numbers and can lose precision; cast to text[] for exact values. Enum arrays and arrays of
 domains are unverified. Finite dates and timestamps without time zone use Node's local timezone.
 Custom pg parsers need matching application types.
 
+### Insert and update inputs
+
+The same file provides `Rows.Insert['table']` and `Rows.Update['table']` for bound write inputs.
+These are ordinary TypeScript types. `--out` accepts `.ts` or `.d.ts`; the examples use `.d.ts`
+because the file contains only declarations.
+
+```ts
+import type { Rows } from './generated-schema.js';
+
+type NewProfile = Rows.Insert['profiles'];
+type ProfilePatch = Pick<Rows.Update['profiles'], 'name' | 'bio'>;
+
+const profile: NewProfile = { name: 'Ada' };
+const patch: ProfilePatch = { name: undefined, bio: null };
+sql.insertValues(profile, ['name', 'bio', 'score']);
+sql.assignments(patch, ['name', 'bio']);
+```
+
+Insert fields are required when nonnullable and without a default. Other writable insert fields
+are optional; every writable update field is optional. `undefined` requests a default on insert
+and omits an assignment on update. Explicit `null` is accepted only when the column and its domain
+chain permit it. Domain defaults count; column defaults take precedence.
+
+Computed columns and `GENERATED ALWAYS` identity columns cannot receive values. Serial and
+`GENERATED BY DEFAULT` identity columns are optional on insert and writable on update. Other
+primary keys remain writable. Use `Pick` or `Omit` for application-specific restrictions and keep
+expressions, `DEFAULT`, and special identity overrides in SQL.
+
+Write representations in the table above also apply to verified array elements. Serialize JSON
+with `JSON.stringify`, including JSON arrays; a JSON string containing `null` differs from SQL null.
+Use timestamp strings for infinities. Unverified non-null write values use `never` and warn;
+nullable fields still accept null. Supply an application-owned replacement when needed, for example
+`Omit<Rows.Insert['events'], 'delay'> & { delay: string }` for a reviewed interval-text input.
+
+Apply these types through annotations, `satisfies`, or helper generic arguments such as
+`sql.insertValues<NewProfile>(input)`. They check shapes and representations, not authorization,
+constraints, JSON contents, or nonempty inputs. Optional fields accept explicit `undefined`,
+including with `exactOptionalPropertyTypes`. Selected columns can discard required fields; see
+the [cookbook example](mutations.md#input-types-sql-checking-and-runtime-validation).
+
 ## SQL checking with SafeQL
 
 SafeQL checks SQL against a real PostgreSQL schema and infers result types. ESLint runs that check
@@ -230,8 +365,8 @@ Configure [SafeQL normally](https://safeql.dev/api/). Tenon's optional `safeql`
 two objects:
 
 - `safeqlPlugin` is a SafeQL plugin descriptor. Add it to each Tenon connection's `plugins` list. It
-  translates constant fragments and identifiers, preserves runtime parameter behavior, and supplies
-  pg result mappings. SafeQL owns database analysis and annotation fixes.
+  translates constant fragments, official mutation helpers, and identifiers, preserves parameter
+  behavior, and supplies pg result mappings. SafeQL owns database analysis and annotation fixes.
 - `eslintPlugin` supplies `tenon/check-composition`. Register it in ESLint and enable the rule to
   report queries that the adapter cannot resolve, including runtime-built fragments and escaped
   outer templates.
@@ -248,11 +383,8 @@ existing TypeScript installation:
 npm install --save-dev eslint typescript-eslint @ts-safeql/eslint-plugin
 ```
 
-SafeQL and ESLint are the integration's hosts, and the adapter imports TypeScript to inspect query
-expressions. They are optional peers because Tenon's database runtime does not need them.
-`typescript-eslint` is an application-owned parser dependency, not a Tenon peer. Your ESLint
-configuration imports SafeQL and the parser explicitly. Use a TypeScript version supported by that
-lint toolchain. The `pg` driver remains Tenon's required runtime peer.
+These are development dependencies. Reuse your existing type-aware parser configuration and a
+TypeScript version supported by the lint toolchain. Tenon's database runtime does not load them.
 
 For a project with `src/**/*.ts` and a `tsconfig.json`:
 
@@ -289,9 +421,6 @@ configuration. `projectService` uses the nearest TypeScript project for each fil
 `DATABASE_URL` through your application's environment setup and point it at a development/test
 database with migrations applied. This example does not load `.env` files.
 
-The `.mjs` example avoids a current declaration mismatch between SafeQL's configuration helper and
-ESLint's `defineConfig`. This affects configuration typechecking, not query result types.
-
 `targets` selects the SQL tag spelling. If you alias `sql`, add the alias to the targets. For a
 single database, `targets: [{ tag: { regex: '.*' } }]` selects all tags; Tenon's adapter filters
 that down to actual Tenon queries, including aliases and object properties. Neither the adapter nor
@@ -311,6 +440,9 @@ They run all enabled ESLint rules, and `lint:fix` can change non-SQL code too:
 
 ### Generate and check annotations
 
+For an existing persistence layer, start with the [incremental audit workflow](adoption-guide.md#adopt-sql-checking-incrementally).
+It covers a separate SQL lint command, fix previews, and application refinements.
+
 Write a query without a result annotation:
 
 ```ts
@@ -372,25 +504,48 @@ file group, each extending its own `safeql.configs.connections({ ... })`. Use no
 `files` patterns when database settings differ. Normal SafeQL configurations for other libraries can
 coexist; add Tenon's adapter only to connections checking Tenon queries.
 
-If a database has same-named tables in different schemas, qualify them in SQL, for example
-`SELECT id FROM billing.accounts`. SafeQL can infer the wrong type for an unqualified table even
-when the connection's `search_path` selects the correct table at execution. Explicit schema names
-avoid that ambiguity.
+Qualify same-named tables with their schemas, for example `SELECT id FROM billing.accounts`, so
+the intended relation is explicit in both checking and execution.
 
 ### Supported SQL and limitations
 
 Within the configured targets, the adapter recognizes Tenon's `sql` export through imports, local
 aliases, namespace imports, and object properties that retain its TypeScript type. It checks
-constant fragments and `sql.join` with literal arrays, including nested fragments. Separators must
-be literal strings or const strings. Literal `identifier()` names and const string names are
-supported. Values use the same parameter placeholders in static checking and execution, inside or
-outside fragments. PostgreSQL infers their types from the SQL context; Tenon does not add casts
-based on JavaScript types. Mutable references, runtime lists, conditional fragments,
-function-generated fragments, and dynamic identifiers produce `tenon/check-composition` diagnostics.
-Suppress only that rule on the particular query when runtime variants have database tests. SQL and
-annotation errors still come from `@ts-safeql/check-sql`. An imported fragment must have an
-inspectable source initializer; declarations alone cannot describe its SQL. It does not execute
-application code to discover SQL.
+constant fragments and `sql.join` with nonempty literal arrays, including nested fragments.
+Separators and `identifier()` names must resolve to literal strings or const string initializers.
+Values use the same parameter placeholders in static checking and execution, inside or outside
+fragments. PostgreSQL infers their types from SQL context; Tenon does not add casts based on
+JavaScript types.
+
+The checker follows const fragment initializers, including imported constants with inspectable
+source. It does not inspect function bodies, substitute helper arguments/defaults, or choose
+JavaScript conditional branches. Function-generated fragments and conditional SQL structure are
+unsupported even when a particular helper appears simple or a condition is a literal. Mutable
+references, runtime filter lists, and dynamic identifiers are also unsupported. Ordinary value
+expressions remain bound parameters; calls that produce data for an official mutation helper can
+use its explicit column-list contract.
+
+`tenon/check-composition` points to the first unsupported interpolation in each query and explains
+why it cannot be checked. For example, opaque mutation inputs need an inline column list, while
+fragment-returning functions remain outside static analysis. Errors reached through shared constants
+are reported at the consuming query. ESLint suppressions must cover the reported expression's line;
+a scoped disable/enable can cover one multiline query.
+
+Reusable authorization and other application policy can still live in fragment-returning functions
+at runtime. Keep that policy centralized and cover its behavior with database tests. Suppress
+`tenon/check-composition` only on the particular query, with a reason, when its variants are tested.
+Do not duplicate policy merely to obtain static coverage. SQL and annotation errors in checkable
+queries continue to come from `@ts-safeql/check-sql`.
+
+Ordinary functions containing complete `sql` templates remain checkable. Each template is analyzed
+where it is written, including constant fragments defined in that function:
+
+```ts
+function findUsers(email: string) {
+  const predicate = sql.fragment`email = ${email}`;
+  return sql`SELECT id FROM users WHERE ${predicate}`;
+}
+```
 
 Use literal line breaks in `sql` templates and bind string values with `${value}`. The composition
 rule rejects JavaScript escapes such as `\n` or `\'` in the outer template: SafeQL reads raw
@@ -436,7 +591,7 @@ tenon new <name> [--directory migrations]
 tenon migrate [--directory migrations] [--namespace public]
 tenon status [--directory migrations] [--namespace public]
 tenon rollback [--directory migrations] [--namespace public] [--steps 1]
-tenon generate [--namespace public] [--out src/generated-schema.ts] [--check]
+tenon generate [--namespace public] [--out path] [--check]
 tenon baseline capture|adopt [--directory migrations] [--namespace public]
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kequtech/tenon-orm",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "ISC",
   "type": "module",
   "description": "A PostgreSQL ORM designed for coding agents, with explicit SQL, typed queries, and migrations",

package/dist/generation/row-types.d.ts

@@ -1,2 +0,0 @@
-import type { TableRow } from './catalog.js';
-export declare function renderRowTypes(tables: readonly TableRow[], namespace: string, onWarning: (message: string) => void): string;

package/dist/generation/row-types.js

@@ -1,115 +0,0 @@
-// Every generated table remains accessible through Rows["exact SQL name"].
-const reservedTypeNames = new Set(`
-  as await break case catch class const continue debugger default delete do else enum
-  export extends false finally for function if implements import in instanceof
-  interface let new null package private protected public return static super
-  switch this throw true try typeof var void while with yield any bigint boolean
-  intrinsic never number object string symbol undefined unknown
-  Rows globalThis PgArray
-`
-    .trim()
-    .split(/\s+/));
-function canExportRowName(name) {
-    return (/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(name) && !reservedTypeNames.has(name));
-}
-// Exact built-in OIDs with verified default pg text parsers. Array parsers do
-// not necessarily use their scalar type's representation (notably numeric[]).
-const arrayTypes = {
-    '1000': 'boolean',
-    '1001': 'import("node:buffer").Buffer',
-    '1005': 'number',
-    '1007': 'number',
-    '1021': 'number',
-    '1022': 'number',
-    '1028': 'number',
-    '1016': 'string',
-    '1231': 'number',
-    '1009': 'string',
-    '1014': 'string',
-    '1015': 'string',
-    '1183': 'string',
-    '1270': 'string',
-    '2951': 'string',
-    '1182': 'globalThis.Date | number',
-    '1115': 'globalThis.Date | number',
-    '1185': 'globalThis.Date | number',
-    '199': 'unknown',
-    '3807': 'unknown',
-};
-const scalarTypes = {
-    int2: 'number',
-    int4: 'number',
-    oid: 'number',
-    float4: 'number',
-    float8: 'number',
-    bool: 'boolean',
-    text: 'string',
-    varchar: 'string',
-    bpchar: 'string',
-    time: 'string',
-    timetz: 'string',
-    uuid: 'string',
-    // pg returns +/-Infinity as numbers. TypeScript has no infinity literal type.
-    date: 'globalThis.Date | number',
-    timestamp: 'globalThis.Date | number',
-    timestamptz: 'globalThis.Date | number',
-    int8: 'string',
-    numeric: 'string',
-    json: 'unknown',
-    jsonb: 'unknown',
-    bytea: 'import("node:buffer").Buffer',
-};
-function isSupportedArray(value) {
-    return Object.hasOwn(arrayTypes, value.oid);
-}
-function columnType(value, column, onWarning) {
-    let scalar;
-    if (isSupportedArray(value)) {
-        scalar = `PgArray<${arrayTypes[value.oid]}>`;
-    }
-    else if (value.typeKind === 'e') {
-        scalar = value.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
-    }
-    else {
-        const type = value.typeSchema === 'pg_catalog' && Object.hasOwn(scalarTypes, value.type)
-            ? scalarTypes[value.type]
-            : undefined;
-        if (type) {
-            scalar = type;
-        }
-        else {
-            const underlying = value.declaredOid === value.oid
-                ? ''
-                : ` with underlying type ${JSON.stringify(value.typeSchema)}.${JSON.stringify(value.type)} (OID ${value.oid})`;
-            onWarning(`Column ${column} uses PostgreSQL type ${JSON.stringify(value.declaredSchema)}.${JSON.stringify(value.declaredType)} (OID ${value.declaredOid})${underlying} without a verified pg mapping; generated as unknown.`);
-            scalar = 'unknown';
-        }
-    }
-    // unknown already includes null, including for nullable JSON and unmapped types.
-    return `${scalar}${value.nullable && scalar !== 'unknown' ? ' | null' : ''}`;
-}
-export function renderRowTypes(tables, namespace, onWarning) {
-    const rows = tables.map((table) => {
-        const tableName = JSON.stringify(table.name);
-        const columns = table.columns.map((column) => {
-            const columnName = JSON.stringify(column.name);
-            const path = `${JSON.stringify(namespace)}.${tableName}.${columnName}`;
-            return `    ${columnName}: ${columnType(column, path, onWarning)};`;
-        });
-        return `  ${tableName}: {
-${columns.join('\n')}
-  };`;
-    });
-    const aliases = tables
-        .filter((table) => canExportRowName(table.name))
-        .map((table) => `export type ${table.name} = Rows[${JSON.stringify(table.name)}];`);
-    const arrays = tables.some((table) => table.columns.some(isSupportedArray))
-        ? 'export type PgArray<T> = (T | null | PgArray<T>)[];\n\n'
-        : '';
-    return `${arrays}// Full database rows. Compose query types with Pick, indexed access, and intersections.
-export type Rows = {
-${rows.join('\n')}
-};
-${aliases.join('\n')}
-`;
-}