@kequtech/tenon-orm 0.1.1 → 0.1.3

package/docs/reference.md

@@ -86,22 +86,22 @@ const query = sql<{ id: number }>`SELECT id FROM public."User"
 NUL, and fit PostgreSQL's 63-byte identifier limit. Choose names from application-approved
 alternatives; quoting does not authorize access. Ordinary strings such as `'DESC'` are bound values,
 not SQL syntax. For ordering, use complete query alternatives or application-selected fragments
-containing `ASC` or `DESC`; runtime-selected fragments need checker exclusions and tests.
+containing `ASC` or `DESC`.
 
 `unsafeSql<Row>(text, values)` accepts externally authored, trusted SQL and an explicit values
-array, including `[]` when empty. It bypasses static SQL checking. Never concatenate request input
-into its text. Full `sql` or `unsafeSql` queries cannot be inserted into other queries; use
+array, including `[]` when empty. Never concatenate request input into its text.
+Full `sql` or `unsafeSql` queries cannot be inserted into other queries; use
 fragments for partial SQL.
 
 ## SQL fragments and joins
 
 `sql.fragment` creates an immutable piece of SQL with bound values. It has no row type and cannot
-execute alone. Insert it into a complete `sql<Row>` query. Constant fragments can share a predicate
-between, for example, a list query and a count query. Ordinary fixed conditions are usually clearer
-directly in the query.
+execute alone. Insert it into a complete `sql<Row>` query. Use fragments to share predicates or
+other SQL expressions between queries. Blank fragments throw.
 
-`sql.join(fragments, separator)` combines a nonempty array of fragments into a new fragment.
-Separators are exactly:
+`sql.join(fragments, separator)` combines fragments into a new fragment. Use it when the number of
+parts varies: optional filters, a condition for each search term, or a list of SQL expressions.
+Write fixed structure directly in SQL. Supported separators are:
 
 | Argument | Inserted SQL | Typical use                |
 | -------- | ------------ | -------------------------- |
@@ -109,35 +109,22 @@ Separators are exactly:
 | `'OR'`   | `OR`         | Any condition may hold     |
 | `','`    | `, `         | Projections or assignments |
 
-No default, arbitrary string, or fragment separator is accepted. Runtime validation also protects
-JavaScript callers. A single item is returned as a new fragment without extra separators. Empty
-lists and blank fragments throw; choose empty-list behavior explicitly in application code.
-
-Joins do not add parentheses or alter SQL precedence. Group alternatives before combining them with
-other conditions:
-
 ```ts
-const alternatives = sql.join(
-  [sql.fragment`email = ${primary}`, sql.fragment`email = ${secondary}`],
-  'OR',
-);
-const conditions = sql.join(
-  [sql.fragment`(${alternatives})`, sql.fragment`active = ${true}`],
-  'AND',
-);
-const query = sql<{ id: number }>`SELECT id FROM public."User" WHERE ${conditions}`;
+const conditions = [sql.fragment`active = ${true}`];
+if (email !== undefined) conditions.push(sql.fragment`email = ${email}`);
+if (afterId !== undefined) conditions.push(sql.fragment`id > ${afterId}`);
+
+const query = sql<{ id: number }>`SELECT id FROM public."User"
+  WHERE ${sql.join(conditions, 'AND')} ORDER BY id`;
 ```
 
+The list must be nonempty; the example keeps the active condition even when both optional filters
+are absent. Joins insert separators without adding parentheses or changing SQL precedence. Group
+mixed AND/OR expressions with parentheses, as in ordinary SQL.
+
 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, 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
@@ -188,8 +175,7 @@ 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:
+names throw. TypeScript checks selected names against the input's known keys:
 
 ```ts
 const rows: { name: string; bio?: string | null }[] = buildRows();
@@ -199,10 +185,10 @@ 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 schema metadata. Omit generated columns; PostgreSQL enforces identity,
-generation, required-column, and constraint rules. They do not generate insert/update input types
-or prove that the JavaScript input values match database column types. Retain application input
-contracts and validation. To reset an update field to its default, write `column = DEFAULT` in the
+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.
 
@@ -211,24 +197,8 @@ Tenon rejects larger queries and does not split them automatically. Choose batch
 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.
+See the [mutation cookbook](mutations.md) for common patterns and
+[checking mutation fragments](#checking-mutation-fragments) for optional SQL checking.
 
 ## Transactions, guarded writes, and errors
 
@@ -277,42 +247,85 @@ 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
+`--check` reports a missing file or shows a short text diff when the saved output differs from the
+current database. It never rewrites the file. 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
@@ -341,11 +354,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`:
 
@@ -382,9 +392,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
@@ -404,6 +411,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
@@ -465,16 +475,14 @@ 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 nonempty literal arrays, including nested fragments.
+constant fragments and `sql.join` with inline nonempty array literals, 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
@@ -484,10 +492,17 @@ The checker follows const fragment initializers, including imported constants wi
 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
+fragment references and dynamic identifiers are also unsupported. Arrays stored in variables or
+assembled in loops are valid `sql.join` inputs at runtime but are not analyzed. 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.
@@ -537,6 +552,25 @@ tests; a checker cannot infer your parser policy. Column keys are `Table.column`
 names across schemas need care. Type overrides merge with the adapter's defaults. `unsafeSql` is
 outside static checking, and arbitrary JSON still needs application validation.
 
+### 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.
+
 ## Command reference
 
 All database commands use `DATABASE_URL`; environment files are not loaded automatically. For
@@ -548,7 +582,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.1",
+  "version": "0.1.3",
   "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')}
-`;
-}