attention-manifest-protocol 0.4.2 → 0.4.3

package/src/database/sql/sql.ts

@@ -1,543 +0,0 @@
-/**
- * Generic SQL layer for one table.
- *
- * Every concrete table adapter extends {@link Sql} and supplies its
- * {@link TableMeta}. The base class owns the statement shapes shared by all
- * tables: primary-key lookup, list, count, insert, update, delete, upsert and
- * existence checks. Table-specific queries belong in a concrete subclass and
- * use the protected `query`, `queryOne`, `run` and `quote` helpers.
- *
- * Parameters are always bound; identifiers come from trusted {@link TableMeta}
- * values and are validated before they are interpolated.
- */
-import type { DatabaseSync } from "node:sqlite";
-
-import type { PrimaryKey } from "../entity/entity.ts";
-import type { TableMeta } from "../entity/meta.ts";
-
-/**
- * Value accepted by a SQLite bound parameter.
- */
-export type SqlParameter = string | number | bigint | null | Uint8Array;
-
-/**
- * Result of an INSERT, UPDATE or DELETE statement.
- */
-export interface MutationResult {
-    /**
-     * Number of rows changed by the statement.
-     */
-    readonly changes: number;
-    /**
-     * SQLite rowid generated by an INSERT, or zero when none was generated.
-     */
-    readonly lastInsertRowid: number | bigint;
-}
-
-/**
- * Raw result returned by `StatementSync.run`.
- *
- * `changes` may be a bigint on platforms where SQLite reports 64-bit counts;
- * public {@link MutationResult} values normalize it to a number.
- */
-interface RawMutationResult {
-    changes: number | bigint;
-    lastInsertRowid: number | bigint;
-}
-
-/**
- * Options for a generated SELECT.
- */
-export interface SelectOptions {
-    /**
-     * Optional SQL after WHERE.
-     */
-    readonly where?: string;
-    /**
-     * Bound values for the WHERE fragment.
-     */
-    readonly params?: readonly SqlParameter[];
-    /**
-     * Full ORDER BY fragment, for example a value returned by `Sort.toSql()`.
-     */
-    readonly orderBy?: string;
-    /**
-     * Maximum row count.
-     */
-    readonly limit?: number;
-    /**
-     * Number of rows to skip.
-     */
-    readonly offset?: number;
-    /**
-     * Optional column projection.
-     */
-    readonly columns?: readonly string[];
-}
-
-/**
- * Row shape for COUNT queries.
- */
-interface CountRow {
-    n: number;
-}
-
-/**
- * Convert a JavaScript value into a value `node:sqlite` can bind.
- *
- * Booleans become `1`/`0`, `undefined` becomes `NULL`, and unsupported object
- * types fail early instead of being stringified silently.
- *
- * @param value - Value from a repository or service.
- * @returns A bindable SQLite parameter.
- * @throws TypeError when the value has no SQLite representation.
- */
-export const toSqlParameter: (value: unknown) => SqlParameter = (value: unknown): SqlParameter => {
-    if (value === (void 0) || value === null) {
-        return null;
-    }
-    if (typeof(value) === "boolean") {
-        return value ? 1 : 0;
-    }
-    if (typeof(value) === "string" || typeof(value) === "bigint") {
-        return value;
-    }
-    if (typeof(value) === "number") {
-        if (!Number.isFinite(value)) {
-            throw new TypeError("SQL parameters cannot be NaN or Infinity");
-        }
-        return value;
-    }
-    if (value instanceof Uint8Array) {
-        return value;
-    }
-    throw new TypeError(`Unsupported SQL parameter type: ${Object.prototype.toString.call(value)}`);
-};
-
-/**
- * Validate a SQL identifier before it is interpolated into a statement.
- *
- * @param identifier - Table or column name.
- * @returns The identifier unchanged.
- * @throws Error when the identifier contains anything except letters, digits
- * and underscores, or when it starts with a digit.
- */
-export const assertSqlIdentifier: (identifier: string) => string = (identifier: string): string => {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
-        throw new Error(`Invalid SQL identifier: ${identifier}`);
-    }
-    return identifier;
-};
-
-/**
- * Abstract CRUD adapter for a single table.
- *
- * @typeParam TEntity - Row shape returned by the table.
- * @typeParam TKey - Primary-key type.
- */
-export abstract class Sql<TEntity extends object, TKey extends PrimaryKey = PrimaryKey> {
-    protected readonly db: DatabaseSync;
-    readonly meta: TableMeta;
-    private readonly columnSet: ReadonlySet<string>;
-
-    /**
-     * Create a table adapter.
-     *
-     * @param db - Open SQLite connection.
-     * @param meta - Table, primary key and column metadata.
-     */
-    protected constructor(db: DatabaseSync, meta: TableMeta) {
-        this.db = db;
-        this.meta = meta;
-        this.columnSet = new Set(meta.columns);
-        this.assertMeta();
-    }
-
-    /**
-     * Physical table name.
-     */
-    get table(): string {
-        return this.meta.table;
-    }
-
-    /**
-     * Primary-key column name.
-     */
-    get primaryKey(): string {
-        return this.meta.primaryKey;
-    }
-
-    /**
-     * Columns allowed in generated statements.
-     */
-    get columns(): readonly string[] {
-        return this.meta.columns;
-    }
-
-    /**
-     * Find one row by primary key.
-     *
-     * @param id - Primary-key value.
-     * @returns The row, or `undefined` when absent.
-     */
-    findById(id: TKey): TEntity | undefined {
-        const row: unknown = this.db
-            .prepare(`SELECT * FROM ${this.quote(this.table)} WHERE ${this.quote(this.primaryKey)} = ? LIMIT 1`)
-            .get(toSqlParameter(id));
-        return row as TEntity | undefined;
-    }
-
-    /**
-     * Read rows in unspecified order.
-     *
-     * @param limit - Maximum row count.
-     * @returns Matching rows.
-     */
-    all(limit: number = 1000): TEntity[] {
-        const bounded: number = this.normalizeLimit(limit);
-        return this.db.prepare(`SELECT * FROM ${this.quote(this.table)} LIMIT ?`).all(bounded) as unknown as TEntity[];
-    }
-
-    /**
-     * Read rows with a trusted SQL WHERE fragment.
-     *
-     * The fragment is not analyzed; callers must pass only literals and
-     * placeholders, never interpolated user input.
-     *
-     * @param clause - SQL after `WHERE`.
-     * @param params - Bound values for the clause.
-     * @returns Matching rows.
-     */
-    where(clause: string, ...params: SqlParameter[]): TEntity[] {
-        const where: string = clause.trim();
-        if (where.length === 0) {
-            throw new Error("where clause must not be empty");
-        }
-        return this.db.prepare(`SELECT * FROM ${this.quote(this.table)} WHERE ${where}`).all(...params) as unknown as TEntity[];
-    }
-
-    /**
-     * Read rows with optional filtering, ordering and pagination.
-     *
-     * @param options - Select options.
-     * @returns Matching rows.
-     */
-    select(options: SelectOptions = {}): TEntity[] {
-        const where: string = options.where?.trim() ?? "";
-        const params: SqlParameter[] = options.params === (void 0) ? [] : [...options.params];
-        if (where.length === 0 && params.length > 0) {
-            throw new Error("select parameters require a where clause");
-        }
-        let sql: string = `SELECT ${this.selectList(options.columns)} FROM ${this.quote(this.table)}`;
-        if (where.length > 0) {
-            sql += ` WHERE ${where}`;
-        }
-        const orderBy: string = options.orderBy?.trim() ?? "";
-        if (orderBy.length > 0) {
-            sql += ` ${orderBy}`;
-        }
-        if (options.limit !== (void 0)) {
-            const limit: number = this.normalizeLimit(options.limit);
-            sql += " LIMIT ?";
-            params.push(limit);
-        } else if (options.offset !== (void 0) && options.offset > 0) {
-            this.normalizeLimit(options.offset);
-            sql += " LIMIT -1";
-        }
-        if (options.offset !== (void 0)) {
-            const offset: number = this.normalizeLimit(options.offset);
-            sql += " OFFSET ?";
-            params.push(offset);
-        }
-        return this.query<TEntity>(sql, ...params);
-    }
-
-    /**
-     * Count rows, optionally restricted by a WHERE fragment.
-     *
-     * @param clause - Optional SQL after `WHERE`.
-     * @param params - Bound values for the clause.
-     * @returns Number of matching rows.
-     */
-    count(clause?: string, ...params: SqlParameter[]): number {
-        const where: string = clause?.trim() ?? "";
-        const sql: string =
-            where.length === 0 ? `SELECT COUNT(*) AS n FROM ${this.quote(this.table)}` : `SELECT COUNT(*) AS n FROM ${this.quote(this.table)} WHERE ${where}`;
-        const row: CountRow | undefined = this.db.prepare(sql).get(...params) as unknown as CountRow | undefined;
-        return row?.n ?? 0;
-    }
-
-    /**
-     * Test whether a primary key exists.
-     *
-     * @param id - Primary-key value.
-     * @returns `true` when the row exists.
-     */
-    exists(id: TKey): boolean {
-        const row: unknown = this.db
-            .prepare(`SELECT 1 AS present FROM ${this.quote(this.table)} WHERE ${this.quote(this.primaryKey)} = ? LIMIT 1`)
-            .get(toSqlParameter(id));
-        return row !== (void 0);
-    }
-
-    /**
-     * Insert one row.
-     *
-     * @param values - Column values; unknown keys are rejected.
-     * @returns Mutation metadata.
-     */
-    insert(values: Readonly<Record<string, unknown>>): MutationResult {
-        const columns: string[] = this.collectColumns(values, true);
-        const placeholders: string = columns.map(() => "?").join(", ");
-        const params: SqlParameter[] = this.collectParams(values, columns);
-        const sql: string = `INSERT INTO ${this.quote(this.table)} (${columns.map((column) => this.quote(column)).join(", ")}) VALUES (${placeholders})`;
-        return this.run(sql, ...params);
-    }
-
-    /**
-     * Update one row by primary key.
-     *
-     * @param id - Primary-key value.
-     * @param values - Column values; the primary key is ignored.
-     * @returns Number of changed rows.
-     */
-    update(id: TKey, values: Readonly<Record<string, unknown>>): number {
-        const columns: string[] = this.collectColumns(values, false);
-        const params: SqlParameter[] = this.collectParams(values, columns);
-        const assignments: string = columns.map((column) => `${this.quote(column)} = ?`).join(", ");
-        const sql: string = `UPDATE ${this.quote(this.table)} SET ${assignments} WHERE ${this.quote(this.primaryKey)} = ?`;
-        const result: RawMutationResult = this.db.prepare(sql).run(...params, toSqlParameter(id));
-        return Number(result.changes);
-    }
-
-    /**
-     * Update rows selected by a trusted WHERE fragment.
-     *
-     * @param clause - SQL after `WHERE`.
-     * @param values - Column values; the primary key is ignored.
-     * @param params - Bound values for the clause.
-     * @returns Number of changed rows.
-     */
-    updateWhere(clause: string, values: Readonly<Record<string, unknown>>, ...params: SqlParameter[]): number {
-        const where: string = clause.trim();
-        if (where.length === 0) {
-            throw new Error("where clause must not be empty");
-        }
-        const columns: string[] = this.collectColumns(values, false);
-        const assignments: string = columns.map((column) => `${this.quote(column)} = ?`).join(", ");
-        const sql: string = `UPDATE ${this.quote(this.table)} SET ${assignments} WHERE ${where}`;
-        const result: RawMutationResult = this.db.prepare(sql).run(...this.collectParams(values, columns), ...params);
-        return Number(result.changes);
-    }
-
-    /**
-     * Delete one row by primary key.
-     *
-     * @param id - Primary-key value.
-     * @returns Number of deleted rows.
-     */
-    delete(id: TKey): number {
-        const result: RawMutationResult = this.db
-            .prepare(`DELETE FROM ${this.quote(this.table)} WHERE ${this.quote(this.primaryKey)} = ?`)
-            .run(toSqlParameter(id));
-        return Number(result.changes);
-    }
-
-    /**
-     * Delete rows selected by a trusted WHERE fragment.
-     *
-     * @param clause - SQL after `WHERE`.
-     * @param params - Bound values for the clause.
-     * @returns Number of deleted rows.
-     */
-    deleteWhere(clause: string, ...params: SqlParameter[]): number {
-        const where: string = clause.trim();
-        if (where.length === 0) {
-            throw new Error("where clause must not be empty");
-        }
-        const result: RawMutationResult = this.db.prepare(`DELETE FROM ${this.quote(this.table)} WHERE ${where}`).run(...params);
-        return Number(result.changes);
-    }
-
-    /**
-     * Insert a row, replacing conflicting columns on a conflict.
-     *
-     * @param values - Column values; conflict columns must be present.
-     * @param conflictColumns - Unique columns; defaults to the primary key.
-     * @returns Mutation metadata.
-     */
-    upsert(values: Readonly<Record<string, unknown>>, conflictColumns?: readonly string[]): MutationResult {
-        const columns: string[] = this.collectColumns(values, true);
-        const params: SqlParameter[] = this.collectParams(values, columns);
-        const conflicts: readonly string[] = conflictColumns ?? [this.primaryKey];
-        for (let index: number = 0; index < conflicts.length; index += 1) {
-            const column: string = conflicts[index];
-            if (!columns.includes(column)) {
-                throw new Error(`upsert conflict column is not supplied: ${column}`);
-            }
-        }
-        const conflictSql: string = conflicts.map((column) => this.quote(column)).join(", ");
-        const updates: string[] = columns.filter((column) => !conflicts.includes(column));
-        const action: string =
-            updates.length === 0
-                ? "DO NOTHING"
-                : `DO UPDATE SET ${updates.map((column) => `${this.quote(column)} = excluded.${this.quote(column)}`).join(", ")}`;
-        const placeholders: string = columns.map(() => "?").join(", ");
-        const sql: string = `INSERT INTO ${this.quote(this.table)} (${columns.map((column) => this.quote(column)).join(", ")}) VALUES (${placeholders}) ON CONFLICT(${conflictSql}) ${action}`;
-        return this.run(sql, ...params);
-    }
-
-    /**
-     * Build a SELECT column list.
-     *
-     * @param columns - Optional columns; omitted means all columns.
-     * @returns SQL column list.
-     */
-    private selectList(columns?: readonly string[]): string {
-        if (columns === (void 0) || columns.length === 0) {
-            return "*";
-        }
-        return columns.map((column) => this.quote(column)).join(", ");
-    }
-
-    /**
-     * Execute a trusted statement with bound parameters.
-     *
-     * @param sql - Complete SQL statement.
-     * @param params - Bound values.
-     * @returns Mutation metadata.
-     */
-    protected run(sql: string, ...params: SqlParameter[]): MutationResult {
-        const result: RawMutationResult = this.db.prepare(sql).run(...params);
-        return {
-            changes: Number(result.changes),
-            lastInsertRowid: result.lastInsertRowid,
-        };
-    }
-
-    /**
-     * Read rows from a trusted statement.
-     *
-     * @typeParam TRow - Row shape.
-     * @param sql - Complete SQL statement.
-     * @param params - Bound values.
-     * @returns Rows.
-     */
-    query<TRow>(sql: string, ...params: SqlParameter[]): TRow[] {
-        return this.db.prepare(sql).all(...params) as TRow[];
-    }
-
-    /**
-     * Read one row from a trusted statement.
-     *
-     * @typeParam TRow - Row shape.
-     * @param sql - Complete SQL statement.
-     * @param params - Bound values.
-     * @returns The row, or `undefined`.
-     */
-    queryOne<TRow>(sql: string, ...params: SqlParameter[]): TRow | undefined {
-        return this.db.prepare(sql).get(...params) as TRow | undefined;
-    }
-
-    /**
-     * Quote an identifier after validating it.
-     *
-     * @param identifier - Table or column name.
-     * @returns Double-quoted identifier.
-     */
-    protected quote(identifier: string): string {
-        return `"${assertSqlIdentifier(identifier)}"`;
-    }
-
-    /**
-     * Check that the table metadata is internally consistent.
-     */
-    private assertMeta(): void {
-        assertSqlIdentifier(this.meta.table);
-        assertSqlIdentifier(this.meta.primaryKey);
-        if (this.meta.columns.length === 0) {
-            throw new Error(`table ${this.meta.table} must declare at least one column`);
-        }
-        if (!this.columnSet.has(this.meta.primaryKey)) {
-            throw new Error(`primary key ${this.meta.primaryKey} is not listed in columns`);
-        }
-        for (let index: number = 0; index < this.meta.columns.length; index += 1) {
-            assertSqlIdentifier(this.meta.columns[index]);
-        }
-    }
-
-    /**
-     * Select writable columns from a value map.
-     *
-     * @param values - Caller-supplied values.
-     * @param includePrimaryKey - Whether the primary key is writable.
-     * @returns Ordered column names.
-     */
-    private collectColumns(values: Readonly<Record<string, unknown>>, includePrimaryKey: boolean): string[] {
-        const keys: string[] = Object.keys(values);
-        const columns: string[] = [];
-        for (let index: number = 0; index < keys.length; index += 1) {
-            const column: string = keys[index];
-            if (!this.columnSet.has(column)) {
-                throw new Error(`unknown column for ${this.table}: ${column}`);
-            }
-            if (!includePrimaryKey && column === this.primaryKey) {
-                continue;
-            }
-            columns.push(column);
-        }
-        if (columns.length === 0) {
-            throw new Error(`no writable columns supplied for ${this.table}`);
-        }
-        return columns;
-    }
-
-    /**
-     * Build bound parameters in column order.
-     *
-     * @param values - Caller-supplied values.
-     * @param columns - Ordered column names.
-     * @returns Bindable parameters.
-     */
-    private collectParams(values: Readonly<Record<string, unknown>>, columns: readonly string[]): SqlParameter[] {
-        const params: SqlParameter[] = [];
-        for (let index: number = 0; index < columns.length; index += 1) {
-            params.push(toSqlParameter(values[columns[index]]));
-        }
-        return params;
-    }
-
-    /**
-     * Validate and normalize a LIMIT value.
-     *
-     * @param limit - Requested row count.
-     * @returns A non-negative integer.
-     */
-    private normalizeLimit(limit: number): number {
-        if (!Number.isInteger(limit) || limit < 0) {
-            throw new RangeError("limit must be a non-negative integer");
-        }
-        return limit;
-    }
-}
-
-/**
- * Concrete SQL adapter for a table that only needs generated CRUD statements.
- *
- * Table-specific operations can instead subclass {@link Sql} and use the
- * public query helpers.
- *
- * @typeParam TEntity - Row shape returned by the table.
- * @typeParam TKey - Primary-key type.
- */
-export class TableSql<TEntity extends object, TKey extends PrimaryKey = PrimaryKey> extends Sql<TEntity, TKey> {
-    /**
-     * Create a generated table adapter.
-     *
-     * @param db - Open SQLite connection.
-     * @param meta - Table, primary key and column metadata.
-     */
-    constructor(db: DatabaseSync, meta: TableMeta) {
-        super(db, meta);
-    }
-}