tina4-nodejs 3.13.94 → 3.13.96

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

@@ -78,6 +78,102 @@ export declare class SQLTranslator {
      * first dot. Firebird has no schemas, so its adapter ignores this.
      */
     static splitSchema(name: string): [string | null, string];
+    /**
+     * Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
+     * Sourced from test/fixtures/batch_write_contract.json, byte-identical in all
+     * four frameworks.
+     */
+    static readonly MAX_BIND_PARAMS: Record<string, number>;
+    /**
+     * The four frameworks do not agree on what an engine calls itself — Python
+     * and PHP report "postgresql", Ruby and Node report "postgres". Without
+     * normalising, the cap lookup misses and the collapse silently does nothing
+     * on the engine with the largest win.
+     */
+    static readonly ENGINE_ALIASES: Record<string, string>;
+    private static readonly INSERT_VALUES;
+    /**
+     * Engines whose lastInsertId reports the FIRST generated id of a multi-row
+     * INSERT rather than the last. Verified live, not assumed: a 3-row insert
+     * into a fresh MySQL table reports 1 while MAX(id) is 3. SQLite, PostgreSQL
+     * and MSSQL already report the last, so collapsing does not change them.
+     */
+    static readonly FIRST_ID_ENGINES: readonly string[];
+    /**
+     * Normalise a collapsed batch's last id to the LAST row's id.
+     *
+     * A row-at-a-time batch reports the last row's id simply because the last
+     * statement inserted the last row. Collapsing rows into one statement changes
+     * that on any engine that reports the FIRST generated id, so this restores
+     * the contract instead of quietly redefining it. The ids in one statement are
+     * consecutive, so the last is `first + rows - 1`.
+     */
+    static batchLastId(reportedId: unknown, rowsInChunk: number, engine: string): unknown;
+    /**
+     * Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
+     *
+     * A batch that loops one INSERT per row pays a full network round-trip per
+     * row, and the round-trip — not SQL building — is the entire cost of a batch
+     * write. Measured over 500 rows: PostgreSQL 9848ms row-at-a-time against
+     * 15.8ms as a single multi-row statement (625x), MySQL 216x, MSSQL 121x.
+     *
+     * PURE: no I/O and no engine contact, so the chunking rules are checkable
+     * without a database. The live-engine runners prove the rows land.
+     *
+     * @returns Statements to run INSTEAD of the loop, or an EMPTY array meaning
+     *          "not collapsible — keep looping", which is always correct.
+     */
+    static buildBatchInserts(sql: string, paramSets: unknown[][], engine: string): Array<[string, unknown[]]>;
+    /**
+     * Blank out string literals, quoted identifiers and comments, so a keyword
+     * search sees only real SQL. Blanks are spaces of the SAME LENGTH (newlines
+     * preserved), so offsets and line structure still line up with the original.
+     *
+     * This exists because "does the caller's SQL already have a LIMIT?" used to be
+     * `sql.toUpperCase().split("--")[0].includes("LIMIT")`, and MEASURED on a real
+     * 150-row table with the 100-row cap in force, every one of these returned
+     * ALL 150 ROWS instead of 100:
+     *
+     *     SELECT * FROM t WHERE label != 'LIMIT' ORDER BY id     -- literal
+     *     SELECT * FROM t ORDER BY id -- LIMIT 5                 -- line comment
+     *     SELECT * FROM t ORDER BY id /* LIMIT 5 *\/              -- block comment
+     *
+     * A column named `rate_limit` does it too. That is a silently UNCAPPED read of
+     * a whole table, which is the exact production incident the row cap exists to
+     * prevent, reachable through an ordinary column name.
+     *
+     * @param sql Raw SQL, exactly as the caller wrote it.
+     * @returns The same string with literals and comments replaced by spaces.
+     */
+    static scrubSqlText(sql: string): string;
+    /**
+     * True when the statement ENDS with its own LIMIT clause, so appending another
+     * would be wrong (and on SQLite, a syntax error).
+     *
+     * Anchored to the END on purpose. A bare "contains LIMIT" test also matches a
+     * LIMIT inside a subquery, where the OUTER statement still needs its cap. This
+     * is tina4-php's `SqlNormalizerTrait::hasTrailingLimit` regex, ported verbatim
+     * so all four frameworks answer identically: it accepts a numeric value, `?`,
+     * `$1` and `:name` placeholders, MySQL's `LIMIT a, b`, and a trailing OFFSET.
+     *
+     * @param sql Raw SQL; literals and comments are scrubbed before matching.
+     */
+    static hasTrailingLimit(sql: string): boolean;
+    /**
+     * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
+     *
+     * The clause goes on a NEW LINE. Appending it inline is the second half of the
+     * same bug: `SELECT * FROM t -- note` + ` LIMIT 100` puts the clause INSIDE the
+     * trailing comment, where SQLite silently ignores it and the whole table comes
+     * back. A newline cannot be commented out by a `--` that started on the line
+     * above. Trailing semicolons are stripped first for the same reason
+     * (`SELECT * FROM t;` + `LIMIT 100` is a syntax error).
+     *
+     * @param sql    The caller's statement.
+     * @param limit  Row cap to apply; a non-positive value means "no cap".
+     * @param offset Rows to skip; omitted or 0 emits no OFFSET.
+     */
+    static appendLimit(sql: string, limit?: number, offset?: number): string;
 }
 /**
  * Simple in-memory query cache with TTL support.
@@ -91,9 +187,37 @@ export declare class QueryCache {
         maxSize?: number;
     });
     /**
-     * Generate a cache key from a SQL query and params.
+     * Stable identity of the DATABASE a cache entry came from.
+     *
+     * `engine://host:port/database` - and deliberately NOTHING else.
+     *
+     * WHY IT EXISTS: the key used to be `query:${sql}:${params}` with nothing
+     * naming the connection, so on any SHARED backend two databases cross-served
+     * each other's rows. Two apps pointed at one Redis, or one app with a primary
+     * and an analytics connection, silently read each other's data. Identical SQL
+     * text across tenants is the COMMON case, not an edge case, so the collision
+     * was the normal outcome.
+     *
+     * WHY NO CREDENTIALS: a password in the key means every rotation silently
+     * cold-starts the cache, and a shared backend's key namespace is visible to
+     * every tenant of that backend - a secret must never be folded into it. The
+     * username is out for the same reason plus a second: two connections
+     * differing only by role read the SAME rows and should share the entry.
+     *
+     * WHY NOTHING PER-PROCESS: no pid, no object id, no salt. Those would isolate
+     * the databases by ACCIDENT and destroy the point of a shared cache, because
+     * no instance would ever hit another instance's entry.
+     */
+    static cacheIdentity(url: string): string;
+    /**
+     * Generate a cache key from DATABASE IDENTITY + SQL + params.
+     *
+     * The NUL separators keep the three parts from running together, so a table
+     * named after the tail of a database name cannot forge another database's
+     * key. The key is not hashed here: the only backend with a key-length limit
+     * is memcached, and its backend already SHA-256-hashes whatever it is given.
      */
-    static queryKey(sql: string, params?: unknown[]): string;
+    static queryKey(sql: string, params?: unknown[], identity?: string): string;
     /**
      * Get a cached value. Returns undefined if expired or missing.
      */

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

@@ -28,6 +28,13 @@ export interface RelationshipDefinition {
 }
 export interface ModelDefinition {
     tableName: string;
+    /**
+     * The model CLASS name (e.g. `Item` for tableName `items`), carried from
+     * `ModelClass.name` at discovery. Swagger keys `components.schemas` by this —
+     * the type name a generated client wants — falling back to a singular
+     * PascalCase derivation of tableName when a raw definition carries none.
+     */
+    className?: string;
     fields: Record<string, FieldDefinition>;
     fieldMapping?: Record<string, string>;
     softDelete?: boolean;
@@ -66,8 +73,8 @@ export interface DatabaseAdapter {
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
     /** Insert one or more rows into a table, returns result with lastId. */
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
-    /** Update rows in a table matching filter, returns affected row count. */
-    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
     /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
     delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
     /** Start a transaction. */
@@ -77,9 +84,9 @@ export interface DatabaseAdapter {
     /** Rollback the current transaction. */
     rollback(): void;
     /** List all tables in the database. */
-    tables(): string[];
+    getTables(): string[];
     /** List columns with types for a table. */
-    columns(table: string): ColumnInfo[];
+    getColumns(table: string): ColumnInfo[];
     /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
     lastInsertId(): number | bigint | string | null;
     /** Close the connection. */
@@ -95,40 +102,16 @@ export interface DatabaseAdapter {
     }>;
     /** Add a column to an existing table (legacy, used by migration). */
     addColumn?(table: string, colName: string, def: FieldDefinition): void;
-}
-export interface PaginatedResult<T = Record<string, unknown>> {
-    data: T[];
-    page: number;
-    perPage: number;
-    total: number;
-    totalPages: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}
-/**
- * Wraps an array of fetched rows with convenience methods.
- *
- * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
- */
-export declare class FetchResult<T = Record<string, unknown>> {
-    readonly records: T[];
-    readonly count: number;
-    readonly sql: string;
-    constructor(records: T[], sql?: string);
-    /** Paginate the in-memory result set. */
-    toPaginate(page?: number, perPage?: number): PaginatedResult<T>;
-    /** Return the first record or null. */
-    first(): T | null;
-    /** Return the last record or null. */
-    last(): T | null;
-    /** Check if result is empty. */
-    isEmpty(): boolean;
-    /** Convert to plain array. */
-    toArray(): T[];
-    /** Convert to JSON string. */
-    toJSON(): string;
-    /** Iterate over records. */
-    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Stable identity of the DATABASE this adapter is connected to, as
+     * `engine://host:port/database` with NO credentials - set by whoever built
+     * the adapter from a URL or config.
+     *
+     * The query cache folds this into every key. Without it two databases sharing
+     * one cache backend cross-serve each other's rows, because identical SQL text
+     * across tenants is the common case.
+     */
+    cacheIdentity?: string;
 }
 export interface QueryOptions {
     filter?: Record<string, unknown>;