tina4-nodejs 3.13.138 → 3.13.140

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";