@kequtech/tenon-orm 0.0.0-stage → 0.1.1

package/dist/migrations/history.js

@@ -0,0 +1,30 @@
+import { qualified } from '../sql.js';
+export const migrationTable = '__tenon_migrations';
+export async function migrationState(client, namespace, migrations) {
+    const exists = await client.query('SELECT to_regclass($1)::text AS name', [qualified(namespace, migrationTable)]);
+    if (exists.rows[0].name === null) {
+        return [];
+    }
+    const { rows: applied } = await client.query(`SELECT id, name, checksum FROM ${qualified(namespace, migrationTable)} ORDER BY id::numeric`);
+    for (const [i, record] of applied.entries()) {
+        const file = migrations[i];
+        if (!file ||
+            file.id !== record.id ||
+            file.name !== record.name ||
+            file.checksum !== record.checksum) {
+            throw new Error(`Migration history differs from files at version ${record.id}; restore applied files before continuing.`);
+        }
+    }
+    return applied;
+}
+export async function createHistoryTable(client, namespace) {
+    await client.query(`CREATE TABLE IF NOT EXISTS ${qualified(namespace, migrationTable)} (
+      id TEXT PRIMARY KEY CHECK (id ~ '^[0-9]+$'),
+      name TEXT NOT NULL,
+      checksum TEXT NOT NULL,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`);
+}
+export async function recordMigration(client, namespace, migration) {
+    await client.query(`INSERT INTO ${qualified(namespace, migrationTable)} (id, name, checksum) VALUES ($1, $2, $3)`, [migration.id, migration.name, migration.checksum]);
+}

package/dist/migrations/sql.d.ts

@@ -0,0 +1,2 @@
+/** Find statement starts without splitting quoted strings, DO bodies or comments. */
+export declare function validateMigrationSql(sql: string, filename: string): void;

package/dist/migrations/sql.js

@@ -0,0 +1,94 @@
+/** Find statement starts without splitting quoted strings, DO bodies or comments. */
+export function validateMigrationSql(sql, filename) {
+    let statement = '';
+    let quote;
+    let commentDepth = 0;
+    let lineComment = false;
+    let escapeString = false;
+    function check() {
+        const words = statement.trim().replace(/\s+/g, ' ').toUpperCase();
+        if (/^(BEGIN|COMMIT|END|ROLLBACK|ABORT|SAVEPOINT|RELEASE)\b|^START TRANSACTION\b|^PREPARE TRANSACTION\b/.test(words)) {
+            throw new Error(`Migration ${filename} must not contain transaction-control statements; Tenon owns the transaction.`);
+        }
+        statement = '';
+    }
+    for (let i = 0; i < sql.length; i++) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (lineComment) {
+            if (ch === '\n' || ch === '\r') {
+                lineComment = false;
+                statement += ' ';
+            }
+            continue;
+        }
+        if (commentDepth) {
+            if (ch === '/' && next === '*') {
+                commentDepth++;
+                i++;
+            }
+            else if (ch === '*' && next === '/') {
+                commentDepth--;
+                i++;
+                statement += ' ';
+            }
+            continue;
+        }
+        if (quote) {
+            if (quote.startsWith('$')) {
+                if (sql.startsWith(quote, i)) {
+                    i += quote.length - 1;
+                    quote = undefined;
+                }
+            }
+            else if (escapeString && ch === '\\') {
+                i++;
+            }
+            else if (ch === quote) {
+                if (next === quote) {
+                    i++;
+                }
+                else {
+                    quote = undefined;
+                }
+            }
+            continue;
+        }
+        if (ch === '-' && next === '-') {
+            lineComment = true;
+            i++;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            commentDepth = 1;
+            i++;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            escapeString = ch === "'" && /(?:^|\W)[eE]$/.test(sql.slice(0, i));
+            quote = ch;
+            statement += ' quoted ';
+            continue;
+        }
+        // A dollar inside an unquoted identifier is not the start of a SQL body.
+        if (ch === '$' && (i === 0 || !/[A-Za-z_0-9$\u0080-\uFFFF]/.test(sql[i - 1]))) {
+            const match = /^\$(?:[A-Za-z_][A-Za-z_0-9]*)?\$/.exec(sql.slice(i));
+            if (match) {
+                quote = match[0];
+                i += quote.length - 1;
+                statement += ' body ';
+                continue;
+            }
+        }
+        if (ch === ';') {
+            check();
+        }
+        else {
+            statement += ch;
+        }
+    }
+    if (quote || commentDepth) {
+        throw new Error(`Unterminated SQL string or comment in migration ${filename}.`);
+    }
+    check();
+}

package/dist/migrations.d.ts

@@ -0,0 +1,10 @@
+import type { DatabaseToolOptions } from './migrations/connection.js';
+export interface MigrationStatus {
+    readonly applied: readonly string[];
+    readonly pending: readonly string[];
+}
+export declare function migrationStatus(options: DatabaseToolOptions): Promise<MigrationStatus>;
+export declare function migrate(options: DatabaseToolOptions): Promise<readonly string[]>;
+export declare function rollback(options: DatabaseToolOptions & {
+    readonly steps?: number;
+}): Promise<readonly string[]>;

package/dist/migrations.js

@@ -0,0 +1,68 @@
+import { withMigrationLock } from './migrations/connection.js';
+import { readMigrations } from './migrations/files.js';
+import { createHistoryTable, migrationState, migrationTable, recordMigration, } from './migrations/history.js';
+import { qualified, quote } from './sql.js';
+export async function migrationStatus(options) {
+    const files = await readMigrations(options.directory);
+    return withMigrationLock(options, 'shared', async (client, namespace) => {
+        const applied = await migrationState(client, namespace, files);
+        return {
+            applied: applied.map((m) => m.id),
+            pending: files.slice(applied.length).map((m) => m.id),
+        };
+    });
+}
+async function execute(options, direction, steps) {
+    if (!Number.isSafeInteger(steps) || steps < 1) {
+        throw new Error('Rollback steps must be a positive safe integer.');
+    }
+    const files = await readMigrations(options.directory);
+    return withMigrationLock(options, 'exclusive', async (client, namespace) => {
+        const applied = await migrationState(client, namespace, files);
+        const selected = direction === 'up'
+            ? files.slice(applied.length)
+            : files.slice(Math.max(0, applied.length - steps), applied.length).reverse();
+        if (direction === 'down' && selected.some((file) => file.down === undefined)) {
+            throw new Error('A selected migration has no down SQL and cannot be rolled back.');
+        }
+        if (!selected.length) {
+            return [];
+        }
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${quote(namespace)}`);
+        await createHistoryTable(client, namespace);
+        const completed = [];
+        for (const file of selected) {
+            try {
+                await client.query('BEGIN');
+                // Match the string-literal rules used by the authored migration scanner.
+                await client.query('SET LOCAL standard_conforming_strings TO on');
+                await client.query(`SET LOCAL search_path TO ${quote(namespace)}, pg_catalog`);
+                await client.query(direction === 'up' ? file.up : file.down);
+                if (direction === 'up') {
+                    await recordMigration(client, namespace, file);
+                }
+                else {
+                    await client.query(`DELETE FROM ${qualified(namespace, migrationTable)} WHERE id = $1`, [
+                        file.id,
+                    ]);
+                }
+                const result = await client.query('COMMIT');
+                if (result.command !== 'COMMIT') {
+                    throw new Error('The migration transaction was rolled back.');
+                }
+                completed.push(file.id);
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : 'Unknown database error';
+                throw new Error(`Migration ${file.id}_${file.name} (${direction}) failed: ${reason}. Earlier migrations in this run may have committed.`, { cause });
+            }
+        }
+        return completed;
+    });
+}
+export function migrate(options) {
+    return execute(options, 'up', 1);
+}
+export function rollback(options) {
+    return execute(options, 'down', options.steps ?? 1);
+}

package/dist/mutations.d.ts

@@ -0,0 +1,11 @@
+export type MutationPart = string | Readonly<{
+    value: unknown;
+}>;
+export type MutationColumns<Row> = Row extends object ? Extract<keyof Row, string> : never;
+/** Validate and quote one explicit column list, shared by runtime and SQL checking. */
+export declare function mutationColumns(columns: readonly string[]): string[];
+/** SQL structure depends only on these columns and cells, never on JavaScript source. */
+export declare function insertLayout(columns: readonly string[], rows: readonly (readonly unknown[])[]): MutationPart[];
+export declare function assignmentLayout(columns: readonly string[], values: readonly unknown[]): MutationPart[];
+export declare function insertParts(input: object | readonly object[], selected?: readonly string[]): MutationPart[];
+export declare function assignmentParts(input: object, selected?: readonly string[]): MutationPart[];

package/dist/mutations.js

@@ -0,0 +1,87 @@
+import { quote } from './sql.js';
+import { plainObject } from './validation.js';
+/** Validate and quote one explicit column list, shared by runtime and SQL checking. */
+export function mutationColumns(columns) {
+    if (!Array.isArray(columns) || !columns.length)
+        throw new Error('Mutation columns must be a nonempty array.');
+    const seen = new Set();
+    return Array.from(columns, (column) => {
+        if (typeof column !== 'string')
+            throw new Error('Mutation column names must be strings.');
+        quote(column);
+        if (seen.has(column))
+            throw new Error(`Duplicate mutation column ${JSON.stringify(column)}.`);
+        seen.add(column);
+        return column;
+    });
+}
+/** SQL structure depends only on these columns and cells, never on JavaScript source. */
+export function insertLayout(columns, rows) {
+    if (!rows.length)
+        throw new Error('sql.insertValues requires at least one row.');
+    if (!columns.length) {
+        if (rows.length !== 1)
+            throw new Error('Default-only inserts require exactly one row.');
+        return ['DEFAULT VALUES'];
+    }
+    const parts = [`(${columns.map(quote).join(', ')}) VALUES `];
+    for (const [index, row] of rows.entries()) {
+        if (index)
+            parts.push(', ');
+        parts.push('(');
+        for (const [column, value] of row.entries()) {
+            if (column)
+                parts.push(', ');
+            parts.push(value === undefined ? 'DEFAULT' : Object.freeze({ value }));
+        }
+        parts.push(')');
+    }
+    return parts;
+}
+export function assignmentLayout(columns, values) {
+    const parts = [];
+    for (const [index, column] of columns.entries()) {
+        const value = values[index];
+        if (value === undefined)
+            continue;
+        if (parts.length)
+            parts.push(', ');
+        parts.push(`${quote(column)} = `, Object.freeze({ value }));
+    }
+    if (!parts.length)
+        throw new Error('sql.assignments requires at least one defined field.');
+    return parts;
+}
+function record(value, helper, index) {
+    return plainObject(value, `${helper} row ${index + 1}`);
+}
+function cell(row, column, helper, index) {
+    const property = Object.getOwnPropertyDescriptor(row, column);
+    if (!property)
+        return undefined;
+    if (!('value' in property))
+        throw new Error(`${helper} row ${index + 1} column ${JSON.stringify(column)} must be a data property.`);
+    const value = property.value;
+    if (value &&
+        typeof value === 'object' &&
+        ['fragment', 'identifier', 'query'].some((kind) => Symbol.for(`@kequtech/tenon-orm/${kind}`) in value)) {
+        throw new Error(`${helper} row ${index + 1} column ${JSON.stringify(column)} expects a bound value; put SQL expressions in the surrounding statement.`);
+    }
+    return value;
+}
+export function insertParts(input, selected) {
+    const rows = Array.from(Array.isArray(input) ? input : [input], (row, index) => record(row, 'sql.insertValues', index));
+    if (!rows.length)
+        throw new Error('sql.insertValues requires at least one row.');
+    const columns = selected === undefined
+        ? [
+            ...new Set(rows.flatMap((row, index) => Object.keys(row).filter((column) => cell(row, column, 'sql.insertValues', index) !== undefined))),
+        ]
+        : mutationColumns(selected);
+    return insertLayout(columns, rows.map((row, index) => columns.map((column) => cell(row, column, 'sql.insertValues', index))));
+}
+export function assignmentParts(input, selected) {
+    const row = record(input, 'sql.assignments', 0);
+    const columns = selected === undefined ? Object.keys(row) : mutationColumns(selected);
+    return assignmentLayout(columns, columns.map((column) => cell(row, column, 'sql.assignments', 0)));
+}

package/dist/query-options.d.ts

@@ -0,0 +1,15 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { AffectedRowsConstraint } from './affected-rows.js';
+import type { UnknownRow } from './query.js';
+export type QueryReturnMode = 'native' | 'many' | 'oneOrNone' | 'one';
+export interface QueryOptions {
+    readonly returns?: QueryReturnMode;
+    readonly affectedRows?: AffectedRowsConstraint;
+    /** Optional diagnostic label. No SQL or input values are sent to observers. */
+    readonly label?: string;
+}
+export type QueryOutput<Row extends QueryResultRow, Mode extends QueryReturnMode> = Mode extends 'native' ? QueryResult<Row> : Mode extends 'many' ? Row[] : Mode extends 'oneOrNone' ? Row | undefined : Row;
+export declare function validateOptions(options?: QueryOptions): Readonly<QueryOptions & {
+    returns: QueryReturnMode;
+}>;
+export declare function queryOutput(options: QueryOptions, result: QueryResult<UnknownRow>): object | undefined;

package/dist/query-options.js

@@ -0,0 +1,35 @@
+import { validateAffectedRows } from './affected-rows.js';
+import { plainObject } from './validation.js';
+export function validateOptions(options) {
+    const config = options === undefined ? {} : plainObject(options, 'Query options');
+    for (const key of Object.keys(config)) {
+        if (!['returns', 'affectedRows', 'label'].includes(key))
+            throw new Error(`Unknown query option: ${key}`);
+    }
+    const returns = config.returns ?? 'native';
+    if (config.returns === null ||
+        !['native', 'many', 'oneOrNone', 'one'].includes(returns)) {
+        throw new Error('Query returns must be native, many, oneOrNone, or one.');
+    }
+    const affectedRows = validateAffectedRows(config.affectedRows);
+    const label = config.label;
+    if (label !== undefined && (typeof label !== 'string' || !label.trim())) {
+        throw new Error('Query label must be a nonempty string.');
+    }
+    return Object.freeze({
+        returns: returns,
+        ...(affectedRows && { affectedRows }),
+        ...(typeof label === 'string' && { label }),
+    });
+}
+export function queryOutput(options, result) {
+    if (options.returns === 'native')
+        return result;
+    if (options.returns === 'many')
+        return result.rows;
+    const expected = options.returns === 'oneOrNone' ? 'at most one row' : 'exactly one row';
+    if (result.rows.length > 1 || (options.returns === 'one' && result.rows.length === 0)) {
+        throw new Error(`${options.label ?? 'Query'} expected ${expected}, but returned ${result.rows.length} rows.`);
+    }
+    return result.rows[0];
+}

package/dist/query.d.ts

@@ -0,0 +1,38 @@
+import type { QueryResultRow } from 'pg';
+import { type MutationColumns } from './mutations.js';
+export type UnknownRow = Record<string, unknown>;
+/** A parameterized statement. The row type describes one returned record. */
+export interface SqlQuery<Row extends QueryResultRow = UnknownRow> {
+    readonly text: string;
+    readonly values: readonly unknown[];
+    /** Type-only field; a stable key preserves row inference across package copies. */
+    readonly __rowType?: Row;
+}
+interface Identifier {
+    readonly names: readonly string[];
+}
+/** Quote identifier components separately; ordinary interpolations always bind values. */
+export declare function identifier(...names: string[]): Identifier;
+/** A composable piece of SQL, not an executable query or a result-type declaration. */
+export interface SqlFragment {
+    /** Stable across separately installed copies; runtime identity uses a shared symbol. */
+    readonly __tenonFragment: true;
+}
+declare function fragment(strings: TemplateStringsArray, ...values: readonly unknown[]): SqlFragment;
+declare function join(fragments: readonly SqlFragment[], separator: 'AND' | 'OR' | ','): SqlFragment;
+/** Object fields become bound values; absent insert cells use PostgreSQL defaults. */
+declare function insertValues<Row extends object>(input: Row | readonly Row[], columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+/** Omit undefined fields; null remains a value. Empty assignments reject. */
+declare function assignments<Row extends object>(input: Row, columns?: readonly NoInfer<MutationColumns<Row>>[]): SqlFragment;
+declare function createQuery<Row extends QueryResultRow = UnknownRow>(strings: TemplateStringsArray, ...values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
+/** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
+export declare const sql: typeof createQuery & {
+    fragment: typeof fragment;
+    join: typeof join;
+    insertValues: typeof insertValues;
+    assignments: typeof assignments;
+};
+/** Escape hatch for externally authored SQL. Never concatenate application input into text. */
+export declare function unsafeSql<Row extends QueryResultRow = UnknownRow>(text: string, values: readonly unknown[]): NoInfer<SqlQuery<Row>>;
+export declare function assertQuery(value: unknown): asserts value is SqlQuery;
+export {};

package/dist/query.js

@@ -0,0 +1,129 @@
+import { joinSeparator, quote } from './sql.js';
+import { assignmentParts, insertParts, } from './mutations.js';
+// Shared symbols let separately installed copies exchange queries and identifiers.
+const queryTag = Symbol.for('@kequtech/tenon-orm/query');
+const identifierTag = Symbol.for('@kequtech/tenon-orm/identifier');
+/** Quote identifier components separately; ordinary interpolations always bind values. */
+export function identifier(...names) {
+    if (!names.length)
+        throw new Error('An identifier needs at least one name.');
+    names.forEach(quote);
+    return Object.freeze({ [identifierTag]: true, names: Object.freeze([...names]) });
+}
+const fragmentTag = Symbol.for('@kequtech/tenon-orm/fragment');
+function fragmentParts(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !(fragmentTag in value) ||
+        !Array.isArray(value[fragmentTag])) {
+        throw new Error('Expected a fragment created with sql.fragment or sql.join.');
+    }
+    return value[fragmentTag];
+}
+/** Preserve SQL text separately from parameters; never rewrite dollar placeholders. */
+function templateParts(strings, values) {
+    if (!Array.isArray(strings) ||
+        !Array.isArray(strings.raw) ||
+        strings.length !== values.length + 1 ||
+        strings.some((chunk) => typeof chunk !== 'string')) {
+        throw new Error('sql and sql.fragment must be used as template tags.');
+    }
+    const parts = [strings[0]];
+    for (const [i, value] of values.entries()) {
+        if (value && typeof value === 'object' && fragmentTag in value) {
+            for (const part of fragmentParts(value))
+                parts.push(part);
+        }
+        else if (value &&
+            typeof value === 'object' &&
+            identifierTag in value &&
+            value[identifierTag] === true) {
+            if (!('names' in value) || !Array.isArray(value.names) || !value.names.length) {
+                throw new Error('An identifier needs at least one name.');
+            }
+            parts.push(value.names.map(quote).join('.'));
+        }
+        else {
+            if (value && typeof value === 'object' && queryTag in value && value[queryTag] === true) {
+                throw new Error('Nested SQL queries are not supported; use sql.fragment for composition.');
+            }
+            parts.push(Object.freeze({ value }));
+        }
+        parts.push(strings[i + 1]);
+    }
+    return Object.freeze(parts);
+}
+function fragment(strings, ...values) {
+    const parts = templateParts(strings, values);
+    if (!parts.some((part) => typeof part !== 'string' || part.trim())) {
+        throw new Error('SQL fragments must not be empty.');
+    }
+    return Object.freeze({ __tenonFragment: true, [fragmentTag]: parts });
+}
+function join(fragments, separator) {
+    if (!Array.isArray(fragments) || !fragments.length) {
+        throw new Error('sql.join requires at least one fragment; handle an empty list explicitly.');
+    }
+    const between = joinSeparator(separator);
+    const parts = [];
+    for (const [i, item] of fragments.entries()) {
+        if (i)
+            parts.push(between);
+        for (const part of fragmentParts(item))
+            parts.push(part);
+    }
+    return Object.freeze({ __tenonFragment: true, [fragmentTag]: Object.freeze(parts) });
+}
+/** Object fields become bound values; absent insert cells use PostgreSQL defaults. */
+function insertValues(input, columns) {
+    return Object.freeze({
+        __tenonFragment: true,
+        [fragmentTag]: Object.freeze(insertParts(input, columns)),
+    });
+}
+/** Omit undefined fields; null remains a value. Empty assignments reject. */
+function assignments(input, columns) {
+    return Object.freeze({
+        __tenonFragment: true,
+        [fragmentTag]: Object.freeze(assignmentParts(input, columns)),
+    });
+}
+function createQuery(strings, ...values) {
+    const parameters = [];
+    let text = '';
+    for (const part of templateParts(strings, values)) {
+        if (typeof part === 'string') {
+            text += part;
+        }
+        else {
+            parameters.push(part.value);
+            text += '$' + parameters.length;
+        }
+    }
+    return unsafeSql(text, parameters);
+}
+/** Values bind parameters; identifiers quote names; fragments compose authored SQL. */
+export const sql = Object.assign(createQuery, { fragment, join, insertValues, assignments });
+/** Escape hatch for externally authored SQL. Never concatenate application input into text. */
+export function unsafeSql(text, values) {
+    if (typeof text !== 'string' || !text.trim())
+        throw new Error('SQL must be a nonempty string.');
+    if (!Array.isArray(values))
+        throw new Error('SQL input must be an explicit array.');
+    if (values.length > 65535)
+        throw new Error('A PostgreSQL query supports at most 65535 bound parameters; split large batches explicitly.');
+    return Object.freeze({ [queryTag]: true, text, values: Object.freeze([...values]) });
+}
+export function assertQuery(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !(queryTag in value) ||
+        value[queryTag] !== true ||
+        !('text' in value) ||
+        typeof value.text !== 'string' ||
+        !value.text.trim() ||
+        !('values' in value) ||
+        !Array.isArray(value.values)) {
+        throw new Error('Expected a query created with sql or unsafeSql.');
+    }
+}

package/dist/safeql/composition.d.ts

@@ -0,0 +1,9 @@
+import ts from 'typescript';
+export { CompositionError } from './static.js';
+export declare function isExport(node: ts.Node, checker: ts.TypeChecker, name: string): boolean;
+export declare function isFragment(type: ts.Type): boolean;
+/** Reconstruct only immutable fragments and literal join lists. Never execute application code. */
+export declare function renderFragment(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;
+export declare function renderIdentifier(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;
+export declare function isIdentifierType(type: ts.Type): boolean;
+export declare function renderValue(node: ts.Node, checker: ts.TypeChecker, seen?: Set<ts.Node>): string;