tina4-nodejs 3.13.92 → 3.13.95

package/types/orm/src/adapters/mssql.d.ts

@@ -0,0 +1,77 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface MssqlConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+    options?: Record<string, unknown>;
+}
+export declare class MssqlAdapter implements DatabaseAdapter {
+    private config;
+    /**
+     * Postgres, MySQL and MSSQL all REQUIRE a name for a derived table, so
+     * the COUNT probe in Database.countProbe wraps as
+     * `FROM (sql) AS _count_query`. SQLite and Firebird leave this unset and
+     * get no alias - Firebird rejects `AS` in that position.
+     */
+    readonly countSubqueryAlias = "_count_query";
+    private connection;
+    private _lastInsertId;
+    private _inTransaction;
+    constructor(config: MssqlConfig | string);
+    /** Connect to MSSQL. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private parseUrl;
+    private ensureConnected;
+    /** Translate SQL for MSSQL dialect. */
+    translateSql(sql: string): string;
+    private execSqlPromise;
+    /**
+     * Convert ? placeholders to @p0, @p1, ... for tedious.
+     *
+     * `startAt` lets a caller that has already consumed N placeholders (an UPDATE
+     * whose SET values are @p0..@p{N-1}) continue the numbering into a raw WHERE
+     * fragment instead of restarting at @p0.
+     */
+    private convertPlaceholders;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    getTables(): string[];
+    tablesAsync(): Promise<string[]>;
+    getColumns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+}

package/types/orm/src/adapters/mysql.d.ts

@@ -0,0 +1,67 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface MysqlConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+}
+export declare class MysqlAdapter implements DatabaseAdapter {
+    private config;
+    /**
+     * Postgres, MySQL and MSSQL all REQUIRE a name for a derived table, so
+     * the COUNT probe in Database.countProbe wraps as
+     * `FROM (sql) AS _count_query`. SQLite and Firebird leave this unset and
+     * get no alias - Firebird rejects `AS` in that position.
+     */
+    readonly countSubqueryAlias = "_count_query";
+    private connection;
+    private _lastInsertId;
+    private _inTransaction;
+    constructor(config: MysqlConfig | string);
+    /** Connect to MySQL. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    private queryPromise;
+    /** Translate SQL for MySQL dialect. */
+    translateSql(sql: string): string;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    getTables(): string[];
+    tablesAsync(): Promise<string[]>;
+    getColumns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+}

package/types/orm/src/adapters/odbc.d.ts

@@ -0,0 +1,94 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface OdbcConfig {
+    /** Full ODBC connection string, e.g. "DSN=MyDSN" or "DRIVER={SQL Server};SERVER=host;DATABASE=db" */
+    connectionString: string;
+}
+export declare class OdbcAdapter implements DatabaseAdapter {
+    private config;
+    private connection;
+    private _lastInsertId;
+    private _inTransaction;
+    /**
+     * Accepts either an OdbcConfig object or a raw connection string.
+     * When created via Database.create("odbc:///DSN=MyDSN"), the "odbc:///"
+     * prefix is stripped by parseDatabaseUrl and the remainder is passed here.
+     */
+    constructor(config: OdbcConfig | string);
+    /** Extract the raw ODBC connection string from config. */
+    private getConnectionString;
+    /**
+     * The address for a diagnostic message. ODBC hides it inside an opaque
+     * driver keyword string, so this reads the standard keywords and falls back to
+     * the data-source name - it is never used to connect, only to say which target
+     * hung.
+     */
+    private describeTarget;
+    /** Connect to the ODBC data source. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    insert(table: string, data: Record<string, unknown>): DatabaseResult;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult;
+    startTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
+    tableExists(name: string): boolean;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    getTableColumns(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    addColumn(table: string, colName: string, def: FieldDefinition): void;
+    /** Execute a write statement (INSERT, UPDATE, DELETE, DDL). */
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    /** Execute a statement with multiple parameter sets inside a single transaction. */
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    /** Run a SELECT and return all matching rows. */
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Run a SELECT with optional LIMIT/OFFSET pagination. */
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    /** Run a SELECT and return the first row or null. */
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    /** Insert a single row into a table. */
+    insertAsync(table: string, data: Record<string, unknown>): Promise<DatabaseResult>;
+    /** Update rows in a table matching filter. */
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    /** Delete rows from a table. */
+    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): Promise<DatabaseResult>;
+    /** Begin a transaction. */
+    startTransactionAsync(): Promise<void>;
+    /** Commit the current transaction. */
+    commitAsync(): Promise<void>;
+    /** Rollback the current transaction. */
+    rollbackAsync(): Promise<void>;
+    /** List all user tables using ODBC catalog functions. */
+    tablesAsync(): Promise<string[]>;
+    /** Get column metadata for a table using ODBC catalog functions. */
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    /** Check whether a table exists. */
+    tableExistsAsync(name: string): Promise<boolean>;
+    /** Create a table from a FieldDefinition map. Uses generic SQL — works with most ODBC sources. */
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /** Get raw column name+type list for a table. */
+    getTableColumnsAsync(name: string): Promise<Array<{
+        name: string;
+        type: string;
+    }>>;
+    /** Add a column to an existing table. */
+    addColumnAsync(table: string, colName: string, def: FieldDefinition): Promise<void>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+}

package/types/orm/src/adapters/postgres.d.ts

@@ -0,0 +1,86 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface PostgresConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+}
+export declare class PostgresAdapter implements DatabaseAdapter {
+    private config;
+    /**
+     * Postgres, MySQL and MSSQL all REQUIRE a name for a derived table, so
+     * the COUNT probe in Database.countProbe wraps as
+     * `FROM (sql) AS _count_query`. SQLite and Firebird leave this unset and
+     * get no alias - Firebird rejects `AS` in that position.
+     */
+    readonly countSubqueryAlias = "_count_query";
+    private client;
+    private _lastInsertId;
+    private _inTransaction;
+    constructor(config: PostgresConfig | string);
+    /** Connect to PostgreSQL. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    /** Convert ? placeholders to $1, $2, ... for pg. */
+    /** Ensure bytea columns are Buffer (already the case with pg). No-op guard. */
+    private decodeBlobs;
+    private convertPlaceholders;
+    /**
+     * Normalise an `id` column value (typed `unknown` because pg row values are
+     * `unknown`) into the shape `_lastInsertId` / `DatabaseResult.lastId`
+     * expect. At runtime PG returns numeric PKs as number/bigint (the int8/numeric
+     * type parsers above coerce them to Number); a numeric string is coerced to a
+     * number so the SERIAL path always returns the integer id.
+     *
+     * A non-numeric string id — the UUID PK case (`id uuid PRIMARY KEY DEFAULT
+     * gen_random_uuid()`) returned via RETURNING — is preserved as-is so the
+     * insert surfaces the actual id instead of null (#256). null/undefined/empty
+     * still become null.
+     */
+    private normalizeId;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    /** Async executeMany for real usage. */
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    /** Async execute for real usage. */
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /** Async query for real usage. */
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    getTables(): string[];
+    tablesAsync(): Promise<string[]>;
+    getColumns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | string | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /** Translate SQL for PostgreSQL dialect. */
+    translateSql(sql: string): string;
+}

package/types/orm/src/adapters/sqlDialect.d.ts

@@ -0,0 +1,71 @@
+/**
+ * One CRUD SQL builder for every engine, instead of one per adapter.
+ *
+ * Feature 3's last open item, the 4.3x LOC finding: `insert`/`update`/`delete`
+ * built their SQL independently in all seven adapters. Building
+ * `INSERT INTO x (a, b) VALUES (?, ?)` is not engine-specific work - Ruby has
+ * always done it once - and the seven copies differed in exactly two ways:
+ *
+ *   IDENTIFIER QUOTING   "col"  |  `col`  |  [col]  |  Firebird's fbQuote
+ *   PARAMETER MARKER     ?      |  $1     |  @p1
+ *
+ * Both are captured in a `Dialect` below, so the builders are shared and each
+ * adapter declares only what genuinely differs about its engine.
+ *
+ * These functions build STRINGS and nothing else. Execution and result
+ * extraction stay in the adapters on purpose: those really are per-driver
+ * (`client.query` vs `lastInsertRowid` vs a Firebird transaction handle), and
+ * folding them in here would trade a real duplication for a fake abstraction.
+ *
+ * MongoDB has no entry: it does not build SQL at all.
+ */
+/** How one engine spells identifiers and parameter markers. */
+export interface Dialect {
+    /** Quote a table or column name for this engine. */
+    quote(name: string): string;
+    /**
+     * The parameter marker for the 1-based position `index`. Engines with
+     * positional markers ($1, @p1) use the index; the rest ignore it.
+     */
+    marker(index: number): string;
+}
+/** SQLite, and ODBC which follows the SQL standard spelling. */
+export declare const ANSI_DIALECT: Dialect;
+/** PostgreSQL: standard quoting, positional $N markers. */
+export declare const POSTGRES_DIALECT: Dialect;
+/** MySQL: backtick quoting. */
+export declare const MYSQL_DIALECT: Dialect;
+/** MSSQL: bracket quoting, named @pN markers. */
+export declare const MSSQL_DIALECT: Dialect;
+/**
+ * Firebird quotes only when it has to: an unquoted identifier is folded to
+ * UPPER CASE, so quoting a lower-case name would make it unfindable. The
+ * adapter owns that rule and passes its own quoter in.
+ */
+export declare function firebirdDialect(fbQuote: (name: string) => string): Dialect;
+/**
+ * `INSERT INTO <table> (<cols>) VALUES (<markers>)`.
+ *
+ * @param suffix Appended verbatim - PostgreSQL passes " RETURNING *" and MSSQL
+ *               its SCOPE_IDENTITY() probe, the genuinely engine-specific parts.
+ * @param startAt Position of the FIRST marker. PostgreSQL numbers its `$N` from
+ *                1; MSSQL names its `@pN` from 0 and BINDS by that same name, so
+ *                shifting it would produce SQL whose parameters do not exist.
+ *                Engines using `?` ignore this.
+ */
+export declare function buildInsert(dialect: Dialect, table: string, keys: string[], suffix?: string, startAt?: number): string;
+/**
+ * The `SET a = ?, b = ?` fragment of an UPDATE.
+ *
+ * @param startAt 1-based position of the FIRST marker. An UPDATE's WHERE
+ *                clause continues the numbering after the SET values, so a
+ *                positional engine ($N, @pN) must not restart at 1.
+ */
+export declare function buildSetClause(dialect: Dialect, keys: string[], startAt?: number): string;
+/**
+ * The `a = ? AND b = ?` fragment for an object filter.
+ *
+ * @param startAt 1-based position of the first marker, for the same reason as
+ *                buildSetClause.
+ */
+export declare function buildWhereClause(dialect: Dialect, keys: string[], startAt?: number): string;

package/types/orm/src/adapters/sqlite.d.ts

@@ -0,0 +1,68 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export declare class SQLiteAdapter implements DatabaseAdapter {
+    private db;
+    private _lastInsertId;
+    /**
+     * TINA4_DATABASE_CONNECT_TIMEOUT DOES NOT APPLY HERE, deliberately.
+     *
+     * There is no connect() to bound: `node:sqlite` opens the file in this
+     * SYNCHRONOUS constructor, and a synchronous call cannot be interrupted by a
+     * timer on the same thread - the event loop only gets to run the timer after
+     * `new DatabaseSync()` has already returned. There is also no host and no port
+     * to name in a timeout error. The one case that could still block is a local
+     * file on a wedged network mount, which is a kernel-level stall no JS bound
+     * can reach. Stated here so the exclusion reads as a decision rather than an
+     * adapter somebody forgot.
+     */
+    constructor(dbPath: string);
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
+    private _inTransaction;
+    startTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    /**
+     * Atomically increment and return the next value of a tina4_sequences row.
+     *
+     * DB-contract B (no duplicate primary keys under concurrency): the old
+     * read-increment-read path in Database.sequenceNext() yields at every `await`
+     * between the read and the write, so two concurrent async callers can read the
+     * same `current_value` and return the same id. This method runs the WHOLE
+     * operation — ensure-table, seed-if-absent, and the increment-and-return — as
+     * ONE synchronous burst on the single shared `node:sqlite` connection. Because
+     * `node:sqlite` is synchronous and JavaScript is single-threaded, no other
+     * async task can interleave between the statements (there is no `await`
+     * inside), so the increment is atomic and every caller gets a distinct id.
+     * This is the Node analog of the Python master holding SQLiteAdapter._write_lock
+     * across the whole op.
+     *
+     * On SQLite >= 3.35 a single `UPDATE ... SET current_value = current_value + 1
+     * ... RETURNING current_value` is itself atomic and returns the new value in
+     * one statement (read via prepare().all() — stmt.run() does not surface
+     * RETURNING rows). Older SQLite does `UPDATE ... + 1` then `SELECT`, still
+     * race-safe because both run in the same synchronous burst.
+     *
+     * @throws if the sequence row vanishes mid-increment (never silently returns 1).
+     */
+    sequenceNextSqlite(seqName: string, seedValue: number): number;
+    tableExists(name: string): boolean;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    getTableColumns(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    addColumn(table: string, colName: string, def: FieldDefinition): void;
+}

package/types/orm/src/autoCrud.d.ts

@@ -0,0 +1,73 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+import type { DiscoveredModel } from "./model.js";
+/**
+ * Auto-CRUD — discovers ORM models and auto-generates REST endpoints.
+ *
+ * Generated endpoints per model:
+ *   GET    /api/{table}        — list with pagination, filtering, sorting
+ *   GET    /api/{table}/{id}   — get single record
+ *   POST   /api/{table}        — create record
+ *   PUT    /api/{table}/{id}   — update record
+ *   DELETE /api/{table}/{id}   — delete record
+ */
+/**
+ * Options accepted by the AutoCrud registration API.
+ *
+ * `public` is the cross-backend escape hatch (parity with python's `public=True`
+ * and php's `bool $public`). Write routes (POST/PUT/DELETE) are secure-by-default
+ * — the router gates them unless a def sets `secure: false`. Set `public: true`
+ * to open the generated write routes explicitly. Reads (GET) are always public.
+ */
+export interface AutoCrudOptions {
+    /** When true, the generated write routes (POST/PUT/DELETE) are OPEN (secure:false). Default false → secure. */
+    public?: boolean;
+}
+export declare class AutoCrud {
+    private static registered;
+    /** tableName -> public-writes flag (default secure); mirrors php's `$this->public`. */
+    private static publicWrites;
+    /**
+     * Register a model for auto-CRUD.
+     *
+     * @param options.public If true, the generated write routes are OPEN (no auth).
+     *   Default (false) keeps them secure-by-default, matching the framework's write gate.
+     */
+    static register(model: DiscoveredModel, prefix?: string, options?: AutoCrudOptions): void;
+    /**
+     * Discover models from the provided array and register them.
+     * (In Node.js, models are discovered by the server and passed in.)
+     */
+    static discover(discoveredModels: DiscoveredModel[], prefix?: string, options?: AutoCrudOptions): string[];
+    /**
+     * Return all registered models.
+     */
+    static models(): Map<string, DiscoveredModel>;
+    /**
+     * Clear all registered models (useful for testing).
+     */
+    static clear(): void;
+    /**
+     * Generate route definitions for all registered models, honouring each
+     * model's per-table `public` flag (set at register/discover time).
+     */
+    static generateRoutes(): RouteDefinition[];
+}
+/**
+ * Filter discovered models down to those that explicitly opted into auto-CRUD via
+ * `static autoCrud = true` (the documented opt-in gate; default false). The server
+ * passes only these to generateCrudRoutes, so a model without the flag gets no CRUD
+ * endpoints. Exported so the opt-in gate is locked in by a test rather than
+ * re-implemented at each call site.
+ */
+export declare function crudEligibleModels(models: DiscoveredModel[]): DiscoveredModel[];
+/**
+ * Generate CRUD route definitions for the given models.
+ * (Standalone function for backward compatibility.)
+ *
+ * @param options.public When true, the generated write routes (POST/PUT/DELETE)
+ *   opt OUT of the router's secure-by-default write gate (`secure: false`) — the
+ *   cross-backend escape hatch (parity with python `public=True` / php `$public`).
+ *   Default (false) leaves `secure` unset so the router gates writes (secure:true).
+ *   GET routes are unaffected (reads are already public).
+ */
+export declare function generateCrudRoutes(models: DiscoveredModel[], options?: AutoCrudOptions): RouteDefinition[];