@kequtech/tenon-orm 0.0.0-stage → 0.1.1

package/dist/safeql/composition.js

@@ -0,0 +1,159 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import ts from 'typescript';
+import { joinSeparator, quote } from '../sql.js';
+import { renderMutation } from './mutations.js';
+import { CompositionError, initializer, literalString, unwrap } from './static.js';
+export { CompositionError } from './static.js';
+/** Recognize Tenon's declarations without claiming another library's SQL tags. */
+const tenonModules = new Map();
+function isTenonModule(filename) {
+    const cached = tenonModules.get(filename);
+    if (cached !== undefined)
+        return cached;
+    let matches = false;
+    if (['query.ts', 'query.d.ts'].includes(basename(filename)) &&
+        ['src', 'dist'].includes(basename(dirname(filename)))) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dirname(filename), '..', 'package.json'), 'utf8'));
+            matches =
+                typeof manifest === 'object' &&
+                    manifest !== null &&
+                    'name' in manifest &&
+                    manifest.name === '@kequtech/tenon-orm';
+        }
+        catch {
+            // An unrelated or unavailable declaration is not a Tenon export.
+        }
+    }
+    tenonModules.set(filename, matches);
+    return matches;
+}
+export function isExport(node, checker, name) {
+    // Call signatures retain their declaration through local aliases, object properties,
+    // and typeof annotations. Symbol names alone only recognize direct imports.
+    return checker
+        .getTypeAtLocation(node)
+        .getCallSignatures()
+        .some((signature) => {
+        const declaration = signature.declaration;
+        return (declaration &&
+            ts.isFunctionDeclaration(declaration) &&
+            declaration.name?.text === (name === 'sql' ? 'createQuery' : name) &&
+            isTenonModule(declaration.getSourceFile().fileName));
+    });
+}
+export function isFragment(type) {
+    return type.isUnion()
+        ? type.types.some(isFragment)
+        : type.getProperty('__tenonFragment') !== undefined;
+}
+/** Reconstruct only immutable fragments and literal join lists. Never execute application code. */
+export function renderFragment(node, checker, seen = new Set()) {
+    node = unwrap(node);
+    if (seen.has(node))
+        throw new CompositionError('Circular fragment reference.');
+    const visited = new Set(seen).add(node);
+    if (ts.isIdentifier(node)) {
+        const value = initializer(node, checker);
+        if (value)
+            return renderFragment(value, checker, visited);
+    }
+    if (ts.isTaggedTemplateExpression(node) &&
+        ts.isPropertyAccessExpression(node.tag) &&
+        node.tag.name.text === 'fragment' &&
+        isExport(node.tag.expression, checker, 'sql')) {
+        const template = node.template;
+        if (ts.isNoSubstitutionTemplateLiteral(template))
+            return template.text;
+        let text = template.head.text;
+        for (const span of template.templateSpans) {
+            text += renderValue(span.expression, checker, visited) + span.literal.text;
+        }
+        return text;
+    }
+    if (ts.isCallExpression(node)) {
+        for (const kind of ['insertValues', 'assignments']) {
+            if (isExport(node.expression, checker, kind))
+                return renderMutation(kind, node, checker);
+        }
+    }
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === 'join' &&
+        isExport(node.expression.expression, checker, 'sql')) {
+        const [items, separator] = node.arguments;
+        const list = items && unwrap(items);
+        if (!list ||
+            !ts.isArrayLiteralExpression(list) ||
+            !list.elements.length ||
+            !separator ||
+            node.arguments.length !== 2) {
+            throw new CompositionError('sql.join needs a nonempty literal array and a separator for static checking.');
+        }
+        const value = literalString(separator, checker);
+        if (value === undefined) {
+            throw new CompositionError('sql.join separators must be literal strings or const strings.');
+        }
+        let between;
+        try {
+            between = joinSeparator(value);
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            throw new CompositionError(error.message);
+        }
+        return list.elements.map((item) => renderFragment(item, checker, visited)).join(between);
+    }
+    throw new CompositionError('Only constant sql.fragment templates, literal sql.join arrays, and official mutation helpers are supported. Function-generated fragments and conditional SQL structure are not analyzed.');
+}
+export function renderIdentifier(node, checker, seen = new Set()) {
+    node = unwrap(node);
+    if (seen.has(node))
+        throw new CompositionError('Circular identifier reference.');
+    const visited = new Set(seen).add(node);
+    if (ts.isIdentifier(node)) {
+        const value = initializer(node, checker);
+        if (value)
+            return renderIdentifier(value, checker, visited);
+    }
+    if (ts.isCallExpression(node) &&
+        isExport(node.expression, checker, 'identifier') &&
+        node.arguments.length) {
+        return node.arguments
+            .map((part) => {
+            const value = literalString(part, checker);
+            if (value === undefined) {
+                throw new CompositionError('Identifier names must be literal strings or const strings.');
+            }
+            try {
+                return quote(value);
+            }
+            catch (error) {
+                if (!(error instanceof Error))
+                    throw error;
+                throw new CompositionError(error.message);
+            }
+        })
+            .join('.');
+    }
+    throw new CompositionError('The identifier is selected at runtime.');
+}
+export function isIdentifierType(type) {
+    if (type.isUnion())
+        return type.types.some(isIdentifierType);
+    const symbol = type.getSymbol();
+    return (symbol?.getName() === 'Identifier' &&
+        Boolean(symbol.declarations?.some((declaration) => isTenonModule(declaration.getSourceFile().fileName))));
+}
+export function renderValue(node, checker, seen = new Set()) {
+    const type = checker.getTypeAtLocation(node);
+    if (isFragment(type))
+        return renderFragment(node, checker, seen);
+    if (isIdentifierType(type))
+        return renderIdentifier(node, checker, seen);
+    // Match runtime SQL: PostgreSQL infers parameter types from SQL context, never
+    // from JavaScript types. SafeQL numbers these tokens, respecting quotes/comments.
+    return '$N';
+}

package/dist/safeql/eslint.d.ts

@@ -0,0 +1,2 @@
+import type { ESLint } from 'eslint';
+export declare const eslintPlugin: ESLint.Plugin;

package/dist/safeql/eslint.js

@@ -0,0 +1,45 @@
+import ts from 'typescript';
+import { CompositionError, isExport, renderValue } from './composition.js';
+export const eslintPlugin = {
+    rules: {
+        'check-composition': {
+            meta: {
+                type: 'problem',
+                docs: { description: 'Report Tenon queries that cannot be statically checked.' },
+                schema: [],
+            },
+            create(context) {
+                // ESLint leaves parser services untyped; require the TypeScript parser's public services.
+                const { program, esTreeNodeToTSNodeMap: nodes } = context.sourceCode.parserServices;
+                if (!program || !nodes) {
+                    throw new Error('tenon/check-composition requires type-aware TypeScript parsing. Enable parserOptions.project or projectService.');
+                }
+                const checker = program.getTypeChecker();
+                return {
+                    TaggedTemplateExpression(node) {
+                        const template = nodes.get(node);
+                        if (!template ||
+                            !ts.isTaggedTemplateExpression(template) ||
+                            !isExport(template.tag, checker, 'sql'))
+                            return;
+                        try {
+                            if (node.quasi.quasis.some(({ value }) => value.raw !== value.cooked)) {
+                                throw new CompositionError('JavaScript escapes in an outer sql template would be checked as different SQL. Use literal newlines and bound string values instead.');
+                            }
+                            if (ts.isTemplateExpression(template.template)) {
+                                for (const span of template.template.templateSpans) {
+                                    renderValue(span.expression, checker);
+                                }
+                            }
+                        }
+                        catch (error) {
+                            if (!(error instanceof CompositionError))
+                                throw error;
+                            context.report({ node, message: error.message });
+                        }
+                    },
+                };
+            },
+        },
+    },
+};

package/dist/safeql/mutations.d.ts

@@ -0,0 +1,3 @@
+import ts from 'typescript';
+/** Understand the official mutation contract, never the implementation of a JavaScript helper. */
+export declare function renderMutation(kind: 'insertValues' | 'assignments', node: ts.CallExpression, checker: ts.TypeChecker): string;

package/dist/safeql/mutations.js

@@ -0,0 +1,74 @@
+import ts from 'typescript';
+import { assignmentLayout, insertLayout, mutationColumns } from '../mutations.js';
+import { CompositionError, isUndefined, literalString, unwrap } from './static.js';
+const parameter = 0;
+function fields(input) {
+    const node = unwrap(input);
+    if (!ts.isObjectLiteralExpression(node)) {
+        throw new CompositionError('Mutation inputs need inline object literals or an explicit literal column list.');
+    }
+    const result = new Map();
+    for (const property of node.properties) {
+        if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
+            throw new CompositionError('Mutation object spreads, accessors, and methods need an explicit literal column list.');
+        }
+        const name = property.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name) && !ts.isNumericLiteral(name)) {
+            throw new CompositionError('Mutation keys must be literal names; use an explicit literal column list.');
+        }
+        if (name.text === '__proto__')
+            throw new CompositionError('Prototype-setting object literals are unsupported mutation inputs.');
+        if (result.has(name.text))
+            throw new CompositionError('Duplicate mutation object keys are unsupported.');
+        result.set(name.text, ts.isPropertyAssignment(property) ? property.initializer : property.name);
+    }
+    return result;
+}
+/** Understand the official mutation contract, never the implementation of a JavaScript helper. */
+export function renderMutation(kind, node, checker) {
+    if (node.questionDotToken ||
+        node.arguments.some(ts.isSpreadElement) ||
+        node.arguments.length < 1 ||
+        node.arguments.length > 2) {
+        throw new CompositionError(`sql.${kind} requires an input and an optional literal column list.`);
+    }
+    try {
+        const [argument, selected] = node.arguments;
+        let columns;
+        let rows;
+        if (selected && !isUndefined(selected, checker)) {
+            const list = unwrap(selected);
+            if (!ts.isArrayLiteralExpression(list))
+                throw new CompositionError('Mutation columns must be an inline literal array.');
+            columns = mutationColumns(list.elements.map((item) => {
+                const column = literalString(item, checker);
+                if (column === undefined)
+                    throw new CompositionError('Mutation columns must be literal strings or const strings.');
+                return column;
+            }));
+            // A fixed column contract covers any nonempty batch and every omitted/default cell.
+            // Check all selected columns conservatively; no runtime data or JS types become SQL.
+            rows = [columns.map(() => parameter)];
+        }
+        else {
+            const value = unwrap(argument);
+            const objects = kind === 'insertValues' && ts.isArrayLiteralExpression(value)
+                ? value.elements.map(fields)
+                : [fields(value)];
+            columns = [
+                ...new Set(objects.flatMap((row) => [...row].filter(([, value]) => !isUndefined(value, checker)).map(([key]) => key))),
+            ];
+            rows = objects.map((row) => columns.map((column) => {
+                const cell = row.get(column);
+                return !cell || isUndefined(cell, checker) ? undefined : parameter;
+            }));
+        }
+        const parts = kind === 'insertValues' ? insertLayout(columns, rows) : assignmentLayout(columns, rows[0]);
+        return parts.map((part) => (typeof part === 'string' ? part : '$N')).join('');
+    }
+    catch (error) {
+        if (!(error instanceof Error))
+            throw error;
+        throw new CompositionError(`sql.${kind}: ${error instanceof CompositionError ? error.detail : error.message}`);
+    }
+}

package/dist/safeql/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { SafeQLPlugin } from '@ts-safeql/plugin-utils';
+/** Loaded through the exported SafeQL plugin descriptor. */
+export declare function factory(): SafeQLPlugin;

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/static.d.ts

@@ -0,0 +1,10 @@
+import ts from 'typescript';
+export declare class CompositionError extends Error {
+    readonly detail: string;
+    readonly name = "TenonCompositionError";
+    constructor(detail: string);
+}
+export declare function unwrap(node: ts.Node): ts.Node;
+export declare function initializer(node: ts.Identifier, checker: ts.TypeChecker): ts.Expression | undefined;
+export declare function literalString(node: ts.Node, checker: ts.TypeChecker): string | undefined;
+export declare function isUndefined(node: ts.Node, checker: ts.TypeChecker): boolean;

package/dist/safeql/static.js

@@ -0,0 +1,59 @@
+import ts from 'typescript';
+export class CompositionError extends Error {
+    detail;
+    name = 'TenonCompositionError';
+    constructor(detail) {
+        super(`Tenon cannot statically check this composition: ${detail} Use a static query/fragment, or an explicit lint suppression with database tests for every runtime variant.`);
+        this.detail = detail;
+    }
+}
+export function unwrap(node) {
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+        node = node.expression;
+    return node;
+}
+export function initializer(node, checker) {
+    let symbol = checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias)
+        symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    return declaration &&
+        ts.isVariableDeclaration(declaration) &&
+        ts.isVariableDeclarationList(declaration.parent) &&
+        declaration.parent.flags & ts.NodeFlags.Const
+        ? declaration.initializer
+        : undefined;
+}
+/** Follow immutable const aliases only. Never inspect functions or evaluate expressions. */
+function constant(node, checker) {
+    const seen = new Set();
+    node = unwrap(node);
+    while (ts.isIdentifier(node)) {
+        if (seen.has(node))
+            throw new CompositionError('Circular const reference.');
+        if (seen.size >= 1000)
+            throw new CompositionError('Const resolution exceeds 1000 references.');
+        seen.add(node);
+        const value = initializer(node, checker);
+        if (!value)
+            break;
+        node = unwrap(value);
+    }
+    return node;
+}
+export function literalString(node, checker) {
+    const value = constant(node, checker);
+    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+        ? value.text
+        : undefined;
+}
+export function isUndefined(node, checker) {
+    const value = constant(node, checker);
+    return (ts.isIdentifier(value) &&
+        value.text === 'undefined' &&
+        !checker.getSymbolAtLocation(value)?.declarations?.length);
+}

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;
+}