tina4-nodejs 3.13.94 → 3.13.95

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

@@ -1,9 +1,3 @@
-/**
- * Tina4 Firebird Adapter — uses the `node-firebird` package (optional peer dependency).
- *
- * Install: npm install node-firebird
- * URL format: firebird://user:pass@host:port/path/to/database.fdb
- */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 /**
  * Turn a URL path component into a Firebird database identifier.
@@ -57,6 +51,39 @@ export interface FirebirdConfig {
     /** Connection charset. Overridden by a `?charset=` URL query; see resolveFirebirdCharset. */
     charset?: string;
 }
+/**
+ * Quote an identifier the way Firebird actually stores it: UPPERCASE.
+ *
+ * Firebird folds an UNQUOTED identifier to upper case and treats a QUOTED one as
+ * case-sensitive. So after the ordinary `CREATE TABLE probe_t (...)` the table is
+ * PROBE_T, and `INSERT INTO "probe_t"` matches nothing:
+ *
+ *     Dynamic SQL Error / Table unknown / probe_t
+ *
+ * That broke the insert path against every conventionally-created table, columns
+ * included. A name the caller has ALREADY quoted is passed through untouched,
+ * which is the escape hatch for a genuinely case-sensitive `CREATE TABLE "orders"`.
+ */
+export declare function fbQuote(name: string): string;
+/**
+ * Firebird's stored column name, folded back only when it was folded.
+ *
+ * Firebird's identifier folding is ASYMMETRIC. An unquoted `AS x` is stored
+ * UPPERCASE, so the driver hands back "X" where every other engine Tina4
+ * supports gives "x" — PostgreSQL folds to lower, and MySQL, SQLite and MSSQL
+ * preserve what you wrote. Portable code reading row.x broke on Firebird alone.
+ *
+ * A QUOTED `AS "MyCol"` is stored exactly as written, and that case is
+ * deliberate — the caller asked for it — so it is left alone. Folding
+ * unconditionally makes a mixed-case key unreachable, the same asymmetric trap
+ * that made tableExists miss quoted tables.
+ *
+ * So: fold back only a name carrying no lowercase letter, the only thing
+ * unquoted folding can produce. A quoted ALL-CAPS name is genuinely
+ * indistinguishable from a folded one and is lowercased too; that ambiguity is
+ * Firebird's, and it is the one spelling this cannot round-trip.
+ */
+export declare function firebirdColumnName(raw: string): string;
 export declare class FirebirdAdapter implements DatabaseAdapter {
     private config;
     private db;
@@ -116,22 +143,40 @@ export declare class FirebirdAdapter implements DatabaseAdapter {
     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>): Promise<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>): Promise<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>;
-    tables(): string[];
+    getTables(): string[];
     tablesAsync(): Promise<string[]>;
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     columnsAsync(table: string): Promise<ColumnInfo[]>;
     lastInsertId(): number | bigint | null;
     close(): void;
     tableExists(name: string): boolean;
+    /**
+     * Is this table present, under either spelling Firebird could have stored?
+     *
+     * Firebird's folding rule is ASYMMETRIC:
+     *     CREATE TABLE foo     -> stored as FOO   (unquoted folds to UPPER)
+     *     CREATE TABLE "Foo"   -> stored as Foo   (quoted keeps its case)
+     *
+     * So upper-casing is CORRECT for the unquoted case - the common one - and
+     * WRONG for a quoted mixed-case table, which is a real thing on Firebird.
+     * Dropping the upper-case would not fix that, it would invert which half is
+     * broken.
+     *
+     * tableExistsAsync("Foo") is genuinely AMBIGUOUS: the caller could mean the
+     * quoted `Foo` or the unquoted `FOO`. Match EITHER. Do not "simplify" this
+     * back to one comparison - that is the bug it replaces, where a quoted
+     * mixed-case table read as absent and createTableAsync's idempotency guard
+     * (below) never fired.
+     */
     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/mongodb.d.ts

@@ -55,9 +55,9 @@ export declare class MongodbAdapter implements DatabaseAdapter {
     commitAsync(): Promise<void>;
     rollback(): void;
     rollbackAsync(): Promise<void>;
-    tables(): string[];
+    getTables(): string[];
     tablesAsync(): Promise<string[]>;
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     /**
      * Infer column schema by sampling a document from the collection.
      * MongoDB is schema-less; this returns field names and inferred JS types.

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

@@ -1,9 +1,3 @@
-/**
- * Tina4 MSSQL Adapter — uses the `tedious` package (optional peer dependency).
- *
- * Install: npm install tedious
- * URL format: mssql://user:pass@host:port/database
- */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 export interface MssqlConfig {
     host?: string;
@@ -16,6 +10,13 @@ export interface MssqlConfig {
 }
 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;
@@ -27,7 +28,13 @@ export declare class MssqlAdapter implements DatabaseAdapter {
     /** Translate SQL for MSSQL dialect. */
     translateSql(sql: string): string;
     private execSqlPromise;
-    /** Convert ? placeholders to @p0, @p1, ... for tedious. */
+    /**
+     * 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[][]): {
@@ -48,18 +55,18 @@ export declare class MssqlAdapter implements DatabaseAdapter {
     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>): Promise<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>): Promise<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>;
-    tables(): string[];
+    getTables(): string[];
     tablesAsync(): Promise<string[]>;
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     columnsAsync(table: string): Promise<ColumnInfo[]>;
     lastInsertId(): number | bigint | null;
     close(): void;

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

@@ -1,9 +1,3 @@
-/**
- * Tina4 MySQL Adapter — uses the `mysql2` package (optional peer dependency).
- *
- * Install: npm install mysql2
- * URL format: mysql://user:pass@host:port/database
- */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 export interface MysqlConfig {
     host?: string;
@@ -15,6 +9,13 @@ export interface MysqlConfig {
 }
 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;
@@ -44,18 +45,18 @@ export declare class MysqlAdapter implements DatabaseAdapter {
     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>): Promise<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>): Promise<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>;
-    tables(): string[];
+    getTables(): string[];
     tablesAsync(): Promise<string[]>;
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     columnsAsync(table: string): Promise<ColumnInfo[]>;
     lastInsertId(): number | bigint | null;
     close(): void;

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

@@ -1,13 +1,3 @@
-/**
- * Tina4 ODBC Adapter — uses the `odbc` package (optional peer dependency).
- *
- * Install: npm install odbc
- * URL format: odbc:///DSN=MyDSN
- *             odbc:///DRIVER={driver};SERVER=host;DATABASE=db
- *
- * The connection string after stripping the "odbc:///" prefix is passed
- * directly to odbc.connect(), so any valid ODBC connection string works.
- */
 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" */
@@ -26,6 +16,13 @@ export declare class OdbcAdapter implements DatabaseAdapter {
     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;
@@ -43,8 +40,8 @@ export declare class OdbcAdapter implements DatabaseAdapter {
     startTransaction(): void;
     commit(): void;
     rollback(): void;
-    tables(): string[];
-    columns(table: string): ColumnInfo[];
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
     tableExists(name: string): boolean;
     createTable(name: string, columns: Record<string, FieldDefinition>): void;
     getTableColumns(name: string): Array<{

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

@@ -1,9 +1,3 @@
-/**
- * Tina4 PostgreSQL Adapter — uses the `pg` package (optional peer dependency).
- *
- * Install: npm install pg @types/pg
- * URL format: postgresql://user:pass@host:port/database
- */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 export interface PostgresConfig {
     host?: string;
@@ -15,6 +9,13 @@ export interface PostgresConfig {
 }
 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;
@@ -61,18 +62,18 @@ export declare class PostgresAdapter implements DatabaseAdapter {
     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>): Promise<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>): Promise<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>;
-    tables(): string[];
+    getTables(): string[];
     tablesAsync(): Promise<string[]>;
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     columnsAsync(table: string): Promise<ColumnInfo[]>;
     lastInsertId(): number | bigint | string | null;
     close(): void;

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

@@ -2,6 +2,18 @@ import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } fro
 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[][]): {
@@ -12,14 +24,14 @@ export declare class SQLiteAdapter implements DatabaseAdapter {
     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>, params?: 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;
-    tables(): string[];
-    columns(table: string): ColumnInfo[];
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
     lastInsertId(): number | bigint | null;
     close(): void;
     /**

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

@@ -135,6 +135,21 @@ export declare class BaseModel {
      * Get the primary key field name (JS property name).
      */
     protected static getPkField(): string;
+    /**
+     * EVERY primary-key field name, in declaration order.
+     *
+     * A key may span several columns. `getPkField()` returns only the FIRST and
+     * is kept for the auto-increment paths, which are single-column by
+     * definition. Anything that ADDRESSES a row must use this: keying on one
+     * column of a composite key matches every row sharing that value, which is
+     * the data-loss shape feature 4 removed from the raw write path below.
+     */
+    protected static getPkFields(): string[];
+    /** A WHERE naming EVERY primary-key column, and its bound params. */
+    protected pkWhere(): {
+        sql: string;
+        params: unknown[];
+    };
     /**
      * Get the primary key database column name (applies fieldMapping).
      */
@@ -195,20 +210,41 @@ export declare class BaseModel {
      */
     load(filter?: string, params?: unknown[], include?: string[]): Promise<boolean>;
     /**
-     * Find all records, optionally with a where clause.
-     * Alias: all()
-     * @param where Optional WHERE clause.
-     * @param params Optional query parameters.
-     * @param include Optional array of relationship names to eager-load.
+     * Find all records.
+     *
+     * BREAKING (3.13.95, parity): the signature is now
+     * `all(limit?, offset?, include?, orderBy?)`. It NO LONGER accepts leading
+     * `where`/`params`.
+     *
+     * Node was the sole outlier of the four. The master and the other two never
+     * had a filter on `all()`:
+     *   Python  all(limit=100, offset=0, include=None, order_by=None)
+     *   PHP     all(int $limit = 100, int $offset = 0, ?array $include, ?string $orderBy)
+     *   Ruby    all(limit: 100, offset: nil, order_by: nil, include: nil)
+     * Node's extra leading parameters shifted every argument, so the same
+     * positional call meant different things in different languages -- which is
+     * precisely what the parity mandate exists to prevent.
+     *
+     * MIGRATION: a filtered read moves to `where()`, which already exists and
+     * takes the conditions first:
+     *   before: User.all("age > ?", [28])
+     *   after:  User.where("age > ?", [28])
+     * TypeScript callers get a compile error (string is not assignable to number),
+     * so the break is loud rather than silent.
+     *
+     * @param limit   Max records (default 100, the shared cross-framework cap).
+     * @param offset  Records to skip (default 0).
+     * @param include Relationship names to eager-load.
+     * @param orderBy ORDER BY clause (e.g. "name ASC").
      */
-    static all<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, where?: string, params?: unknown[], include?: string[], orderBy?: string): Promise<T[]>;
+    static all<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<T[]>;
     /**
      * Query records with a WHERE clause.
      * Matches Python/PHP/Ruby where() API.
      *
      * @param conditions WHERE clause (e.g. "age > ? AND active = ?")
      * @param params     Bind parameters
-     * @param limit      Max records (default 20)
+     * @param limit      Max records (default 100)
      * @param offset     Skip records (default 0)
      * @param include    Relationship names to eager-load
      * @param orderBy    ORDER BY clause (e.g. "name ASC")
@@ -299,7 +335,7 @@ export declare class BaseModel {
      * @param sql     SQL query string.
      * @param params  Bind parameters.
      * @param ttl     Cache TTL in seconds (default 60).
-     * @param limit   Max records to return (default 20).
+     * @param limit   Max records to return (default 100).
      * @param offset  Records to skip (default 0).
      * @param include Relationship names to eager-load on cache miss.
      */
@@ -311,7 +347,7 @@ export declare class BaseModel {
     /**
      * Execute a raw SQL SELECT and return results as model instances.
      */
-    static select<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[]): Promise<T[]>;
+    static select<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]>;
     static selectOne<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], include?: string[]): Promise<T | null>;
     /**
      * Permanently delete this instance, bypassing soft delete.

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

@@ -83,6 +83,19 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     private backend;
     private backendPromise;
     private backendName;
+    /**
+     * WHICH DATABASE this wrapper caches for, folded into every cache key.
+     * Empty only for an adapter built outside the URL/config funnels, which then
+     * behaves exactly as before rather than colliding with a tagged one.
+     *
+     * Optional-chained on the ADAPTER, not just the property. `setAdapter(null)`
+     * is the documented reset idiom (migrateCli.test.ts uses it to clear ORM
+     * state between cases) and it reaches here through wrapWithCache. Before the
+     * identity field existed the constructor only STORED the adapter, so a null
+     * passed through harmlessly; reading `adapter.cacheIdentity` turned that
+     * reset into "Cannot read properties of null".
+     */
+    private readonly identity;
     constructor(adapter: DatabaseAdapter, options?: CachedAdapterOptions);
     /**
      * Whether the persistent layer should use a distributed/serialised backend.
@@ -140,13 +153,13 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): T[];
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null;
     insert(table: string, data: Record<string, unknown> | 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;
+    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;
     startTransaction(): void;
     commit(): void;
     rollback(): void;
-    tables(): string[];
-    columns(table: string): ColumnInfo[];
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
     lastInsertId(): number | bigint | string | null;
     close(): void;
     tableExists(name: string): boolean;
@@ -161,7 +174,7 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
     insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
-    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): Promise<DatabaseResult>;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
     deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult>;
     startTransactionAsync(): Promise<void>;
     commitAsync(): Promise<void>;

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

@@ -0,0 +1,100 @@
+/** Seconds. Long enough for a cold cross-region connect, short enough to page. */
+export declare const DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS = 10;
+/**
+ * Resolve the connect budget in MILLISECONDS, or `null` when the bound is
+ * disabled.
+ *
+ * Milliseconds because every consumer needs them: `setTimeout` and all four
+ * driver knobs are in ms. Seconds are the operator-facing unit, so the variable
+ * is read as seconds and converted once, here.
+ *
+ * Call this ONCE per connect and pass the result down - it is the only resolver,
+ * so calling it twice would warn twice about one typo.
+ */
+export declare function connectTimeoutMillis(): number | null;
+/**
+ * Clock slack when deciding whether a failed connect was OUR bound expiring.
+ *
+ * THE DECISION IS MADE BY ELAPSED TIME, NEVER BY MATCHING THE DRIVER'S TEXT.
+ * The four clients word an expiry four different ways - pg `timeout expired`,
+ * mysql2 `connect ETIMEDOUT`, tedious `Failed to connect to ... in 2000ms`,
+ * Mongo `Server selection timed out after 2000 ms` - and a marker table would
+ * drift the moment any of them reworded, then MISS. A missed timeout is the
+ * whole defect this file exists to prevent, so nothing here reads the message.
+ *
+ * WHY 50ms, AND WHY NOT ZERO. Python and PHP use no tolerance at all, PHP having
+ * measured its four C clients OVERSHOOTING their deadline by ~3ms at a 3s bound -
+ * a client that measures its own elapsed time can never report early. Node's
+ * knobs are not those: all four are plain JS `setTimeout` calls (pg `client.js`,
+ * mysql2 `base/connection.js`, tedious `connection.js`, and the Mongo driver's
+ * selection loop), and libuv's loop time is coarse, so a Node timer CAN fire
+ * before `performance.now()` agrees the budget has passed. MEASURED, 60 rounds
+ * at a 200ms budget:
+ *
+ *     Linux  x64,   Node v24.18.0   earliest -0.7125ms   (fires EARLY)
+ *     darwin arm64, Node v24.9.0    earliest +0.0872ms   (never early)
+ *
+ * Zero would therefore be a real miss on Linux. 50ms is a ~70x margin on the
+ * measured worst case, and still 0.5% of the 10s default. Ruby's 250ms is for a
+ * different problem - libpq's `connect_timeout` is INTEGER SECONDS and reads a
+ * 10s bound back as 9.998s - which no Node client has.
+ *
+ * It does NOT inflate the operator's N: it only widens what COUNTS as the bound
+ * expiring, never how long anything waits. It errs deliberately: over-translating
+ * a genuine fast failure that lands within 50ms of the bound still shows the
+ * operator the driver's real error (`Driver reported:`, plus `cause`), whereas
+ * under-translating hands them a bare driver message naming no variable.
+ */
+export declare const CONNECT_TIMEOUT_TOLERANCE_MS = 50;
+/**
+ * The value for a driver's own connect-timeout option, from the Tina4 budget.
+ * `null` in, `null` out - a disabled bound sets no driver option at all.
+ *
+ * ROUNDED UP, AND NEVER TO 0. Up, so the driver's timer can never expire before
+ * our clock has reached the bound - that ordering is the whole basis for the
+ * elapsed-time test in `withConnectTimeout`, and rounding down would break it.
+ * Never 0, because three of the four knobs read 0 as WAIT FOREVER: pg does
+ * `connectionTimeoutMillis || 0` then `if (> 0)`, mysql2 does
+ * `if (this.config.connectTimeout)`, and libpq (the same trap Python and Ruby
+ * name) treats `connect_timeout=0` as no limit. A sub-millisecond bound must
+ * therefore floor at 1ms rather than silently disabling the bound being set.
+ */
+export declare function driverConnectTimeoutMillis(budgetMs: number | null): number | null;
+/**
+ * Best-effort host/port for the DIAGNOSTIC, from either a config object or a
+ * connection URL. Never used to connect - the adapter has already done that with
+ * its own parsing, and this must not become a second, divergent parser that
+ * decides where anything dials.
+ */
+export declare function connectTarget(config: {
+    host?: string;
+    port?: number;
+} | string, defaultPort: number): {
+    host: string;
+    port: number | string;
+};
+/**
+ * Bound a driver connect, and name the bound when it expires.
+ *
+ * @param attempt   a THUNK that starts the driver's connect. It is a thunk, not a
+ *                  promise, so OUR CLOCK STARTS FIRST - everything that touches
+ *                  the driver must run inside it. That ordering is load-bearing:
+ *                  the driver arms its own timer somewhere in here (mysql2 arms
+ *                  its at the END OF ITS CONSTRUCTOR, not in `connect()`), and
+ *                  only by starting first can we know that the driver's timer
+ *                  cannot expire before `elapsed` has reached the bound.
+ * @param budgetMs  from `connectTimeoutMillis()`; `null` runs `attempt` untouched
+ * @param host      named in the error - an operator needs to know WHICH server hung
+ * @param port      named in the error alongside the host
+ * @param abandon   called if the driver answers AFTER we gave up, with whatever it
+ *                  produced. Nobody will ever use that connection, so the adapter
+ *                  closes it here rather than leaking a socket for the life of the
+ *                  process - a connect that is retried every 10s would otherwise
+ *                  accumulate one abandoned connection per attempt, forever.
+ *
+ * TWO WAYS OUT, both wearing the same message. Normally the DRIVER's timer fires
+ * first (it was armed first) and we TRANSLATE its failure; where the driver has
+ * no knob, or its knob did not cover the phase that hung, our own timer fires as
+ * the backstop and there is no driver diagnosis to report.
+ */
+export declare function withConnectTimeout<T>(attempt: () => Promise<T>, budgetMs: number | null, host: string, port: number | string, abandon?: (arrived: T) => void): Promise<T>;