@kequtech/tenon-orm 0.1.1 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
 Your coding agent already knows SQL. Tenon gives it a small API for parameterized queries,
-transactions, and migrations, with optional tooling to check SQL and generate result types. Queries
+transactions, and migrations, with optional tooling to check SQL and generate database types. Queries
 stay readable, reusable operations are ordinary functions, and humans can review exactly what will
 run against the database.
 
@@ -47,7 +47,7 @@ Tenon also provides:
 
 - Transactions and affected-row limits that roll back rejected writes.
 - SQL migration files and a CLI to apply, inspect, and roll back migrations.
-- TypeScript table row types generated from your database.
+- TypeScript row, insert, and update types generated from your database.
 - SQL fragments for sharing query parts or assembling variable conditions.
 
 Joins, relationships, aggregates, and upserts use ordinary PostgreSQL SQL. Tenon does not introduce
@@ -69,6 +69,8 @@ migrations and table type generation are independent conveniences.
 For object-based writes, `sql.insertValues(rows)` preserves database defaults across heterogeneous
 rows and `sql.assignments(patch)` omits undefined fields. Keep the surrounding SQL explicit. Both
 support selected columns and [SafeQL checking](docs/reference.md#object-based-mutation-fragments).
+Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
+against your schema.
 
 ## Checking query results
 
@@ -79,12 +81,10 @@ For that, Tenon provides an optional integration with [SafeQL](https://safeql.de
 SQL against your development database and can write or repair the result annotation. ESLint runs the
 check during development and CI; it is not part of query execution.
 
-Configure SafeQL in your application's ESLint setup. Tenon supplies a `safeqlPlugin` adapter for its
-queries, constant fragments, and official mutation helpers, plus an `eslintPlugin` rule that flags
-queries the adapter cannot check. SafeQL handles database analysis and result annotations; Tenon keeps the SQL and pg type
-mappings consistent with execution. Both integrations are optional development tooling. See
-[SQL checking setup](docs/reference.md#sql-checking-with-safeql) for installation and a complete
-configuration, including multiple databases.
+Configure SafeQL in your application's ESLint setup with Tenon's `safeqlPlugin` adapter and
+`eslintPlugin` companion rule. The adapter supports queries, constant fragments, and mutation
+helpers; the rule reports queries it cannot inspect. See the
+[SQL checking setup](docs/reference.md#sql-checking-with-safeql).
 
 Checking complements typed inputs and database tests. It does not validate request values or
 arbitrary JSON, and runtime-built query variants need their own tests.
@@ -97,7 +97,9 @@ arbitrary JSON, and runtime-built query variants need their own tests.
 - **[Reference](docs/reference.md)** — complete options, SQL checking setup, type mappings, and
   limitations.
 - **[Adoption guide](docs/adoption-guide.md)** — replace an existing ORM and, if needed, transfer
-  migration ownership.
+  migration ownership; upgrade local write helpers and adopt SQL checking incrementally.
+- **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, batching, and
+  the boundaries between input typing and SQL checking.
 
 The complete `docs/` folder ships with the npm package. Maintainer instructions are in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md), which is not

package/dist/generate.js

@@ -1,5 +1,5 @@
 import { readTables } from './generation/catalog.js';
-import { renderRowTypes } from './generation/row-types.js';
+import { renderTableTypes } from './generation/table-types.js';
 import { domainSummaries, schemaSummary, tableSummary } from './generation/schema-summary.js';
 import { withMigrationLock } from './migrations/connection.js';
 import { quote } from './sql.js';
@@ -24,7 +24,7 @@ export async function generateDefinitions(options) {
             summaries.push(await tableSummary(client, table.oid, table.name));
         }
         const domains = await domainSummaries(client, definitions.flatMap((table) => table.columns.map((column) => column.declaredOid)));
-        const types = renderRowTypes(definitions, namespace, onWarning);
+        const types = renderTableTypes(definitions, namespace, onWarning);
         await client.query('COMMIT');
         return `// Generated by Tenon from the PostgreSQL schema. Do not edit.
 // Commit this file and regenerate it after changing the schema.

package/dist/generation/catalog.d.ts

@@ -9,6 +9,9 @@ export interface ColumnRow {
     declaredType: string;
     declaredSchema: string;
     nullable: boolean;
+    writeNullable: boolean;
+    hasDefault: boolean;
+    writable: boolean;
     choices: string[] | null;
 }
 export interface TableRow {

package/dist/generation/catalog.js

@@ -11,16 +11,19 @@ export async function readTables(client, namespace) {
         // Attached descendants are storage details, not separate generated models.
         const columns = await client.query(`
         WITH RECURSIVE resolved AS (
-          SELECT a.attnum, t.oid, t.typbasetype
+          SELECT a.attnum, t.oid, t.typbasetype, t.typnotnull AS domain_not_null
           FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
           WHERE a.attrelid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
           UNION ALL
-          SELECT r.attnum, t.oid, t.typbasetype
+          SELECT r.attnum, t.oid, t.typbasetype, r.domain_not_null OR t.typnotnull
           FROM resolved r JOIN pg_catalog.pg_type t ON t.oid = r.typbasetype
         )
         SELECT a.attname AS name, t.oid::text AS oid, t.typname AS type, tn.nspname AS "typeSchema", t.typtype AS "typeKind",
           declared.oid::text AS "declaredOid", declared.typname AS "declaredType", dn.nspname AS "declaredSchema",
           NOT a.attnotnull AS nullable,
+          NOT (a.attnotnull OR r.domain_not_null) AS "writeNullable",
+          (a.atthasdef OR declared.typdefaultbin IS NOT NULL OR a.attidentity <> '') AS "hasDefault",
+          (a.attgenerated = '' AND a.attidentity <> 'a') AS writable,
           (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder) FROM pg_catalog.pg_enum e WHERE e.enumtypid = t.oid) AS choices
         FROM pg_catalog.pg_attribute a
           JOIN resolved r ON r.attnum = a.attnum AND r.typbasetype = 0

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

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

package/dist/generation/table-types.js

@@ -0,0 +1,146 @@
+// 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));
+}
+// A string means the read and write representations match. Arrays use verified
+// built-in OIDs because their parsers can differ from scalar parsers (numeric[]).
+const arrayTypes = {
+    '1000': 'boolean',
+    '1001': 'import("node:buffer").Buffer',
+    '1005': 'number',
+    '1007': 'number',
+    '1021': 'number',
+    '1022': 'number',
+    '1028': 'number',
+    '1016': { read: 'string', write: 'string | bigint' },
+    '1231': { read: 'number', write: 'string | number' },
+    '1009': 'string',
+    '1014': 'string',
+    '1015': 'string',
+    '1183': 'string',
+    '1270': 'string',
+    '2951': 'string',
+    '1182': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '1115': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '1185': { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    '199': { read: 'unknown', write: 'string' },
+    '3807': { read: 'unknown', write: 'string' },
+};
+const scalarTypes = {
+    int2: 'number',
+    int4: 'number',
+    oid: 'number',
+    float4: 'number',
+    float8: 'number',
+    bool: 'boolean',
+    text: 'string',
+    name: 'string',
+    varchar: 'string',
+    bpchar: 'string',
+    time: 'string',
+    timetz: 'string',
+    uuid: 'string',
+    // pg returns +/-Infinity as numbers. TypeScript has no infinity literal type.
+    date: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    timestamp: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    timestamptz: { read: 'globalThis.Date | number', write: 'globalThis.Date | string' },
+    int8: { read: 'string', write: 'string | bigint' },
+    numeric: { read: 'string', write: 'string | number' },
+    json: { read: 'unknown', write: 'string' },
+    jsonb: { read: 'unknown', write: 'string' },
+    bytea: 'import("node:buffer").Buffer',
+};
+function valueTypes(mapping) {
+    return typeof mapping === 'string' ? { read: mapping, write: mapping } : mapping;
+}
+function isSupportedArray(value) {
+    return Object.hasOwn(arrayTypes, value.oid);
+}
+function columnTypes(value, column, onWarning) {
+    let types;
+    if (isSupportedArray(value)) {
+        const element = valueTypes(arrayTypes[value.oid]);
+        types = { read: `PgArray<${element.read}>`, write: `PgArray<${element.write}>` };
+    }
+    else if (value.typeKind === 'e') {
+        const choice = value.choices?.map((choice) => JSON.stringify(choice)).join(' | ') || 'never';
+        types = { read: choice, write: choice };
+    }
+    else {
+        const type = value.typeSchema === 'pg_catalog' && Object.hasOwn(scalarTypes, value.type)
+            ? scalarTypes[value.type]
+            : undefined;
+        if (type) {
+            types = valueTypes(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 for reads and never for non-null writes.`);
+            types = { read: 'unknown', write: 'never' };
+        }
+    }
+    // unknown already includes null, including for nullable JSON and unmapped types.
+    return {
+        read: `${types.read}${value.nullable && types.read !== 'unknown' ? ' | null' : ''}`,
+        write: `${types.write}${value.writeNullable ? ' | null' : ''}`,
+    };
+}
+export function renderTableTypes(tables, namespace, onWarning) {
+    const definitions = 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}`;
+            const types = columnTypes(column, path, onWarning);
+            const requiredOnInsert = column.writable && !column.hasDefault && !column.writeNullable;
+            const optionalInputType = column.writable ? `${types.write} | undefined` : 'never';
+            return {
+                row: `    ${columnName}: ${types.read};`,
+                insert: `    ${columnName}${requiredOnInsert ? '' : '?'}: ${requiredOnInsert ? types.write : optionalInputType};`,
+                update: `    ${columnName}?: ${optionalInputType};`,
+            };
+        });
+        return { tableName, columns };
+    });
+    const render = (kind, indent = '') => definitions
+        .map(({ tableName, columns }) => `${indent}  ${tableName}: {
+${columns.map((column) => indent + column[kind]).join('\n')}
+${indent}  };`)
+        .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 = {
+${render('row')}
+};
+
+export declare namespace Rows {
+  // Bound inputs for sql.insertValues. Missing/undefined fields use database defaults.
+  type Insert = {
+${render('insert', '  ')}
+  };
+
+  // Bound inputs for sql.assignments. Missing/undefined fields are omitted.
+  type Update = {
+${render('update', '  ')}
+  };
+}
+${aliases.join('\n')}
+`;
+}

package/dist/mutations.d.ts

@@ -1,7 +1,7 @@
 export type MutationPart = string | Readonly<{
     value: unknown;
 }>;
-export type MutationColumns<Row> = Row extends object ? Extract<keyof Row, string> : never;
+export type MutationColumns<Input> = Input extends object ? Extract<keyof Input, string> : never;
 /** Validate and quote one explicit column list, shared by runtime and SQL checking. */
 export declare function mutationColumns(columns: readonly string[]): string[];
 /** SQL structure depends only on these columns and cells, never on JavaScript source. */

package/dist/query.d.ts

@@ -21,9 +21,9 @@ export interface SqlFragment {
 declare function fragment(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlFragment;
 declare function join(fragments: readonly SqlFragment[], separator: 'AND' | 'OR' | ','): SqlFragment;
 /** Object fields become bound values; absent insert cells use PostgreSQL defaults. */
-declare function insertValues<Row extends object>(input: Row | readonly Row[], columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+declare function insertValues<Input extends object>(input: Input | readonly Input[], columns?: readonly NoInfer<MutationColumns<Input>>[]): SqlFragment;
 /** Omit undefined fields; null remains a value. Empty assignments reject. */
-declare function assignments<Row extends object>(input: Row, columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+declare function assignments<Input extends object>(input: Input, columns?: readonly NoInfer<MutationColumns<Input>>[]): SqlFragment;
 declare function createQuery<Row extends QueryResultRow = UnknownRow>(strings: TemplateStringsArray, ...values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
 /** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
 export declare const sql: typeof createQuery & {

package/dist/query.js

@@ -111,7 +111,7 @@ export function unsafeSql(text, values) {
     if (!Array.isArray(values))
         throw new Error('SQL input must be an explicit array.');
     if (values.length > 65535)
-        throw new Error('A PostgreSQL query supports at most 65535 bound parameters; split large batches explicitly.');
+        throw new Error(`A PostgreSQL query supports at most 65535 bound parameters; received ${values.length}. Split large batches explicitly.`);
     return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
 }
 export function assertQuery(value) {

package/dist/safeql/composition.js

@@ -106,6 +106,15 @@ export function renderFragment(node, checker, seen = new Set()) {
         }
         return list.elements.map((item) => renderFragment(item, checker, visited)).join(between);
     }
+    if (ts.isCallExpression(node)) {
+        throw new CompositionError(`Function-generated fragments from ${node.expression.getText()}() are not analyzed; the checker does not inspect function bodies.`);
+    }
+    if (ts.isConditionalExpression(node)) {
+        throw new CompositionError('Conditional fragments are not analyzed; the checker does not choose JavaScript branches, even for literal conditions.');
+    }
+    if (ts.isIdentifier(node)) {
+        throw new CompositionError(`Fragment "${node.text}" has no inspectable const initializer; mutable and runtime-supplied fragments are not analyzed.`);
+    }
     throw new CompositionError('Only constant sql.fragment templates, literal sql.join arrays, and official mutation helpers are supported. Function-generated fragments and conditional SQL structure are not analyzed.');
 }
 export function renderIdentifier(node, checker, seen = new Set()) {

package/dist/safeql/eslint.js

@@ -22,21 +22,26 @@ export const eslintPlugin = {
                             !ts.isTaggedTemplateExpression(template) ||
                             !isExport(template.tag, checker, 'sql'))
                             return;
-                        try {
-                            if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
-                                throw new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.');
-                            }
-                            if (ts.isTemplateExpression(template.template)) {
-                                for (const span of template.template.templateSpans) {
+                        if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
+                            context.report({
+                                node,
+                                message: new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.').message,
+                            });
+                            return;
+                        }
+                        if (ts.isTemplateExpression(template.template)) {
+                            for (const [index, span] of template.template.templateSpans.entries()) {
+                                try {
                                     renderValue(span.expression, checker);
                                 }
+                                catch (error) {
+                                    if (!(error instanceof CompositionError))
+                                        throw error;
+                                    context.report({ node: node.quasi.expressions[index], message: error.message });
+                                    return;
+                                }
                             }
                         }
-                        catch (error) {
-                            if (!(error instanceof CompositionError))
-                                throw error;
-                            context.report({ node, message: error.message });
-                        }
                     },
                 };
             },

package/docs/adoption-guide.md

@@ -11,10 +11,10 @@ queries or generate types; keep the existing migration runner if that is the int
 1. Locate the old ORM's connection setup, schema, migrations, and call sites. Identify behavior
    supplied by the ORM: validation, IDs, timestamps, hooks, defaults, relation loading,
    serialization, and transaction boundaries.
-2. If table row types will help your application, generate them from the existing database:
+2. If row and mutation input types will help your application, generate them from the existing database:
 
    ```sh
-   npx tenon generate --out src/generated-schema.ts
+   npx tenon generate --out src/generated-schema.d.ts
    ```
 
    Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
@@ -25,14 +25,107 @@ queries or generate types; keep the existing migration runner if that is the int
    Generated types describe pg values: check bigint/numeric strings, dates, JSON, and arrays when
    the old ORM transformed them.
 4. If using optional SQL checking, configure the
-   [SafeQL integration](reference.md#sql-checking-with-safeql) to generate query annotations and
-   check them against the intended schema. Run tests against a dedicated test database. Verify
+   [SafeQL integration](reference.md#sql-checking-with-safeql) and follow the
+   [incremental audit workflow](#adopt-sql-checking-incrementally) below before accepting generated
+   annotations. Run tests against a dedicated test database. Verify
    writes and rollback, relationships, validation, and any hooks you moved into application code or
    SQL. A schema-preserving first release makes application rollback easier.
 5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
    migration tooling until the migration transition below is complete, if that transition is part of
    the work.
 
+## Replace local write helpers
+
+Use `sql.insertValues(rows)` and `sql.assignments(patch)` in place of local object-to-SQL utilities:
+
+```ts
+import { sql } from '@kequtech/tenon-orm';
+
+const insert = sql`INSERT INTO profiles ${sql.insertValues(rows)} RETURNING id`;
+const update = sql`UPDATE profiles SET ${sql.assignments(patch)} WHERE id = ${id}`;
+```
+
+Compare omission, defaults, nulls, and empty-input behavior with the old helpers. Keep expressions
+in SQL and remove the local utilities after their callers move. Generated `Rows.Insert` and
+`Rows.Update` types can replace handwritten table inputs; retain application-specific refinements
+and validation. Run the existing write and rollback workflows. See the [mutation cookbook](mutations.md).
+
+## Adopt SQL checking incrementally
+
+For an existing application, including Next.js, SQL checking can run as a separate audit while the
+normal lint/build commands keep their existing database requirements. Extend the existing flat
+ESLint configuration rather than replacing it. After installing the
+[checking dependencies](reference.md#install-and-configure), a single-database setup can use:
+
+```js
+// eslint.sql.config.mjs
+import { defineConfig } from 'eslint/config';
+import baseConfig from './eslint.config.mjs';
+import safeql from '@ts-safeql/eslint-plugin/config';
+import tseslint from 'typescript-eslint';
+import { safeqlPlugin, eslintPlugin } from '@kequtech/tenon-orm/safeql';
+
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error('DATABASE_URL is required for SQL checking');
+
+export default defineConfig(baseConfig, {
+  files: ['src/**/*.ts', 'src/**/*.tsx'],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: { projectService: true },
+  },
+  plugins: { tenon: eslintPlugin },
+  rules: { 'tenon/check-composition': 'error' },
+  extends: [
+    safeql.configs.connections({
+      databaseUrl,
+      plugins: [safeqlPlugin],
+      targets: [{ tag: { regex: '.*' } }],
+    }),
+  ],
+});
+```
+
+Preserve existing type-aware parser settings where configured. The broad target above lets Tenon
+recognize aliases; use distinct targets for [multiple databases](reference.md#configuration-choices-and-multiple-databases).
+The example does not load environment files. Use the application's existing environment loader
+and URL selection to supply its migrated development/test database through `DATABASE_URL`.
+
+```json
+{
+  "scripts": {
+    "lint:sql": "eslint --config eslint.sql.config.mjs \"src/**/*.{ts,tsx}\""
+  }
+}
+```
+
+Start with `npm run lint:sql`. Keep both checking rules enabled and distinguish the findings:
+
+- SQL errors identify problems in reconstructed SQL; review them before accepting inferred types.
+- Missing/mismatched annotations may reflect an outdated type, a deliberate application refinement,
+  or a checker limitation. They are not all demonstrated application bugs.
+- `tenon/check-composition` means SQL analysis was skipped. Add inline selected columns for opaque
+  mutation inputs where useful. Keep reusable authorization policy centralized when its fragments
+  remain unsupported, with database tests for runtime variants.
+
+Preview fixes on a small module first, without writing source. Invoke ESLint directly to select
+one file, since the script above already supplies a source glob:
+
+```sh
+npx eslint --config eslint.sql.config.mjs src/database/profiles.ts --fix-dry-run --format json
+```
+
+Review the proposed annotations, apply selected changes deliberately, and run TypeScript and
+database tests. Broader inferred types may require validation where raw database values enter the
+application. For example, require a finite `Date` before calling `.getTime()`, validate structured
+JSON from `unknown`, and justify CHECK-constrained string refinements with matching schema checks
+or a reviewed column override. Do not globally map timestamps to `Date`: pg can return numeric
+infinities. See [checker mappings](reference.md#supported-sql-and-limitations).
+
+Unsupported queries have not had their SQL verified. Keep database tests for their runtime variants
+and use explained suppressions only where appropriate. Once the intended scope passes, make SQL
+checking a required CI step. Fix commands can also apply other enabled ESLint rules.
+
 ## Move migration ownership to Tenon
 
 Choose one final schema checkpoint for the old runner and bring existing target databases to it.

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.
 
@@ -124,6 +124,11 @@ 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.
 
+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).
+
 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
@@ -140,10 +145,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 +205,9 @@ 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.
 
+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. The selected column lists
+above also let the optional SQL checker inspect runtime-built inputs. They select fields rather
+than 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:
@@ -255,9 +259,10 @@ works, but it does not prove that every variant is valid SQL or returns the decl
 const filters = [sql.fragment`active = ${true}`];
 if (email !== undefined) filters.push(sql.fragment`email = ${email}`);
 
-// eslint-disable-next-line tenon/check-composition -- Runtime filters are covered by database tests.
+/* eslint-disable 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`;
+/* eslint-enable tenon/check-composition */
 ```
 
 The initial condition keeps this list nonempty. Empty lists throw so that missing filters cannot

package/docs/mutations.md

@@ -22,13 +22,54 @@ required fields and constraints.
 For runtime-built rows, supply an inline column list for SafeQL:
 
 ```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
@@ -89,8 +130,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,8 +148,9 @@ 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.
+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.
 
 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,

package/docs/reference.md

@@ -199,10 +199,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.
 
@@ -277,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
@@ -341,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`:
 
@@ -382,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
@@ -404,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
@@ -465,10 +504,8 @@ 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
 
@@ -488,6 +525,12 @@ references, runtime filter lists, and dynamic identifiers are also unsupported.
 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.
@@ -548,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.1",
+  "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')}
-`;
-}