@kequtech/tenon-orm 0.1.0 → 0.1.1

package/README.md

@@ -64,6 +64,12 @@ migrations and table type generation are independent conveniences.
 >
 > — Codex, after working on Tenon. An interested party, to put it mildly.
 
+## Object-based writes
+
+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).
+
 ## Checking query results
 
 The type in `sql<{ id: number; email: string }>` describes what you expect back. TypeScript alone
@@ -74,8 +80,8 @@ SQL against your development database and can write or repair the result annotat
 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 and constant fragments, 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
+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.

package/dist/mutations.d.ts

@@ -0,0 +1,11 @@
+export type MutationPart = string | Readonly<{
+    value: unknown;
+}>;
+export type MutationColumns<Row> = Row extends object ? Extract<keyof Row, 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. */
+export declare function insertLayout(columns: readonly string[], rows: readonly (readonly unknown[])[]): MutationPart[];
+export declare function assignmentLayout(columns: readonly string[], values: readonly unknown[]): MutationPart[];
+export declare function insertParts(input: object | readonly object[], selected?: readonly string[]): MutationPart[];
+export declare function assignmentParts(input: object, selected?: readonly string[]): MutationPart[];

package/dist/mutations.js

@@ -0,0 +1,87 @@
+import { quote } from './sql.js';
+import { plainObject } from './validation.js';
+/** Validate and quote one explicit column list, shared by runtime and SQL checking. */
+export function mutationColumns(columns) {
+    if (!Array.isArray(columns) || !columns.length)
+        throw new Error('Mutation columns must be a nonempty array.');
+    const seen = new Set();
+    return Array.from(columns, (column) => {
+        if (typeof column !== 'string')
+            throw new Error('Mutation column names must be strings.');
+        quote(column);
+        if (seen.has(column))
+            throw new Error(`Duplicate mutation column ${JSON.stringify(column)}.`);
+        seen.add(column);
+        return column;
+    });
+}
+/** SQL structure depends only on these columns and cells, never on JavaScript source. */
+export function insertLayout(columns, rows) {
+    if (!rows.length)
+        throw new Error('sql.insertValues requires at least one row.');
+    if (!columns.length) {
+        if (rows.length !== 1)
+            throw new Error('Default-only inserts require exactly one row.');
+        return ['DEFAULT VALUES'];
+    }
+    const parts = [`(${columns.map(quote).join(', ')}) VALUES `];
+    for (const [index, row] of rows.entries()) {
+        if (index)
+            parts.push(', ');
+        parts.push('(');
+        for (const [column, value] of row.entries()) {
+            if (column)
+                parts.push(', ');
+            parts.push(value === undefined ? 'DEFAULT' : Object.freeze({ value }));
+        }
+        parts.push(')');
+    }
+    return parts;
+}
+export function assignmentLayout(columns, values) {
+    const parts = [];
+    for (const [index, column] of columns.entries()) {
+        const value = values[index];
+        if (value === undefined)
+            continue;
+        if (parts.length)
+            parts.push(', ');
+        parts.push(`${quote(column)} = `, Object.freeze({ value }));
+    }
+    if (!parts.length)
+        throw new Error('sql.assignments requires at least one defined field.');
+    return parts;
+}
+function record(value, helper, index) {
+    return plainObject(value, `${helper} row ${index + 1}`);
+}
+function cell(row, column, helper, index) {
+    const property = Object.getOwnPropertyDescriptor(row, column);
+    if (!property)
+        return undefined;
+    if (!('value' in property))
+        throw new Error(`${helper} row ${index + 1} column ${JSON.stringify(column)} must be a data property.`);
+    const value = property.value;
+    if (value &&
+        typeof value === 'object' &&
+        ['fragment', 'identifier', 'query'].some((kind) => Symbol.for(`@kequtech/tenon-orm/${kind}`) in value)) {
+        throw new Error(`${helper} row ${index + 1} column ${JSON.stringify(column)} expects a bound value; put SQL expressions in the surrounding statement.`);
+    }
+    return value;
+}
+export function insertParts(input, selected) {
+    const rows = Array.from(Array.isArray(input) ? input : [input], (row, index) => record(row, 'sql.insertValues', index));
+    if (!rows.length)
+        throw new Error('sql.insertValues requires at least one row.');
+    const columns = selected === undefined
+        ? [
+            ...new Set(rows.flatMap((row, index) => Object.keys(row).filter((column) => cell(row, column, 'sql.insertValues', index) !== undefined))),
+        ]
+        : mutationColumns(selected);
+    return insertLayout(columns, rows.map((row, index) => columns.map((column) => cell(row, column, 'sql.insertValues', index))));
+}
+export function assignmentParts(input, selected) {
+    const row = record(input, 'sql.assignments', 0);
+    const columns = selected === undefined ? Object.keys(row) : mutationColumns(selected);
+    return assignmentLayout(columns, columns.map((column) => cell(row, column, 'sql.assignments', 0)));
+}

package/dist/query.d.ts

@@ -1,4 +1,5 @@
 import type { QueryResultRow } from 'pg';
+import { type MutationColumns } from './mutations.js';
 export type UnknownRow = Record<string, unknown>;
 /** A parameterized statement. The row type describes one returned record. */
 export interface SqlQuery<Row extends QueryResultRow = UnknownRow> {
@@ -19,11 +20,17 @@ 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;
+/** 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 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 & {
     fragment: typeof fragment;
     join: typeof join;
+    insertValues: typeof insertValues;
+    assignments: typeof assignments;
 };
 /** Escape hatch for externally authored SQL. Never concatenate application input into text. */
 export declare function unsafeSql<Row extends QueryResultRow = UnknownRow>(text: string, values: readonly unknown[]): NoInfer<SqlQuery<Row>>;

package/dist/query.js

@@ -1,4 +1,5 @@
 import { joinSeparator, quote } from './sql.js';
+import { assignmentParts, insertParts, } from './mutations.js';
 // Shared symbols let separately installed copies exchange queries and identifiers.
 const queryTag = Symbol.for('@kequtech/tenon-orm/query');
 const identifierTag = Symbol.for('@kequtech/tenon-orm/identifier');
@@ -30,7 +31,8 @@ function templateParts(strings, values) {
     const parts = [strings[0]];
     for (const [i, value] of values.entries()) {
         if (value && typeof value === 'object' && fragmentTag in value) {
-            parts.push(...fragmentParts(value));
+            for (const part of fragmentParts(value))
+                parts.push(part);
         }
         else if (value &&
             typeof value === 'object' &&
@@ -67,10 +69,25 @@ function join(fragments, separator) {
     for (const [i, item] of fragments.entries()) {
         if (i)
             parts.push(between);
-        parts.push(...fragmentParts(item));
+        for (const part of fragmentParts(item))
+            parts.push(part);
     }
     return Object.freeze({ __tenonFragment: true, [fragmentTag]: Object.freeze(parts) });
 }
+/** Object fields become bound values; absent insert cells use PostgreSQL defaults. */
+function insertValues(input, columns) {
+    return Object.freeze({
+        __tenonFragment: true,
+        [fragmentTag]: Object.freeze(insertParts(input, columns)),
+    });
+}
+/** Omit undefined fields; null remains a value. Empty assignments reject. */
+function assignments(input, columns) {
+    return Object.freeze({
+        __tenonFragment: true,
+        [fragmentTag]: Object.freeze(assignmentParts(input, columns)),
+    });
+}
 function createQuery(strings, ...values) {
     const parameters = [];
     let text = '';
@@ -86,13 +103,15 @@ function createQuery(strings, ...values) {
     return unsafeSql(text, parameters);
 }
 /** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
-export const sql = Object.assign(createQuery, { fragment, join });
+export const sql = Object.assign(createQuery, { fragment, join, insertValues, assignments });
 /** Escape hatch for externally authored SQL. Never concatenate application input into text. */
 export function unsafeSql(text, values) {
     if (typeof text !== 'string' || !text.trim())
         throw new Error('SQL must be a nonempty string.');
     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.');
     return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
 }
 export function assertQuery(value) {

package/dist/safeql/composition.d.ts

@@ -1,8 +1,5 @@
 import ts from 'typescript';
-export declare class CompositionError extends Error {
-    readonly name = "TenonCompositionError";
-    constructor(detail: string);
-}
+export { CompositionError } from './static.js';
 export declare function isExport(node: ts.Node, checker: ts.TypeChecker, name: string): boolean;
 export declare function isFragment(type: ts.Type): boolean;
 /** Reconstruct only immutable fragments and literal join lists. Never execute application code. */

package/dist/safeql/composition.js

@@ -2,12 +2,9 @@ import { readFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import ts from 'typescript';
 import { joinSeparator, quote } from '../sql.js';
-export class CompositionError extends Error {
-    name = 'TenonCompositionError';
-    constructor(detail) {
-        super(`Tenon cannot statically check this composition: ${detail} Use a static query/fragment, or an explicit lint suppression with database tests for every runtime variant.`);
-    }
-}
+import { renderMutation } from './mutations.js';
+import { CompositionError, initializer, literalString, unwrap } from './static.js';
+export { CompositionError } from './static.js';
 /** Recognize Tenon's declarations without claiming another library's SQL tags. */
 const tenonModules = new Map();
 function isTenonModule(filename) {
@@ -46,49 +43,11 @@ export function isExport(node, checker, name) {
             isTenonModule(declaration.getSourceFile().fileName));
     });
 }
-function unwrap(node) {
-    while (ts.isParenthesizedExpression(node) ||
-        ts.isAsExpression(node) ||
-        ts.isSatisfiesExpression(node) ||
-        ts.isNonNullExpression(node) ||
-        ts.isTypeAssertionExpression(node)) {
-        node = node.expression;
-    }
-    return node;
-}
-function initializer(node, checker) {
-    let symbol = checker.getSymbolAtLocation(node);
-    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
-        symbol = checker.getAliasedSymbol(symbol);
-    const declaration = symbol?.valueDeclaration;
-    if (declaration &&
-        ts.isVariableDeclaration(declaration) &&
-        ts.isVariableDeclarationList(declaration.parent) &&
-        declaration.parent.flags & ts.NodeFlags.Const) {
-        return declaration.initializer;
-    }
-    return undefined;
-}
 export function isFragment(type) {
     return type.isUnion()
         ? type.types.some(isFragment)
         : type.getProperty('__tenonFragment') !== undefined;
 }
-/** Follow actual const initializers, never assume a literal type proves a runtime value. */
-function literalString(node, checker) {
-    let value = unwrap(node);
-    const seen = new Set();
-    while (ts.isIdentifier(value) && !seen.has(value)) {
-        seen.add(value);
-        const next = initializer(value, checker);
-        if (!next)
-            break;
-        value = unwrap(next);
-    }
-    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
-        ? value.text
-        : undefined;
-}
 /** Reconstruct only immutable fragments and literal join lists. Never execute application code. */
 export function renderFragment(node, checker, seen = new Set()) {
     node = unwrap(node);
@@ -113,6 +72,12 @@ export function renderFragment(node, checker, seen = new Set()) {
         }
         return text;
     }
+    if (ts.isCallExpression(node)) {
+        for (const kind of ['insertValues', 'assignments']) {
+            if (isExport(node.expression, checker, kind))
+                return renderMutation(kind, node, checker);
+        }
+    }
     if (ts.isCallExpression(node) &&
         ts.isPropertyAccessExpression(node.expression) &&
         node.expression.name.text === 'join' &&
@@ -141,7 +106,7 @@ export function renderFragment(node, checker, seen = new Set()) {
         }
         return list.elements.map((item) => renderFragment(item, checker, visited)).join(between);
     }
-    throw new CompositionError('Only sql.fragment templates, const fragment references, and sql.join with literal arrays are supported.');
+    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()) {
     node = unwrap(node);

package/dist/safeql/mutations.d.ts

@@ -0,0 +1,3 @@
+import ts from 'typescript';
+/** Understand the official mutation contract, never the implementation of a JavaScript helper. */
+export declare function renderMutation(kind: 'insertValues' | 'assignments', node: ts.CallExpression, checker: ts.TypeChecker): string;

package/dist/safeql/mutations.js

@@ -0,0 +1,74 @@
+import ts from 'typescript';
+import { assignmentLayout, insertLayout, mutationColumns } from '../mutations.js';
+import { CompositionError, isUndefined, literalString, unwrap } from './static.js';
+const parameter = 0;
+function fields(input) {
+    const node = unwrap(input);
+    if (!ts.isObjectLiteralExpression(node)) {
+        throw new CompositionError('Mutation inputs need inline object literals or an explicit literal column list.');
+    }
+    const result = new Map();
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
+            throw new CompositionError('Mutation object spreads, accessors, and methods need an explicit literal column list.');
+        }
+        const name = property.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name) && !ts.isNumericLiteral(name)) {
+            throw new CompositionError('Mutation keys must be literal names; use an explicit literal column list.');
+        }
+        if (name.text === '__proto__')
+            throw new CompositionError('Prototype-setting object literals are unsupported mutation inputs.');
+        if (result.has(name.text))
+            throw new CompositionError('Duplicate mutation object keys are unsupported.');
+        result.set(name.text, ts.isPropertyAssignment(property) ? property.initializer : property.name);
+    }
+    return result;
+}
+/** Understand the official mutation contract, never the implementation of a JavaScript helper. */
+export function renderMutation(kind, node, checker) {
+    if (node.questionDotToken ||
+        node.arguments.some(ts.isSpreadElement) ||
+        node.arguments.length < 1 ||
+        node.arguments.length > 2) {
+        throw new CompositionError(`sql.${kind} requires an input and an optional literal column list.`);
+    }
+    try {
+        const [argument, selected] = node.arguments;
+        let columns;
+        let rows;
+        if (selected && !isUndefined(selected, checker)) {
+            const list = unwrap(selected);
+            if (!ts.isArrayLiteralExpression(list))
+                throw new CompositionError('Mutation columns must be an inline literal array.');
+            columns = mutationColumns(list.elements.map((item) => {
+                const column = literalString(item, checker);
+                if (column === undefined)
+                    throw new CompositionError('Mutation columns must be literal strings or const strings.');
+                return column;
+            }));
+            // A fixed column contract covers any nonempty batch and every omitted/default cell.
+            // Check all selected columns conservatively; no runtime data or JS types become SQL.
+            rows = [columns.map(() => parameter)];
+        }
+        else {
+            const value = unwrap(argument);
+            const objects = kind === 'insertValues' && ts.isArrayLiteralExpression(value)
+                ? value.elements.map(fields)
+                : [fields(value)];
+            columns = [
+                ...new Set(objects.flatMap((row) => [...row].filter(([, value]) => !isUndefined(value, checker)).map(([key]) => key))),
+            ];
+            rows = objects.map((row) => columns.map((column) => {
+                const cell = row.get(column);
+                return !cell || isUndefined(cell, checker) ? undefined : parameter;
+            }));
+        }
+        const parts = kind === 'insertValues' ? insertLayout(columns, rows) : assignmentLayout(columns, rows[0]);
+        return parts.map((part) => (typeof part === 'string' ? part : '$N')).join('');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new CompositionError(`sql.${kind}: ${error instanceof CompositionError ? error.detail : error.message}`);
+    }
+}

package/dist/safeql/static.d.ts

@@ -0,0 +1,10 @@
+import ts from 'typescript';
+export declare class CompositionError extends Error {
+    readonly detail: string;
+    readonly name = "TenonCompositionError";
+    constructor(detail: string);
+}
+export declare function unwrap(node: ts.Node): ts.Node;
+export declare function initializer(node: ts.Identifier, checker: ts.TypeChecker): ts.Expression | undefined;
+export declare function literalString(node: ts.Node, checker: ts.TypeChecker): string | undefined;
+export declare function isUndefined(node: ts.Node, checker: ts.TypeChecker): boolean;

package/dist/safeql/static.js

@@ -0,0 +1,59 @@
+import ts from 'typescript';
+export class CompositionError extends Error {
+    detail;
+    name = 'TenonCompositionError';
+    constructor(detail) {
+        super(`Tenon cannot statically check this composition: ${detail} Use a static query/fragment, or an explicit lint suppression with database tests for every runtime variant.`);
+        this.detail = detail;
+    }
+}
+export function unwrap(node) {
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+        node = node.expression;
+    return node;
+}
+export function initializer(node, checker) {
+    let symbol = checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    return declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const
+        ? declaration.initializer
+        : undefined;
+}
+/** Follow immutable const aliases only. Never inspect functions or evaluate expressions. */
+function constant(node, checker) {
+    const seen = new Set();
+    node = unwrap(node);
+    while (ts.isIdentifier(node)) {
+        if (seen.has(node))
+            throw new CompositionError('Circular const reference.');
+        if (seen.size >= 1000)
+            throw new CompositionError('Const resolution exceeds 1000 references.');
+        seen.add(node);
+        const value = initializer(node, checker);
+        if (!value)
+            break;
+        node = unwrap(value);
+    }
+    return node;
+}
+export function literalString(node, checker) {
+    const value = constant(node, checker);
+    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+        ? value.text
+        : undefined;
+}
+export function isUndefined(node, checker) {
+    const value = constant(node, checker);
+    return (ts.isIdentifier(value) &&
+        value.text === 'undefined' &&
+        !checker.getSymbolAtLocation(value)?.declarations?.length);
+}

package/docs/agent-guide.md

@@ -108,12 +108,28 @@ const count = sql<{ count: string }>`SELECT count(*) AS count FROM public."User"
 
 `pattern` and `limit` are validated application inputs. To compose existing predicates, use
 `sql.join([first, second], 'AND')`. The checker supports literal join arrays, constant fragments,
-and literal/const-string separators. It rejects mutable, conditional, function-generated, or
-runtime-built composition. Prefer fixed SQL for simple optional filters, e.g.
+literal/const-string separators, and [official mutation helpers](reference.md#object-based-mutation-fragments).
+It rejects mutable or runtime-dependent SQL structure. Prefer fixed SQL for simple optional filters, e.g.
 `(${email}::text IS NULL OR email = ${email})`. If runtime composition is required, retain an
 explicit result type, suppress `tenon/check-composition` only on that query with a reason, and test
 each branch. Parameter binding alone does not establish result correctness.
 
+## Object-based writes
+
+Use official `sql.insertValues(rowOrRows, columns?)` and `sql.assignments(patch, columns?)` fragments
+instead of application helpers that enumerate object keys. Keep tables, authorization predicates,
+expressions, conflict behavior and `RETURNING` visible in SQL. Insert missing/undefined fields use
+PostgreSQL defaults; update missing/undefined fields are omitted. Explicit null stays null. Empty
+batches/updates throw; a single default-only insert works. Omit generated columns and batch large
+writes explicitly below the query-wide limit of 65,535 parameters. Expressions and queries are
+rejected as cell values; write arithmetic, `DEFAULT`, and `excluded.column` in the surrounding SQL.
+
+SafeQL reads inline object/array literals directly. Runtime inputs, spreads and data-builder results
+need explicit inline selected columns, e.g. `sql.insertValues(rows, ['name', 'score'])`. Checking
+uses all selected columns conservatively, without interpreting application JavaScript. It verifies
+SQL and result annotations, not input values, constraints, or nonempty runtime input. See the
+[mutation contract](reference.md#object-based-mutation-fragments) and [cookbook](mutations.md).
+
 ## Configure and run SQL checking
 
 SafeQL checks SQL against the development/test schema and generates or verifies result annotations.
@@ -205,10 +221,15 @@ the wrong type for an unqualified table despite the connection's `search_path`;
 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. 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.
+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

package/docs/human-guide.md

@@ -162,6 +162,24 @@ outside a callback transaction. The guard checks a count; you still need the cor
 and application authorization. Checking returned rows with `returns` alone does not undo an
 autocommitted write.
 
+## Write objects without building column lists by hand
+
+Use `sql.insertValues(rowOrRows)` inside an authored `INSERT` and `sql.assignments(patch)` after
+`SET`. Inserts use database defaults for missing/undefined fields; updates omit those fields.
+Explicit `null` stays null. Empty batches and updates throw. Heterogeneous insert rows remain
+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}`);
+```
+
+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).
+
 ## Check your SQL and result types
 
 There are three different jobs here:
@@ -171,8 +189,8 @@ There are three different jobs here:
 - 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 and constant fragments. A small companion ESLint rule,
-`tenon/check-composition`, flags queries that cannot be checked statically. SafeQL performs the
+`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

package/docs/mutations.md

@@ -0,0 +1,115 @@
+# Mutation cookbook
+
+Keep SQL structure visible and let the official helpers handle object fields. See the
+[reference](reference.md#object-based-mutation-fragments) for the complete contract. Examples use
+application-owned inputs and clients; add the authorization predicates required by your product.
+
+## Defaults, undefined, and null in batches
+
+```ts
+await db.query(
+  sql`INSERT INTO profiles ${sql.insertValues([
+    { name: 'Ada', bio: null },
+    { name: 'Lin', score: 4, bio: undefined },
+  ])} RETURNING id`,
+);
+```
+
+The first row uses the score default. The second uses the bio default. Explicit null in the first
+row stays null. Columns are aligned across rows. Omit generated columns and let PostgreSQL enforce
+required fields and constraints.
+
+For runtime-built rows, supply an inline column list for SafeQL:
+
+```ts
+const rows: { name: string; bio?: string | null; score?: number }[] = 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.
+
+## Patches mixed with SQL expressions
+
+```ts
+await db.query(sql`UPDATE profiles
+  SET ${sql.assignments({ name, bio })}, revision = revision + 1, score = DEFAULT
+  WHERE id = ${id}`);
+```
+
+Undefined fields are omitted; null clears a field. Expressions, `DEFAULT`, and references to
+`excluded.column` belong in SQL, not in mutation objects.
+
+An empty patch throws even if the surrounding statement has other assignments. Choose an
+expression-only query explicitly when that is the intended behavior:
+
+```ts
+const patch: { name?: string; bio?: string | null } = readPatch();
+if (patch.name !== undefined || patch.bio !== undefined) {
+  await db.query(sql`UPDATE profiles
+    SET ${sql.assignments(patch, ['name', 'bio'])}, revision = revision + 1
+    WHERE id = ${id}`);
+} else {
+  await db.query(sql`UPDATE profiles SET revision = revision + 1 WHERE id = ${id}`);
+}
+```
+
+## Preserve an omitted field during an upsert
+
+Use complete query variants when an option changes conflict behavior. Both templates can be
+checked independently; the checker need not choose a JavaScript branch:
+
+```ts
+if (email !== undefined) {
+  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app, email })}
+    ON CONFLICT (profile_id) DO UPDATE
+    SET in_app = excluded.in_app, email = excluded.email`);
+} else {
+  await db.query(sql`INSERT INTO preferences ${sql.insertValues({ profile_id, in_app })}
+    ON CONFLICT (profile_id) DO UPDATE SET in_app = excluded.in_app`);
+}
+```
+
+The second query leaves an existing email value unchanged. Missing an insert field uses its
+database default; that alone does not decide what an upsert should overwrite.
+
+## JSONB arrays and PostgreSQL arrays
+
+Tenon preserves pg's value conversion. A JavaScript array binds as a PostgreSQL array. To write an
+array into a JSON/JSONB column, serialize it explicitly:
+
+```ts
+const handles = ['ada', 'lin'];
+await db.query(
+  sql`INSERT INTO deliveries ${sql.insertValues({
+    recipients_json: JSON.stringify(handles), // jsonb column
+    recipient_handles: handles, // text[] column
+  })}`,
+);
+```
+
+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.
+
+## Batches in one transaction
+
+Choose the batch size in the caller and keep all writes on the transaction client:
+
+```ts
+await db.transaction(async (tx) => {
+  for (let offset = 0; offset < rows.length; offset += 300) {
+    const batch = rows.slice(offset, offset + 300);
+    await tx.query(sql`INSERT INTO profiles ${sql.insertValues(batch, ['name', 'bio', 'score'])}`);
+  }
+});
+```
+
+A failure rolls back all batches. The helper rejects an empty batch; this loop makes no insert
+calls for empty input. The query-wide limit is 65,535 bound parameters, including parameters outside
+the mutation fragment. Defaults consume no parameters. Account for your selected column count and
+surrounding query when choosing a batch size; Tenon never splits queries automatically.
+
+Reusable authorization fragments remain valid at runtime. Keep shared policy in application
+functions and test it rather than duplicating it for static coverage. Function-generated SQL,
+conditional fragments, and dynamic filter lists remain outside static checking.

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 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
+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
@@ -230,8 +323,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.
@@ -381,16 +474,35 @@ avoid that ambiguity.
 
 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.
+
+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

package/package.json

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