@kequtech/tenon-orm 0.3.1 → 0.4.2

package/dist/migrations/history.js

@@ -1,11 +1,11 @@
 import { qualified } from '../sql.js';
 export const migrationTable = '__tenon_migrations';
 export async function migrationState(client, namespace, migrations) {
-    const exists = await client.query('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    const exists = await client.queryClassic('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
     if (exists.rows[0].name === null) {
         return [];
     }
-    const { rows: applied } = await client.query(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`);
+    const { rows: applied } = await client.queryClassic(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`, []);
     for (const [i, record] of applied.entries()) {
         const file = migrations[i];
         if (!file ||
@@ -18,13 +18,13 @@ export async function migrationState(client, namespace, migrations) {
     return applied;
 }
 export async function createHistoryTable(client, namespace) {
-    await client.query(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
+    await client.queryClassic(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
       id TEXT PRIMARY KEY CHECK (id ~ '^[0-9]+$'),
       name TEXT NOT NULL,
       checksum TEXT NOT NULL,
       applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
-    )`);
+    )`, []);
 }
 export async function recordMigration(client, namespace, migration) {
-    await client.query(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
+    await client.queryClassic(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
 }

package/dist/migrations.js

@@ -28,25 +28,23 @@ async function execute(options, direction, steps) {
         if (!selected.length) {
             return [];
         }
-        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`);
+        await client.queryClassic(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`, []);
         await createHistoryTable(client, namespace);
         const completed = [];
         for (const file of selected) {
             try {
-                await client.query('BEGIN');
+                await client.queryClassic('BEGIN', []);
                 // Match the string-literal rules used by the authored migration scanner.
-                await client.query('SET LOCAL standard_conforming_strings TO on');
-                await client.query(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`);
-                await client.query(direction === 'up' ? file.up : file.down);
+                await client.queryClassic('SET LOCAL standard_conforming_strings TO on', []);
+                await client.queryClassic(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`, []);
+                await client.script(direction === 'up' ? file.up : file.down);
                 if (direction === 'up') {
                     await recordMigration(client, namespace, file);
                 }
                 else {
-                    await client.query(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [
-                        file.id,
-                    ]);
+                    await client.queryClassic(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [file.id]);
                 }
-                const result = await client.query('COMMIT');
+                const result = await client.queryClassic('COMMIT', []);
                 if (result.command !== 'COMMIT') {
                     throw new Error('The migration transaction was rolled back.');
                 }

package/dist/query-options.d.ts

@@ -8,7 +8,7 @@ export interface QueryOptions {
     /** Optional diagnostic label. No SQL or input values are sent to observers. */
     readonly label?: string;
 }
-export type QueryOutput<Row extends object, Mode extends QueryReturnMode> = Mode extends 'native' ? QueryResult<Row> : Mode extends 'many' ? Row[] : Mode extends 'oneOrNone' ? Row | undefined : Row;
+export type QueryOutput<Row extends object, Mode extends QueryReturnMode> = Mode extends 'native' ? QueryResult<Row> : Mode extends 'many' ? readonly Row[] : Mode extends 'oneOrNone' ? Row | undefined : Row;
 export declare function validateOptions(options?: QueryOptions): Readonly<QueryOptions & {
     returns: QueryReturnMode;
 }>;

package/dist/query.js

@@ -124,6 +124,6 @@ export function assertQuery(value) {
         !value.text.trim() ||
         !('values' in value) ||
         !Array.isArray(value.values)) {
-        throw new Error('Expected a query created with sql or unsafeSql.');
+        throw new Error('Expected a query created with sql or unsafeSql from @kequtech/tenon-orm.');
     }
 }

package/dist/transaction.d.ts

@@ -1,4 +1,4 @@
-import type { Pool } from 'pg';
+import type { Pool } from '@kequtech/pgclear';
 import type { QueryExecutor } from './connection.js';
-/** The callback owns one connection and expires before commit or rollback begins. */
+/** Serialize whole Tenon policies; pgclear owns transaction, savepoint and transport recovery. */
 export declare function withTransaction<T>(pool: Pool, work: (query: QueryExecutor) => Promise<T>): Promise<T>;

package/dist/transaction.js

@@ -1,81 +1,25 @@
-import { executeSql, watchClient } from './connection.js';
-/** The callback owns one connection and expires before commit or rollback begins. */
-export async function withTransaction(pool, work) {
-    const client = await pool.connect();
-    const connection = watchClient(client);
-    let active = true;
-    let began = false;
-    let releaseError;
-    let savepointId = 0;
-    let pending = Promise.resolve();
-    let recoveryFailure;
-    const query = async (text, input, readResult, guarded) => {
-        if (!active)
-            throw new Error('The transaction has finished.');
-        // Queue whole operations, including savepoint cleanup. Otherwise concurrent
-        // calls could place another write inside a savepoint that gets rolled back.
-        const operation = pending.then(async () => {
-            connection.check();
-            if (recoveryFailure)
-                throw recoveryFailure;
-            if (!guarded)
-                return readResult(await executeSql(client, text, input));
-            const savepoint = `tenon_affected_rows_${++savepointId}`;
-            await client.query(`SAVEPOINT ${savepoint}`);
-            try {
-                const result = readResult(await executeSql(client, text, input));
-                await client.query(`RELEASE SAVEPOINT ${savepoint}`);
-                return result;
-            }
-            catch (error) {
-                try {
-                    await client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
-                    await client.query(`RELEASE SAVEPOINT ${savepoint}`);
-                }
-                catch (rollbackError) {
-                    // Even if application code catches this error, the outer transaction
-                    // must not commit when the rejected write could still be present.
-                    recoveryFailure = new AggregateError([error, rollbackError], 'Operation and savepoint recovery failed.');
-                    throw recoveryFailure;
-                }
-                throw error;
-            }
-        });
-        pending = operation.then(() => { }, () => { });
-        return operation;
-    };
-    try {
-        await client.query('BEGIN');
-        began = true;
-        const result = await work(query);
-        active = false;
-        await pending;
-        connection.check();
-        if (recoveryFailure)
-            throw recoveryFailure;
-        const committed = await client.query('COMMIT');
-        if (committed.command !== 'COMMIT') {
-            throw new Error('PostgreSQL rolled back the aborted transaction.');
-        }
-        return result;
-    }
-    catch (error) {
-        active = false;
-        await pending;
-        if (!began) {
-            releaseError = error instanceof Error ? error : new Error('BEGIN failed.');
-            throw error;
-        }
+import { executeSql } from './connection.js';
+/** Serialize whole Tenon policies; pgclear owns transaction, savepoint and transport recovery. */
+export function withTransaction(pool, work) {
+    return pool.transaction(async (transaction) => {
+        let active = true;
+        let pending = Promise.resolve();
+        const query = (text, input, readResult, guarded) => {
+            if (!active)
+                return Promise.reject(new Error('The transaction has finished.'));
+            const operation = pending.then(() => {
+                const execute = async (scope) => readResult(await executeSql(scope, text, input));
+                return guarded ? transaction.savepoint(execute) : execute(transaction);
+            });
+            pending = operation.then(() => { }, () => { });
+            return operation;
+        };
         try {
-            await client.query('ROLLBACK');
+            return await work(query);
         }
-        catch (rollbackError) {
-            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
-            throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
+        finally {
+            active = false;
+            await pending;
         }
-        throw error;
-    }
-    finally {
-        connection.release(releaseError);
-    }
+    });
 }

package/dist/types.d.ts

@@ -1,7 +1,8 @@
-import type { Pool } from 'pg';
+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>;

package/docs/adoption-guide.md

@@ -1,72 +1,47 @@
 # Adopting Tenon
 
-Replace application queries independently of migration ownership. Tenon can query an existing schema
-and generate types while the current migration runner stays in place. For a Tenon version upgrade,
-read the [Changelog](../CHANGELOG.md).
+You can replace application queries without changing migration ownership. Tenon queries and type
+generation work with an existing schema and any migration runner. For a Tenon upgrade, read the
+[shipped changelog](../CHANGELOG.md) from your resolved version through the target version.
 
 ## Preserve connections and behavior
 
-Keep the existing database URI, credentials, TLS requirements, schema, and data. Tenon can add
-driver settings through pg configuration:
+Reuse the existing database URI, credentials, schema, TLS requirements, and data. Pool configuration
+uses pgclear options; timeout names include `Ms`. Configure runtime names with
+`startupParameters: { search_path: 'app,public' }`, or qualify tables in SQL. Tooling `namespace`
+does not configure runtime queries.
 
-```ts
-import { createTenon } from '@kequtech/tenon-orm';
-
-const db = createTenon({
-  connection: {
-    connectionString: existingUri,
-    connectionTimeoutMillis: 5000,
-  },
-});
-```
-
-Translate old driver configuration into pg `PoolConfig` rather than passing it through. Pool
-timeouts use milliseconds. Preserve runtime `search_path` through the pg startup options string, for
-example `options: '-c search_path=app,public'`. URI startup options take precedence when both are
-supplied. CLI `--namespace` does not change runtime queries. See
-[connection options](reference.md#installation-and-connection).
-
-Before conversion, identify behavior supplied by the old ORM: IDs/defaults, timestamps, validation,
-hooks, serialization, relationships, and transaction boundaries. Preserve it explicitly in
-application code or SQL where required.
+Before replacing an ORM, identify behavior it currently supplies: IDs/defaults, timestamps,
+validation, hooks, serialization, relationship loading, and transaction boundaries. Preserve needed
+behavior in application code, constraints, or SQL. Tenon has no model lifecycle or implicit loading.
 
 ## Replace queries
 
-1. Optionally generate persistence types from the existing schema:
-
-   ```sh
-   npx tenon generate --namespace public --out src/generated-schema.d.ts
-   ```
-
-   This needs no Tenon migration history. Use the application's namespace and commit exact output.
-
-2. Replace queries with parameterized SQL in ordinary functions accepting `QueryClient` where
-   callers may supply `db` or `tx`. Retain projections, ordering, null handling, and authorization.
-3. Review value conversions against [Tenon's mappings](reference.md#generated-types-and-checking):
-   numeric values, dates, arrays, and JSON serialization may differ from the previous driver.
-   Generated declarations do not replace domain validation.
-4. Inspect meaningful completed query variants and run database assertions for actual rows,
-   permissions, write effects, and rollback. See [query inspection](query-inspection.md).
-5. Remove unused runtime dependencies and generated code after their callers are gone. Dependencies
-   retained by other application code or installed transitively may still be needed.
-
-Check cardinality when replacing a first-row accessor. `oneOrNone` rejects multiple rows and `one`
-also rejects zero rows. Use deterministic `ORDER BY` plus `LIMIT 1` when choosing one of several
-matches is intended; modes do not add a limit.
-
-Use `sql.insertValues` and `sql.assignments` to replace object-to-SQL utilities, checking omission,
-default, null, and empty-input semantics. Generated `Rows.Insert`/`Rows.Update` types can replace
-handwritten persistence inputs. See the [mutation cookbook](mutations.md).
-
-Use `tx.query` for work that must commit together. Native pool calls do not join Tenon transactions.
-For driver features, preserve resource ownership and recovery policy under the
-[native access contract](reference.md#native-driver-access).
+1. Optionally generate persistence types with
+   `await db.generateTypes({ out: 'src/generated-schema.d.ts', namespace: 'public' })`.
+   Use the application's schema and codec registry; no Tenon migration history is required.
+2. Replace one workflow at a time with parameterized SQL in ordinary functions. Accept
+   `QueryClient` when callers may use either `db` or `tx`. Preserve selected columns, ordering,
+   null handling, authorization predicates, and transaction boundaries.
+3. Review input/output mappings and validate domain values at the persistence boundary. Generated
+   types do not validate JSON members or application constraints.
+4. Test actual rows, writes, permissions, and rollback. Use source checking and inspection where
+   useful. See [choosing a validation tool](reference.md#choosing-a-validation-tool).
+5. Remove unused dependencies/generated code once all their callers are gone.
+
+When replacing a first-row accessor, decide whether multiple matches should be an error.
+`oneOrNone` rejects multiple rows and `one` also rejects absence. To choose one match deliberately,
+author deterministic `ORDER BY ... LIMIT 1`; result modes do not add a limit.
+
+For object-to-SQL utilities, review omission, defaults, null, and empty patches against
+[the write guide](mutations.md). Use `tx.query` for every operation that must commit together;
+native pool calls do not join Tenon transactions.
 
 ## Transfer migration ownership
 
-Choose one final checkpoint for the old runner. Bring existing databases to it and disable that
-runner before handover; the runners do not share locks. Capture from a trusted reference database,
-preferably a disposable replay of the legacy migrations.
+Choose the old runner's final schema checkpoint. Bring every existing database to it and disable
+that runner before handover; the runners do not share locks. Capture one baseline from a trusted
+reference database, preferably a disposable replay of the old migrations.
 
 ### Capture a baseline
 
@@ -77,72 +52,74 @@ npx tenon baseline capture --directory migrations --namespace app --schema app
 ```
 
 The directory must contain no SQL files. Capture uses native
-`pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` with no down
-file. Install compatible PostgreSQL client tools on PATH; prefer the server's major version.
+`pg_dump --schema-only --no-owner --no-privileges` and writes `0001_baseline.up.sql` without a down
+file. Install compatible PostgreSQL client tools on PATH, preferably matching the server's major
+version. Capture does not modify source data or history and does not preserve sequence positions.
 
-| Option                | Scope                                                                                |
-| --------------------- | ------------------------------------------------------------------------------------ |
-| `--namespace app`     | Tenon history table to exclude from capture; history/runner scope for later commands |
-| `--schema app`        | Objects selected by native `pg_dump`; repeat to select additional schemas            |
-| Runtime `search_path` | Configured independently on the application connection                               |
+| Setting               | What it selects                                                         |
+| --------------------- | ----------------------------------------------------------------------- |
+| `--namespace app`     | Tenon history table to exclude; history/runner scope for later commands |
+| `--schema app`        | Schema objects included by pg_dump; repeat for more schemas             |
+| Runtime `search_path` | Application name resolution, configured separately                      |
 
-Omitting `--schema` captures the whole database schema, even with a custom namespace. Capture does
-not modify source data/history or preserve sequence positions. It excludes Tenon's selected history
-table but can retain the old runner's metadata tables. Review and commit the SQL. Preserve the
-capture header, which opts this reviewed dump into native baseline parsing; do not add it to
-handwritten migrations.
+Omitting `--schema` captures the whole database schema, even with a custom namespace. The selected
+Tenon history table is excluded; old-runner metadata tables may remain. Review and commit the SQL.
+Preserve the capture header: it opts this reviewed dump into native baseline parsing. Do not add
+that header to handwritten migrations.
 
-A scoped dump can refer to objects it does not include. Provision external schemas, functions,
-extensions, and referenced roles before they are needed. A fresh replay must execute representative
-operations, not just reproduce generated relation types. Tenon requires no particular extension.
+A scoped dump may depend on objects outside its scope. Provision required external schemas,
+extensions, functions, and roles. Fresh replay must exercise representative application operations,
+not merely reproduce table types. Tenon itself requires no particular extension.
 
 ### Check and adopt an existing database
 
-Verify the final legacy checkpoint before adoption. If using schema comparisons, freeze separate
-reference definitions rather than comparing against types regenerated after later migrations.
-`generateDefinitions` covers relation metadata, not functions or privileges; include reviewed
-catalog checks for other objects the application needs. Tenon does not perform these comparisons.
-
-Generated declaration text is not a version-stable schema fingerprint: driver mappings and generator
-changes can alter it without schema drift. The schema-summary comments expose SQL definitions, but
-their formatting and PostgreSQL's rendering of those definitions are not a stable comparison format
-either. If an existing adoption guard hashes generated text, preserve its original reference and
-freeze a separate reference for each supported generator version from a disposable replay of the
-immutable checkpoint. Compare the replay's metadata with the reviewed checkpoint before accepting
-the new reference; never derive a replacement from whichever live database is configured. Keep
-independent function and privilege checks, and test both matching adoption and refusal after drift.
-This application guard is separate from Tenon's migration checksums; keep applied SQL unchanged.
+Confirm that each existing database matches the reviewed final checkpoint. Tenon does not compare
+the live schema with the baseline. Adoption records its checksum without executing its SQL:
 
 ```sh
 npx tenon baseline adopt --directory migrations --namespace app
 npx tenon migrate --directory migrations --namespace app
 ```
 
-Adoption records the baseline checksum without executing its SQL. The namespace must already exist.
-Repeating matching adoption is harmless, including after later migrations; history conflicts fail.
-Once Tenon owns history, add forward migrations rather than editing the baseline.
+The namespace must already exist. Repeating adoption with matching history is harmless, including
+after later migrations; conflicting history fails. Once adopted, leave the baseline unchanged and
+add forward migrations.
+
+For an application-owned schema guard, keep a frozen checkpoint reference. Generated relation types
+do not cover functions or privileges; check required objects separately. Neither generated text nor
+schema-summary formatting is a version-stable fingerprint. If a guard hashes that text, preserve
+its original reference and freeze a separate reviewed reference for each generator version, taken
+from a disposable replay of the immutable checkpoint. Verify that replay against the checkpoint
+before accepting the reference; do not derive it from whichever live database is configured.
+Test both matching adoption and refusal after drift. This is separate from migration checksums.
 
 ### Replay a fresh database
 
-Run `tenon migrate --directory migrations --namespace app`, without adoption. It executes the same
-committed baseline and subsequent migrations. Apply the deployment's required roles, ownership, and
-grants before application access.
-
-The portable baseline omits ownership, grants/revokes, and default privileges. Objects are recreated
-under the migration role. For `SECURITY DEFINER` functions, that owner controls execution authority,
-and new functions ordinarily permit `PUBLIC` execution. Keep fixed policy such as revoking public
-execution in reviewed baseline SQL before first adoption or in a forward migration. Deployment
-provisioning supplies named roles, owners, and grants. Verify permitted and denied operations on
-both adopted and fresh environments. See the
-[pg_dump contract](https://www.postgresql.org/docs/16/app-pgdump.html).
-
-For development, generate types after migrating; production runs migrations and consumes committed
-types. Test existing-row preservation, repeatable adoption, subsequent migrations, and fresh replay.
-A schema-only baseline and down migration are not backups. The missing down file prevents rollback
-across the baseline; use the application's backup/recovery procedure for that boundary.
-
-Programmatic capture is
-`captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` and returns
-`{ id, upPath }`. It requires a native libpq connection string; an explicitly empty `schemas` list
-fails. `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime connection
-forms and returns newly recorded IDs.
+```sh
+npx tenon migrate --directory migrations --namespace app
+```
+
+Do not adopt a fresh database. Migration executes the committed baseline and subsequent files.
+The dump omits ownership, grants/revokes, and default privileges; objects are recreated under the
+migration role. Deployment provisioning must supply required roles, owners, and grants.
+
+For `SECURITY DEFINER` functions, the recreated owner controls authority. PostgreSQL ordinarily grants
+`PUBLIC` execution on new functions. Put fixed policy such as revoking public execution in reviewed
+baseline SQL before first adoption, or in a forward migration. Supply deployment-specific role names
+and grants during provisioning. Verify permitted and denied operations on adopted and fresh databases.
+
+Test preserved existing rows, repeatable adoption, later migrations, and fresh replay. A schema-only
+baseline is not a backup; the missing down file prevents rollback across it. Use the application's
+backup/recovery procedure for that boundary.
+
+### Baseline API
+
+- `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` returns
+  `{ id, upPath }`. Connection is a native libpq connection string passed to pg_dump. Omitting
+  `schemas` captures the whole database schema; an empty list rejects. Warnings default to
+  `console.warn`.
+- `adoptBaseline({ connection, directory?, namespace? })` accepts Tenon's runtime connection forms
+  and returns newly recorded IDs. It requires `0001_baseline.up.sql` with no down file.
+
+Defaults are directory `migrations` and namespace `public`. See [migrations](migrations.md) for
+history validation, per-file transactions, and locking.