@kequtech/tenon-orm 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Kequtech
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# Tenon ORM
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
+
+Your coding agent already knows SQL. Tenon gives it a small API for parameterized queries,
+transactions, and migrations, with optional tooling to check SQL and generate result types. Queries
+stay readable, reusable operations are ordinary functions, and humans can review exactly what will
+run against the database.
+
+Tenon takes the place of an ORM without hiding PostgreSQL behind a query builder. You or your agent
+write the SQL; Tenon handles binding values and returning results. Your application controls the
+`pg` driver, connection configuration, and validation.
+
+```sh
+npm install @kequtech/tenon-orm pg
+```
+
+Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and
+development typings for Node and `pg`.
+
+```ts
+import { createTenon, sql } from '@kequtech/tenon-orm';
+
+const connection = process.env.DATABASE_URL;
+if (!connection) throw new Error('DATABASE_URL is required');
+const db = createTenon({ connection });
+
+try {
+  const email = 'reader@example.test';
+  const user = await db.query(
+    sql<{ id: number; email: string }>`
+      SELECT id, email FROM public."User" WHERE email = ${email}
+    `,
+    { returns: 'oneOrNone' },
+  );
+  // user is { id: number; email: string } | undefined
+} finally {
+  await db.close();
+}
+```
+
+This standalone example assumes the table exists. In a server, reuse an instance per database and
+close it at shutdown, not after each request. Use `returns: 'many'` for an array, `'one'` when a row
+must exist, or omit the option for the driver's full result.
+
+Tenon also provides:
+
+- Transactions and affected-row limits that roll back rejected writes.
+- SQL migration files and a CLI to apply, inspect, and roll back migrations.
+- TypeScript table row types generated from your database.
+- SQL fragments for sharing query parts or assembling variable conditions.
+
+Joins, relationships, aggregates, and upserts use ordinary PostgreSQL SQL. Tenon does not introduce
+model classes or automatically load related records. Input validation, authorization, and database
+performance remain application concerns. You can keep an existing migration runner; Tenon's
+migrations and table type generation are independent conveniences.
+
+## Here's what a coding agent says about it
+
+> "The appeal is that I can read the query, see where the transaction starts and ends, and put
+> reusable logic in a function. There isn't much framework machinery to learn. The tradeoff is that
+> someone still has to write the SQL and check the result types. I'm happy to do that part. Please
+> still review my SQL."
+>
+> — Codex, after working on Tenon. An interested party, to put it mildly.
+
+## Object-based writes
+
+For object-based writes, `sql.insertValues(rows)` preserves database defaults across heterogeneous
+rows and `sql.assignments(patch)` omits undefined fields. Keep the surrounding SQL explicit. Both
+support selected columns and [SafeQL checking](docs/reference.md#object-based-mutation-fragments).
+
+## Checking query results
+
+The type in `sql<{ id: number; email: string }>` describes what you expect back. TypeScript alone
+cannot verify that your SQL actually selects those columns.
+
+For that, Tenon provides an optional integration with [SafeQL](https://safeql.dev/). SafeQL checks
+SQL against your development database and can write or repair the result annotation. ESLint runs the
+check during development and CI; it is not part of query execution.
+
+Configure SafeQL in your application's ESLint setup. Tenon supplies a `safeqlPlugin` adapter for its
+queries, constant fragments, and official mutation helpers, plus an `eslintPlugin` rule that flags
+queries the adapter cannot check. SafeQL handles database analysis and result annotations; Tenon keeps the SQL and pg type
+mappings consistent with execution. Both integrations are optional development tooling. See
+[SQL checking setup](docs/reference.md#sql-checking-with-safeql) for installation and a complete
+configuration, including multiple databases.
+
+Checking complements typed inputs and database tests. It does not validate request values or
+arbitrary JSON, and runtime-built query variants need their own tests.
+
+## Documentation
+
+- **[Human guide](docs/human-guide.md)** — learn the workflow through practical examples.
+- **[Agent guide](docs/agent-guide.md)** — self-contained setup, API contracts, and implementation
+  conventions.
+- **[Reference](docs/reference.md)** — complete options, SQL checking setup, type mappings, and
+  limitations.
+- **[Adoption guide](docs/adoption-guide.md)** — replace an existing ORM and, if needed, transfer
+  migration ownership.
+
+The complete `docs/` folder ships with the npm package. Maintainer instructions are in
+[CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md), which is not
+bundled.
+
+[ISC licensed](LICENSE). Maintained by [Kequtech](https://github.com/kequtech).

package/dist/affected-rows.d.ts

@@ -0,0 +1,11 @@
+import type { QueryResult } from 'pg';
+/** PostgreSQL's final command count, independent of RETURNING. */
+export type AffectedRowsConstraint = {
+    readonly max: number;
+    readonly exact?: never;
+} | {
+    readonly exact: number;
+    readonly max?: never;
+};
+export declare function validateAffectedRows(value: unknown): AffectedRowsConstraint | undefined;
+export declare function checkAffectedRows(constraint: AffectedRowsConstraint, result: QueryResult<Record<string, unknown>>): void;

package/dist/affected-rows.js

@@ -0,0 +1,30 @@
+import { AffectedRowsError } from './errors.js';
+import { plainObject } from './validation.js';
+export function validateAffectedRows(value) {
+    if (value === undefined)
+        return undefined;
+    const config = plainObject(value, 'affectedRows');
+    const keys = Object.keys(config);
+    const key = keys[0];
+    if (keys.length !== 1 || (key !== 'max' && key !== 'exact')) {
+        throw new Error('affectedRows must specify exactly one of max or exact.');
+    }
+    const count = config[key];
+    if (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0) {
+        throw new Error('affectedRows must be a nonnegative safe integer.');
+    }
+    return Object.freeze(key === 'max' ? { max: count } : { exact: count });
+}
+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);
+    }
+    const expected = constraint.exact ?? constraint.max;
+    const matches = constraint.exact === undefined ? result.rowCount <= expected : result.rowCount === expected;
+    if (!matches) {
+        throw new AffectedRowsError(constraint, result.rowCount, result.command, true);
+    }
+}

package/dist/baseline.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseToolOptions } from './migrations/connection.js';
+export interface CaptureBaselineOptions {
+    /** Native libpq connection string, passed directly to pg_dump. */
+    readonly connection: string;
+    readonly namespace?: string;
+    /** Optional native pg_dump schema selection; omitted captures the whole database schema. */
+    readonly schemas?: readonly string[];
+    readonly directory?: string;
+    /** Receives native pg_dump warnings; defaults to console.warn. */
+    readonly onWarning?: (message: string) => void;
+}
+export interface CapturedBaseline {
+    readonly id: string;
+    readonly upPath: string;
+}
+/** Capture schema only. No source history writes, comparisons or ORM cleanup. */
+export declare function captureBaseline(options: CaptureBaselineOptions): Promise<CapturedBaseline>;
+/** Acknowledge the saved baseline on an existing database; never execute its SQL. */
+export declare function adoptBaseline(options: DatabaseToolOptions): Promise<readonly string[]>;

package/dist/baseline.js

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import { link, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { prepareBaselineSql } from './migrations/baseline-sql.js';
+import { withMigrationLock } from './migrations/connection.js';
+import { readMigrations, withMigrationCreationLock } from './migrations/files.js';
+import { createHistoryTable, migrationState, migrationTable, recordMigration, } from './migrations/history.js';
+import { qualified, quote } from './sql.js';
+const run = promisify(execFile);
+/** Capture schema only. No source history writes, comparisons or ORM cleanup. */
+export async function captureBaseline(options) {
+    if (typeof options.connection !== 'string' || !options.connection.trim()) {
+        throw new Error('Baseline capture requires an explicit nonempty connection string.');
+    }
+    if (options.schemas !== undefined && options.schemas.length === 0) {
+        throw new Error('Baseline schemas must not be empty; omit schemas to capture the whole database schema.');
+    }
+    const namespace = options.namespace ?? 'public';
+    quote(namespace);
+    const schemas = options.schemas?.map((schema) => `--schema=${quote(schema)}`) ?? [];
+    return withMigrationCreationLock(options.directory ?? 'migrations', async (directory) => {
+        if ((await readdir(directory)).some((name) => name.endsWith('.sql'))) {
+            throw new Error('Baseline capture requires an empty Tenon migration directory. Existing files were not changed.');
+        }
+        const temporary = await mkdtemp(join(directory, '.tenon-baseline-'));
+        try {
+            const file = join(temporary, 'dump.sql');
+            let warnings;
+            try {
+                const result = await run('pg_dump', [
+                    '--dbname',
+                    options.connection,
+                    '--no-password',
+                    '--schema-only',
+                    '--no-owner',
+                    '--no-privileges',
+                    '--quote-all-identifiers',
+                    '--strict-names',
+                    ...schemas,
+                    `--exclude-table=${qualified(namespace, migrationTable)}`,
+                    '--file',
+                    file,
+                ]);
+                warnings = result.stderr.trim();
+            }
+            catch (error) {
+                // execFile's Error includes argv, potentially containing credentials.
+                // Do not propagate that Error, its command line, or a credential-bearing cause.
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                    throw new Error('Baseline capture requires pg_dump on PATH. Install PostgreSQL client tools.');
+                }
+                throw new Error('pg_dump failed. Check database access, permissions and PostgreSQL client/server compatibility. No baseline was written.');
+            }
+            if (warnings) {
+                (options.onWarning ?? console.warn)(warnings);
+            }
+            const upPath = join(directory, '0001_baseline.up.sql');
+            const prepared = join(temporary, 'migration.sql');
+            await writeFile(prepared, prepareBaselineSql(await readFile(file, 'utf8'), namespace));
+            // Publish a complete file atomically without replacing an existing path.
+            await link(prepared, upPath);
+            return { id: '0001', upPath };
+        }
+        finally {
+            await rm(temporary, { recursive: true, force: true });
+        }
+    });
+}
+/** Acknowledge the saved baseline on an existing database; never execute its SQL. */
+export async function adoptBaseline(options) {
+    const files = await readMigrations(options.directory);
+    const baseline = files[0];
+    if (!baseline ||
+        baseline.id !== '0001' ||
+        baseline.name !== 'baseline' ||
+        baseline.down !== undefined) {
+        throw new Error('Adoption requires 0001_baseline.up.sql with no down file. Capture and commit a baseline first.');
+    }
+    return withMigrationLock(options, 'exclusive', async (client, namespace) => {
+        const applied = await migrationState(client, namespace, files);
+        if (applied.length) {
+            return [];
+        }
+        const schema = await client.query('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 createHistoryTable(client, namespace);
+        await recordMigration(client, namespace, baseline);
+        const result = await client.query('COMMIT');
+        if (result.command !== 'COMMIT') {
+            throw new Error('Baseline adoption was rolled back.');
+        }
+        return [baseline.id];
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { adoptBaseline, captureBaseline } from './baseline.js';
+import { generateDefinitions } from './generate.js';
+import { migrate, migrationStatus, rollback } from './migrations.js';
+import { createMigration } from './migrations/files.js';
+const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
+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]
+rollback: --steps 1
+Connection: DATABASE_URL
+`;
+function warn(message) {
+    process.stderr.write(`Warning: ${message}\n`);
+}
+/** Check without writing, or replace the complete generated file atomically. */
+async function writeDefinitions(source, filename, check) {
+    const output = resolve(filename);
+    if (check) {
+        let existing;
+        try {
+            existing = await readFile(output, 'utf8');
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+                throw error;
+            }
+        }
+        if (existing !== source) {
+            throw new Error('Generated definitions are stale or missing; run tenon generate and commit the result.');
+        }
+        process.stdout.write('Generated definitions are current.\n');
+        return;
+    }
+    await mkdir(dirname(output), { recursive: true });
+    const temporary = `${output}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, source, 'utf8');
+        await rename(temporary, output);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    process.stdout.write(`Generated ${output}\n`);
+}
+async function runBaseline(action, options) {
+    warn("Capture one shared baseline at the old ORM's final schema checkpoint. Each existing database must be at that checkpoint before adoption. Tenon does not compare schemas or remove the old ORM.");
+    if (action === 'capture') {
+        const result = await captureBaseline({ ...options, onWarning: warn });
+        process.stdout.write(`Captured ${result.upPath}. Source history and data were not changed. Commit this file and generated definitions.\n`);
+    }
+    else {
+        warn('Adoption records 0001_baseline without executing its SQL. Use migrate for a fresh database. Disable the old migration runner when switching to Tenon.');
+        const completed = await adoptBaseline(options);
+        process.stdout.write(`baseline adopt: ${completed.length ? completed.join(', ') : 'already recorded'}\n`);
+    }
+}
+async function main() {
+    const { positionals, values, tokens } = parseArgs({
+        allowPositionals: true,
+        tokens: true,
+        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 },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(help);
+        return;
+    }
+    const [command, argument] = positionals;
+    // 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')
+        allowed.add('directory');
+    if (command !== 'new') {
+        allowed.add('namespace');
+    }
+    if (command === 'generate') {
+        allowed.add('out');
+        allowed.add('check');
+    }
+    if (command === 'rollback') {
+        allowed.add('steps');
+    }
+    if (command === 'baseline' && argument === 'capture') {
+        allowed.add('schema');
+    }
+    for (const token of tokens) {
+        if (token.kind === 'option' && !allowed.has(token.name)) {
+            throw new Error(`--${token.name} is not supported by ${command ?? 'this command'}.`);
+        }
+    }
+    if (command === 'new') {
+        if (positionals.length !== 2) {
+            throw new Error('Use new <name> to create a migration pair.');
+        }
+        const files = await createMigration({ name: argument, directory: values.directory });
+        process.stdout.write(`Created ${files.upPath}\nCreated ${files.downPath}\n`);
+        return;
+    }
+    const baseline = command === 'baseline' && (argument === 'capture' || argument === 'adopt');
+    const valid = baseline
+        ? positionals.length === 2
+        : positionals.length === 1 &&
+            ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
+    if (!valid) {
+        throw new Error('Choose new, baseline capture|adopt, migrate, generate, status, or rollback. Use --help for options.');
+    }
+    const connection = process.env.DATABASE_URL;
+    if (!connection) {
+        throw new Error('DATABASE_URL is required.');
+    }
+    const options = { connection, directory: values.directory, namespace: values.namespace };
+    if (baseline) {
+        await runBaseline(argument, {
+            ...options,
+            ...(values.schema ? { schemas: values.schema } : {}),
+        });
+        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;
+        default: {
+            const completed = command === 'migrate'
+                ? await migrate(options)
+                : await rollback({ ...options, steps: Number(values.steps) });
+            process.stdout.write(`${command}: ${completed.length ? completed.join(', ') : 'nothing to do'}\n`);
+        }
+    }
+}
+main().catch((error) => {
+    // Do not print connection configuration or raw SQL/parameter payloads.
+    process.stderr.write(`${error instanceof Error ? error.message : 'Database command failed.'}\n`);
+    process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+import type { QueryExecutor } from './connection.js';
+import type { QueryEvent, Transaction } from './types.js';
+/** All public execution shares validation, atomic checks, and result handling. */
+export declare function createClient(query: QueryExecutor, onQuery?: (event: QueryEvent) => void | Promise<void>): Transaction;

package/dist/client.js

@@ -0,0 +1,54 @@
+import { checkAffectedRows } from './affected-rows.js';
+import { queryOutput, validateOptions } from './query-options.js';
+import { assertQuery } from './query.js';
+import { validateTransactionSql } from './transaction-sql.js';
+/** All public execution shares validation, atomic checks, and result handling. */
+export function createClient(query, onQuery) {
+    async function execute(statement, input) {
+        const options = validateOptions(input);
+        assertQuery(statement);
+        validateTransactionSql(statement.text, options.label ?? 'Query');
+        const started = performance.now();
+        let command;
+        let rowCount;
+        let failure;
+        let succeeded = false;
+        try {
+            const value = await query(statement.text, statement.values, (result) => {
+                command = result.command;
+                rowCount = result.rowCount;
+                if (options.affectedRows)
+                    checkAffectedRows(options.affectedRows, result);
+                return queryOutput(options, result);
+            }, options.affectedRows !== undefined);
+            succeeded = true;
+            return value;
+        }
+        catch (error) {
+            failure = error;
+            throw error;
+        }
+        finally {
+            if (onQuery) {
+                const code = failure && typeof failure === 'object' && 'code' in failure ? failure.code : undefined;
+                const event = Object.freeze({
+                    ...(options.label && { label: options.label }),
+                    durationMs: performance.now() - started,
+                    outcome: succeeded ? 'success' : 'error',
+                    ...(command !== undefined && { command }),
+                    ...(rowCount !== undefined && { rowCount }),
+                    ...(typeof code === 'string' && { errorCode: code }),
+                });
+                // Diagnostics must not turn a committed write into an apparent failure.
+                const report = () => process.emitWarning('Tenon onQuery callback failed; query outcome was preserved.');
+                try {
+                    void Promise.resolve(onQuery(event)).catch(report);
+                }
+                catch {
+                    report();
+                }
+            }
+        }
+    }
+    return { query: execute };
+}

package/dist/connection.d.ts

@@ -0,0 +1,15 @@
+import type { PoolClient, PoolConfig, QueryResult } from 'pg';
+import { Pool } from 'pg';
+export type Connection = string | PoolConfig | Pool;
+export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult<Record<string, unknown>>) => T, guarded: boolean) => Promise<T>;
+/** Borrow application pools; own pools created from a connection string or config. */
+export declare function createPool(connection: Connection): {
+    pool: Pool;
+    owned: boolean;
+};
+/** Observe failures between queries until ownership returns to the pool. */
+export declare function watchClient(client: PoolClient): {
+    check(): void;
+    release(error?: Error): void;
+};
+export declare function executeSql(connection: Pool | PoolClient, text: string, input: readonly unknown[]): Promise<QueryResult<Record<string, unknown>>>;

package/dist/connection.js

@@ -0,0 +1,51 @@
+import { Pool } from 'pg';
+import { plainObject } from './validation.js';
+/** Borrow application pools; own pools created from a connection string or config. */
+export function createPool(connection) {
+    if (connection instanceof Pool) {
+        return { pool: connection, owned: false };
+    }
+    // Missing configuration must not silently select pg's environment defaults.
+    // An explicit config object (including {}) may still use those defaults.
+    if (typeof connection === 'string') {
+        if (!connection.trim())
+            throw new Error('Connection string must not be empty.');
+    }
+    else {
+        plainObject(connection, 'Connection configuration');
+    }
+    const config = typeof connection === 'string' ? { connectionString: connection } : connection;
+    const pool = new Pool(config);
+    // pg removes broken idle clients itself, but an unhandled pool error would
+    // still terminate Node. Borrowed pools keep their application's error policy.
+    pool.on('error', (error) => process.emitWarning(error));
+    return { pool, owned: true };
+}
+/** Observe failures between queries until ownership returns to the pool. */
+export function watchClient(client) {
+    let failure;
+    const onError = (error) => {
+        failure ??= error;
+    };
+    client.on('error', onError);
+    return {
+        check() {
+            if (failure) {
+                throw failure;
+            }
+        },
+        release(error) {
+            try {
+                client.release(error ?? failure);
+            }
+            finally {
+                client.removeListener('error', onError);
+            }
+        },
+    };
+}
+export function executeSql(connection, text, input) {
+    // Extended protocol makes even a zero-parameter call one SQL statement.
+    const config = { text, values: [...input], queryMode: 'extended' };
+    return connection.query(config);
+}

package/dist/database.d.ts

@@ -0,0 +1,7 @@
+import type { Connection } from './connection.js';
+import type { Database, QueryEvent } from './types.js';
+export interface TenonOptions {
+    readonly connection: Connection;
+    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
+}
+export declare function createTenon(options: TenonOptions): Database;

package/dist/database.js

@@ -0,0 +1,44 @@
+import { createClient } from './client.js';
+import { createPool, executeSql } from './connection.js';
+import { withTransaction } from './transaction.js';
+import { plainObject } from './validation.js';
+export function createTenon(options) {
+    for (const key of Object.keys(plainObject(options, 'Tenon options'))) {
+        if (key !== 'connection' && key !== 'onQuery') {
+            throw new Error(`Unknown Tenon option: ${key}`);
+        }
+    }
+    if (options.onQuery !== undefined && typeof options.onQuery !== 'function') {
+        throw new Error('onQuery must be a function.');
+    }
+    const { pool, owned } = createPool(options.connection);
+    let closed = false;
+    function checkOpen() {
+        if (closed) {
+            throw new Error('This database instance is closed.');
+        }
+    }
+    const query = async (text, input, readResult, guarded) => {
+        checkOpen();
+        if (guarded) {
+            return withTransaction(pool, (query) => query(text, input, readResult, false));
+        }
+        return readResult(await executeSql(pool, text, input));
+    };
+    return {
+        ...createClient(query, options.onQuery),
+        async transaction(callback) {
+            checkOpen();
+            return withTransaction(pool, (query) => callback(createClient(query, options.onQuery)));
+        },
+        async close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (owned) {
+                await pool.end();
+            }
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+import type { AffectedRowsConstraint } from './affected-rows.js';
+export declare class AffectedRowsError extends Error {
+    name: string;
+    readonly code: 'TENON_AFFECTED_ROWS_MISMATCH' | 'TENON_AFFECTED_ROWS_UNSUPPORTED';
+    readonly expected: AffectedRowsConstraint;
+    readonly actual: number | null;
+    readonly command: string;
+    constructor(expected: AffectedRowsConstraint, actual: number | null, command: string, supported: boolean);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class AffectedRowsError extends Error {
+    name = 'AffectedRowsError';
+    code;
+    expected;
+    actual;
+    command;
+    constructor(expected, actual, command, supported) {
+        const limit = expected.exact ?? expected.max;
+        const comparison = expected.exact === undefined ? 'at most' : 'exactly';
+        super(supported
+            ? `Expected ${comparison} ${limit} affected rows, but PostgreSQL reported ${actual}.`
+            : 'affectedRows requires an INSERT, UPDATE, DELETE, or MERGE command count.');
+        this.code = supported ? 'TENON_AFFECTED_ROWS_MISMATCH' : 'TENON_AFFECTED_ROWS_UNSUPPORTED';
+        this.expected = Object.freeze({ ...expected });
+        this.actual = actual;
+        this.command = command;
+    }
+}