tina4-nodejs 3.13.137 → 3.13.139

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

@@ -38,6 +38,17 @@ export declare class PostgresAdapter implements DatabaseAdapter {
     /** Ensure bytea columns are Buffer (already the case with pg). No-op guard. */
     private decodeBlobs;
     private convertPlaceholders;
+    /**
+     * 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;
     /**
      * Normalise an `id` column value (typed `unknown` because pg row values are
      * `unknown`) into the shape `_lastInsertId` / `DatabaseResult.lastId`

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

@@ -29,6 +29,21 @@ export interface Dialect {
      */
     marker(index: number): string;
 }
+/**
+ * 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 declare function quoteIdentifierWith(name: string, open: string, close: string, upperCase?: boolean): string;
+/** The ANSI default: `"name"` (SQLite, PostgreSQL, MSSQL, ODBC). */
+export declare function quoteIdentifierAnsi(name: string): string;
 /** SQLite, and ODBC which follows the SQL standard spelling. */
 export declare const ANSI_DIALECT: Dialect;
 /** PostgreSQL: standard quoting, positional $N markers. */
@@ -43,6 +58,16 @@ export declare const MSSQL_DIALECT: Dialect;
  * adapter owns that rule and passes its own quoter in.
  */
 export declare function firebirdDialect(fbQuote: (name: string) => string): Dialect;
+/**
+ * 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 declare function assertColumnNames(keys: Iterable<string>): void;
 /**
  * `INSERT INTO <table> (<cols>) VALUES (<markers>)`.
  *

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

@@ -36,6 +36,13 @@ export declare class SQLiteAdapter implements DatabaseAdapter {
     execute(sql: string, params?: unknown[]): unknown;
     executeMany(sql: string, paramsList: unknown[][]): DatabaseResult;
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): 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[];
     fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
     fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
     insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;

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

@@ -112,6 +112,11 @@ export declare class BaseModel {
      * SQLite URLs are initialised synchronously. Other engines require initDatabase()
      * to be called before first use.
      */
+    /**
+     * Quote a table/column name in the dialect of the adapter this model runs on
+     * (MySQL backticks, Firebird upper-cased, `"name"` elsewhere).
+     */
+    protected static quoteName(name: string): string;
     protected static getDb(): DatabaseAdapter;
     /**
      * Get the primary key field name (JS property name).

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

@@ -144,10 +144,31 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     private backendSetRows;
     private backendGetOne;
     private backendSetOne;
+    /**
+     * A write that arrives through a READ method (fetch/fetchOne/query of an
+     * `INSERT ... RETURNING`) is still a write: its result must never be cached
+     * (a repeat would answer from the cache and never insert) and it flushes the
+     * cache like every other write (tina4-python#133 contract).
+     */
+    private isWriteRead;
+    /** Run a write that came through a read method, then flush (never store). */
+    private runWrite;
+    private runWriteAsync;
     /** ADR-0044 required capability — delegates to the wrapped adapter. */
     connect(): void | Promise<void>;
+    /**
+     * The derived-table alias the COUNT probe needs, forwarded from the wrapped
+     * adapter. SQL Server and MySQL REQUIRE `FROM (<sql>) AS _count_query`; the
+     * probe reads this property off whatever adapter it is handed, and
+     * Database.create() hands it THIS wrapper. Without the forward the probe ran
+     * unaliased, the engine rejected it, the error was swallowed, and
+     * `result.count` silently became the page length on those two engines.
+     */
+    get countSubqueryAlias(): string | undefined;
     /** ADR-0044 required capability — delegates to the wrapped adapter. */
     getDatabaseType(): string;
+    /** Identifier quoting is the wrapped engine's, never the wrapper's. */
+    quoteIdentifier(name: string): string;
     /**
      * ADR-0044 required capability — a native boolean, readable and writable.
      * A getter/setter pair (not a plain field) so it genuinely delegates to the
@@ -158,6 +179,12 @@ export declare class CachedDatabaseAdapter implements DatabaseAdapter {
     get supportsAtomicBatch(): boolean;
     set supportsAtomicBatch(value: boolean);
     execute(sql: string, params?: unknown[]): unknown;
+    /**
+     * Forward an adapter's row-returning execute (SQLite, Firebird), for
+     * Database.execute(). Resolves `undefined` when the wrapped adapter has none
+     * - WITHOUT running anything - so the caller falls back to execute().
+     */
+    executeRowsAsync(sql: string, params?: unknown[]): Promise<unknown[] | undefined>;
     executeMany(sql: string, paramsList: unknown[][]): import("./types.js").DatabaseResult | {
         totalAffected: number;
         lastId?: number | bigint;

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

@@ -28,8 +28,27 @@ export declare function stripTrailingSemicolons(sql: string): string;
  * the single chokepoint every public read/write flows through.
  */
 export declare function adapterFetch<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): Promise<T[]>;
+/**
+ * Quote a table/column name the ORM emits, in the bound adapter's dialect
+ * (MySQL backticks, Firebird upper-cased, `"name"` elsewhere). Python master:
+ * `Database.quote_identifier`. Only for framework-emitted identifiers - a
+ * user's raw SQL is never rewritten.
+ */
+export declare function quoteIdentifier(adapter: DatabaseAdapter | null | undefined, name: string): string;
 export declare function adapterQuery<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<T[]>;
 export declare function adapterFetchOne<T = Record<string, unknown>>(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<T | null>;
+/**
+ * Run a row-producing statement through an adapter's own row-returning execute
+ * (SQLite's executeRows, Firebird's executeRowsAsync, or the cache wrapper
+ * forwarding either). `undefined` means the adapter has none and NOTHING ran.
+ */
+export declare function adapterExecuteRows(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<unknown[] | undefined>;
+/**
+ * The rows inside a driver's execute() result: pg and tedious carry `.rows`,
+ * mysql2 and odbc return the row array itself, and a MySQL CALL returns
+ * `[[rows], OkPacket]`. `undefined` when the result carries no row list.
+ */
+export declare function rowsFromExecuteResult(result: unknown): unknown[] | undefined;
 export declare function adapterExecute(adapter: DatabaseAdapter, sql: string, params?: unknown[]): Promise<unknown>;
 /**
  * ADR-0044: the adapter-level batch primitive, called exactly once by
@@ -277,6 +296,11 @@ export declare class Database {
      * the same Database don't clobber each other. startTransaction() sets the
      * pin via .enterWith(); commit()/rollback() clear it.
      */
+    private leases;
+    private discardedSlots;
+    private repairs;
+    private leaseOwner;
+    private operationStore;
     private txStore;
     /**
      * Create a Database wrapping an existing adapter.
@@ -317,8 +341,13 @@ export declare class Database {
      * that adapter is returned for every call so the whole transaction is
      * atomic on one connection. Otherwise pooled mode round-robins.
      */
+    private availableAdapter;
+    private reserveAdapter;
+    private releaseAdapter;
+    private repairDiscardedConnections;
+    private withConnectionOperation;
     private getNextAdapter;
-    /** Get the underlying adapter (for advanced / escape-hatch usage). */
+    /** Non-owning peek excluding leased connections. Use checkout/checkin for concurrent raw driver work. */
     getAdapter(): DatabaseAdapter;
     /** Get the pool size (0 = single connection mode). */
     poolSize(): number;
@@ -331,12 +360,8 @@ export declare class Database {
      * The caller is responsible for returning it via checkin().
      */
     checkout(): DatabaseAdapter;
-    /**
-     * Return a borrowed connection to the pool.
-     * For round-robin pools this is a no-op (connections stay in the pool array),
-     * but the method exists for API parity and future pooling strategies.
-     */
-    checkin(_adapter: DatabaseAdapter): void;
+    /** Only the borrowing async context can release an explicit lease. */
+    checkin(adapter: DatabaseAdapter): void;
     /**
      * Close all pooled connections and clear the pool.
      * Equivalent to close() but named for explicit pool teardown.
@@ -405,6 +430,12 @@ export declare class Database {
     fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: {
         noCache?: boolean;
     }): Promise<T[]>;
+    /**
+     * Close a write that ran through fetch()/fetchOne() the way execute() closes
+     * its own: auto-commit outside an explicit transaction, and leave it to the
+     * caller's commit()/rollback() inside one.
+     */
+    private commitFetchWrite;
     /**
      * Execute a write statement.
      *
@@ -459,6 +490,14 @@ export declare class Database {
      * throws rather than silently changing nothing (audit feature 4, P1).
      */
     update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseWriteResult>;
+    /**
+     * ADR-0069 (G3): a data or filter-map key must be a plain identifier - it is
+     * emitted as a column name. Checked here, before any adapter work, so every
+     * engine raises the same error; the SQL builders (sqlDialect) check again for
+     * callers that use an adapter directly. MongoDB builds no SQL and its keys are
+     * document paths, so it is left alone.
+     */
+    private assertWriteKeys;
     /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
     delete(table: string, filter?: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseWriteResult>;
     /** Remove every row. The explicit spelling of a whole-table delete. */

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

@@ -1,11 +1,3 @@
-/**
- * Graph connection URL parser — the DatabaseUrl sibling for graph engines.
- *
- * Parse a graph connection URL into its parts, the same way DatabaseUrl does for
- * SQL. `engine` is the CANONICAL name the factory selects an adapter by; a scheme
- * alias (bolt/neo4j/memgraph all speak Bolt/Cypher and share ONE adapter) resolves
- * to its engine here. See tina4-documentation/plan/v3/features/139-graph-databases.md.
- */
 /** The canonical graph engine names. */
 export type GraphEngine = "ultipa" | "bolt" | "arango";
 /** A parsed graph URL: engine, host, port, graph, credentials, params. */

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

@@ -15,7 +15,7 @@ export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, rec
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes, crudEligibleModels } from "./autoCrud.js";
 export type { AutoCrudOptions } from "./autoCrud.js";
-export { buildQuery, parseQueryString } from "./query.js";
+export { buildQuery, parseQueryString, UnknownFieldError, InvalidQueryParameterError } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";

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

@@ -1,4 +1,4 @@
-import type { QueryOptions } from "./types.js";
+import type { FieldDefinition, QueryOptions } from "./types.js";
 export interface ParsedQuery {
     where: string;
     orderBy: string;
@@ -6,12 +6,58 @@ export interface ParsedQuery {
     offset: number;
     params: unknown[];
 }
-export declare function buildQuery(tableName: string, options: QueryOptions, extraConditions?: string[]): {
+/**
+ * Resolve a caller-supplied key to the model's DB column, or null when the key
+ * is not a declared field.
+ *
+ * tina4: ADR-0069 - identifiers that reach SQL come from the model, never the
+ * request. The key may be a declared field (property) name or that field's
+ * column name; either way the column returned is the model's own, so nothing
+ * but a declared column can be emitted. `columnOf` is the caller's existing
+ * property->column mapping (BaseModel.getDbColumn / AutoCrud's getDbCol), so
+ * the mapping rule lives in one place. Own keys only, so an inherited Object
+ * property can never resolve. Used by AutoCrud (filter + sort) and by
+ * BaseModel.find(object).
+ */
+export declare function resolveFieldColumn(fields: Record<string, FieldDefinition>, columnOf: (field: string) => string, key: string): string | null;
+/**
+ * The declared FIELD (property) name a key names - by the field name itself or
+ * by its column - or null. The write-side twin of resolveFieldColumn(): AutoCrud
+ * writes need the field, to validate the body and then map it to its column.
+ */
+export declare function resolveField(fields: Record<string, FieldDefinition>, columnOf: (field: string) => string, key: string): string | null;
+/** A filter or sort key that does not resolve to a declared model field. */
+export declare class UnknownFieldError extends Error {
+    readonly kind: "filter" | "sort";
+    readonly field: string;
+    constructor(kind: "filter" | "sort", field: string);
+}
+/** A query parameter whose SHAPE is wrong (a list or map where one value belongs). */
+export declare class InvalidQueryParameterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build the list SQL from parsed query options.
+ *
+ * `quote` renders every table/column name the builder emits - pass the bound
+ * adapter's dialect (`(name) => quoteIdentifier(adapter, name)`); the default is
+ * the ANSI `"name"`.
+ *
+ * Every filter key and sort field is passed through `resolveColumn` (see
+ * resolveFieldColumn) and only the column it returns is emitted; a key it does
+ * not resolve throws UnknownFieldError before any SQL exists. With no
+ * resolver, no filter or sort key resolves (ADR-0069).
+ */
+export declare function buildQuery(tableName: string, options: QueryOptions, extraConditions?: string[], quote?: (name: string) => string, resolveColumn?: (key: string) => string | null): {
     sql: string;
     countSql: string;
     params: unknown[];
     limit: number;
     offset: number;
     page: number;
+    /** The same SELECT without LIMIT/OFFSET, for adapterFetch to page in the engine's own syntax. */
+    pageSql: string;
+    /** The filter parameters alone (params minus the trailing limit/offset). */
+    filterParams: unknown[];
 };
 export declare function parseQueryString(query: Record<string, string>): QueryOptions;

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

@@ -33,7 +33,8 @@ export declare class LocalStorage implements StorageBackend {
     exists(key: string): boolean;
 }
 /**
- * S3-compatible store (AWS S3, MinIO, ...). Opt-in; needs @aws-sdk/client-s3.
+ * S3-compatible store (AWS S3, MinIO, ...). Opt-in; the app installs the SDK:
+ * `npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner`.
  * Presigned GET URLs let clients fetch large blobs straight from object
  * storage instead of streaming through the app.
  */

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

@@ -1,21 +1,3 @@
-/**
- * Tina4 SQL Translation — Cross-engine SQL translator.
- *
- * Translates SQL dialect differences between engines so that application
- * code can use a single SQL style and have it adapted at runtime.
- *
- *   import { SQLTranslator } from "@tina4/orm";
- *
- *   // Firebird: LIMIT/OFFSET → ROWS X TO Y
- *   SQLTranslator.limitToRows("SELECT * FROM users LIMIT 10 OFFSET 5");
- *   // → "SELECT * FROM users ROWS 6 TO 15"
- *
- *   // MSSQL: LIMIT → TOP N
- *   SQLTranslator.limitToTop("SELECT * FROM users LIMIT 10");
- *   // → "SELECT TOP 10 * FROM users"
- *
- * Also includes a query cache with TTL support.
- */
 export declare class SQLTranslator {
     private static readonly SPATIAL_ENGINES;
     private static readonly SPATIAL_IDENTIFIER;
@@ -101,6 +83,29 @@ export declare class SQLTranslator {
      * ? → :1, :2, :3 (Oracle, Firebird)
      */
     static placeholderStyle(sql: string, style: string): string;
+    /**
+     * Offsets of the REAL `?` placeholders in a statement: every `?` that is not
+     * inside a string literal ('...', Postgres E'...', dollar-quoted $$...$$ /
+     * $tag$...$tag$), a quoted identifier ("..." or `...`), or a comment (-- to
+     * end of line, /* ... *\/). A plain text replace turned the `?` in
+     * `SELECT 'why?' AS v, ? AS n` into a placeholder and shifted every binding
+     * after it (tina4-python#138).
+     *
+     * @param sql Raw SQL, exactly as the caller wrote it.
+     * @param options.backslashEscapes Treat `\` as an escape inside '...' and
+     *   "..." as well (MySQL's default string syntax). E'...' always does.
+     */
+    static placeholderPositions(sql: string, options?: {
+        backslashEscapes?: boolean;
+    }): number[];
+    /**
+     * Replace each REAL `?` placeholder (see placeholderPositions) with
+     * `marker(index)`, index counting from 0. Literals, quoted identifiers and
+     * comments are copied through untouched.
+     */
+    static replacePlaceholders(sql: string, marker: (index: number) => string, options?: {
+        backslashEscapes?: boolean;
+    }): string;
     /**
      * Detect and strip RETURNING clause from INSERT/UPDATE statements.
      * Returns the cleaned SQL and the list of RETURNING columns.
@@ -204,6 +209,53 @@ export declare class SQLTranslator {
      * @param sql Raw SQL; literals and comments are scrubbed before matching.
      */
     static hasTrailingLimit(sql: string): boolean;
+    /**
+     * Strip a trailing TOP-LEVEL `ORDER BY` so the statement can be wrapped in
+     * `SELECT COUNT(*) FROM (<sql>) AS _count_query` for the row-count probe.
+     *
+     * SQL Server rejects an ORDER BY inside a derived table unless it carries
+     * TOP/OFFSET/FETCH (error 1033), so the probe failed - and the total fell
+     * back to the page length - for any read ending in ORDER BY. ORDER BY cannot
+     * change a COUNT, so dropping it for the probe ONLY is safe; the paginated
+     * query keeps it. An ORDER BY nested in a subquery, or one already legalised
+     * by a following OFFSET/FETCH/FOR, is left intact. Positions are found on the
+     * scrubbed text, so an `ORDER BY` inside a literal or comment is ignored.
+     * Parity with Python `_strip_trailing_order_by` / PHP `stripTrailingOrderBy`.
+     *
+     * @param sql The read statement the probe is about to wrap.
+     */
+    static stripTrailingOrderBy(sql: string): string;
+    /**
+     * True when the statement CHANGES data, even though it may return rows.
+     *
+     * fetch()/fetchOne() are the natural way to run a write that RETURNS rows
+     * (`INSERT ... RETURNING id`, SQL Server's `OUTPUT inserted.id`), so they
+     * cannot treat every statement as a read (tina4-python#133). A write is one
+     * whose first word is a DML verb, or a `WITH` whose body holds one (a
+     * data-modifying CTE ends in SELECT). The shared cross-framework contract:
+     * a write through fetch/fetchOne runs exactly once, with no COUNT probe and
+     * no LIMIT/OFFSET/ROWS/TOP pagination, is never cached, and commits like
+     * execute(). Python's `_is_write_statement` answers identically.
+     *
+     * Literals and comments are scrubbed first, so `WHERE note = 'DELETE'` stays
+     * a read. Erring towards "write" is the safe direction: a read misread as a
+     * write only loses its pagination and cache for that one call.
+     *
+     * @param sql Raw SQL, exactly as the caller wrote it.
+     */
+    static isWriteStatement(sql: string): boolean;
+    /**
+     * Which kind of rows a statement produces, for execute() (cross-framework
+     * contract): "read" (SELECT, WITH ... SELECT, VALUES, SHOW, EXPLAIN,
+     * DESCRIBE), "returning" (a write with RETURNING, or SQL Server's OUTPUT
+     * inserted./deleted.), "procedure" (CALL / EXEC / EXECUTE, which may return a
+     * result set), or null for a statement that produces none. A data-modifying
+     * CTE (WITH ... INSERT ... SELECT) produces rows too, so it is "read" here and
+     * a write for isWriteStatement(). Literals and comments are scrubbed first.
+     *
+     * @param sql Raw SQL, exactly as the caller wrote it.
+     */
+    static rowsKind(sql: string): "read" | "returning" | "procedure" | null;
     /**
      * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
      *

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

@@ -99,6 +99,12 @@ export interface DatabaseAdapter {
     connect(): void | Promise<void>;
     /** Return the canonical, credential-free engine name ("sqlite", "postgres", ...). */
     getDatabaseType(): string;
+    /**
+     * Quote a table/column name the ORM emits, in this engine's dialect
+     * (Python master: `quote_identifier`). Optional: an adapter without it gets
+     * the ANSI `"name"` default through `quoteIdentifier(adapter, name)`.
+     */
+    quoteIdentifier?(name: string): string;
     /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
     execute(sql: string, params?: unknown[]): unknown;
     /**