@kequtech/tenon-orm 0.3.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.4.2
+
+- Rewrite the README and consumer guides around a complete getting-started workflow and task-based navigation.
+- Add guides for SQL queries, schema types and values, connections, and migrations, including joins, pagination, codec configuration, rollback, and migration recovery.
+- Clarify query result modes, write guards, generated types, source checking, and their validation limits. This release changes documentation only; no application migration is required.
+
+## 0.4.1
+
+- Add `db.generateTypes({ out, namespace?, check?, onWarning? })`, using the instance's configured codecs.
+- Remove `tenon generate`; run generation and freshness checks from an application script.
+  Use the configured database instance, set `check: true` for freshness checks, and close it when
+  the script finishes. See the [generation script example](docs/human-guide.md#generate-types).
+
+## 0.4.0
+
+### Breaking changes
+
+- Replace bundled `pg` and `@types/pg` with the `@kequtech/pgclear` runtime dependency (`^0.3.0`).
+  Installing Tenon includes the driver; compatible driver patches can update independently.
+  Connections accept a PostgreSQL URI, pgclear `PoolOptions`, or a pgclear `Pool`; translate former
+  pg configuration and supply deployment settings explicitly.
+  PG environment defaults, pgpass/service files, and pg-specific URI options are not read. See
+  [connection configuration](docs/connections.md#configure-a-database-instance).
+- `db.native` is now a pgclear `Pool`. Use `queryClassic(text, values?)` for finished SQL and
+  acquire/withSession for held sessions; native `query` accepts pgclear's own sql tag only. Prepared
+  statements, streams, and COPY use the public session APIs. Use pgclear `listen` for dedicated
+  notifications. Pool shutdown, transaction outcomes, and savepoint recovery delegate to the driver.
+- Command counts remain safe integer numbers; int8/bigserial, SQL count(*) and int8 array elements
+  use exact strings. Temporal values and exact numeric arrays are strings, bytes are Uint8Array,
+  and result arrays are readonly. JSON/array binds need pgclear json/param or encoded strings.
+  Plain bigint, Date, and supported native/polyfilled Temporal inputs use text and server inference;
+  output conversions are opt-in. Undefined, plain objects, and arrays reject; mutation-helper
+  undefined still omits. JSON encoding still rejects bigint values.
+- Tenon owns schema generation and exports `Database[table]['row' | 'insert' | 'update']`.
+  Regenerate committed definitions and review write representations. Replace `Rows[table]`,
+  `Rows.Insert[table]`, and `Rows.Update[table]` with `Database[table]['row']`,
+  `Database[table]['insert']`, and `Database[table]['update']`.
+  Catalog queries, schema summaries, defaults/domains/identities, and TypeScript rendering live in
+  Tenon; decoder representations come from pgclear. Import generation from Tenon instead of pgclear.
+  Tenon retains migration coordination, atomic file output, and `generate --check` freshness checks.
+
+### Added and improved
+
+- Re-export Pgclear parameter/codec helpers and their types through Tenon, so application queries
+  and generated declarations use one import path. Use Tenon's `sql` for `db.query`.
+- Add optional `tenon check` for a project, file, or file:line, with readable/JSON diagnostics and a
+  programmatic `@kequtech/tenon-orm/check` API. Fixed fragments, joins, explicit object shapes, and
+  bounded ternaries are checked through pgclear Describe without importing application code or
+  executing application SQL. Definite mismatches and unchecked queries fail; inconclusive
+  nullability, JSON shapes, decoder types, and refinements remain unproven notes.
+- Bundle TypeScript 6 for source checking and load it only on the checking path. Ordinary execution
+  continues to trust result annotations; database tests remain necessary for rows and write effects.
+- Inspection uses public pgclear Describe with parameter OID hints and a selected codec registry.
+  Custom text codecs can declare `text.typescript`; generation and source checking use that metadata,
+  including derived arrays, without duplicate readTypes declarations. Unidentified custom decoders
+  remain unresolved. Migrations, generation, and inspection use public pgclear sessions without a
+  private protocol adapter. Catalog reads keep default decoding on the application's borrowed session.
+- Clarify the documentation reading path, common failures, optional patch checking, and the roles of
+  source checking, SQL inspection, and generated-file freshness. Keep historical driver reviews out
+  of the published consumer docs.
+
+## 0.3.1
+
+- Expand documentation for driver configuration, transaction result adapters, value mappings, and
+  validation between persistence representations and application domain values.
+
 ## 0.3.0
 
 - **Breaking:** `pg@8.23.1` replaces Postgres.js. Use pg `PoolConfig` (`connectionString` for a URI)

package/README.md

@@ -2,16 +2,20 @@
 
 A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
-Write SQL directly, bind values with a template tag, and reuse queries through ordinary functions.
-Tenon provides transactions, affected-row guards, SQL migrations, generated database types, and
-query inspection. It includes its pinned pg driver.
+Tenon keeps database work in forms coding agents can read, write, and check: explicit SQL, ordinary
+TypeScript functions, and SQL migrations. Queries carry their result types and execution options
+together, so an agent and the person reviewing its work can see what an operation does in one place.
 
 ```sh
 npm install @kequtech/tenon-orm
 ```
 
-Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
-development typings.
+Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript applications need TypeScript 6+ and Node.js
+typings. The PostgreSQL driver, [pgclear](https://github.com/kequtech/pgclear), is included.
+
+## Query with SQL
+
+This example assumes a `public.users` table with integer `id` and text `email` columns:
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
@@ -28,38 +32,89 @@ try {
     `,
     { returns: 'oneOrNone' },
   );
-  // user is { id: number; email: string } | undefined
+  // user: { id: number; email: string } | undefined
 } finally {
   await db.close();
 }
 ```
 
-The example assumes `public.users` exists. In a server, reuse the instance and close it at shutdown.
-`oneOrNone` rejects multiple rows; use `one` for exactly one row, `many` for an array, or omit
-`returns` for the driver's result object and metadata.
+`${email}` becomes `$1` in the SQL, with the value passed separately. `sql<Row>` describes one
+returned row. `returns` chooses how Tenon gives those rows back:
+
+| `returns`          | You receive                                         | Required rows |
+| ------------------ | --------------------------------------------------- | ------------- |
+| `many`             | `readonly Row[]`                                    | Any number    |
+| `oneOrNone`        | `Row \| undefined`                                  | Zero or one   |
+| `one`              | `Row`                                               | Exactly one   |
+| `native` (default) | Driver result with `rows`, `rowCount`, and `fields` | Any number    |
+
+A row-count mismatch throws. The modes do not add `LIMIT` or change the SQL. In a server, reuse one
+database instance and close it during shutdown. Supply environment variables through your application;
+Tenon does not load `.env` files.
+
+## Designed for coding agents
+
+Tenon's API gives coding agents concrete code to work with and explicit contracts to preserve:
 
-Joins, relationships, aggregates, and upserts use PostgreSQL SQL. Object-based writes can use
-`sql.insertValues` and `sql.assignments` while keeping the surrounding statement explicit.
-`db.native` exposes the underlying `pg.Pool` for LISTEN, cursors, COPY, and other driver features;
-those calls bypass Tenon's query and transaction guards.
+- **Readable SQL.** Selected columns, joins, filters, and conflict handling are visible in the query.
+  An agent can inspect the operation directly and use PostgreSQL's existing vocabulary.
+- **Ordinary TypeScript.** Reusable queries are functions. An agent can follow imports, change a
+  function, and pass the same query code a database or transaction client.
+- **Explicit write limits.** A query can require exactly one affected row or set a maximum. Tenon
+  rolls back the operation if that bound is violated.
+- **Actionable checks.** Generated table types describe storage contracts; `tenon check` reports
+  contradictions between recoverable SQL and declared types. Freshness checks catch stale generated
+  declarations, and database tests verify results and effects.
 
-`sql<Row>` declares an expected result type. `describeQuery` inspects the finished SQL through
-PostgreSQL without executing it; it does not verify that annotation. Keep database tests for actual
-rows and write effects. Validation, authorization, and retry policy belong to the application.
-Existing migration runners can be retained; Tenon's migrations and type generation are optional.
+The guides and changelog ship with the package, giving an agent documentation for the installed
+version. For work in an existing project, start with the [agent guide](docs/agent-guide.md).
+
+## How Tenon fits together
+
+- **SQL defines the operation.** Use PostgreSQL joins, aggregates, constraints, and upserts directly.
+  Reuse queries with ordinary functions; use fragments when parts of the SQL need to vary.
+- **TypeScript describes the values.** Declare query projections with `sql<Row>`. Optionally generate
+  table read/insert/update types with `db.generateTypes({ out: 'src/generated-schema.d.ts' })`.
+- **Transactions define what commits together.** Use `db.transaction(async (tx) => { ... })` and run
+  every participating query through `tx`.
+- **Write guards check affected rows.** `{ affectedRows: { exact: 1 } }` rolls back a write unless
+  exactly one row was affected. `{ max: 1 }` allows zero or one.
+- **Migrations change the schema.** Tenon's optional runner applies numbered SQL files. You can keep
+  an existing schema and migration runner.
+
+For object inputs, `sql.insertValues(input)` and `sql.assignments(patch)` build the column/value
+parts of a statement. The table, conditions, expressions, and conflict behavior stay in your SQL.
+There are no model instances or implicit relationship loading.
+
+Query types are declarations. Tenon does not validate returned data against `Row` during execution.
+The optional `tenon check` command compares recoverable source queries with TypeScript types and
+PostgreSQL metadata. Keep database tests for actual results and write effects.
+
+Some PostgreSQL values need care: bigint columns and `count(*)` read as exact strings, numeric and
+temporal values also default to strings, and JSON/array inputs use explicit encoding helpers. Command
+`rowCount` is a number or null. See [value mappings](docs/schema-types.md#value-mappings) before
+choosing application types.
 
 ## Documentation
 
-- **[Human guide](docs/human-guide.md)** — a table, queries, transactions, and generated types.
-- **[Agent guide](docs/agent-guide.md)** — implementation contracts and upgrade workflow.
-- **[Reference](docs/reference.md)** — API options, value mappings, CLI, and limitations.
-- **[Adoption guide](docs/adoption-guide.md)** — replace an ORM and transfer migration ownership.
-- **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, and batching.
-- **[Query inspection](docs/query-inspection.md)** — Describe reports and database tests.
-- **[Changelog](CHANGELOG.md)** — versioned changes and upgrade instructions.
+Start with [Getting started](docs/human-guide.md) for a complete table-to-query example. Then choose
+the guide for your task:
+
+| Guide                                                      | What it covers                                                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Writing queries](docs/sql.md)                             | Parameters, reusable functions, joins, aggregates, pagination, and fragments |
+| [Writing data](docs/mutations.md)                          | Inserts, patches, defaults, upserts, JSON, arrays, and batches               |
+| [Schema types and values](docs/schema-types.md)            | Generation, read/write types, codecs, and domain validation                  |
+| [Migrations](docs/migrations.md)                           | Creating, applying, inspecting, and rolling back SQL migrations              |
+| [Connections and driver access](docs/connections.md)       | Pool configuration, shutdown, custom codecs, and native features             |
+| [Checking query types](docs/query-checking.md)             | Source-aware checks and their supported SQL composition                      |
+| [Inspecting and testing queries](docs/query-inspection.md) | PostgreSQL metadata and tests of real behavior                               |
+| [Adopting Tenon](docs/adoption-guide.md)                   | Replacing an ORM and transferring migration ownership                        |
+| [Agent guide](docs/agent-guide.md)                         | A short implementation workflow for an existing project                      |
+| [API and CLI reference](docs/reference.md)                 | Signatures, options, errors, commands, and troubleshooting                   |
 
-These documents all ship with the npm package, including the changelog so an agent upgrading a
-project can read the relevant release entries locally. Repository maintenance instructions are in
+The README, guides, and [changelog](CHANGELOG.md) ship with the npm package. Read the documentation
+for your installed version when upgrading. Library maintenance is covered in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md).
 
 [ISC licensed](LICENSE). Maintained by [Kequtech](https://github.com/kequtech).

package/dist/affected-rows.js

@@ -18,7 +18,6 @@ export function validateAffectedRows(value) {
 export function checkAffectedRows(constraint, result) {
     if (!['INSERT', 'UPDATE', 'DELETE', 'MERGE'].includes(result.command) ||
         result.rowCount === null ||
-        !Number.isSafeInteger(result.rowCount) ||
         result.rowCount < 0) {
         throw new AffectedRowsError(constraint, result.rowCount, result.command, false);
     }

package/dist/baseline.js

@@ -82,16 +82,14 @@ export async function adoptBaseline(options) {
         if (applied.length) {
             return [];
         }
-        const schema = await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [
-            namespace,
-        ]);
+        const schema = await client.queryClassic('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [namespace]);
         if (!schema.rows.length) {
             throw new Error('The baseline namespace does not exist. Use migrate to initialize a fresh database.');
         }
-        await client.query('BEGIN');
+        await client.queryClassic('BEGIN', []);
         await createHistoryTable(client, namespace);
         await recordMigration(client, namespace, baseline);
-        const result = await client.query('COMMIT');
+        const result = await client.queryClassic('COMMIT', []);
         if (result.command !== 'COMMIT') {
             throw new Error('Baseline adoption was rolled back.');
         }

package/dist/check/contracts.d.ts

@@ -0,0 +1,6 @@
+import type { QueryDescription } from '../inspection/types.js';
+import { type Project } from './project.js';
+import type { QueryNode, QueryVariant } from './source.js';
+import type { CheckDiagnostic } from './types.js';
+/** Compare non-NULL representations; nullability and value refinements remain explicit limitations. */
+export declare function compareContracts(project: Project, query: QueryNode, variant: QueryVariant, description: QueryDescription, readTypes: Readonly<Record<number, string>>): CheckDiagnostic[];

package/dist/check/contracts.js

@@ -0,0 +1,206 @@
+import ts from 'typescript';
+import { location } from './project.js';
+function kinds(project, type, seen = new Set()) {
+    if (seen.has(type))
+        return new Set();
+    seen.add(type);
+    if (type.isUnion())
+        return new Set(type.types.flatMap((member) => [...kinds(project, member, seen)]));
+    if (type.isIntersection())
+        return new Set(type.types.flatMap((member) => [...kinds(project, member, seen)]));
+    if (type.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Never))
+        return new Set();
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter))
+        return new Set(['unknown']);
+    for (const [flag, name] of [
+        [ts.TypeFlags.StringLike, 'string'],
+        [ts.TypeFlags.NumberLike, 'number'],
+        [ts.TypeFlags.BigIntLike, 'bigint'],
+        [ts.TypeFlags.BooleanLike, 'boolean'],
+    ])
+        if (type.flags & flag)
+            return new Set([name]);
+    if (project.checker.isArrayType(type) || project.checker.isTupleType(type))
+        return new Set(['array']);
+    return new Set(['object']);
+}
+function disjoint(project, actual, expected, depth = 0) {
+    if (depth > 8)
+        return false;
+    const a = kinds(project, actual), b = kinds(project, expected);
+    if (!b.size)
+        return true;
+    if (a.has('unknown') || b.has('unknown'))
+        return false;
+    if (![...a].some((kind) => b.has(kind)))
+        return true;
+    if (a.size === 1 && a.has('array') && b.size === 1 && b.has('array')) {
+        const elements = (type) => (type.isUnion() ? type.types : [type]).flatMap((part) => {
+            const element = project.checker.getIndexTypeOfType(part, ts.IndexKind.Number);
+            return element ? [element] : [];
+        });
+        const actualElements = elements(actual), expectedElements = elements(expected);
+        return (actualElements.length > 0 &&
+            expectedElements.length > 0 &&
+            actualElements.every((a) => expectedElements.every((b) => disjoint(project, a, b, depth + 1))));
+    }
+    if (a.size === 1 && a.has('object') && b.size === 1 && b.has('object')) {
+        for (const property of actual.getProperties()) {
+            const other = expected.getProperty(property.name);
+            if (!other ||
+                (property.flags & ts.SymbolFlags.Optional && other.flags & ts.SymbolFlags.Optional))
+                continue;
+            const context = project.selected[0];
+            if (disjoint(project, project.checker.getTypeOfSymbolAtLocation(property, context), project.checker.getTypeOfSymbolAtLocation(other, context), depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+function rowType(project, query) {
+    const explicit = query.typeArguments?.[0];
+    if (explicit)
+        return project.checker.getTypeFromTypeNode(explicit);
+    const contextual = project.checker.getContextualType(query);
+    const type = contextual ?? project.checker.getTypeAtLocation(query);
+    const property = type.getProperty('__rowType');
+    return property
+        ? project.checker.getNonNullableType(project.checker.getTypeOfSymbolAtLocation(property, query))
+        : undefined;
+}
+/** Compare non-NULL representations; nullability and value refinements remain explicit limitations. */
+export function compareContracts(project, query, variant, description, readTypes) {
+    const checker = project.checker;
+    const at = location(query);
+    const diagnostics = [];
+    for (const [index, parameter] of variant.parameters.entries()) {
+        const expected = description.parameters[index];
+        if (!expected)
+            continue;
+        const inputKinds = kinds(project, parameter.type);
+        if (inputKinds.has('string') || inputKinds.has('number')) {
+            diagnostics.push({
+                ...location(parameter.node),
+                kind: 'unproven',
+                code: 'parameter-value-unproven',
+                parameter: index + 1,
+                expected: expected.postgres,
+                observed: checker.typeToString(parameter.type),
+                message: `Parameter ${index + 1}${parameter.field ? ` (${parameter.field})` : ''}: ${checker.typeToString(parameter.type)} does not prove PostgreSQL ranges or textual formats for ${expected.postgres}.`,
+            });
+        }
+    }
+    if (description.columns.length)
+        diagnostics.push({
+            ...at,
+            kind: 'unproven',
+            code: 'nullability-unproven',
+            message: 'Describe does not establish result nullability; column representation checks exclude SQL NULL.',
+        });
+    for (const issue of description.issues) {
+        if (issue.code === 'duplicate-column')
+            diagnostics.push({
+                ...at,
+                kind: 'mismatch',
+                code: issue.code,
+                resultColumn: issue.column,
+                message: issue.message,
+            });
+    }
+    const declared = rowType(project, query);
+    if (!declared ||
+        declared.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.TypeParameter)) {
+        diagnostics.push({
+            ...at,
+            kind: 'unproven',
+            code: 'result-type-unproven',
+            message: 'No concrete declared result shape was resolved.',
+        });
+        return diagnostics;
+    }
+    const alternatives = declared.isUnion() ? declared.types : [declared];
+    const results = alternatives.map((row) => {
+        const findings = [];
+        for (const property of row.getProperties()) {
+            if (!(property.flags & ts.SymbolFlags.Optional) &&
+                !description.columns.some((column) => column.name === property.name)) {
+                findings.push({
+                    ...at,
+                    kind: 'mismatch',
+                    code: 'missing-column',
+                    resultColumn: property.name,
+                    expected: checker.typeToString(checker.getTypeOfSymbolAtLocation(property, query)),
+                    observed: 'absent',
+                    message: `Required result property ${JSON.stringify(property.name)} is absent from the SQL result.`,
+                });
+            }
+        }
+        for (const column of description.columns) {
+            const property = row.getProperty(column.name);
+            const expected = property
+                ? checker.getTypeOfSymbolAtLocation(property, query)
+                : checker.getIndexTypeOfType(row, ts.IndexKind.String);
+            if (!expected)
+                continue; // Structural result types may omit additional selected columns.
+            const representation = readTypes[column.oid] ?? column.readType;
+            const actual = project.types.get(representation);
+            const common = {
+                ...at,
+                resultColumn: column.name,
+                expected: checker.typeToString(expected),
+                observed: representation,
+            };
+            if (!actual || actual.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) {
+                findings.push({
+                    ...common,
+                    kind: 'unproven',
+                    code: 'result-representation-unproven',
+                    message: `Column ${JSON.stringify(column.name)} has an unresolved decoder representation or JSON shape; ${checker.typeToString(expected)} is unproven.`,
+                });
+                continue;
+            }
+            const nonnull = checker.getNonNullableType(expected);
+            if (nonnull.flags & ts.TypeFlags.Any) {
+                findings.push({
+                    ...common,
+                    kind: 'unproven',
+                    code: 'result-type-unproven',
+                    message: `Column ${JSON.stringify(column.name)} is declared as any.`,
+                });
+            }
+            else if (!checker.isTypeAssignableTo(actual, nonnull)) {
+                const mismatch = disjoint(project, actual, nonnull);
+                findings.push({
+                    ...common,
+                    kind: mismatch ? 'mismatch' : 'unproven',
+                    code: mismatch ? 'result-type-mismatch' : 'result-refinement-unproven',
+                    message: `Column ${JSON.stringify(column.name)} decodes as ${representation}; its declared type ${checker.typeToString(expected)} ${mismatch ? 'contradicts that representation' : 'requires a refinement Describe cannot prove'}.`,
+                });
+            }
+        }
+        return findings;
+    });
+    const compatible = results.filter((findings) => !findings.some((finding) => finding.kind === 'mismatch'));
+    if (compatible.length) {
+        compatible.sort((a, b) => a.length - b.length);
+        diagnostics.push(...compatible[0]);
+    }
+    else if (results.length === 1)
+        diagnostics.push(...results[0]);
+    else {
+        diagnostics.push({
+            ...at,
+            kind: 'mismatch',
+            code: 'result-union-mismatch',
+            expected: checker.typeToString(declared),
+            observed: description.rowType ?? 'no row declaration',
+            message: `No declared result union member matches this SQL variant: ${results
+                .map((findings) => findings
+                .filter((finding) => finding.kind === 'mismatch')
+                .map((finding) => finding.message)
+                .join(' '))
+                .join(' / ')}`,
+        });
+    }
+    return diagnostics;
+}

package/dist/check/project.d.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+import type { CheckOptions, CheckDiagnostic, SourceLocation } from './types.js';
+export declare function location(node: ts.Node): SourceLocation;
+export declare function symbol(checker: ts.TypeChecker, node: ts.Node): ts.Symbol | undefined;
+export declare function loadProject(options: CheckOptions): {
+    program: ts.Program;
+    checker: ts.TypeChecker;
+    types: Map<string, ts.Type>;
+    parameterType: ts.Type;
+    files: ts.SourceFile[];
+    selected: ts.SourceFile[];
+    line: number | undefined;
+    project: string;
+    diagnostics: CheckDiagnostic[];
+};
+export type Project = ReturnType<typeof loadProject>;
+/** Resolve actual exported symbols, including aliases and barrel re-exports. */
+export declare function librarySymbols(project: Project): ReadonlyMap<string, ts.Symbol>;