@kequtech/tenon-orm 0.1.0 → 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
@@ -64,6 +64,14 @@ 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).
+Use [generated input types](docs/reference.md#insert-and-update-inputs) to check those objects
+against your schema.
+
 ## Checking query results
 
 The type in `sql<{ id: number; email: string }>` describes what you expect back. TypeScript alone
@@ -73,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 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
-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.
@@ -91,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

@@ -0,0 +1,11 @@
+export type MutationPart = string | Readonly<{
+    value: unknown;
+}>;
+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. */
+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<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<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 & {
     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; 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.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,16 @@ 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.');
+    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()) {
     node = unwrap(node);

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/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;