tina4-nodejs 3.13.136 → 3.13.138

package/packages/orm/src/adapters/firebird.ts

@@ -1,10 +1,18 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * 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 { firebirdDialect, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
+import { firebirdDialect, buildInsert, buildSetClause, buildWhereClause, quoteIdentifierWith } from "./sqlDialect.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslator.js";
 import { connectTimeoutMillis, withConnectTimeout } from "../connectTimeout.js";
@@ -235,6 +243,15 @@ export class FirebirdAdapter implements DatabaseAdapter {
     return 'firebird';
   }
 
+  /**
+   * Quote a name the ORM emits the way Firebird stores it: UPPER CASE (see
+   * fbQuote). An already-quoted name passes through - the escape hatch for a
+   * genuinely case-sensitive table. Python master: FirebirdAdapter.quote_identifier.
+   */
+  quoteIdentifier(name: string): string {
+    return quoteIdentifierWith(name, '"', '"', true);
+  }
+
   /** ADR-0044: readable/writable native boolean. */
   autocommit = true;
 
@@ -523,17 +540,39 @@ export class FirebirdAdapter implements DatabaseAdapter {
 
   async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
     this.ensureConnected();
+    if (/\bRETURNING\b/i.test(sql)) {
+      // A RETURNING statement hands back rows (the ORM reads the generated key
+      // from them, as it does on PostgreSQL). node-firebird answers a single
+      // returned row as a bare object, so normalise it to a row list.
+      const returned = await this.queryPromise(sql, params);
+      const rows = Array.isArray(returned) ? returned : returned ? [returned] : [];
+      return { rows: rows.map((row) => foldColumnNames(row)) };
+    }
     await this.executePromise(sql, params);
     return undefined;
   }
 
+  /**
+   * Run a row-producing statement ONCE and return its rows, for
+   * Database.execute(). node-firebird's execute() returns no rows, so a SELECT
+   * or an `INSERT ... RETURNING` through execute() used to lose them.
+   */
+  async executeRowsAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+    this.ensureConnected();
+    return this.queryAsync<T>(sql, params);
+  }
+
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
     throw new Error("Use queryAsync() for Firebird.");
   }
 
   async queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
     this.ensureConnected();
-    const rows = await this.queryPromise(sql, params);
+    const result = await this.queryPromise(sql, params);
+    // A singleton statement (`INSERT ... VALUES ... RETURNING id`) comes back from
+    // node-firebird as ONE row object, not an array of rows (MEASURED), so it is
+    // wrapped here rather than iterated as if it were a list.
+    const rows: unknown[] = Array.isArray(result) ? result : (result && typeof result === "object" ? [result] : []);
     const decoded: T[] = [];
     for (const row of rows as T[]) {
       decoded.push(await this.decodeBlobs(foldColumnNames(row)));
@@ -565,6 +604,9 @@ export class FirebirdAdapter implements DatabaseAdapter {
   }
 
   async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.queryAsync<T>(sql, params);
     let effectiveSql = sql;
     if (limit !== undefined) {
       const offset = skip ?? 0;
@@ -581,7 +623,12 @@ export class FirebirdAdapter implements DatabaseAdapter {
   }
 
   async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
-    const rows = await this.fetchAsync<T>(sql, params, 1, 0);
+    // A write runs unpaginated: Firebird rejects `INSERT ... RETURNING id ROWS 1
+    // TO 1` (ROWS is not valid on INSERT, and on UPDATE/DELETE it must precede
+    // RETURNING), so fetchOne() of a RETURNING write failed (#133 contract).
+    const rows = SQLTranslator.isWriteStatement(sql)
+      ? await this.queryAsync<T>(sql, params)
+      : await this.fetchAsync<T>(sql, params, 1, 0);
     return rows[0] ?? null;
   }
 

package/packages/orm/src/adapters/mongodb.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 MongoDB Adapter — uses the `mongodb` package (optional peer dependency).
  *

package/packages/orm/src/adapters/mssql.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 MSSQL Adapter — uses the `tedious` package (optional peer dependency).
  *
@@ -231,12 +239,23 @@ export class MssqlAdapter implements DatabaseAdapter {
    * `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.
+   *
+   * Only REAL placeholders are rewritten: a `?` inside a string literal, a
+   * quoted identifier or a comment is left alone (tina4-python#138).
    */
   private convertPlaceholders(sql: string, startAt = 0): string {
-    let count = startAt;
-    return sql.replace(/\?/g, () => {
-      return `@p${count++}`;
-    });
+    return SQLTranslator.replacePlaceholders(sql, (index) => `@p${startAt + index}`);
+  }
+
+  /**
+   * The SQL the driver receives. With NO parameters it is sent EXACTLY as
+   * written (the cross-framework contract): there is nothing to bind.
+   *
+   * tina4: with parameters every `?` outside a literal, quoted identifier or
+   * comment is a placeholder.
+   */
+  private bindable(sql: string, params?: unknown[]): string {
+    return params && params.length > 0 ? this.convertPlaceholders(sql) : sql;
   }
 
   execute(sql: string, params?: unknown[]): unknown {
@@ -275,7 +294,7 @@ export class MssqlAdapter implements DatabaseAdapter {
   async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
     this.ensureConnected();
     const translated = this.translateSql(sql);
-    const converted = this.convertPlaceholders(translated);
+    const converted = this.bindable(translated, params);
     return this.execSqlPromise(converted, params);
   }
 
@@ -286,7 +305,7 @@ export class MssqlAdapter implements DatabaseAdapter {
   async queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
     this.ensureConnected();
     const translated = this.translateSql(sql);
-    const converted = this.convertPlaceholders(translated);
+    const converted = this.bindable(translated, params);
     const result = await this.execSqlPromise(converted, params);
     return result.rows as T[];
   }
@@ -296,6 +315,9 @@ export class MssqlAdapter implements DatabaseAdapter {
   }
 
   async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.queryAsync<T>(sql, params);
     let effectiveSql = sql;
     if (limit !== undefined && limit > 0) {
       // MSSQL-PAGINATION-DIVERGE: ONE pagination strategy across all four
@@ -430,7 +452,7 @@ export class MssqlAdapter implements DatabaseAdapter {
     // `WHERE [0] = @p0 AND [1] = @p1 ...` — db.truncate() was broken outright.
     if (typeof filter === "string") {
       const sql = filter
-        ? `DELETE FROM [${table}] WHERE ${this.convertPlaceholders(filter)}`
+        ? `DELETE FROM [${table}] WHERE ${this.bindable(filter, params)}`
         : `DELETE FROM [${table}]`;
       try {
         const result = await this.execSqlPromise(sql, params ?? []);

package/packages/orm/src/adapters/mysql.ts

@@ -1,10 +1,18 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 MySQL Adapter — uses the `mysql2` package (optional peer dependency).
  *
  * Install: npm install mysql2
  * URL format: mysql://user:pass@host:port/database
  */
-import { MYSQL_DIALECT, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
+import { MYSQL_DIALECT, buildInsert, buildSetClause, buildWhereClause, quoteIdentifierWith } from "./sqlDialect.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslator.js";
 import { connectTarget, connectTimeoutMillis, driverConnectTimeoutMillis, withConnectTimeout } from "../connectTimeout.js";
@@ -62,6 +70,11 @@ export class MysqlAdapter implements DatabaseAdapter {
     return 'mysql';
   }
 
+  /** MySQL identifiers are backtick-quoted; a double-quoted token is a string. */
+  quoteIdentifier(name: string): string {
+    return quoteIdentifierWith(name, "`", "`");
+  }
+
   /** ADR-0044: readable/writable native boolean. */
   autocommit = true;
 
@@ -218,6 +231,9 @@ export class MysqlAdapter implements DatabaseAdapter {
   }
 
   async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.queryAsync<T>(sql, params);
     let effectiveSql = sql;
     if (limit !== undefined) {
       effectiveSql += ` LIMIT ${limit}`;

package/packages/orm/src/adapters/odbc.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 ODBC Adapter — uses the `odbc` package (optional peer dependency).
  *
@@ -270,6 +278,9 @@ export class OdbcAdapter implements DatabaseAdapter {
     limit?: number,
     skip?: number,
   ): Promise<T[]> {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.queryAsync<T>(sql, params);
     // See SQLTranslator.appendLimit: the old inline check was a substring search,
     // so a LIMIT in a string literal or a trailing comment silently dropped the
     // row cap and returned every row.

package/packages/orm/src/adapters/pg-types.d.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Minimal ambient type surface for the optional `pg` (node-postgres) peer
  * dependency. `@types/pg` is intentionally NOT a dependency (pg is an optional

package/packages/orm/src/adapters/postgres.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * Tina4 PostgreSQL Adapter — uses the `pg` package (optional peer dependency).
  *
@@ -159,12 +167,27 @@ export class PostgresAdapter implements DatabaseAdapter {
   // `startAt` lets a caller that has already consumed N placeholders (an UPDATE
   // whose SET values are $1..$N) continue the numbering into a raw WHERE
   // fragment instead of restarting at $1.
+  //
+  // Only REAL placeholders are rewritten: a `?` inside a string literal (incl.
+  // E'...' and $$...$$), a quoted identifier or a comment is left alone. A plain
+  // text replace bound `SELECT 'why?' AS v, ? AS n`'s parameter INTO the
+  // literal and left the real marker unbound (tina4-python#138).
   private convertPlaceholders(sql: string, startAt = 1): string {
-    let count = startAt - 1;
-    return sql.replace(/\?/g, () => {
-      count++;
-      return `$${count}`;
-    });
+    return SQLTranslator.replacePlaceholders(sql, (index) => `$${startAt + index}`);
+  }
+
+  /**
+   * The SQL the driver receives. With NO parameters it is sent EXACTLY as
+   * written (the cross-framework contract): there is nothing to bind, and the
+   * rewrite would turn PostgreSQL's jsonb operators `?`, `?|` and `?&` into
+   * unbound markers.
+   *
+   * tina4: with parameters every `?` outside a literal, quoted identifier or
+   * comment is a placeholder - use jsonb_exists(), jsonb_exists_any() or
+   * jsonb_exists_all() instead of the `?`, `?|` or `?&` operators.
+   */
+  private bindable(sql: string, params?: unknown[]): string {
+    return params && params.length > 0 ? this.convertPlaceholders(sql) : sql;
   }
 
   /**
@@ -232,7 +255,7 @@ export class PostgresAdapter implements DatabaseAdapter {
   /** Async execute for real usage. */
   async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
     this.ensureConnected();
-    const convertedSql = this.convertPlaceholders(sql);
+    const convertedSql = this.bindable(sql, params);
     const result = await this.client!.query(convertedSql, params);
     if (result.rows?.[0]?.id !== undefined) {
       this._lastInsertId = this.normalizeId(result.rows[0].id);
@@ -247,7 +270,7 @@ export class PostgresAdapter implements DatabaseAdapter {
   /** Async query for real usage. */
   async queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
     this.ensureConnected();
-    const convertedSql = this.convertPlaceholders(sql);
+    const convertedSql = this.bindable(sql, params);
     const result = await this.client!.query(convertedSql, params);
     return (result.rows as T[]).map(row => this.decodeBlobs(row));
   }
@@ -257,6 +280,9 @@ export class PostgresAdapter implements DatabaseAdapter {
   }
 
   async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.queryAsync<T>(sql, params);
     let effectiveSql = sql;
     if (limit !== undefined) {
       effectiveSql += ` LIMIT ${limit}`;
@@ -378,7 +404,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     // was broken outright on PostgreSQL.
     if (typeof filter === "string") {
       const sql = filter
-        ? `DELETE FROM "${table}" WHERE ${this.convertPlaceholders(filter)}`
+        ? `DELETE FROM "${table}" WHERE ${this.bindable(filter, params)}`
         : `DELETE FROM "${table}"`;
       try {
         const result = await this.client!.query(sql, params ?? []);

package/packages/orm/src/adapters/sqlDialect.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 /**
  * One CRUD SQL builder for every engine, instead of one per adapter.
  *
@@ -32,6 +40,35 @@ export interface Dialect {
 }
 
 const doubleQuote = (name: string): string => `"${name}"`;
+
+/**
+ * Quote a table/column name the ORM emits, in one engine's identifier quotes.
+ *
+ * Port of the Python master's `quote_identifier` (adapter.py; Firebird's
+ * override upper-cases): idempotent (an already-quoted name is returned
+ * unchanged), dot-aware (`schema.table` quotes each part), and a non-identifier
+ * (`*`, `COUNT(*)`, an expression) is passed through untouched. An embedded
+ * closing quote is doubled.
+ *
+ * `upperCase` is Firebird's rule: an unquoted identifier is stored UPPER CASE,
+ * so a lower-case name must be quoted upper-case to match it.
+ */
+export function quoteIdentifierWith(name: string, open: string, close: string, upperCase = false): string {
+  if (!name) return name;
+  const trimmed = name.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith(open) && trimmed.endsWith(close)) return trimmed;
+  if (trimmed.includes(".")) {
+    return trimmed.split(".").map((part) => quoteIdentifierWith(part, open, close, upperCase)).join(".");
+  }
+  if (!/^[\p{L}\p{N}_$]+$/u.test(trimmed)) return trimmed;
+  const body = upperCase ? trimmed.toUpperCase() : trimmed;
+  return `${open}${body.split(close).join(close + close)}${close}`;
+}
+
+/** The ANSI default: `"name"` (SQLite, PostgreSQL, MSSQL, ODBC). */
+export function quoteIdentifierAnsi(name: string): string {
+  return quoteIdentifierWith(name, '"', '"');
+}
 const questionMark = (): string => "?";
 
 /** SQLite, and ODBC which follows the SQL standard spelling. */
@@ -64,6 +101,23 @@ export function firebirdDialect(fbQuote: (name: string) => string): Dialect {
   return { quote: fbQuote, marker: questionMark };
 }
 
+const PLAIN_COLUMN_NAME = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+/**
+ * Refuse a data or filter-map key that is not a plain identifier.
+ *
+ * tina4: ADR-0069 (G3) - the write helpers emit these keys as column names, and
+ * the dialect quoters do not escape, so a key must be a plain identifier
+ * (letters, digits, underscore, dollar; not starting with a digit) before any
+ * SQL is built. Valid names are emitted exactly as before. Table names are
+ * developer code and are not checked here.
+ */
+export function assertColumnNames(keys: Iterable<string>): void {
+  for (const key of keys) {
+    if (!PLAIN_COLUMN_NAME.test(key)) throw new Error(`Invalid column name '${key}'`);
+  }
+}
+
 /**
  * `INSERT INTO <table> (<cols>) VALUES (<markers>)`.
  *
@@ -81,6 +135,7 @@ export function buildInsert(
   suffix = "",
   startAt = 1,
 ): string {
+  assertColumnNames(keys);
   const columns = keys.map((k) => dialect.quote(k)).join(", ");
   const placeholders = keys.map((_, i) => dialect.marker(startAt + i)).join(", ");
   return `INSERT INTO ${dialect.quote(table)} (${columns}) VALUES (${placeholders})${suffix}`;
@@ -98,6 +153,7 @@ export function buildSetClause(
   keys: string[],
   startAt = 1,
 ): string {
+  assertColumnNames(keys);
   return keys
     .map((k, i) => `${dialect.quote(k)} = ${dialect.marker(startAt + i)}`)
     .join(", ");
@@ -114,6 +170,7 @@ export function buildWhereClause(
   keys: string[],
   startAt = 1,
 ): string {
+  assertColumnNames(keys);
   return keys
     .map((k, i) => `${dialect.quote(k)} = ${dialect.marker(startAt + i)}`)
     .join(" AND ");

package/packages/orm/src/adapters/sqlite.ts

@@ -1,3 +1,11 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
 import { DatabaseSync } from "node:sqlite";
 import { ANSI_DIALECT, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
 import { mkdirSync } from "node:fs";
@@ -219,7 +227,25 @@ export class SQLiteAdapter implements DatabaseAdapter {
     return (params ? stmt.all(...toSqlParams(params)) : stmt.all()) as T[];
   }
 
+  /**
+   * Run a row-producing statement ONCE and return its rows, for
+   * Database.execute(). execute()'s run() discards rows, so a SELECT or an
+   * `INSERT ... RETURNING` through execute() used to lose them. A write still
+   * records its last insert id, exactly as execute() does.
+   */
+  executeRows<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
+    const rows = this.query<T>(sql, params);
+    if (SQLTranslator.isWriteStatement(sql)) {
+      const last = this.db.prepare("SELECT last_insert_rowid() AS id").get() as { id?: number | bigint } | undefined;
+      if (last?.id !== undefined) this._lastInsertId = last.id;
+    }
+    return rows;
+  }
+
   fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
+    // A write that returns rows (INSERT/UPDATE/DELETE ... RETURNING) runs exactly
+    // as written: a LIMIT/OFFSET appended to DML is a syntax error (#133 contract).
+    if (SQLTranslator.isWriteStatement(sql)) return this.query<T>(sql, params);
     // SQLTranslator.appendLimit owns BOTH halves of this decision: it scrubs
     // literals and comments before asking "does the caller already have a
     // LIMIT?", and it appends on a new line so the clause can never land inside