tina4-nodejs 3.13.139 → 3.13.141

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

@@ -0,0 +1,178 @@
+/*
+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 write composer for every SQL engine, instead of one per adapter.
+ *
+ * `sqlDialect.ts` already collapsed the SQL *fragment* builders (columns, the
+ * SET list, the WHERE list). What it did NOT collapse was the METHOD BODIES:
+ * every SQL adapter's `insert`/`update`/`delete` re-implemented the SAME
+ * envelope around those fragments — the string-filter branch vs the hash-filter
+ * branch, the `[...Object.values(data), ...(params ?? [])]` value assembly, the
+ * batch fan-out — differing only in the two things a `Dialect` already captures
+ * (identifier quoting, parameter marker) plus three per-engine knobs:
+ *
+ *   INSERT SUFFIX     "" | " RETURNING *" | "; SELECT SCOPE_IDENTITY() AS id"
+ *   MARKER START      1 (PostgreSQL $N) | 0 (MSSQL @pN) | ignored (`?` engines)
+ *   FRAGMENT REWRITE  a raw "id = ?" WHERE string: identity on a `?` engine,
+ *                     convertPlaceholders/bindable on a positional one
+ *
+ * This is the Node port of the Python master's `SqlCrudMixin`
+ * (tina4_python/database/adapter.py): build the SQL and the ordered parameter
+ * list engine-neutrally from a dialect + those knobs, and hand the pair back to
+ * the adapter to EXECUTE.
+ *
+ * Like `sqlDialect.ts`, these functions build STRINGS and parameter arrays and
+ * NOTHING else. Execution and result extraction stay in the adapters on purpose:
+ * `this.db.prepare().run()` vs `await this.client!.query()` vs tedious vs a
+ * Firebird transaction handle, and RETURNING / SCOPE_IDENTITY() / lastId /
+ * affectedRows normalisation, are genuinely per-driver — folding them in here
+ * would trade a real duplication for a fake abstraction.
+ *
+ * MongoDB has no entry: it does not build SQL at all.
+ */
+
+import { type Dialect, buildInsert, buildSetClause, buildWhereClause } from "./sqlDialect.js";
+
+/** A composed statement: the SQL text and its ordered parameter list. */
+export interface CrudSql {
+  sql: string;
+  values: unknown[];
+}
+
+/**
+ * A composed batch INSERT: one SQL statement plus one parameter row per input
+ * record, ready for the adapter's own `executeMany`.
+ */
+export interface CrudBatchSql {
+  sql: string;
+  paramsList: unknown[][];
+}
+
+/** The only per-engine differences in a composed write's SQL + parameter list. */
+export interface WriteOptions {
+  /**
+   * 1-based position of the FIRST parameter marker. PostgreSQL numbers `$N`
+   * from 1; MSSQL names `@pN` from 0 and BINDS by that name, so the start must
+   * match its binding loop. Engines whose marker is `?` ignore it. Default 1.
+   */
+  startAt?: number;
+  /**
+   * Rewrite a raw string WHERE fragment's `?` markers for this engine, given the
+   * 1-based position of the fragment's first marker. `?` engines leave it
+   * untouched (the default); a positional engine passes its `convertPlaceholders`
+   * / `bindable`. Only ever applied to the developer-supplied string filter,
+   * never to the framework-built hash WHERE.
+   */
+  convertFragment?: (fragment: string, startAt: number) => string;
+}
+
+const identityFragment = (fragment: string): string => fragment;
+
+/**
+ * A single-row INSERT: `INSERT INTO t (a, b) VALUES (?, ?)<suffix>` and the row's
+ * values in column order. `suffix` carries the genuinely engine-specific tail
+ * (PostgreSQL's ` RETURNING *`, MSSQL's SCOPE_IDENTITY() probe).
+ */
+export function buildInsertRow(
+  dialect: Dialect,
+  table: string,
+  data: Record<string, unknown>,
+  suffix = "",
+  options: WriteOptions = {},
+): CrudSql {
+  const keys = Object.keys(data);
+  const sql = buildInsert(dialect, table, keys, suffix, options.startAt ?? 1);
+  return { sql, values: Object.values(data) };
+}
+
+/**
+ * A batch INSERT from a list of rows — one parameterised statement the adapter
+ * runs once per row via its own `executeMany`. Returns `null` for an empty list
+ * (the adapters treat that as a no-op affecting zero rows). The keys come from
+ * the first row, exactly as every adapter already assumed.
+ */
+export function buildInsertRows(
+  dialect: Dialect,
+  table: string,
+  rows: Record<string, unknown>[],
+): CrudBatchSql | null {
+  if (rows.length === 0) return null;
+  const keys = Object.keys(rows[0]);
+  const sql = buildInsert(dialect, table, keys);
+  const paramsList = rows.map((row) => keys.map((k) => row[k]));
+  return { sql, paramsList };
+}
+
+/**
+ * An UPDATE from a data object and either a hash filter (`{id: 5}` →
+ * `WHERE "id" = ?`) or a raw string filter (`"id = ?"` + `params`). The SET
+ * values always lead the parameter list; the WHERE values follow.
+ */
+export function buildUpdate(
+  dialect: Dialect,
+  table: string,
+  data: Record<string, unknown>,
+  filter: Record<string, unknown> | string,
+  params?: unknown[],
+  options: WriteOptions = {},
+): CrudSql {
+  const startAt = options.startAt ?? 1;
+  const convertFragment = options.convertFragment ?? identityFragment;
+  const dataKeys = Object.keys(data);
+  const setClauses = buildSetClause(dialect, dataKeys, startAt);
+  const whereStart = startAt + dataKeys.length;
+
+  if (typeof filter === "string") {
+    const where = filter ? ` WHERE ${convertFragment(filter, whereStart)}` : "";
+    return {
+      sql: `UPDATE ${dialect.quote(table)} SET ${setClauses}${where}`,
+      values: [...Object.values(data), ...(params ?? [])],
+    };
+  }
+
+  const whereClauses = buildWhereClause(dialect, Object.keys(filter), whereStart);
+  return {
+    sql: `UPDATE ${dialect.quote(table)} SET ${setClauses} WHERE ${whereClauses}`,
+    values: [...Object.values(data), ...Object.values(filter)],
+  };
+}
+
+/**
+ * A DELETE from either a hash filter (`{id: 5}` → `WHERE "id" = ?`) or a raw
+ * string filter (`"age < ?"` + `params`). An empty string filter deletes the
+ * whole table (the explicit `truncate()` spelling routes through here).
+ *
+ * The array-of-dicts filter form is NOT handled here: only SQLite and ODBC
+ * accept it, and both loop it into per-row `delete` calls that land back in one
+ * of the two branches above — that fan-out stays in those two adapters.
+ */
+export function buildDelete(
+  dialect: Dialect,
+  table: string,
+  filter: Record<string, unknown> | string,
+  params?: unknown[],
+  options: WriteOptions = {},
+): CrudSql {
+  const startAt = options.startAt ?? 1;
+  const convertFragment = options.convertFragment ?? identityFragment;
+
+  if (typeof filter === "string") {
+    const where = filter ? ` WHERE ${convertFragment(filter, startAt)}` : "";
+    return {
+      sql: `DELETE FROM ${dialect.quote(table)}${where}`,
+      values: params ?? [],
+    };
+  }
+
+  const whereClauses = buildWhereClause(dialect, Object.keys(filter), startAt);
+  return {
+    sql: `DELETE FROM ${dialect.quote(table)} WHERE ${whereClauses}`,
+    values: Object.values(filter),
+  };
+}

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

@@ -7,9 +7,10 @@ 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 { ANSI_DIALECT } from "./sqlDialect.js";
+import { buildDelete, buildInsertRow, buildInsertRows, buildUpdate } from "./sqlCrud.js";
 import { mkdirSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslator.js";
 
@@ -76,31 +77,45 @@ function sqliteVersionAtLeast(major: number, minor: number, patch: number): bool
  *
  * Matches the tina4-python + tina4-php convention:
  *   ":memory:"         → passthrough
- *   "data/app.db"      → {cwd}/data/app.db  (auto-mkdir under cwd)
+ *   "data/app.db"      → {cwd}/data/app.db  (parent auto-created, mode 0775)
  *   "/abs/app.db"      → /abs/app.db        (NO auto-mkdir; user's responsibility)
- *   "C:/Users/app.db"  → C:/Users/app.db    (NO auto-mkdir)
+ *   "C:/Users/app.db"  → C:/Users/app.db    (recognised as absolute on EVERY OS)
+ *   "../../etc/foo.db" → REFUSED loudly (its parent escapes cwd)
  *
- * Never mkdir a directory that isn't a descendant of cwd — that was the
- * root cause of the `EROFS: read-only file system, mkdir '/data'` crash
- * reported on macOS.
+ * The canonical contract is ADR-0086. Two things this pins that node:path alone
+ * gets wrong: a drive-letter path is absolute on POSIX too (isAbsolute does not
+ * recognise it, so it would be re-rooted under cwd), and a relative path whose
+ * parent escapes cwd must be REFUSED — never the silent mkdir outside the
+ * project that was the root cause of the `EROFS: mkdir '/data'` crash.
  */
-function resolveSqlitePath(dbPath: string): string {
+export function resolveSqlitePath(dbPath: string): string {
   if (dbPath === ":memory:") return dbPath;
 
-  let path = dbPath;
-  if (!isAbsolute(path)) {
-    path = join(process.cwd(), path);
-    // Auto-mkdir is safe here — we know the parent is under cwd
-    mkdirSync(dirname(path), { recursive: true });
-  } else {
-    // Absolute path. Only auto-mkdir if it's a descendant of cwd.
-    const cwd = resolve(process.cwd());
-    const abs = resolve(path);
-    if (abs.startsWith(cwd + "/") || abs === cwd) {
-      mkdirSync(dirname(abs), { recursive: true });
-    }
-    // Otherwise, trust the user — don't touch the filesystem.
+  // A Windows drive-letter path (C:/... or C:\...) is absolute on EVERY OS.
+  // node:path.isAbsolute does NOT recognise it on POSIX (it would re-root the
+  // path under cwd), so recognise it explicitly for parity (ADR-0086).
+  const isWindowsAbs = /^[A-Za-z]:[\\/]/.test(dbPath);
+  if (isAbsolute(dbPath) || isWindowsAbs) {
+    // Absolute — trust the user; never auto-mkdir (parity with the other three).
+    return dbPath;
   }
+
+  // Relative — resolve under cwd; create the parent (mode 0775) ONLY when it
+  // stays inside cwd. A relative path whose parent escapes the project is
+  // REFUSED loudly — never a silent mkdir outside the project.
+  const cwd = resolve(process.cwd());
+  const path = join(cwd, dbPath);
+  const parent = dirname(path);
+  const absParent = resolve(parent);
+  if (absParent !== cwd && !absParent.startsWith(cwd + sep)) {
+    throw new Error(
+      `SQLite path "${dbPath}" resolves outside the project directory: ` +
+        `"${absParent}" is not within "${cwd}". Tina4 refuses to create ` +
+        `directories outside the project (ADR-0086). Use an absolute path for a ` +
+        `database that lives outside the project.`,
+    );
+  }
+  mkdirSync(parent, { recursive: true, mode: 0o775 });
   return path;
 }
 
@@ -264,17 +279,13 @@ export class SQLiteAdapter implements DatabaseAdapter {
 
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult {
     if (Array.isArray(data)) {
-      if (data.length === 0) return { success: true, affectedRows: 0 };
-      const keys = Object.keys(data[0]);
-      const sql = buildInsert(ANSI_DIALECT, table, keys);
-      const paramsList = data.map((row) => keys.map((k) => row[k]));
-      const result = this.executeMany(sql, paramsList);
+      const batch = buildInsertRows(ANSI_DIALECT, table, data);
+      if (!batch) return { success: true, affectedRows: 0 };
+      const result = this.executeMany(batch.sql, batch.paramsList);
       return { success: true, affectedRows: result.affectedRows, lastId: result.lastId };
     }
 
-    const keys = Object.keys(data);
-    const sql = buildInsert(ANSI_DIALECT, table, keys);
-    const values = Object.values(data);
+    const { sql, values } = buildInsertRow(ANSI_DIALECT, table, data);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));
@@ -286,30 +297,11 @@ export class SQLiteAdapter implements DatabaseAdapter {
   }
 
   update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult {
-    const setClauses = buildSetClause(ANSI_DIALECT, Object.keys(data));
-
-    // A raw WHERE fragment + params is half the write_path contract's filter
-    // form ("a string filter with params works the same as a hash filter").
-    // Without this branch Object.keys("id = ?") yields the STRING INDICES
-    // ["0","1",...], producing `WHERE "0" = ? AND "1" = ?` and SQLite reports
-    // `no such column: "0"`. delete() below already carried this branch and
-    // update() did not — the same gap 3.13.94 closed in the postgres/mysql/
-    // mssql/firebird adapters, still open here on the DEFAULT engine.
-    if (typeof filter === "string") {
-      const where = filter ? ` WHERE ${filter}` : "";
-      const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses}${where}`;
-      const values = [...Object.values(data), ...(params ?? [])];
-      try {
-        const result = this.db.prepare(sql).run(...toSqlParams(values));
-        return { success: true, affectedRows: Number(result.changes) };
-      } catch (e) {
-        return { success: false, affectedRows: 0, error: (e as Error).message };
-      }
-    }
-
-    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
-    const sql = `UPDATE ${ANSI_DIALECT.quote(table)} SET ${setClauses} WHERE ${whereClauses}`;
-    const values = [...Object.values(data), ...Object.values(filter)];
+    // The string-filter vs hash-filter branch and the value assembly live in the
+    // shared composer (sqlCrud.ts); SQLite supplies only its driver execution.
+    // A raw WHERE fragment carries `?` markers, which SQLite uses natively, so no
+    // fragment rewrite is needed.
+    const { sql, values } = buildUpdate(ANSI_DIALECT, table, data, filter, params);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));
@@ -329,19 +321,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
       return { success: true, affectedRows: totalAffected };
     }
 
-    if (typeof filter === "string") {
-      const sql = filter ? `DELETE FROM "${table}" WHERE ${filter}` : `DELETE FROM "${table}"`;
-      try {
-        const result = this.db.prepare(sql).run(...toSqlParams(params ?? []));
-        return { success: true, affectedRows: Number(result.changes) };
-      } catch (e) {
-        return { success: false, affectedRows: 0, error: (e as Error).message };
-      }
-    }
-
-    const whereClauses = buildWhereClause(ANSI_DIALECT, Object.keys(filter));
-    const sql = `DELETE FROM ${ANSI_DIALECT.quote(table)} WHERE ${whereClauses}`;
-    const values = Object.values(filter);
+    const { sql, values } = buildDelete(ANSI_DIALECT, table, filter, params);
 
     try {
       const result = this.db.prepare(sql).run(...toSqlParams(values));

package/packages/orm/src/index.ts

@@ -93,7 +93,7 @@ export type {
 } from "./docstore.js";
 
 // Database adapters
-export { SQLiteAdapter } from "./adapters/sqlite.js";
+export { SQLiteAdapter, resolveSqlitePath } from "./adapters/sqlite.js";
 export { PostgresAdapter } from "./adapters/postgres.js";
 export type { PostgresConfig } from "./adapters/postgres.js";
 export { MysqlAdapter } from "./adapters/mysql.js";

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

@@ -0,0 +1,90 @@
+/**
+ * One CRUD write composer for every SQL engine, instead of one per adapter.
+ *
+ * `sqlDialect.ts` already collapsed the SQL *fragment* builders (columns, the
+ * SET list, the WHERE list). What it did NOT collapse was the METHOD BODIES:
+ * every SQL adapter's `insert`/`update`/`delete` re-implemented the SAME
+ * envelope around those fragments — the string-filter branch vs the hash-filter
+ * branch, the `[...Object.values(data), ...(params ?? [])]` value assembly, the
+ * batch fan-out — differing only in the two things a `Dialect` already captures
+ * (identifier quoting, parameter marker) plus three per-engine knobs:
+ *
+ *   INSERT SUFFIX     "" | " RETURNING *" | "; SELECT SCOPE_IDENTITY() AS id"
+ *   MARKER START      1 (PostgreSQL $N) | 0 (MSSQL @pN) | ignored (`?` engines)
+ *   FRAGMENT REWRITE  a raw "id = ?" WHERE string: identity on a `?` engine,
+ *                     convertPlaceholders/bindable on a positional one
+ *
+ * This is the Node port of the Python master's `SqlCrudMixin`
+ * (tina4_python/database/adapter.py): build the SQL and the ordered parameter
+ * list engine-neutrally from a dialect + those knobs, and hand the pair back to
+ * the adapter to EXECUTE.
+ *
+ * Like `sqlDialect.ts`, these functions build STRINGS and parameter arrays and
+ * NOTHING else. Execution and result extraction stay in the adapters on purpose:
+ * `this.db.prepare().run()` vs `await this.client!.query()` vs tedious vs a
+ * Firebird transaction handle, and RETURNING / SCOPE_IDENTITY() / lastId /
+ * affectedRows normalisation, are genuinely per-driver — folding them in here
+ * would trade a real duplication for a fake abstraction.
+ *
+ * MongoDB has no entry: it does not build SQL at all.
+ */
+import { type Dialect } from "./sqlDialect.js";
+/** A composed statement: the SQL text and its ordered parameter list. */
+export interface CrudSql {
+    sql: string;
+    values: unknown[];
+}
+/**
+ * A composed batch INSERT: one SQL statement plus one parameter row per input
+ * record, ready for the adapter's own `executeMany`.
+ */
+export interface CrudBatchSql {
+    sql: string;
+    paramsList: unknown[][];
+}
+/** The only per-engine differences in a composed write's SQL + parameter list. */
+export interface WriteOptions {
+    /**
+     * 1-based position of the FIRST parameter marker. PostgreSQL numbers `$N`
+     * from 1; MSSQL names `@pN` from 0 and BINDS by that name, so the start must
+     * match its binding loop. Engines whose marker is `?` ignore it. Default 1.
+     */
+    startAt?: number;
+    /**
+     * Rewrite a raw string WHERE fragment's `?` markers for this engine, given the
+     * 1-based position of the fragment's first marker. `?` engines leave it
+     * untouched (the default); a positional engine passes its `convertPlaceholders`
+     * / `bindable`. Only ever applied to the developer-supplied string filter,
+     * never to the framework-built hash WHERE.
+     */
+    convertFragment?: (fragment: string, startAt: number) => string;
+}
+/**
+ * A single-row INSERT: `INSERT INTO t (a, b) VALUES (?, ?)<suffix>` and the row's
+ * values in column order. `suffix` carries the genuinely engine-specific tail
+ * (PostgreSQL's ` RETURNING *`, MSSQL's SCOPE_IDENTITY() probe).
+ */
+export declare function buildInsertRow(dialect: Dialect, table: string, data: Record<string, unknown>, suffix?: string, options?: WriteOptions): CrudSql;
+/**
+ * A batch INSERT from a list of rows — one parameterised statement the adapter
+ * runs once per row via its own `executeMany`. Returns `null` for an empty list
+ * (the adapters treat that as a no-op affecting zero rows). The keys come from
+ * the first row, exactly as every adapter already assumed.
+ */
+export declare function buildInsertRows(dialect: Dialect, table: string, rows: Record<string, unknown>[]): CrudBatchSql | null;
+/**
+ * An UPDATE from a data object and either a hash filter (`{id: 5}` →
+ * `WHERE "id" = ?`) or a raw string filter (`"id = ?"` + `params`). The SET
+ * values always lead the parameter list; the WHERE values follow.
+ */
+export declare function buildUpdate(dialect: Dialect, table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[], options?: WriteOptions): CrudSql;
+/**
+ * A DELETE from either a hash filter (`{id: 5}` → `WHERE "id" = ?`) or a raw
+ * string filter (`"age < ?"` + `params`). An empty string filter deletes the
+ * whole table (the explicit `truncate()` spelling routes through here).
+ *
+ * The array-of-dicts filter form is NOT handled here: only SQLite and ODBC
+ * accept it, and both loop it into per-row `delete` calls that land back in one
+ * of the two branches above — that fan-out stays in those two adapters.
+ */
+export declare function buildDelete(dialect: Dialect, table: string, filter: Record<string, unknown> | string, params?: unknown[], options?: WriteOptions): CrudSql;

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

@@ -1,4 +1,21 @@
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+/**
+ * Resolve a SQLite path argument against the project root (cwd).
+ *
+ * Matches the tina4-python + tina4-php convention:
+ *   ":memory:"         → passthrough
+ *   "data/app.db"      → {cwd}/data/app.db  (parent auto-created, mode 0775)
+ *   "/abs/app.db"      → /abs/app.db        (NO auto-mkdir; user's responsibility)
+ *   "C:/Users/app.db"  → C:/Users/app.db    (recognised as absolute on EVERY OS)
+ *   "../../etc/foo.db" → REFUSED loudly (its parent escapes cwd)
+ *
+ * The canonical contract is ADR-0086. Two things this pins that node:path alone
+ * gets wrong: a drive-letter path is absolute on POSIX too (isAbsolute does not
+ * recognise it, so it would be re-rooted under cwd), and a relative path whose
+ * parent escapes cwd must be REFUSED — never the silent mkdir outside the
+ * project that was the root cause of the `EROFS: mkdir '/data'` crash.
+ */
+export declare function resolveSqlitePath(dbPath: string): string;
 export declare class SQLiteAdapter implements DatabaseAdapter {
     private db;
     private _lastInsertId;

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

@@ -31,7 +31,7 @@ export { seedTable, seedOrm, seedModels, autoFieldMap } from "./seeder.js";
 export type { SeedSummary, SeedOptions } from "./seeder.js";
 export { ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor, getCollection, isServerless, resetDefaultStore, closeDocStore, encodeValue, decodeValue, compileFilter, } from "./docstore.js";
 export type { InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, } from "./docstore.js";
-export { SQLiteAdapter } from "./adapters/sqlite.js";
+export { SQLiteAdapter, resolveSqlitePath } from "./adapters/sqlite.js";
 export { PostgresAdapter } from "./adapters/postgres.js";
 export type { PostgresConfig } from "./adapters/postgres.js";
 export { MysqlAdapter } from "./adapters/mysql.js";