@kequtech/tenon-orm 0.0.0-stage → 0.1.0

package/dist/safeql/plugin.js

@@ -0,0 +1,43 @@
+import ts from 'typescript';
+import { CompositionError, isExport, renderValue } from './composition.js';
+/** Loaded through the exported SafeQL plugin descriptor. */
+export function factory() {
+    return {
+        name: 'tenon',
+        connectionDefaults: {
+            inferLiterals: false,
+            overrides: {
+                types: {
+                    int8: 'string',
+                    numeric: 'string',
+                    json: 'unknown',
+                    jsonb: 'unknown',
+                    date: 'Date | number',
+                    timestamp: 'Date | number',
+                    timestamptz: 'Date | number',
+                },
+            },
+        },
+        onTarget({ node, context }) {
+            const template = context.parser.esTreeNodeToTSNodeMap.get(node);
+            if (!ts.isTaggedTemplateExpression(template) ||
+                !isExport(template.tag, context.checker, 'sql'))
+                return false;
+            // The companion ESLint rule reports unsupported forms. Skip their SQL analysis.
+            if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked))
+                return false;
+            // Defer to SafeQL's configured targets, including per-connection tag selection.
+            return undefined;
+        },
+        onExpression({ context }) {
+            try {
+                return renderValue(context.tsNode, context.checker);
+            }
+            catch (error) {
+                if (!(error instanceof CompositionError))
+                    throw error;
+                return false;
+            }
+        },
+    };
+}

package/dist/safeql.d.ts

@@ -0,0 +1,6 @@
+/** Add to a connection's plugins in normal SafeQL configuration. */
+export declare const safeqlPlugin: {
+    package: string;
+};
+/** Register as `tenon` in ESLint and enable `tenon/check-composition`. */
+export { eslintPlugin } from './safeql/eslint.js';

package/dist/safeql.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from 'node:url';
+/** Add to a connection's plugins in normal SafeQL configuration. */
+export const safeqlPlugin = {
+    package: fileURLToPath(new URL('./safeql/plugin.js', import.meta.url)),
+};
+/** Register as `tenon` in ESLint and enable `tenon/check-composition`. */
+export { eslintPlugin } from './safeql/eslint.js';

package/dist/sql.d.ts

@@ -0,0 +1,5 @@
+export declare function validateName(value: string): void;
+export declare function quote(name: string): string;
+export declare function qualified(namespace: string, table: string): string;
+/** Shared by query assembly and static checking so separators produce identical SQL. */
+export declare function joinSeparator(value: unknown): string;

package/dist/sql.js

@@ -0,0 +1,28 @@
+export function validateName(value) {
+    if (typeof value !== 'string' ||
+        !value ||
+        value.includes('\0') ||
+        Buffer.byteLength(value) > 63) {
+        throw new Error('Identifiers must contain 1–63 UTF-8 bytes and no NUL character.');
+    }
+}
+export function quote(name) {
+    validateName(name);
+    return `"${name.replaceAll('"', '""')}"`;
+}
+export function qualified(namespace, table) {
+    return `${quote(namespace)}.${quote(table)}`;
+}
+/** Shared by query assembly and static checking so separators produce identical SQL. */
+export function joinSeparator(value) {
+    switch (value) {
+        case 'AND':
+            return ' AND ';
+        case 'OR':
+            return ' OR ';
+        case ',':
+            return ', ';
+        default:
+            throw new Error('sql.join separator must be "AND", "OR", or ",".');
+    }
+}

package/dist/transaction-sql.d.ts

@@ -0,0 +1,2 @@
+/** Public SQL cannot take ownership away from Tenon's callback transaction. */
+export declare function validateTransactionSql(sql: string, name: string): void;

package/dist/transaction-sql.js

@@ -0,0 +1,67 @@
+/** Read only the command prefix, leaving strings, bodies and SQL syntax to pg. */
+function commandPrefix(sql) {
+    const words = [];
+    let i = 0;
+    while (i < sql.length && words.length < 3) {
+        if (/\s/.test(sql[i])) {
+            i++;
+            continue;
+        }
+        if (!words.length && sql[i] === ';') {
+            i++;
+            continue;
+        }
+        if (sql.startsWith('--', i)) {
+            i += 2;
+            while (i < sql.length && sql[i] !== '\n' && sql[i] !== '\r') {
+                i++;
+            }
+            continue;
+        }
+        if (sql.startsWith('/*', i)) {
+            let depth = 1;
+            i += 2;
+            while (i < sql.length && depth) {
+                if (sql.startsWith('/*', i)) {
+                    depth++;
+                    i += 2;
+                }
+                else if (sql.startsWith('*/', i)) {
+                    depth--;
+                    i += 2;
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        if (sql[i] === '(') {
+            words.push('(');
+            break;
+        }
+        const word = /^[A-Za-z_\u0080-\uFFFF][A-Za-z_0-9$\u0080-\uFFFF]*/.exec(sql.slice(i));
+        if (!word) {
+            break;
+        }
+        words.push(word[0].toUpperCase());
+        i += word[0].length;
+    }
+    return words;
+}
+/** Public SQL cannot take ownership away from Tenon's callback transaction. */
+export function validateTransactionSql(sql, name) {
+    const [first, second, third] = commandPrefix(sql);
+    const rollbackTo = first === 'ROLLBACK' &&
+        (second === 'TO' || ((second === 'WORK' || second === 'TRANSACTION') && third === 'TO'));
+    if (first === 'BEGIN' ||
+        first === 'COMMIT' ||
+        first === 'END' ||
+        first === 'ABORT' ||
+        (first === 'ROLLBACK' && !rollbackTo) ||
+        (first === 'START' && second === 'TRANSACTION') ||
+        // A SQL prepared statement named transaction is not a prepared transaction.
+        (first === 'PREPARE' && second === 'TRANSACTION' && third !== 'AS' && third !== '(')) {
+        throw new Error(`${name} cannot start or end a transaction; use db.transaction() to manage transaction boundaries.`);
+    }
+}

package/dist/transaction.d.ts

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

package/dist/transaction.js

@@ -0,0 +1,75 @@
+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 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');
+        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;
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch (rollbackError) {
+            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed.');
+            throw new AggregateError([error, rollbackError], 'Transaction and rollback failed.');
+        }
+        throw error;
+    }
+    finally {
+        connection.release(releaseError);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
+import type { SqlQuery } from './query.js';
+export interface QueryClient {
+    query<Row extends QueryResultRow>(query: SqlQuery<Row>, options?: QueryOptions & {
+        readonly returns?: 'native';
+    }): NoInfer<Promise<QueryResult<Row>>>;
+    query<Row extends QueryResultRow, Mode extends QueryReturnMode>(query: SqlQuery<Row>, options: QueryOptions & {
+        readonly returns: Mode;
+    }): NoInfer<Promise<QueryOutput<Row, Mode>>>;
+    query<Row extends QueryResultRow>(query: SqlQuery<Row>, options: QueryOptions | undefined): NoInfer<Promise<QueryOutput<Row, QueryReturnMode>>>;
+}
+export type Transaction = QueryClient;
+export type Database = Transaction & {
+    /** Await all work inside the callback. Commit on success; rollback on an escaping error. */
+    transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+};
+/** One completed public query call, including rollback/commit time for guarded calls. */
+export interface QueryEvent {
+    readonly label?: string;
+    readonly durationMs: number;
+    readonly outcome: 'success' | 'error';
+    readonly command?: string;
+    readonly rowCount?: number | null;
+    /** Stable Tenon or PostgreSQL error code, when available. */
+    readonly errorCode?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1 @@
+export declare function plainObject(value: unknown, name: string): Record<string, unknown>;

package/dist/validation.js

@@ -0,0 +1,10 @@
+export function plainObject(value, name) {
+    if (value === null || typeof value !== 'object') {
+        throw new Error(`${name} must be a plain object.`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${name} must be a plain object.`);
+    }
+    return value;
+}

package/docs/adoption-guide.md

@@ -0,0 +1,91 @@
+# Adopting Tenon from another ORM
+
+This guide covers replacing an existing ORM and, separately, transferring migration ownership. For a
+query tutorial use the [human guide](human-guide.md); for API details use the
+[reference](reference.md). Preserve the existing schema, connection configuration, data, and
+application behavior while replacing the old ORM. Tenon does not need to own migrations to execute
+queries or generate types; keep the existing migration runner if that is the intended scope.
+
+## Replace application queries
+
+1. Locate the old ORM's connection setup, schema, migrations, and call sites. Identify behavior
+   supplied by the ORM: validation, IDs, timestamps, hooks, defaults, relation loading,
+   serialization, and transaction boundaries.
+2. If table row types will help your application, generate them from the existing database:
+
+   ```sh
+   npx tenon generate --out src/generated-schema.ts
+   ```
+
+   Use `--namespace name` for a non-public schema. Generation reads the actual database and requires
+   no Tenon migration history.
+
+3. Replace queries with parameterized SQL in ordinary functions with named object inputs where
+   useful. Preserve each caller's projection, null handling, ordering, and transaction behavior.
+   Generated types describe pg values: check bigint/numeric strings, dates, JSON, and arrays when
+   the old ORM transformed them.
+4. If using optional SQL checking, configure the
+   [SafeQL integration](reference.md#sql-checking-with-safeql) to generate query annotations and
+   check them against the intended schema. Run tests against a dedicated test database. Verify
+   writes and rollback, relationships, validation, and any hooks you moved into application code or
+   SQL. A schema-preserving first release makes application rollback easier.
+5. Remove the old runtime dependency and unused generated code after its callers are gone. Keep the
+   migration tooling until the migration transition below is complete, if that transition is part of
+   the work.
+
+## Move migration ownership to Tenon
+
+Choose one final schema checkpoint for the old runner and bring existing target databases to it.
+Disable its migration/schema synchronization before handing ownership to Tenon. The tools do not
+share locks.
+
+Capture one baseline from the reference database into an empty migration directory:
+
+```sh
+npx tenon baseline capture --directory migrations --namespace public
+```
+
+This uses native `pg_dump --schema-only --no-owner --no-privileges` and writes
+`0001_baseline.up.sql` without a down file. It requires a compatible `pg_dump` on PATH; prefer the
+server's major. Default scope is the whole database schema. Repeat `--schema name` to select schemas
+explicitly, accounting for dependencies, extensions, and required roles. Tenon's selected history
+table is excluded; old ORM metadata is preserved for deliberate cleanup later.
+
+Capture changes no source data, migration history, or sequence positions. Review and commit the SQL.
+Keep the capture header: it identifies native dump SQL that bypasses the authored-migration scanner.
+It is a convention, not proof of provenance; do not use it on handwritten migrations. Normal
+transactional execution and checksums still apply.
+
+On each existing database already at that checkpoint:
+
+```sh
+npx tenon baseline adopt
+```
+
+Adoption records the baseline checksum without executing the SQL or comparing schemas. It requires
+the selected namespace to exist. Repeating matching adoption is harmless, including after later
+migrations; conflicting history fails.
+
+On a fresh database, run migrations instead:
+
+```sh
+npx tenon migrate
+```
+
+That executes the baseline and subsequent migrations. Use the same committed baseline for every
+environment. Do not run adoption unconditionally on fresh databases. Existing databases adopt once
+and then use ordinary `migrate`.
+
+Use the development [`db:migrate` script](human-guide.md#create-a-table) to apply subsequent
+migrations and update table types together. Production continues to run only `npx tenon migrate`.
+Verify both an existing database's upgrade and a fresh replay. Baselines contain schema only; they
+do not back up rows or sequence positions. The missing down file prevents normal rollback through
+the baseline. Keep the application's backup and recovery procedure.
+
+Programmatic equivalents:
+
+- `captureBaseline({ connection, directory?, namespace?, schemas?, onWarning? })` requires a
+  nonempty native libpq connection string and returns `{ id, upPath }`. Omit `schemas` for the whole
+  database schema; an explicitly empty list is rejected.
+- `adoptBaseline({ connection, directory?, namespace? })` accepts the usual Tenon connection options
+  and returns newly recorded migration IDs.