@kequtech/tenon-orm 0.4.0 → 0.4.3

package/dist/config/load.js

@@ -0,0 +1,159 @@
+import { stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sessionOptions, timeoutOptions } from '../inspection/options.js';
+import { validateName } from '../sql.js';
+import { plainObject, validatePath } from '../validation.js';
+export const configNames = [
+    'tenon.config.ts',
+    'tenon.config.mts',
+    'tenon.config.js',
+    'tenon.config.mjs',
+];
+async function exists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function keys(value, label, allowed) {
+    const config = plainObject(value, label);
+    for (const key of Object.keys(config)) {
+        if (!allowed.includes(key))
+            throw new Error(`Unknown ${label} option: ${key}`);
+    }
+    return config;
+}
+/** Find configuration without importing it, including for offline initialization. */
+export async function findConfig(directory = process.cwd()) {
+    while (true) {
+        const candidates = await Promise.all(configNames.map(async (name) => {
+            const candidate = join(directory, name);
+            return (await exists(candidate)) ? candidate : undefined;
+        }));
+        const found = candidates.filter((candidate) => candidate !== undefined);
+        if (found.length > 1)
+            throw new Error(`Multiple Tenon config files in ${directory}; select one with --config.`);
+        if (found.length) {
+            return found[0];
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+export async function loadConfig(filename, required = true) {
+    if (filename !== undefined)
+        validatePath(filename, 'Config filename');
+    const selected = filename === undefined ? await findConfig() : resolve(filename);
+    if (!selected && !required)
+        return undefined;
+    if (!selected)
+        throw new Error('Tenon configuration is required. Run tenon init or pass --config.');
+    let value;
+    try {
+        value = (await import(pathToFileURL(selected).href)).default;
+    }
+    catch {
+        // Import errors may contain credentials from environment validation or dependency messages.
+        throw new Error(`Could not load Tenon configuration: ${selected}. Check the module and its imports.`);
+    }
+    const config = keys(value, 'Tenon config', [
+        'connection',
+        'generate',
+        'migrations',
+        'baseline',
+        'check',
+        'session',
+        'timeouts',
+    ]);
+    if (typeof config.connection === 'string') {
+        if (!config.connection.trim())
+            throw new Error('Tenon config connection must be nonempty.');
+    }
+    else {
+        const connection = plainObject(config.connection, 'Tenon config connection');
+        if ('acquire' in connection || 'close' in connection) {
+            throw new Error('Tenon config requires connection options, not an open pool.');
+        }
+    }
+    const root = dirname(selected);
+    const migrations = keys(config.migrations === undefined ? {} : config.migrations, 'migration config', ['directory', 'namespace']);
+    if (migrations.directory !== undefined)
+        validatePath(migrations.directory, 'Migration directory');
+    if (migrations.namespace !== undefined)
+        validateName(migrations.namespace);
+    let generate;
+    if (config.generate !== undefined) {
+        const options = keys(config.generate, 'generation config', ['out', 'namespace']);
+        validatePath(options.out, 'Generation out');
+        if (options.namespace !== undefined)
+            validateName(options.namespace);
+        generate = {
+            out: resolve(root, options.out),
+            ...(options.namespace !== undefined && { namespace: options.namespace }),
+        };
+    }
+    const check = keys(config.check === undefined ? {} : config.check, 'checking config', [
+        'project',
+        'readTypes',
+    ]);
+    if (check.project !== undefined)
+        validatePath(check.project, 'Checking project');
+    if (check.readTypes !== undefined) {
+        const mappings = plainObject(check.readTypes, 'Checking readTypes');
+        for (const [oid, expression] of Object.entries(mappings)) {
+            if (!/^[1-9]\d*$/.test(oid) ||
+                Number(oid) > 0xffffffff ||
+                typeof expression !== 'string' ||
+                !expression.trim()) {
+                throw new Error('Checking readTypes requires PostgreSQL OIDs and nonempty type expressions.');
+            }
+        }
+    }
+    const baseline = keys(config.baseline === undefined ? {} : config.baseline, 'baseline config', [
+        'connection',
+        'schemas',
+    ]);
+    if (baseline.connection !== undefined &&
+        (typeof baseline.connection !== 'string' ||
+            !baseline.connection.trim() ||
+            baseline.connection.includes('\0'))) {
+        throw new Error('Baseline connection must be a nonempty native libpq connection string.');
+    }
+    if (baseline.schemas !== undefined) {
+        if (!Array.isArray(baseline.schemas) || !baseline.schemas.length)
+            throw new Error('Baseline schemas must be a nonempty array.');
+        for (const schema of baseline.schemas)
+            validateName(schema);
+    }
+    const session = sessionOptions(config.session === undefined ? {} : config.session);
+    const timeouts = timeoutOptions(config.timeouts === undefined ? {} : config.timeouts);
+    return {
+        connection: config.connection,
+        migrations: {
+            directory: resolve(root, migrations.directory ?? 'migrations'),
+            ...(migrations.namespace !== undefined && { namespace: migrations.namespace }),
+        },
+        ...(generate !== undefined && { generate }),
+        check: {
+            project: resolve(root, check.project ?? 'tsconfig.json'),
+            ...(check.readTypes !== undefined && {
+                readTypes: check.readTypes,
+            }),
+        },
+        ...(config.baseline !== undefined && {
+            baseline: {
+                ...(baseline.connection !== undefined && { connection: baseline.connection }),
+                ...(baseline.schemas !== undefined && { schemas: [...baseline.schemas] }),
+            },
+        }),
+        session,
+        timeouts,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectionConfig } from './connection.js';
+import type { InspectionSession, InspectionTimeouts } from './inspection/types.js';
+/** Shared runtime connection values and CLI defaults. Export without opening a database. */
+export interface TenonConfig {
+    readonly connection: ConnectionConfig;
+    readonly generate?: {
+        readonly out: string;
+        readonly namespace?: string;
+    };
+    readonly migrations?: {
+        readonly directory?: string;
+        readonly namespace?: string;
+    };
+    /** Native pg_dump connection/scope; defaults to the main connection only when it is a string. */
+    readonly baseline?: {
+        readonly connection?: string;
+        readonly schemas?: readonly string[];
+    };
+    readonly check?: {
+        readonly project?: string;
+        readonly readTypes?: Readonly<Record<number, string>>;
+    };
+    readonly session?: InspectionSession;
+    readonly timeouts?: InspectionTimeouts;
+}

package/dist/config.js

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

package/dist/connection.d.ts

@@ -1,6 +1,11 @@
 import { type Pool, type PoolOptions, type QueryResult as DriverResult, type Executor } from '@kequtech/pgclear';
 import type { UnknownRow } from './query.js';
 export type ConnectionOptions = PoolOptions;
+/** Connection settings and executable credentials/codecs, without a live pool. */
+export type ConnectionConfig = string | (ConnectionOptions & {
+    readonly acquire?: never;
+    readonly close?: never;
+});
 export type Connection = string | ConnectionOptions | Pool;
 export type QueryResult<Row extends object = UnknownRow> = DriverResult<Row>;
 export type QueryExecutor = <T>(text: string, input: readonly unknown[], readResult: (result: QueryResult) => T, guarded: boolean) => Promise<T>;

package/dist/describe.js

@@ -23,6 +23,8 @@ export async function describeQuery(options) {
             ? { parameterTypes: [...options.query.parameterTypes] }
             : {}),
     };
-    const codecs = options.codecs ?? defaultCodecs;
+    const codecs = options.codecs ??
+        (typeof options.connection === 'object' ? options.connection?.codecs : undefined) ??
+        defaultCodecs;
     return withInspectionConnection(options, async (client, context) => queryDescription(await readStatementMetadata(client, query), context, codecs));
 }

package/dist/generation/output.js

@@ -19,7 +19,6 @@ export async function writeDefinitions(source, filename, check) {
         if (existing !== source) {
             throw new Error(`Generated definitions differ: ${output}\n${definitionDiff(existing, source)}\nRun tenon generate with the same options, omitting --check, then commit the result.`);
         }
-        process.stdout.write('Generated definitions are current.\n');
         return;
     }
     await mkdir(dirname(output), { recursive: true });
@@ -31,5 +30,4 @@ export async function writeDefinitions(source, filename, check) {
     finally {
         await rm(temporary, { force: true });
     }
-    process.stdout.write(`Generated ${output}\n`);
 }

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { builtin, createTemporalCodecs, defaultCodecs, json, param } from '@kequtech/pgclear';
 export type { Codec, CodecRegistry, Parameter, PgArray, TemporalConstructors, TemporalInput, } from '@kequtech/pgclear';
-export type { Connection, ConnectionOptions, QueryResult } from './connection.js';
+export type { Connection, ConnectionConfig, ConnectionOptions, QueryResult } from './connection.js';
 export type { AffectedRowsConstraint } from './affected-rows.js';
 export { createTenon } from './database.js';
 export type { TenonOptions } from './database.js';
+export type { TenonConfig } from './config.js';
 export { AffectedRowsError, CardinalityError } from './errors.js';
 export type { QueryOptions, QueryOutput, QueryReturnMode } from './query-options.js';
 export { identifier, sql, unsafeSql } from './query.js';

package/dist/inspection/cli.d.ts

@@ -21,9 +21,9 @@ export declare const describeFlags: {
 /** Translate CLI flags; validation and defaults belong to the public API. */
 export declare function inspectionSettings(values: Partial<Record<keyof typeof describeFlags, string | undefined>>): {
     session: {
-        role: string | undefined;
-        searchPath: string | undefined;
-        timeZone: string | undefined;
+        timeZone?: string;
+        searchPath?: string;
+        role?: string;
     };
     timeouts: {
         lockMs?: number;
@@ -31,4 +31,3 @@ export declare function inspectionSettings(values: Partial<Record<keyof typeof d
         connectMs?: number;
     };
 };
-export declare function runDescribe(filename: string, connection: string, values: Partial<Record<keyof typeof describeFlags, string | undefined>>): Promise<void>;

package/dist/inspection/cli.js

@@ -1,5 +1,3 @@
-import { readFile } from 'node:fs/promises';
-import { describeQuery } from '../describe.js';
 export const describeFlags = {
     role: { type: 'string' },
     'search-path': { type: 'string' },
@@ -12,9 +10,9 @@ export const describeFlags = {
 export function inspectionSettings(values) {
     return {
         session: {
-            role: values.role,
-            searchPath: values['search-path'],
-            timeZone: values['time-zone'],
+            ...(values.role !== undefined && { role: values.role }),
+            ...(values['search-path'] !== undefined && { searchPath: values['search-path'] }),
+            ...(values['time-zone'] !== undefined && { timeZone: values['time-zone'] }),
         },
         timeouts: {
             ...(values['connect-timeout-ms'] !== undefined
@@ -29,11 +27,3 @@ export function inspectionSettings(values) {
         },
     };
 }
-export async function runDescribe(filename, connection, values) {
-    const result = await describeQuery({
-        connection,
-        query: await readFile(filename, 'utf8'),
-        ...inspectionSettings(values),
-    });
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}

package/dist/inspection/connection.js

@@ -1,27 +1,30 @@
-import { connect } from '@kequtech/pgclear';
+import { createPool, defaultCodecs } from '@kequtech/pgclear';
 import { inspectionOptions } from './options.js';
 export async function withInspectionConnection(options, work) {
-    const { url, limits, session } = inspectionOptions(options);
-    const connection = await connect({
-        connectionString: url.toString(),
+    const { connection, limits, session } = inspectionOptions(options);
+    const pool = createPool({
+        ...connection,
+        codecs: defaultCodecs,
+        maxConnections: 1,
         connectTimeoutMs: limits.connectMs,
         startupParameters: {
+            ...Object.fromEntries(Object.entries(connection.startupParameters ?? {}).filter(([name]) => !['statement_timeout', 'lock_timeout'].includes(name.toLowerCase()))),
             statement_timeout: String(limits.statementMs),
             lock_timeout: String(limits.lockMs),
         },
     });
-    const client = connection;
     try {
-        for (const [key, name] of [
-            ['role', 'role'],
-            ['searchPath', 'search_path'],
-            ['timeZone', 'TimeZone'],
-        ]) {
-            const value = session[key];
-            if (value !== undefined)
-                await client.queryClassic('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
-        }
-        const { rows: [context], } = await client.queryClassic(`
+        return await pool.withSession(async (client) => {
+            for (const [key, name] of [
+                ['role', 'role'],
+                ['searchPath', 'search_path'],
+                ['timeZone', 'TimeZone'],
+            ]) {
+                const value = session[key];
+                if (value !== undefined)
+                    await client.queryClassic('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
+            }
+            const { rows: [context], } = await client.queryClassic(`
       SELECT pg_catalog.current_database() AS database,
         session_user AS "sessionUser", current_user AS "currentUser",
         pg_catalog.current_setting('search_path') AS "searchPath",
@@ -32,11 +35,12 @@ export async function withInspectionConnection(options, work) {
         (SELECT setting::integer FROM pg_catalog.pg_settings
           WHERE name = 'lock_timeout') AS "lockTimeoutMs"
     `, []);
-        if (!context)
-            throw new Error('Inspection context was not returned.');
-        return await work(client, { mode: 'separate-session', readMappings: 'pgclear', ...context });
+            if (!context)
+                throw new Error('Inspection context was not returned.');
+            return await work(client, { mode: 'separate-session', readMappings: 'pgclear', ...context });
+        });
     }
     finally {
-        await connection.close();
+        await pool.close({ timeoutMs: limits.connectMs });
     }
 }

package/dist/inspection/options.d.ts

@@ -1,15 +1,13 @@
-import type { DescribeOptions } from './types.js';
+import type { DescribeOptions, InspectionSession, InspectionTimeouts } from './types.js';
+export declare function sessionOptions(value: unknown): InspectionSession;
+export declare function timeoutOptions(value: unknown): InspectionTimeouts;
 /** Validate and capture caller-owned settings before opening a connection. */
 export declare function inspectionOptions(options: Pick<DescribeOptions, 'connection' | 'session' | 'timeouts'>): {
-    url: URL;
+    connection: import("@kequtech/pgclear").PoolOptions;
     limits: {
         connectMs: number;
         statementMs: number;
         lockMs: number;
     };
-    session: {
-        role?: string | undefined;
-        searchPath?: string | undefined;
-        timeZone?: string | undefined;
-    };
+    session: InspectionSession;
 };

package/dist/inspection/options.js

@@ -1,11 +1,8 @@
 import { plainObject } from '../validation.js';
-/** Validate and capture caller-owned settings before opening a connection. */
-export function inspectionOptions(options) {
-    if (typeof options.connection !== 'string' || !options.connection.trim()) {
-        throw new Error('Describe requires an explicit nonempty connection string.');
-    }
-    plainObject(options.session ?? {}, 'Inspection session');
-    const session = { ...options.session };
+const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
+export function sessionOptions(value) {
+    const input = plainObject(value, 'Inspection session');
+    const session = { ...input };
     for (const [key, value] of Object.entries(session)) {
         if (!['role', 'searchPath', 'timeZone'].includes(key)) {
             throw new Error(`Unknown inspection session option: ${key}`);
@@ -16,9 +13,11 @@ export function inspectionOptions(options) {
             throw new Error(`Inspection session ${key} requires a nonempty string without NUL.`);
         }
     }
-    plainObject(options.timeouts ?? {}, 'Inspection timeouts');
-    const timeouts = { ...options.timeouts };
-    const defaults = { connectMs: 3000, statementMs: 5000, lockMs: 1000 };
+    return session;
+}
+export function timeoutOptions(value) {
+    const input = plainObject(value, 'Inspection timeouts');
+    const timeouts = { ...input };
     for (const [key, value] of Object.entries(timeouts)) {
         if (!Object.hasOwn(defaults, key))
             throw new Error(`Unknown inspection timeout: ${key}`);
@@ -28,24 +27,52 @@ export function inspectionOptions(options) {
             throw new Error(`Inspection timeout ${key} must be a positive integer in milliseconds.`);
         }
     }
+    return timeouts;
+}
+/** Validate and capture caller-owned settings before opening a connection. */
+export function inspectionOptions(options) {
+    let connection;
+    if (typeof options.connection === 'string') {
+        if (!options.connection.trim())
+            throw new Error('Describe requires an explicit nonempty connection string.');
+        connection = { connectionString: options.connection };
+    }
+    else {
+        plainObject(options.connection, 'Inspection connection');
+        if ('acquire' in options.connection || 'close' in options.connection) {
+            throw new Error('Inspection requires connection options, not an open pool.');
+        }
+        connection = { ...options.connection };
+    }
+    if (connection.startupParameters !== undefined) {
+        plainObject(connection.startupParameters, 'Startup parameters');
+    }
+    const session = sessionOptions(options.session ?? {});
+    const timeouts = timeoutOptions(options.timeouts ?? {});
     const limits = {
         connectMs: timeouts.connectMs ?? defaults.connectMs,
         statementMs: timeouts.statementMs ?? defaults.statementMs,
         lockMs: timeouts.lockMs ?? defaults.lockMs,
     };
     // URL startup options must not disable the inspection's server-side bounds.
-    let url;
-    try {
-        url = new URL(options.connection);
-    }
-    catch {
-        throw new Error('Describe requires a PostgreSQL connection URI.');
-    }
-    if (!['postgres:', 'postgresql:'].includes(url.protocol)) {
-        throw new Error('Describe requires a PostgreSQL connection URI.');
+    if (connection.connectionString !== undefined) {
+        let url;
+        try {
+            url = new URL(connection.connectionString);
+        }
+        catch {
+            throw new Error('Describe requires a PostgreSQL connection URI.');
+        }
+        if (!['postgres:', 'postgresql:'].includes(url.protocol)) {
+            throw new Error('Describe requires a PostgreSQL connection URI.');
+        }
+        if (!url.searchParams.has('application_name') && connection.applicationName === undefined) {
+            url.searchParams.set('application_name', 'tenon-describe');
+        }
+        connection = { ...connection, connectionString: url.toString() };
     }
-    if (!url.searchParams.has('application_name')) {
-        url.searchParams.set('application_name', 'tenon-describe');
+    else if (connection.applicationName === undefined) {
+        connection = { ...connection, applicationName: 'tenon-describe' };
     }
-    return { url, limits, session };
+    return { connection, limits, session };
 }

package/dist/inspection/types.d.ts

@@ -1,4 +1,5 @@
 import type { CodecRegistry, DescribeStatement } from '@kequtech/pgclear';
+import type { ConnectionConfig } from '../connection.js';
 export interface InspectionSession {
     readonly role?: string | undefined;
     /** PostgreSQL's search_path setting, as used in the application's connection options. */
@@ -23,8 +24,8 @@ export interface InspectionContext {
     readonly readMappings: 'pgclear';
 }
 export interface DescribeOptions {
-    /** PostgreSQL connection URI. Inspection owns a separate, short-lived connection. */
-    readonly connection: string;
+    /** URI or pool configuration values. Inspection owns a separate, short-lived connection. */
+    readonly connection: ConnectionConfig;
     /** Finished SQL; query values are neither bound nor executed. */
     readonly query: string | DescribeStatement;
     /** Use the same registry as execution; custom decoder types can remain unresolved. */

package/dist/migrations/history.d.ts

@@ -1,4 +1,4 @@
-import type { Session } from '@kequtech/pgclear';
+import { type Session } from '@kequtech/pgclear';
 import type { SqlMigration } from './files.js';
 export declare const migrationTable = "__tenon_migrations";
 interface AppliedMigration {

package/dist/migrations/history.js

@@ -1,11 +1,12 @@
+import { defaultCodecs } from '@kequtech/pgclear';
 import { qualified } from '../sql.js';
 export const migrationTable = '__tenon_migrations';
 export async function migrationState(client, namespace, migrations) {
-    const exists = await client.queryClassic('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    const exists = await client.queryClassic('SELECT pg_catalog.to_regclass($1)::text AS name', [qualified(namespace, migrationTable)], { codecs: defaultCodecs });
     if (exists.rows[0].name === null) {
         return [];
     }
-    const { rows: applied } = await client.queryClassic(`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`, [], { codecs: defaultCodecs });
     for (const [i, record] of applied.entries()) {
         const file = migrations[i];
         if (!file ||

package/dist/validation.d.ts

@@ -1 +1,3 @@
 export declare function plainObject(value: unknown, name: string): Record<string, unknown>;
+/** Validate before resolving paths so an empty override cannot become the working directory. */
+export declare function validatePath(value: unknown, label: string): asserts value is string;

package/dist/validation.js

@@ -8,3 +8,9 @@ export function plainObject(value, name) {
     }
     return value;
 }
+/** Validate before resolving paths so an empty override cannot become the working directory. */
+export function validatePath(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0')) {
+        throw new Error(`${label} must be a nonempty path without NUL.`);
+    }
+}