@kequtech/tenon-orm 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.4
+
+- Pass the shared `TenonConfig` directly to `createTenon`, including its connection, codecs, and
+  `onQuery` observer. `TenonConfig` replaces the `TenonOptions` type.
+- Defer pool creation and connection validation until the first query, transaction, or native-pool
+  access. Importing configuration and closing an unused instance need no credentials. Generated
+  configs use plain environment reads; remove eager credential checks from existing configs.
+- Support named config exports for multiple databases and CLI selection with `--database`. A sole
+  config is selected automatically; ambiguous or unknown names fail without fallback. `tenon init`
+  generates a named `main` export, and existing default exports remain supported.
+- Allow migration-file creation without database credentials while retaining each selected config's
+  migration, generation, and checking settings.
+
+## 0.4.3
+
+- Add shared runtime/CLI configuration and offline `tenon init`. Restore `tenon generate`, share migration defaults, and require config for generation/checking/inspection.
+- Remove `db.generateTypes()`. Add native baseline connection/schema defaults and fix inspection timeout overrides and migration-history lookup under custom search paths.
+
 ## 0.4.2
 
 - Rewrite the README and consumer guides around a complete getting-started workflow and task-based navigation.

package/README.md

@@ -15,14 +15,14 @@ typings. The PostgreSQL driver, [pgclear](https://github.com/kequtech/pgclear),
 
 ## Query with SQL
 
-This example assumes a `public.users` table with integer `id` and text `email` columns:
+This example assumes a `public.users` table with integer `id` and text `email` columns and a
+`main` export in your [shared configuration](docs/configuration.md):
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
+import { main } from './tenon.config.ts';
 
-const connection = process.env.DATABASE_URL;
-if (!connection) throw new Error('DATABASE_URL is required');
-const db = createTenon({ connection });
+const db = createTenon(main);
 
 try {
   const email = 'reader@example.test';
@@ -74,7 +74,7 @@ version. For work in an existing project, start with the [agent guide](docs/agen
 - **SQL defines the operation.** Use PostgreSQL joins, aggregates, constraints, and upserts directly.
   Reuse queries with ordinary functions; use fragments when parts of the SQL need to vary.
 - **TypeScript describes the values.** Declare query projections with `sql<Row>`. Optionally generate
-  table read/insert/update types with `db.generateTypes({ out: 'src/generated-schema.d.ts' })`.
+  table read/insert/update types with `tenon generate`.
 - **Transactions define what commits together.** Use `db.transaction(async (tx) => { ... })` and run
   every participating query through `tx`.
 - **Write guards check affected rows.** `{ affectedRows: { exact: 1 } }` rolls back a write unless
@@ -95,6 +95,16 @@ temporal values also default to strings, and JSON/array inputs use explicit enco
 `rowCount` is a number or null. See [value mappings](docs/schema-types.md#value-mappings) before
 choosing application types.
 
+## Share configuration with the CLI
+
+Run `tenon init` to create `tenon.config.ts`. Put connection settings and codecs in its `main` export,
+then reuse that object with `createTenon(main)`. Initialization stays lazy, so builds that only import
+the database instance need no credentials.
+
+The CLI uses the same config for migrations, `tenon generate`, freshness checks, `tenon check`, and
+`tenon describe query.sql`. For multiple databases, add named exports and select one with `--database`.
+See [shared configuration](docs/configuration.md) for the complete setup.
+
 ## Documentation
 
 Start with [Getting started](docs/human-guide.md) for a complete table-to-query example. Then choose
@@ -102,6 +112,7 @@ the guide for your task:
 
 | Guide                                                      | What it covers                                                               |
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Shared configuration](docs/configuration.md)              | Runtime/CLI connection settings, codecs, command defaults, and overrides     |
 | [Writing queries](docs/sql.md)                             | Parameters, reusable functions, joins, aggregates, pagination, and fragments |
 | [Writing data](docs/mutations.md)                          | Inserts, patches, defaults, upserts, JSON, arrays, and batches               |
 | [Schema types and values](docs/schema-types.md)            | Generation, read/write types, codecs, and domain validation                  |

package/dist/check.js

@@ -17,7 +17,10 @@ export async function checkQueries(options) {
         if (!['connection', 'target', 'project', 'session', 'timeouts', 'codecs', 'readTypes'].includes(name))
             throw new Error(`Unknown check option: ${name}`);
     }
-    const project = loadProject(options);
+    const codecs = options.codecs ??
+        (typeof options.connection === 'object' ? options.connection?.codecs : undefined) ??
+        defaultCodecs;
+    const project = loadProject({ ...options, codecs });
     const libraries = librarySymbols(project);
     const diagnostics = [...project.diagnostics];
     const queries = project.selected.flatMap((source) => new SourceAnalysis(project, libraries).discover(source));
@@ -52,7 +55,6 @@ export async function checkQueries(options) {
         return { query, variants, diagnostics: analysis.issues };
     });
     const reports = [];
-    const codecs = options.codecs ?? defaultCodecs;
     const readTypes = { ...options.readTypes };
     for (const oid of Object.keys(readTypes)) {
         if (codecs.typescript(Number(oid)) !== undefined)

package/dist/cli.js

@@ -1,20 +1,34 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { defaultCodecs } from '@kequtech/pgclear';
 import { adoptBaseline, captureBaseline } from './baseline.js';
-import { describeFlags, inspectionSettings, runDescribe } from './inspection/cli.js';
+import { describeFlags, inspectionSettings } from './inspection/cli.js';
+import { loadConfig } from './config/load.js';
+import { initConfig } from './config/init.js';
+import { configConnection } from './config/connection.js';
+import { generateDefinitions } from './generate.js';
+import { writeDefinitions } from './generation/output.js';
+import { validatePath } from './validation.js';
+import { describeQuery } from './describe.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
-const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
+const help = `tenon init [--config path] (create config without a database)
+tenon migrate|status|rollback [--directory migrations] [--namespace public]
 tenon baseline capture|adopt [--directory migrations] [--namespace public]
-baseline capture: [--schema name ...] (default: whole database schema)
+baseline capture: [--schema name ...] [--connection native-uri] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
+tenon generate [--out path] [--namespace public] [--check] [--config path]
 tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
+generate/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
 describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 describe emits JSON metadata; it does not execute the query or verify result annotations.
 check compares source contracts; mismatches, unchecked sites and no sites fail. Unproven types are notes.
 rollback: --steps 1
-Connection: DATABASE_URL
+All commands accept --config path. Database commands accept --database <export> to select a named config.
+Multiple database exports require --database. Migration commands fall back to DATABASE_URL only without config.
 `;
 function warn(message) {
     process.stderr.write(`Warning: ${message}\n`);
@@ -22,7 +36,14 @@ function warn(message) {
 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 });
+        if (typeof options.connection !== 'string') {
+            throw new Error('Baseline capture needs a native libpq URI. Pass --connection or use a string config connection.');
+        }
+        const result = await captureBaseline({
+            ...options,
+            connection: options.connection,
+            onWarning: warn,
+        });
         process.stdout.write(`Captured ${result.upPath}. Source history and data were not changed. Commit this file and generated definitions.\n`);
     }
     else {
@@ -36,8 +57,13 @@ async function main() {
         allowPositionals: true,
         tokens: true,
         options: {
-            directory: { type: 'string', default: 'migrations' },
-            namespace: { type: 'string', default: 'public' },
+            directory: { type: 'string' },
+            connection: { type: 'string' },
+            namespace: { type: 'string' },
+            config: { type: 'string' },
+            database: { type: 'string' },
+            out: { type: 'string' },
+            check: { type: 'boolean', default: false },
             schema: { type: 'string', multiple: true },
             steps: { type: 'string', default: '1' },
             help: { type: 'boolean', default: false },
@@ -51,22 +77,31 @@ async function main() {
         return;
     }
     const [command, argument] = positionals;
-    if (command === 'generate') {
-        throw new Error('The generate command has been removed. Use db.generateTypes({ out, namespace?, check? }) in an application script so generation uses your configured codecs.');
+    for (const name of ['out', 'directory', 'project']) {
+        if (values[name] !== undefined)
+            validatePath(values[name], `--${name}`);
     }
     // 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 !== 'describe' && command !== 'check')
+    if (!['describe', 'check', 'generate', 'init'].includes(command ?? ''))
         allowed.add('directory');
-    if (command !== 'new' && command !== 'describe' && command !== 'check') {
+    if (!['new', 'describe', 'check', 'init'].includes(command ?? '')) {
         allowed.add('namespace');
     }
     if (command === 'rollback') {
         allowed.add('steps');
     }
+    if (command === 'generate') {
+        allowed.add('out');
+        allowed.add('check');
+    }
+    allowed.add('config');
+    if (command !== 'init')
+        allowed.add('database');
     if (command === 'baseline' && argument === 'capture') {
         allowed.add('schema');
+        allowed.add('connection');
     }
     if (command === 'check') {
         allowed.add('project');
@@ -81,11 +116,22 @@ async function main() {
             throw new Error(`--${token.name} is not supported by ${command ?? 'this command'}.`);
         }
     }
+    if (command === 'init') {
+        if (positionals.length !== 1)
+            throw new Error('Use init [--config path] to create configuration.');
+        const path = await initConfig(values.config);
+        process.stdout.write(`Created ${path}\nSet DATABASE_URL before running database commands.\n`);
+        return;
+    }
     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 });
+        const config = await loadConfig(values.config, values.database, false);
+        const files = await createMigration({
+            name: argument,
+            directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
+        });
         process.stdout.write(`Created ${files.upPath}\nCreated ${files.downPath}\n`);
         return;
     }
@@ -94,25 +140,44 @@ async function main() {
         ? positionals.length <= 2
         : baseline || command === 'describe'
             ? positionals.length === 2
-            : positionals.length === 1 && ['migrate', 'status', 'rollback'].includes(command ?? '');
+            : positionals.length === 1 &&
+                ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose new, baseline capture|adopt, migrate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
-    }
-    const connection = process.env.DATABASE_URL;
-    if (!connection) {
-        throw new Error('DATABASE_URL is required.');
-    }
-    if (command === 'describe') {
-        await runDescribe(argument, connection, values);
-        return;
-    }
-    if (command === 'check') {
+        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
+    }
+    if (command === 'generate' || command === 'check' || command === 'describe') {
+        const config = await loadConfig(values.config, values.database);
+        if (command === 'generate') {
+            const out = values.out === undefined ? config.generate?.out : resolve(values.out);
+            if (out === undefined)
+                throw new Error('Configure generate.out or pass --out.');
+            const namespace = values.namespace ?? config.generate?.namespace ?? config.migrations?.namespace;
+            const source = await generateDefinitions({
+                connection: configConnection(config.connection),
+                onWarning: warn,
+                ...(namespace !== undefined && { namespace }),
+            });
+            await writeDefinitions(source, out, values.check);
+            process.stdout.write(values.check ? 'Generated definitions are current.\n' : `Generated ${out}\n`);
+            return;
+        }
+        const flags = inspectionSettings(values);
+        const settings = {
+            connection: configConnection(config.connection),
+            session: { ...config.session, ...flags.session },
+            timeouts: { ...config.timeouts, ...flags.timeouts },
+        };
+        if (command === 'describe') {
+            const result = await describeQuery({ ...settings, query: await readFile(argument, 'utf8') });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
         const { checkQueries } = await import('./check.js');
         const report = await checkQueries({
-            connection,
+            ...settings,
+            ...config.check,
             ...(argument === undefined ? {} : { target: argument }),
             ...(values.project === undefined ? {} : { project: values.project }),
-            ...inspectionSettings(values),
         });
         if (values.json)
             process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -125,11 +190,24 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    const options = { connection, directory: values.directory, namespace: values.namespace };
+    const config = await loadConfig(values.config, values.database, false);
+    const capture = command === 'baseline' && argument === 'capture';
+    const connection = values.connection ??
+        (capture ? config?.baseline?.connection : undefined) ??
+        (config === undefined ? undefined : configConnection(config.connection)) ??
+        process.env.DATABASE_URL;
+    if (!connection)
+        throw new Error('DATABASE_URL is required.');
+    const options = {
+        connection: typeof connection === 'string' ? connection : { ...connection, codecs: defaultCodecs },
+        directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
+        namespace: values.namespace ?? config?.migrations?.namespace ?? 'public',
+    };
     if (baseline) {
+        const schemas = values.schema ?? (capture ? config?.baseline?.schemas : undefined);
         await runBaseline(argument, {
             ...options,
-            ...(values.schema ? { schemas: values.schema } : {}),
+            ...(schemas !== undefined && { schemas }),
         });
         return;
     }

package/dist/config/connection.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectionOptions } from '../connection.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export declare function configConnection(value: unknown): string | ConnectionOptions;

package/dist/config/connection.js

@@ -0,0 +1,22 @@
+import { plainObject } from '../validation.js';
+/** Resolve only when a command or application actually needs its configured database. */
+export function configConnection(value) {
+    if (value === undefined) {
+        throw new Error('Tenon config connection is required. Check its database environment variables.');
+    }
+    if (typeof value === 'string') {
+        if (!value.trim())
+            throw new Error('Tenon config connection string must be nonempty.');
+        return value;
+    }
+    if (value !== null && typeof value === 'object' && ('acquire' in value || 'close' in value)) {
+        throw new Error('Tenon config requires connection options, not an open pool.');
+    }
+    const connection = plainObject(value, 'Tenon config connection');
+    // An explicitly configured URI must never silently fall back to the driver's local defaults.
+    if ('connectionString' in connection &&
+        (typeof connection.connectionString !== 'string' || !connection.connectionString.trim())) {
+        throw new Error('Tenon config connectionString must be nonempty. Check its database environment variables.');
+    }
+    return connection;
+}

package/dist/config/init.d.ts

@@ -0,0 +1,2 @@
+/** Scaffold one value-only config, without importing existing application code or opening a pool. */
+export declare function initConfig(filename?: string): Promise<string>;

package/dist/config/init.js

@@ -0,0 +1,31 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { validatePath } from '../validation.js';
+import { configNames, findConfig } from './load.js';
+/** Scaffold one value-only config, without importing existing application code or opening a pool. */
+export async function initConfig(filename) {
+    if (filename !== undefined)
+        validatePath(filename, 'Config filename');
+    const output = resolve(filename ?? 'tenon.config.ts');
+    const extension = extname(output);
+    if (!['.ts', '.mts', '.js', '.mjs'].includes(extension)) {
+        throw new Error('Config filename must end in .ts, .mts, .js, or .mjs.');
+    }
+    if (filename === undefined || configNames.includes(basename(output))) {
+        const existing = await findConfig(dirname(output));
+        if (existing && (filename === undefined || dirname(existing) === dirname(output))) {
+            throw new Error(`Tenon configuration already exists: ${existing}. Use or edit that file.`);
+        }
+    }
+    const typed = extension === '.ts' || extension === '.mts';
+    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}export const main = {
+  connection: { connectionString: process.env.DATABASE_URL },
+  migrations: { directory: 'migrations', namespace: 'public' },
+  generate: { out: 'src/generated-schema.d.ts' },
+  check: { project: 'tsconfig.json' },
+}${typed ? ' satisfies TenonConfig' : ''};
+`;
+    await mkdir(dirname(output), { recursive: true });
+    await writeFile(output, source, { encoding: 'utf8', flag: 'wx' });
+    return output;
+}

package/dist/config/load.d.ts

@@ -0,0 +1,7 @@
+import type { TenonConfig } from '../config.js';
+export declare const configNames: string[];
+/** Find configuration without importing it, including for offline initialization. */
+export declare function findConfig(directory?: string): Promise<string | undefined>;
+/** Import only the selected trusted configuration module; never discover application entry points. */
+export declare function loadConfig(filename?: string, database?: string): Promise<TenonConfig>;
+export declare function loadConfig(filename: string | undefined, database: string | undefined, required: false): Promise<TenonConfig | undefined>;

package/dist/config/load.js

@@ -0,0 +1,152 @@
+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';
+import { configObject, configSection } from './validate.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 selectDatabase(exports, database) {
+    const names = Object.keys(exports).filter((name) => {
+        const value = exports[name];
+        return (name === 'default' || (value !== null && typeof value === 'object' && 'connection' in value));
+    });
+    if (database !== undefined && !names.includes(database)) {
+        throw new Error(`Unknown database export: ${database}. Available: ${names.join(', ') || 'none'}.`);
+    }
+    if (database === undefined && names.length !== 1) {
+        throw new Error(names.length
+            ? `Multiple databases exported: ${names.join(', ')}. Select one with --database.`
+            : 'No database configurations exported. Export a Tenon config with a connection field.');
+    }
+    return exports[database ?? names[0]];
+}
+/** 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, database, required = true) {
+    if (filename !== undefined)
+        validatePath(filename, 'Config filename');
+    if (database !== undefined && (!database.trim() || database.includes('\0'))) {
+        throw new Error('--database must be a nonempty export name without NUL.');
+    }
+    const selected = filename === undefined ? await findConfig() : resolve(filename);
+    if (!selected && !required && database === undefined)
+        return undefined;
+    if (!selected)
+        throw new Error('Tenon configuration is required. Run tenon init or pass --config.');
+    let exports;
+    try {
+        exports = await import(pathToFileURL(selected).href);
+    }
+    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 = configObject(selectDatabase(exports, database));
+    const root = dirname(selected);
+    const migrations = configSection(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 = configSection(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 = configSection(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 = configSection(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,
+        ...(config.onQuery !== undefined && {
+            onQuery: config.onQuery,
+        }),
+        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/validate.d.ts

@@ -0,0 +1,3 @@
+export declare function configSection(value: unknown, label: string, allowed: readonly string[]): Record<string, unknown>;
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export declare function configObject(value: unknown): Record<string, unknown>;

package/dist/config/validate.js

@@ -0,0 +1,28 @@
+import { plainObject } from '../validation.js';
+export function configSection(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;
+}
+/** Check the shared shape without resolving credentials or constructing a pool. */
+export function configObject(value) {
+    const config = configSection(value, 'Tenon config', [
+        'connection',
+        'onQuery',
+        'generate',
+        'migrations',
+        'baseline',
+        'check',
+        'session',
+        'timeouts',
+    ]);
+    if (!('connection' in config))
+        throw new Error('Tenon config must declare connection.');
+    if (config.onQuery !== undefined && typeof config.onQuery !== 'function') {
+        throw new Error('Tenon config onQuery must be a function.');
+    }
+    return config;
+}

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+import type { Pool } from '@kequtech/pgclear';
+import type { ConnectionConfig } from './connection.js';
+import type { QueryEvent } from './types.js';
+import type { InspectionSession, InspectionTimeouts } from './inspection/types.js';
+/** Shared runtime connection values and CLI defaults. Export without opening a database. */
+export interface TenonConfig {
+    /** Environment values may be absent during builds; database use validates them. */
+    readonly connection: ConnectionConfig | Pool | undefined;
+    /** Observe runtime queries; native driver calls and CLI tooling do not invoke this callback. */
+    readonly onQuery?: (event: QueryEvent) => void | Promise<void>;
+    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 | undefined;
+        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,9 +1,17 @@
 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 | (Omit<ConnectionOptions, 'connectionString'> & {
+    /** May be absent during builds; operations reject an explicitly missing URI. */
+    readonly connectionString?: string | undefined;
+    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>;
+export declare function isPool(connection: unknown): connection is Pool;
 /** Constructed pools are owned; supplied public pgclear pools remain application-owned. */
 export declare function createConnection(connection: Connection): {
     pool: Pool;

package/dist/connection.js

@@ -1,6 +1,6 @@
 import { createPool, } from '@kequtech/pgclear';
 import { plainObject } from './validation.js';
-function isPool(connection) {
+export function isPool(connection) {
     return (connection !== null &&
         typeof connection === 'object' &&
         'acquire' in connection &&

package/dist/database.d.ts

@@ -1,7 +1,3 @@
-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;
+import type { TenonConfig } from './config.js';
+import type { Database } from './types.js';
+export declare function createTenon(config: TenonConfig): Database;