tina4-nodejs 3.13.137 → 3.13.138

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;
     /**