tina4-nodejs 3.13.94 → 3.13.95

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

@@ -66,8 +66,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 +77,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,6 +95,16 @@ export interface DatabaseAdapter {
     }>;
     /** Add a column to an existing table (legacy, used by migration). */
     addColumn?(table: string, colName: string, def: FieldDefinition): void;
+    /**
+     * 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 PaginatedResult<T = Record<string, unknown>> {
     data: T[];

package/packages/core/src/sessionHandlers/redisHandler.ts

@@ -1,219 +0,0 @@
-/**
- * Tina4 Redis Session Handler — Redis via `redis` npm package (optional dependency).
- *
- * Provides a session handler backed by the official `redis` npm package,
- * complementing the built-in raw-TCP RedisSessionHandler in session.ts.
- *
- * This handler uses synchronous child-process execution (same pattern as
- * valkeyHandler.ts) so it fits the synchronous SessionHandler interface
- * without requiring async refactoring.
- *
- * Configure via environment variables:
- *   TINA4_SESSION_REDIS_HOST     (default: "127.0.0.1")
- *   TINA4_SESSION_REDIS_PORT     (default: 6379)
- *   TINA4_SESSION_REDIS_URL      (optional — full redis:// URL, overrides host/port)
- *   TINA4_SESSION_REDIS_PASSWORD  (optional)
- *   TINA4_SESSION_REDIS_PREFIX   (default: "tina4:session:")
- *   TINA4_SESSION_REDIS_DB       (default: 0)
- */
-import { execFileSync } from "node:child_process";
-import { childFailureError } from "./childError.js";
-import { createRequire } from "node:module";
-import type { SessionHandler } from "../session.js";
-import { respCommandSync } from "./respClient.js";
-
-// Resolve packages relative to this module so the optional `redis` driver is
-// detected exactly as a consumer would resolve it (createRequire works in ESM).
-const moduleRequire = createRequire(import.meta.url);
-function redisDriverAvailable(): boolean {
-  try {
-    moduleRequire.resolve("redis");
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-interface SessionData {
-  _created: number;
-  _accessed: number;
-  [key: string]: unknown;
-}
-
-export interface RedisNpmSessionConfig {
-  host?: string;
-  port?: number;
-  url?: string;
-  password?: string;
-  prefix?: string;
-  db?: number;
-  // Unified SessionConfig fields are tolerated (and ignored) so the central
-  // Session can forward its config object without a structural mismatch.
-  backend?: string;
-  path?: string;
-  ttl?: number;
-  redisHost?: string;
-  redisPort?: number;
-  redisPassword?: string;
-  redisPrefix?: string;
-  redisDb?: number;
-}
-
-/**
- * Redis session handler using the `redis` npm package.
- *
- * Falls back to raw TCP (RESP protocol) if the `redis` package is not
- * installed, matching the approach used by the Valkey handler.
- *
- * Stores session data as JSON strings with Redis TTL for automatic expiry.
- */
-export class RedisNpmSessionHandler implements SessionHandler {
-  private host: string;
-  private port: number;
-  private url: string;
-  private password: string;
-  private prefix: string;
-  private db: number;
-
-  constructor(config?: RedisNpmSessionConfig) {
-    this.url = config?.url
-      ?? process.env.TINA4_SESSION_REDIS_URL
-      ?? "";
-    this.host = config?.host
-      ?? process.env.TINA4_SESSION_REDIS_HOST
-      ?? "127.0.0.1";
-    this.port = config?.port
-      ?? (process.env.TINA4_SESSION_REDIS_PORT
-        ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
-        : 6379);
-    this.password = config?.password
-      ?? process.env.TINA4_SESSION_REDIS_PASSWORD
-      ?? "";
-    this.prefix = config?.prefix
-      ?? process.env.TINA4_SESSION_REDIS_PREFIX
-      ?? "tina4:session:";
-    this.db = config?.db
-      ?? (process.env.TINA4_SESSION_REDIS_DB
-        ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
-        : 0);
-  }
-
-  /** Resolve a host/port for the raw-RESP path (parses TINA4_SESSION_REDIS_URL if set). */
-  private resolveHostPort(): { host: string; port: number } {
-    if (this.url) {
-      try {
-        const u = new URL(this.url);
-        return { host: u.hostname || "127.0.0.1", port: parseInt(u.port, 10) || 6379 };
-      } catch {
-        return { host: this.host, port: this.port };
-      }
-    }
-    return { host: this.host, port: this.port };
-  }
-
-  /**
-   * Execute a Redis command synchronously.
-   *
-   * Prefers the official `redis` driver when it is installed (the class's reason
-   * to exist); otherwise speaks raw RESP via the shared {@link respCommandSync}
-   * transport — same correct path as the Valkey handler, no `redis` dependency.
-   *
-   * A genuine key miss yields `""`; a transport/connection FAILURE (server
-   * unreachable, rejected AUTH, timeout) THROWS so the Session boundary can
-   * distinguish "not found" (silent) from "backend failed" (log-loud + degrade).
-   */
-  private execSync(args: string[]): string {
-    if (redisDriverAvailable()) {
-      return this.execViaNpm(args);
-    }
-    const { host, port } = this.resolveHostPort();
-    return respCommandSync({ host, port, password: this.password, db: this.db }, args, "Redis");
-  }
-
-  /** Drive the command through the `redis` npm client in a short-lived child. */
-  private execViaNpm(args: string[]): string {
-    const script = `
-      const useUrl = ${JSON.stringify(!!this.url)};
-      const url = ${JSON.stringify(this.url)};
-      const host = ${JSON.stringify(this.host)};
-      const port = ${this.port};
-      const password = ${JSON.stringify(this.password)};
-      const db = ${this.db};
-      const args = ${JSON.stringify(args)};
-      (async () => {
-        try {
-          const redis = require("redis");
-          // reconnectStrategy: false — this child runs ONE command and exits, so
-          // retrying inside it is pointless: the handler is called again on the
-          // next request anyway. With the driver's default strategy a refused
-          // connection never rejects, the child hangs until execFileSync's 5s
-          // timeout kills it, and the caller is told "timed out" when the truth
-          // is "connection refused". Off, connect() rejects in ~5ms with the real
-          // reason -- a better message AND no 5s stall per request when Redis is
-          // down.
-          const clientOpts = useUrl
-            ? { url, socket: { reconnectStrategy: false } }
-            : { socket: { host, port, reconnectStrategy: false }, password: password || undefined, database: db };
-          const client = redis.createClient(clientOpts);
-          client.on("error", () => {});
-          await client.connect();
-          const cmd = args[0].toUpperCase();
-          let result;
-          if (cmd === "GET") result = await client.get(args[1]);
-          else if (cmd === "SET") result = await client.set(args[1], args[2]);
-          else if (cmd === "SETEX") result = await client.setEx(args[1], parseInt(args[2], 10), args[3]);
-          else if (cmd === "DEL") result = await client.del(args[1]);
-          await client.quit();
-          const out = (result === null || result === undefined) ? "__NULL__" : String(result);
-          process.stdout.write(out, () => process.exit(0));
-        } catch (err) {
-          // Exit from the write CALLBACK: stderr to a pipe is an async write and
-          // a bare process.exit() truncates it, which left the parent with an
-          // empty stderr and nothing but execFileSync's script-dump message.
-          process.stderr.write(String((err && err.message) || err), () => process.exit(1));
-        }
-      })();
-    `;
-    let result: string;
-    try {
-      result = execFileSync(process.execPath, ["-e", script], {
-        encoding: "utf-8",
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } catch (err) {
-      // The child's stderr carries the driver's real reason; execFileSync's
-      // message carries the whole generated script. Prefer the former.
-      throw childFailureError("Redis", err);
-    }
-    if (result === "__NULL__") return "";       // genuine key miss
-    return result;
-  }
-
-  private key(sessionId: string): string {
-    return `${this.prefix}${sessionId}`;
-  }
-
-  read(sessionId: string): SessionData | null {
-    const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
-    try {
-      return JSON.parse(raw) as SessionData;
-    } catch {
-      return null;
-    }
-  }
-
-  write(sessionId: string, data: SessionData, ttl: number): void {
-    const json = JSON.stringify(data);
-    if (ttl > 0) {
-      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
-    } else {
-      this.execSync(["SET", this.key(sessionId), json]);
-    }
-  }
-
-  destroy(sessionId: string): void {
-    this.execSync(["DEL", this.key(sessionId)]);
-  }
-}

package/types/core/src/sessionHandlers/redisHandler.d.ts

@@ -1,60 +0,0 @@
-import type { SessionHandler } from "../session.js";
-interface SessionData {
-    _created: number;
-    _accessed: number;
-    [key: string]: unknown;
-}
-export interface RedisNpmSessionConfig {
-    host?: string;
-    port?: number;
-    url?: string;
-    password?: string;
-    prefix?: string;
-    db?: number;
-    backend?: string;
-    path?: string;
-    ttl?: number;
-    redisHost?: string;
-    redisPort?: number;
-    redisPassword?: string;
-    redisPrefix?: string;
-    redisDb?: number;
-}
-/**
- * Redis session handler using the `redis` npm package.
- *
- * Falls back to raw TCP (RESP protocol) if the `redis` package is not
- * installed, matching the approach used by the Valkey handler.
- *
- * Stores session data as JSON strings with Redis TTL for automatic expiry.
- */
-export declare class RedisNpmSessionHandler implements SessionHandler {
-    private host;
-    private port;
-    private url;
-    private password;
-    private prefix;
-    private db;
-    constructor(config?: RedisNpmSessionConfig);
-    /** Resolve a host/port for the raw-RESP path (parses TINA4_SESSION_REDIS_URL if set). */
-    private resolveHostPort;
-    /**
-     * Execute a Redis command synchronously.
-     *
-     * Prefers the official `redis` driver when it is installed (the class's reason
-     * to exist); otherwise speaks raw RESP via the shared {@link respCommandSync}
-     * transport — same correct path as the Valkey handler, no `redis` dependency.
-     *
-     * A genuine key miss yields `""`; a transport/connection FAILURE (server
-     * unreachable, rejected AUTH, timeout) THROWS so the Session boundary can
-     * distinguish "not found" (silent) from "backend failed" (log-loud + degrade).
-     */
-    private execSync;
-    /** Drive the command through the `redis` npm client in a short-lived child. */
-    private execViaNpm;
-    private key;
-    read(sessionId: string): SessionData | null;
-    write(sessionId: string, data: SessionData, ttl: number): void;
-    destroy(sessionId: string): void;
-}
-export {};