@kequtech/tenon-orm 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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
@@ -9,7 +22,7 @@
   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
-  [upgrading from 0.3.x](docs/adoption-guide.md#upgrade-from-tenon-03x).
+  [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
@@ -21,7 +34,9 @@
   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, replace former Rows imports, and review write representations.
+  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.

package/README.md

@@ -2,19 +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 and optional source-aware checking. Tenon owns database declarations and application
-TypeScript tooling. Execution, Describe, and value conversion come from the
-`@kequtech/pgclear` runtime dependency. Import `sql`, `json`, `param`, and codec helpers from
-Tenon for application queries; no separate driver installation is needed.
+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';
@@ -31,57 +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.
-
-Command `rowCount` values are numbers. SQL `count(*)`, bigint/bigserial columns, and bigint array
-elements read as exact strings by default. Plain bigint, Date, and supported native/polyfilled
-Temporal inputs use server type inference; output conversions to bigint, Date, or Temporal are
-explicit codec choices. JSON and PostgreSQL arrays use explicit helpers. See the
-[value mappings](docs/reference.md#generated-types-and-checking).
-
-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 pgclear `Pool` for prepared statements, streams, COPY, and
-other driver features; those calls bypass Tenon's query and transaction guards. Use pgclear's
-`listen` for a dedicated notification connection.
-
-`sql<Row>` declares an expected result type. `tenon check src/users.ts:23` checks a recoverable query
-against that type and PostgreSQL Describe without executing the statement. Inconclusive types remain
-unproven; unsupported SQL composition is reported as unchecked. `describeQuery` inspects finished SQL
-without comparing a source 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.
+`${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:
+
+- **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.
+
+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
 
-Start with this README, then follow the [agent guide](docs/agent-guide.md) when working in an
-existing project or the [human guide](docs/human-guide.md) for a first setup. Use the reference for
-specific options and the focused guides when a task needs them. Read the docs shipped with the
-installed Tenon version; unreleased repository changes may differ.
-
-- **[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.
-- **[Query checking](docs/query-checking.md)** — project/file/line checking, composition, and limitations.
-- **[Changelog](CHANGELOG.md)** — versioned changes and upgrade instructions.
-
-For common failures, see [troubleshooting](docs/reference.md#troubleshooting). To choose between
-source checking, SQL inspection, and generated-file freshness, see
-[validation tools](docs/reference.md#choosing-a-validation-tool).
-
-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
+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                   |
+
+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/cli.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { adoptBaseline, captureBaseline } from './baseline.js';
-import { generateDefinitions } from './generate.js';
-import { writeDefinitions } from './generation/output.js';
 import { describeFlags, inspectionSettings, runDescribe } from './inspection/cli.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
@@ -10,7 +8,6 @@ const help = `tenon migrate|status|rollback [--directory migrations] [--namespac
 tenon baseline capture|adopt [--directory migrations] [--namespace public]
 baseline capture: [--schema name ...] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
-tenon generate [--namespace public] [--out src/generated-schema.ts] [--check]
 tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
 describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
@@ -41,9 +38,7 @@ async function main() {
         options: {
             directory: { type: 'string', default: 'migrations' },
             namespace: { type: 'string', default: 'public' },
-            out: { type: 'string', default: 'src/generated-schema.ts' },
             schema: { type: 'string', multiple: true },
-            check: { type: 'boolean', default: false },
             steps: { type: 'string', default: '1' },
             help: { type: 'boolean', default: false },
             project: { type: 'string' },
@@ -56,18 +51,17 @@ async function main() {
         return;
     }
     const [command, argument] = positionals;
+    if (command === 'generate') {
+        throw new Error('The generate command has been removed. Use db.generateTypes({ out, namespace?, check? }) in an application script so generation uses your configured codecs.');
+    }
     // Validate explicitly supplied flags, not defaults. Silently ignoring --check
     // on migrate, for example, would turn an intended dry run into a schema change.
     const allowed = new Set(['help']);
-    if (command !== 'generate' && command !== 'describe' && command !== 'check')
+    if (command !== 'describe' && command !== 'check')
         allowed.add('directory');
     if (command !== 'new' && command !== 'describe' && command !== 'check') {
         allowed.add('namespace');
     }
-    if (command === 'generate') {
-        allowed.add('out');
-        allowed.add('check');
-    }
     if (command === 'rollback') {
         allowed.add('steps');
     }
@@ -100,10 +94,9 @@ async function main() {
         ? positionals.length <= 2
         : baseline || command === 'describe'
             ? positionals.length === 2
-            : positionals.length === 1 &&
-                ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
+            : positionals.length === 1 && ['migrate', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
+        throw new Error('Choose new, baseline capture|adopt, migrate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
     }
     const connection = process.env.DATABASE_URL;
     if (!connection) {
@@ -141,15 +134,6 @@ async function main() {
         return;
     }
     switch (command) {
-        case 'generate': {
-            const source = await generateDefinitions({
-                connection,
-                namespace: values.namespace,
-                onWarning: warn,
-            });
-            await writeDefinitions(source, values.out, values.check);
-            break;
-        }
         case 'status':
             process.stdout.write(`${JSON.stringify(await migrationStatus(options), null, 2)}\n`);
             break;

package/dist/database.js

@@ -2,6 +2,7 @@ import { createClient } from './client.js';
 import { createConnection, executeSql } from './connection.js';
 import { withTransaction } from './transaction.js';
 import { plainObject } from './validation.js';
+import { generateTypes } from './generate.js';
 function closeTimeout(options) {
     const settings = plainObject(options === undefined ? {} : options, 'Close options');
     for (const key of Object.keys(settings)) {
@@ -42,6 +43,10 @@ export function createTenon(options) {
     return {
         ...createClient(query, options.onQuery),
         native: pool,
+        async generateTypes(options) {
+            checkOpen();
+            await generateTypes(pool, options);
+        },
         async transaction(callback) {
             checkOpen();
             return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));

package/dist/generate.d.ts

@@ -4,5 +4,16 @@ export interface GenerateOptions {
     readonly namespace?: string;
     readonly onWarning?: (message: string) => void | Promise<void>;
 }
+export interface GenerateTypesOptions {
+    /** Output path, resolved from the working directory. */
+    readonly out: string;
+    /** Schema to inspect; defaults to public. */
+    readonly namespace?: string;
+    /** Reject missing or stale output without writing. Defaults to false. */
+    readonly check?: boolean;
+    readonly onWarning?: (message: string) => void | Promise<void>;
+}
+/** Generate with the owning database's connection and preserve exact file freshness checks. */
+export declare function generateTypes(connection: Connection, options: GenerateTypesOptions): Promise<void>;
 /** Read one schema snapshot with default catalog codecs and the selected application read mappings. */
 export declare function generateDefinitions(options: GenerateOptions): Promise<string>;

package/dist/generate.js

@@ -4,7 +4,32 @@ import { renderDatabase } from './generation/render.js';
 import { domainSummaries, schemaSummary, tableSummary } from './generation/schema-summary.js';
 import { withMigrationLock } from './migrations/connection.js';
 import { migrationTable } from './migrations/history.js';
-import { quote } from './sql.js';
+import { quote, validateName } from './sql.js';
+import { plainObject } from './validation.js';
+import { writeDefinitions } from './generation/output.js';
+/** Generate with the owning database's connection and preserve exact file freshness checks. */
+export async function generateTypes(connection, options) {
+    const config = plainObject(options, 'Generation options');
+    for (const key of Object.keys(config)) {
+        if (!['out', 'namespace', 'check', 'onWarning'].includes(key)) {
+            throw new Error(`Unknown generation option: ${key}`);
+        }
+    }
+    if (typeof config.out !== 'string' || !config.out.trim() || config.out.includes('\0')) {
+        throw new Error('Generation out must be a nonempty file path.');
+    }
+    if (config.check !== undefined && typeof config.check !== 'boolean') {
+        throw new Error('Generation check must be a boolean.');
+    }
+    if (options.namespace !== undefined)
+        validateName(options.namespace);
+    const source = await generateDefinitions({
+        connection,
+        ...(options.namespace !== undefined && { namespace: options.namespace }),
+        ...(options.onWarning !== undefined && { onWarning: options.onWarning }),
+    });
+    await writeDefinitions(source, config.out, config.check === true);
+}
 /** Read one schema snapshot with default catalog codecs and the selected application read mappings. */
 export async function generateDefinitions(options) {
     if (options.onWarning !== undefined && typeof options.onWarning !== 'function') {

package/dist/generation/output.js

@@ -14,12 +14,11 @@ export async function writeDefinitions(source, filename, check) {
             if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
                 throw error;
             }
-            throw new Error(`Generated definitions file is missing: ${output}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
+            throw new Error(`Generated definitions file is missing: ${output}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
         }
         if (existing !== source) {
-            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
+            throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun db.generateTypes with the same options and check: false, then commit the result.`);
         }
-        process.stdout.write('Generated definitions are current.\n');
         return;
     }
     await mkdir(dirname(output), { recursive: true });
@@ -31,5 +30,4 @@ export async function writeDefinitions(source, filename, check) {
     finally {
         await rm(temporary, { force: true });
     }
-    process.stdout.write(`Generated ${output}\n`);
 }

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { DescribeOptions, DescribedColumn, DescribedType, DescriptionIssue,
 export { adoptBaseline, captureBaseline } from './baseline.js';
 export type { CaptureBaselineOptions, CapturedBaseline } from './baseline.js';
 export { generateDefinitions } from './generate.js';
-export type { GenerateOptions } from './generate.js';
+export type { GenerateOptions, GenerateTypesOptions } from './generate.js';
 export { migrate, migrationStatus, rollback } from './migrations.js';
 export type { MigrationStatus } from './migrations.js';
 export type { DatabaseToolOptions } from './migrations/connection.js';

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { Pool } from '@kequtech/pgclear';
 import type { QueryResult } from './connection.js';
 import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 import type { SqlQuery } from './query.js';
+import type { GenerateTypesOptions } from './generate.js';
 export interface QueryClient {
     query<Row extends object>(query: SqlQuery<Row>, options?: QueryOptions & {
         readonly returns?: 'native';
@@ -19,6 +20,8 @@ export interface CloseOptions {
 export type Database = Transaction & {
     /** The underlying pool-level driver client; native calls bypass Tenon's query and transaction guards. */
     readonly native: Pool;
+    /** Write or check schema declarations using this instance's configured codecs. */
+    generateTypes(options: GenerateTypesOptions): Promise<void>;
     /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
     transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
     close(options?: CloseOptions): Promise<void>;