@kequtech/tenon-orm 0.4.2 → 0.4.4

package/docs/reference.md

@@ -10,12 +10,19 @@ Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScr
 development typings. Install `@kequtech/tenon-orm`; pgclear is included as a runtime dependency.
 
 ```text
-createTenon({ connection, onQuery? }): Database
+createTenon(config: TenonConfig): Database
 ```
 
-`connection` is required: a PostgreSQL URI string, pgclear `PoolOptions`, or an existing pgclear
-`Pool`. `Connection` names this union; `ConnectionOptions` aliases `PoolOptions`. A supplied pool
-retains application ownership. Unknown Tenon or driver configuration options reject.
+Pass one database config directly. Its `connection` holds a PostgreSQL URI, pgclear pool-option
+values, or an application-owned pool. Its optional `onQuery` callback observes runtime queries.
+`ConnectionOptions` aliases pgclear `PoolOptions`; a supplied pool retains application ownership.
+Unknown config keys reject. Connection validation and pool creation wait until the first query,
+transaction, or native-pool access. Closing an unused instance needs no credentials.
+
+`tenon init` generates a named `main` config with plain environment reads and no eager credential
+check. Import it and call `createTenon(main)`. Runtime does not discover files. For multiple databases,
+export one config per database and select the matching export in the CLI with `--database`.
+See [shared configuration](configuration.md) for the complete setup.
 
 The returned `Database` provides:
 
@@ -23,7 +30,6 @@ The returned `Database` provides:
 | ------------------------ | ---------------------------------------------------------------------------------------- |
 | `query(query, options?)` | Execute a Tenon `SqlQuery` and apply result/count options                                |
 | `transaction(callback)`  | Commit on callback success, roll back on an escaping error; return the callback's result |
-| `generateTypes(options)` | Write or check schema declarations using this instance's pool/codecs                     |
 | `native`                 | The underlying pgclear pool                                                              |
 | `close({ timeoutMs? }?)` | Disable the wrapper and close an owned pool; default grace 5,000 ms                      |
 
@@ -206,16 +212,17 @@ Use codes and structured fields rather than matching message text. Retain unexpe
 
 ## Generated types and checking
 
-```text
-db.generateTypes({ out, namespace?, check?, onWarning? }): Promise<void>
-generateDefinitions({ connection, namespace?, onWarning? }): Promise<string>
+```sh
+tenon generate
+tenon generate --check
 ```
 
-`out` is required for file generation. Namespace defaults to `public`; `check` defaults to false.
-Generation inherits the database registry. Missing/stale output rejects under `check: true` without
-writing. See [schema types and values](schema-types.md) for file guarantees, generated shapes,
-value mappings, codecs, and domain validation. The standalone `tenon generate` command was removed;
-use an application script.
+Generation uses [shared configuration](configuration.md) for its connection/codecs, output path,
+and namespace. Missing/stale output rejects under `--check` without writing. See
+[schema types and values](schema-types.md) for file guarantees, generated shapes, and value mappings.
+`generateDefinitions({ connection, namespace?, onWarning? }): Promise<string>` returns source text
+without file handling for custom tooling. Database instances expose query execution and lifecycle
+methods; generation is a CLI tool.
 
 ### Application aliases
 
@@ -234,15 +241,16 @@ Generated types account for defaults, identity/computed columns, domains, and nu
 
 ## Choosing a validation tool
 
-Use the intended development/test schema and role. TypeScript itself needs no connection.
+Use the intended development/test schema and role through shared configuration. TypeScript itself
+needs no connection.
 
-| Tool                                     | Question answered                                                              | Main limit                                                      |
-| ---------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
-| `tsc --noEmit`                           | Does application code satisfy TypeScript contracts?                            | Does not inspect SQL/schema                                     |
-| `tenon check [file.ts[:line]]`           | Does recoverable SQL contradict declared input/result types?                   | Unsupported sites fail; inconclusive properties remain unproven |
-| `tenon describe query.sql`               | What metadata does PostgreSQL report for finished SQL?                         | Does not compare annotations or bind values                     |
-| `db.generateTypes({ out, check: true })` | Does committed output match generation now?                                    | Does not check queries or replace migration status              |
-| Database tests                           | Do exercised queries produce correct rows, effects, permissions, and rollback? | Cover only tested inputs and paths                              |
+| Tool                           | Question answered                                                              | Main limit                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `tsc --noEmit`                 | Does application code satisfy TypeScript contracts?                            | Does not inspect SQL/schema                                     |
+| `tenon check [file.ts[:line]]` | Does recoverable SQL contradict declared input/result types?                   | Unsupported sites fail; inconclusive properties remain unproven |
+| `tenon describe query.sql`     | What metadata does PostgreSQL report for finished SQL?                         | Does not compare annotations or bind values                     |
+| `tenon generate --check`       | Does committed output match generation now?                                    | Does not check queries or replace migration status              |
+| Database tests                 | Do exercised queries produce correct rows, effects, permissions, and rollback? | Cover only tested inputs and paths                              |
 
 After schema changes, migrate the test database, regenerate/review declarations, and run typechecks,
 applicable source checks, and database tests. In CI, check generated output without replacing it.
@@ -255,7 +263,7 @@ take locks. Neither proves actual bound values or write effects.
 The bundled TypeScript compiler loads only through that path or the check command.
 
 Options are `{ connection, target?, project?, session?, timeouts?, codecs?, readTypes? }`.
-Connection is a URI. The report contains `ok`, `project`, `queries`, `diagnostics`, and available
+Connection is a URI or pool-option values; connection codecs are inherited unless `codecs` is explicit. The report contains `ok`, `project`, `queries`, `diagnostics`, and available
 inspection `context`. Mismatches, unchecked sites, and no sites fail; unproven findings alone do not.
 See [query checking](query-checking.md) for selection, supported composition, and custom decoders.
 
@@ -265,7 +273,7 @@ See [query checking](query-checking.md) for selection, supported composition, an
 describeQuery({ connection, query, session?, timeouts?, codecs? }): Promise<QueryDescription>
 ```
 
-Connection is a URI; query is finished SQL text or `{ text, parameterTypes? }`. A `SqlQuery` fits
+Connection is a URI or pool-option values; query is finished SQL text or `{ text, parameterTypes? }`. A `SqlQuery` fits
 because it has `text`; values and its row annotation are not checked. The report includes
 `parameters`, `columns`, `rowType`, `issues`, and `context`. It uses a separate session with bounded
 timeouts. See [query inspection](query-inspection.md) for fields and finding codes.
@@ -279,20 +287,23 @@ prepared statements, and dedicated notification listeners.
 
 ## Troubleshooting
 
-| Symptom                                      | Response                                                                                                                                                     |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `DATABASE_URL is required`                   | Supply the variable to CLI commands. No `.env` files are loaded automatically. Application configuration is explicit.                                        |
-| `PGCLEAR_ENCODE`                             | Check inputs: objects/arrays need `json`/`param`; direct undefined, unsafe integers, nonfinite numbers, and invalid Dates reject. JSON still rejects bigint. |
-| `CardinalityError`                           | Check the expected row count and predicate. To choose one of several rows, author deterministic `ORDER BY ... LIMIT 1`.                                      |
-| `TENON_AFFECTED_ROWS_MISMATCH`               | The guarded operation rolled back. Inspect `actual` and the predicate; retain the intended bound.                                                            |
-| `TENON_AFFECTED_ROWS_UNSUPPORTED`            | The final command lacks a supported write count. Use guards on INSERT/UPDATE/DELETE/MERGE; result modes check returned rows.                                 |
-| Empty assignments                            | All selected fields were missing/undefined. Skip the update or branch to an expression-only statement.                                                       |
-| Duplicate result columns                     | Alias columns uniquely, especially in joins. The driver rejects duplicate object keys.                                                                       |
-| SQLSTATE `42P18` / `42P08` during inspection | Add the intended parameter cast or Describe OID hints. Inspection binds no values.                                                                           |
-| Checker reports `unchecked`                  | Follow the diagnostic. Runtime fragments and optional patches can execute correctly yet remain unsupported by source recovery.                               |
-| Missing/stale generated output               | Check schema, namespace, registry, driver version, and path. Regenerate, review, and commit intended output.                                                 |
-| Migration history conflict                   | Restore original applied files. Add new changes in a forward migration. Checksums include down SQL too.                                                      |
-| Tooling lock wait                            | Check concurrent migration/DDL work, use direct or session pooling, and configure server timeouts.                                                           |
+| Symptom                                       | Response                                                                                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Missing shared configuration                  | Run `tenon init` or select an existing config with `--config`. Generation, checking, and inspection require it.                                              |
+| Multiple databases or unknown database export | Select a named config with `--database name`. Use `--config path` when it belongs to another file.                                                           |
+| Missing or empty config connection            | Set the environment variable read by that database's config before using it. Imports alone need no credentials.                                              |
+| `DATABASE_URL is required`                    | Supply the variable for migration commands without config. Tenon does not load `.env` files.                                                                 |
+| `PGCLEAR_ENCODE`                              | Check inputs: objects/arrays need `json`/`param`; direct undefined, unsafe integers, nonfinite numbers, and invalid Dates reject. JSON still rejects bigint. |
+| `CardinalityError`                            | Check the expected row count and predicate. To choose one of several rows, author deterministic `ORDER BY ... LIMIT 1`.                                      |
+| `TENON_AFFECTED_ROWS_MISMATCH`                | The guarded operation rolled back. Inspect `actual` and the predicate; retain the intended bound.                                                            |
+| `TENON_AFFECTED_ROWS_UNSUPPORTED`             | The final command lacks a supported write count. Use guards on INSERT/UPDATE/DELETE/MERGE; result modes check returned rows.                                 |
+| Empty assignments                             | All selected fields were missing/undefined. Skip the update or branch to an expression-only statement.                                                       |
+| Duplicate result columns                      | Alias columns uniquely, especially in joins. The driver rejects duplicate object keys.                                                                       |
+| SQLSTATE `42P18` / `42P08` during inspection  | Add the intended parameter cast or Describe OID hints. Inspection binds no values.                                                                           |
+| Checker reports `unchecked`                   | Follow the diagnostic. Runtime fragments and optional patches can execute correctly yet remain unsupported by source recovery.                               |
+| Missing/stale generated output                | Check schema, namespace, registry, driver version, and path. Regenerate, review, and commit intended output.                                                 |
+| Migration history conflict                    | Restore original applied files. Add new changes in a forward migration. Checksums include down SQL too.                                                      |
+| Tooling lock wait                             | Check concurrent migration/DDL work, use direct or session pooling, and configure server timeouts.                                                           |
 
 After a guarded query rejects, savepoint cleanup has finished. An unguarded server error normally
 aborts a transaction. A timeout or lost connection does not itself establish whether a commit
@@ -300,15 +311,25 @@ happened; review the transaction contract before adding retries.
 
 ## Command reference
 
-All database commands read `DATABASE_URL`. `new` and `--help` work offline. No environment files
-are loaded. Paths resolve from the working directory; unsupported command flags reject.
+All commands accept `--config path`. Commands using a database config also accept `--database name`
+to select its export. A file with one config is selected automatically; multiple configs require an
+explicit selection. `generate`, `check`, and `describe` require
+[shared configuration](configuration.md) and use its connection/codecs. Migration and baseline
+commands use config when present and fall back to `DATABASE_URL` only when no config is found.
+`init` creates config without importing application code; `new` uses the configured migration
+directory without opening a database; `--help` loads no config. Config modules may read environment variables, but Tenon loads no `.env`
+files automatically.
+Configured paths resolve from the config file; CLI path flags resolve from the working directory.
+Unsupported command flags reject.
 
 ```text
+tenon init [--config path]
 tenon new <name> [--directory migrations]
+tenon generate [--out path] [--namespace schema] [--check]
 tenon migrate [--directory migrations] [--namespace public]
 tenon status [--directory migrations] [--namespace public]
 tenon rollback [--directory migrations] [--namespace public] [--steps 1]
-tenon baseline capture [--directory migrations] [--namespace public] [--schema name ...]
+tenon baseline capture [--directory migrations] [--namespace public] [--schema name ...] [--connection native-uri]
 tenon baseline adopt [--directory migrations] [--namespace public]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
   [--role name] [--search-path value] [--time-zone value]
@@ -317,15 +338,17 @@ tenon describe <query.sql> [--role name] [--search-path value] [--time-zone valu
   [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 ```
 
-| Command                | Output and behavior                                               |
-| ---------------------- | ----------------------------------------------------------------- |
-| `new`                  | Paths of the new empty up/down pair; fill before applying         |
-| `migrate` / `rollback` | Completed IDs or “nothing to do”; each file commits independently |
-| `status`               | JSON `{ applied, pending }`; validates history                    |
-| `baseline capture`     | Writes a reviewed schema-only baseline using native `pg_dump`     |
-| `baseline adopt`       | Records baseline history without executing its SQL                |
-| `check`                | Diagnostics/counts, or a structured report with `--json`          |
-| `describe`             | JSON metadata, including unresolved findings                      |
+| Command                | Output and behavior                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| `init`                 | Creates a minimal TypeScript or JavaScript config, refusing to overwrite existing files |
+| `new`                  | Paths of the new empty up/down pair; fill before applying                               |
+| `migrate` / `rollback` | Completed IDs or “nothing to do”; each file commits independently                       |
+| `status`               | JSON `{ applied, pending }`; validates history                                          |
+| `baseline capture`     | Writes a reviewed schema-only baseline using native `pg_dump`                           |
+| `baseline adopt`       | Records baseline history without executing its SQL                                      |
+| `generate`             | Writes output atomically; `--check` rejects missing/stale output without writing        |
+| `check`                | Diagnostics/counts, or a structured report with `--json`                                |
+| `describe`             | JSON metadata, including unresolved findings                                            |
 
 Successful commands exit 0. Invalid input or a failed operation exits 1. `check` also exits 1 for
 mismatches, unchecked sites, or no sites; unproven findings alone do not fail. `describe` can exit 0

package/docs/schema-types.md

@@ -6,33 +6,35 @@ the selected columns, joins, and expressions.
 
 ## Generate and check a file
 
-Use the application's configured database instance, after migrations have committed:
+Configure `generate.out` in [shared configuration](configuration.md), then run after migrations
+have committed:
 
-```ts
-await db.generateTypes({ out: 'src/generated-schema.d.ts' });
-await db.generateTypes({ out: 'src/generated-schema.d.ts', check: true });
+```sh
+npx tenon generate
+npx tenon generate --check
 ```
 
-The first call writes declarations. The second rejects if they are missing or stale, without
-rewriting them. Use it in CI to verify committed output. The
-[getting-started script](human-guide.md#generate-types) provides a complete command-line wrapper.
+The first command writes declarations. The second rejects missing or stale output without rewriting
+it. Both use the configured connection and codecs. Relative configured paths resolve from the config
+file; `--out` paths resolve from the working directory. The generation namespace comes from
+`generate.namespace`, then `migrations.namespace`, then `public`; `--namespace` overrides it. It is
+independent of runtime `search_path`.
 
-`namespace` defaults to `public`, independently of runtime `search_path`. Pass it explicitly for a
-different schema. Paths resolve from the working directory. Keep exact output unchanged and exclude
-it from automatic formatting.
+Keep exact output unchanged and exclude it from automatic formatting. See
+[getting started](human-guide.md#generate-types) for npm commands.
 
-Generation uses the instance's pool and codecs. It is available on `db`, outside callback
-transactions. It uses a repeatable-read catalog snapshot and shares the migration advisory lock;
-use a direct or session-pooled connection. It needs no migration files or Tenon history.
+Generation runs outside callback transactions. It uses a repeatable-read catalog snapshot and
+shares the migration advisory lock; use a direct or session-pooled connection. It needs no migration
+files or Tenon history.
 
-Tenon creates parent directories and replaces the entire output file atomically. With `check: true`,
-it creates no directories, writes no files, and includes a bounded diff for stale output. An optional
-`onWarning(message)` can be synchronous or asynchronous; the default is `console.warn`. Warning
-handler failures reject generation before output changes. Other filesystem errors propagate.
+Tenon creates parent directories and replaces the entire output file atomically. With `--check`,
+it creates no directories, writes no files, and includes a bounded diff for stale output. The CLI
+prints warnings to stderr. Generation failures preserve the existing file; filesystem errors propagate.
 
 For source text without file handling, use
 `generateDefinitions({ connection, namespace?, onWarning? }): Promise<string>`. Pass the configured
-pool or connection options to retain runtime read mappings.
+pool or connection options to retain runtime read mappings. Its optional `onWarning` callback may
+be synchronous or asynchronous and defaults to `console.warn`; callback failures reject generation.
 
 ## Read the generated types
 
@@ -161,17 +163,22 @@ both become null. For raw JSON text or Date/bigint outputs, configure codecs.
 
 ## Custom codecs
 
-Configure the registry on the application's connection. For example:
+Configure the registry in `tenon.config.ts` so runtime queries and generated declarations use the
+same representations:
 
 ```ts
-import { builtin, createTenon, defaultCodecs } from '@kequtech/tenon-orm';
+import { builtin, defaultCodecs, type TenonConfig } from '@kequtech/tenon-orm';
 
 const codecs = defaultCodecs.with(builtin.int8BigInt).with(builtin.timestamptzDate);
-const db = createTenon({ connection: { connectionString: connection, codecs } });
+export const main = {
+  connection: { connectionString: process.env.DATABASE_URL, codecs },
+  generate: { out: 'src/generated-schema.d.ts' },
+} satisfies TenonConfig;
 ```
 
-Int8 now reads as bigint, and timestamptz reads as a millisecond-precision Date. Regenerate using this
-instance. Scalar overrides affect derived built-in arrays; explicit array overrides win. Date and
+Int8 now reads as bigint, and timestamptz reads as a millisecond-precision Date. Run `tenon generate`
+with this config to update declarations. Scalar overrides affect derived built-in arrays; explicit
+array overrides win. Date and
 Temporal output codecs reject infinity and values outside their supported ranges.
 
 For Temporal, import `createTemporalCodecs` from Tenon and supply a native or compatible polyfill
@@ -196,10 +203,11 @@ checking consume the registry's metadata. An unidentified decoder warns and beco
 a declared representation is trusted, not runtime validation. Under a custom registry, enum output
 may remain string because a decoder can transform labels; enum write inputs retain catalog choices.
 
-Use the same registry for execution, generation, inspection, and source checking. Relative type-import
+Place the registry in shared `connection.codecs` so runtime, CLI generation, inspection, and source
+checking use it consistently. Programmatic inspection/checking inherit `connection.codecs` too. Relative type-import
 expressions resolve from the generated file for saved declarations and from the tsconfig directory
-for checking. Prefer a package or configured alias that resolves in both places. Tenon does not
-execute referenced modules. See [custom-codec checking](query-checking.md#programmatic-use-and-custom-codecs).
+for checking. Prefer a package or configured alias that resolves in both places. Resolving these
+type expressions does not execute their referenced modules. See [custom-codec checking](query-checking.md#programmatic-use-and-custom-codecs).
 
 Catalog queries use default result decoding on the same borrowed session, so application codecs do
 not alter Tenon's metadata inputs. Output codec choices do not select input encoders.
@@ -256,7 +264,7 @@ application's authentication and authorization checks.
 
 ## What freshness checks establish
 
-`check: true` compares the exact generated file with output from this database and codec registry.
+`tenon generate --check` compares the exact generated file with output from this database and codec registry.
 It does not check query annotations, pending migrations, functions, privileges, or every database
 object. A driver or generator update can change output without schema drift. Review generated diffs
 after upgrades. Generated text and schema-summary formatting are not version-stable schema

package/package.json

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