tina4-nodejs 3.13.95 → 3.13.97

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

@@ -38,6 +38,40 @@ export declare function adapterTableExists(adapter: DatabaseAdapter, name: strin
 export declare function adapterTables(adapter: DatabaseAdapter): Promise<string[]>;
 export declare function adapterColumns(adapter: DatabaseAdapter, table: string): Promise<ColumnInfo[]>;
 export declare function adapterCreateTable(adapter: DatabaseAdapter, name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+/**
+ * The true row count for `sql`, ignoring the pagination the caller applied.
+ *
+ * `count` on a DatabaseResult is the TRUE TOTAL for the filter, not the number
+ * of rows the page returned. Node and Ruby used to populate it with
+ * `records.length` while Python and PHP populated it from a probe, so
+ * `db.fetch(sql).count` answered 20 here and 250 there for one query against one
+ * table, and every `toPaginate()` envelope built on it under-reported (ADR-0043).
+ * MEASURED 2026-08-05 on a 250-row table read with limit=20: Node reported total
+ * 20 over 2 pages against Python's 250 over 13.
+ *
+ * This is the single source of truth for that probe. Both read paths that build a
+ * DatabaseResult — `Database.fetch()` and `QueryBuilder.get()` — call it, so the
+ * two can never drift (QueryBuilder.get used to leave `count` at rows-returned,
+ * diverging from db.fetch AND from Python/Ruby, whose get() routes through fetch).
+ *
+ * Only probed when a limit was actually applied. With no limit the rows returned
+ * ARE the whole answer for this SQL, so `records.length` is already the true total
+ * and a second round-trip would buy nothing — which is also what keeps
+ * `fetchAll()` at one query.
+ *
+ * BEST EFFORT, and it can never mask a real failure: it runs AFTER the main query
+ * (which has already thrown on bad SQL) and returns `undefined` on any error.
+ * `undefined` — not 0 — is the miss value, so DatabaseResult falls back to
+ * records.length, a true lower bound. Reporting 0 next to 100 real records would
+ * be the same "states a wrong number authoritatively" defect this exists to remove.
+ *
+ * The closing paren goes on its OWN LINE: appended inline, a trailing
+ * `-- comment` in the caller's SQL comments it out and the probe dies with
+ * "incomplete input". Postgres, MySQL and MSSQL additionally require a name for
+ * the derived table; SQLite and Firebird do not, and Firebird rejects `AS` there —
+ * so the alias comes from the adapter, not an assumption.
+ */
+export declare function probeTotal(adapter: DatabaseAdapter, sql: string, params: unknown[] | undefined, limit: number | undefined): Promise<number | undefined>;
 /**
  * Extract the engine-assigned auto-increment id from an `execute()` result.
  *
@@ -314,36 +348,6 @@ export declare class Database {
      * inherit it and stop returning every row.
      */
     private _fetchWithLimit;
-    /**
-     * The true row count for `sql`, ignoring the pagination we appended.
-     *
-     * `count` is the TRUE TOTAL for the filter, not the number of rows this page
-     * returned. Node and Ruby used to populate it with `records.length` while
-     * Python and PHP populated it from a probe, so `db.fetch(sql).count` answered
-     * 20 here and 250 there for one query against one table, and every paginated
-     * response built on it under-reported. MEASURED 2026-08-05 on a 250-row table
-     * read with limit=20: Node reported total 20 over 2 pages against Python's
-     * 250 over 13.
-     *
-     * Only probed when a limit was actually applied. With no limit the rows
-     * returned ARE the whole answer for this SQL, so `records.length` is already
-     * the true total and a second round-trip would buy nothing — which is also
-     * what keeps `fetchAll()` at one query.
-     *
-     * BEST EFFORT, and it can never mask a real failure: it runs AFTER the main
-     * query (which has already thrown on bad SQL) and returns undefined on any
-     * error. `undefined` — not 0 — is the miss value, so DatabaseResult falls
-     * back to records.length, a true lower bound. Reporting 0 next to 100 real
-     * records would be the same "states a wrong number authoritatively" defect
-     * this change exists to remove.
-     *
-     * The closing paren goes on its OWN LINE: appended inline, a trailing
-     * `-- comment` in the caller's SQL comments it out and the probe dies with
-     * "incomplete input". Postgres, MySQL and MSSQL additionally require a name
-     * for the derived table; SQLite and Firebird do not, and Firebird rejects
-     * `AS` there — so the alias comes from the adapter, not an assumption.
-     */
-    private countProbe;
     /**
      * Fetch a single row or null.
      *

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

@@ -31,53 +31,43 @@ export declare class DatabaseResult implements Iterable<Record<string, unknown>>
     toCsv(): string;
     /** Same as records — plain array of row objects. */
     toArray(): Record<string, unknown>[];
-    /** Pagination envelope — accepts either (page, perPage) or (offset, limit) style.
+    /**
+     * Describe the page this result IS — the canonical pagination envelope.
      *
-     * When called with two arguments both >= 0 and the first >= the second
-     * (i.e. offset-style), pass `{ offset, limit }` as the first argument.
-     * The simplest way is to always use the default (page, perPage) form and
-     * let the autoCRUD layer supply offset/limit from the query string.
+     * Takes NO arguments and derives every field from the query that produced this
+     * result (ADR-0043). Passing ANY argument RAISES: a DatabaseResult holds no
+     * connection, so an argument could only re-slice the rows already in memory and
+     * then report total_pages for pages it can never reach. To read page N, FETCH
+     * page N (limit + offset) and call this with no arguments.
      *
-     * Returns a superset of keys for backwards-compatibility across all clients.
-     */
-    /**
-     * Describe the page this result actually IS. Takes no arguments.
+     * The envelope is EXACTLY seven snake_case keys, identical across all four
+     * frameworks: `records, total, page, per_page, total_pages, limit, offset`.
      *
-     * MEASURED 2026-08-05 on a real 250-row table read with limit=20 offset=40
-     * (page 3 of 13): this reported page 1 of 2 and returned 10 of the 20 rows.
-     * It ignored the query entirely - defaulting page to 1 and perPage to 10 -
-     * then re-sliced the rows it was handed, which were already just that page.
-     * So a caller who paginated correctly at the SQL level had the answer
-     * silently re-paginated underneath them, with a page number that was simply
-     * wrong.
+     *   per_page    = the query's limit
+     *   page        = floor(offset / limit) + 1
+     *   total       = the TRUE total for the filter — Database.fetch (and
+     *                 QueryBuilder.get) run a COUNT probe whenever a limit was
+     *                 applied — NEVER the number of rows returned
+     *   total_pages = ceil(total / per_page)
+     *   records     = the rows the query returned, VERBATIM (never re-sliced)
+     *   limit       = the SQL limit actually applied
+     *   offset      = the SQL offset actually applied
      *
-     * WITH page/perPage it slices this result in memory, the behaviour GitHub
-     * issue #106 asked for. Valid ONLY when the result holds the WHOLE set
-     * (records.length >= count). A PARTIAL result cannot be sliced by page number
-     * without lying: MEASURED on 100,000 rows read under the default cap of 100,
-     * pages 1-5 of 20 were right and every page from 6 onward came back EMPTY
-     * while totalPages reported 5,000.
+     * The JSON payload is snake_case even though the method name is camelCase — a
+     * JSON key is data, not a language surface (ADR-0043). The old duplicate and
+     * camelCase keys (`data`, `count`, `perPage`, `totalPages`, `has_next`,
+     * `has_prev`) are removed: Node emitted 13 keys, the worst offender of the four.
      *
-     * `total` is `count`, and `count` is now the TRUE total for the filter in
-     * all four frameworks - Database.fetch runs a COUNT probe whenever it applied
-     * a limit. It used to be ROWS RETURNED here and in Ruby while Python and PHP
-     * probed, so one query answered 20 in two frameworks and 250 in the other
-     * two.
+     * @throws {TypeError} if called with any argument.
      */
-    toPaginate(page?: number, perPage?: number): {
+    toPaginate(): {
         records: Record<string, unknown>[];
-        data: Record<string, unknown>[];
-        count: number;
         total: number;
-        limit: number;
-        offset: number;
         page: number;
         per_page: number;
-        perPage: number;
-        totalPages: number;
         total_pages: number;
-        has_next: boolean;
-        has_prev: boolean;
+        limit: number;
+        offset: number;
     };
     /** Iterable — for (const row of result) */
     [Symbol.iterator](): Iterator<Record<string, unknown>>;

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

@@ -1,5 +1,4 @@
-export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, PaginatedResult, } from "./types.js";
-export { FetchResult } from "./types.js";
+export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, } from "./types.js";
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
 export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";

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

@@ -206,7 +206,7 @@ export declare function status(adapter?: DatabaseAdapter, options?: {
  */
 export declare function createMigration(description: string, options?: {
     migrationsDir?: string;
-    kind?: "sql" | "class";
+    kind?: "sql" | "code" | "class";
 }): Promise<string | {
     upPath: string;
     downPath: string;
@@ -258,11 +258,12 @@ export declare class Migration {
      * Scaffold a new migration file.
      *
      * kind="sql"   — creates {timestamp}_{description}.sql + .down.sql (default)
-     * kind="class" — creates {timestamp}_{description}.ts with a TypeScript class template
+     * kind="code"  — creates {timestamp}_{description}.ts with a TypeScript class
+     *                 template. "class" is accepted as a legacy alias.
      *
      * Returns the path to the created up file (or class file).
      */
-    create(description: string, kind?: "sql" | "class"): Promise<string | {
+    create(description: string, kind?: "sql" | "code" | "class"): Promise<string | {
         upPath: string;
         downPath: string;
     }>;

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

@@ -28,6 +28,13 @@ export interface RelationshipDefinition {
 }
 export interface ModelDefinition {
     tableName: string;
+    /**
+     * The model CLASS name (e.g. `Item` for tableName `items`), carried from
+     * `ModelClass.name` at discovery. Swagger keys `components.schemas` by this —
+     * the type name a generated client wants — falling back to a singular
+     * PascalCase derivation of tableName when a raw definition carries none.
+     */
+    className?: string;
     fields: Record<string, FieldDefinition>;
     fieldMapping?: Record<string, string>;
     softDelete?: boolean;
@@ -106,40 +113,6 @@ export interface DatabaseAdapter {
      */
     cacheIdentity?: string;
 }
-export interface PaginatedResult<T = Record<string, unknown>> {
-    data: T[];
-    page: number;
-    perPage: number;
-    total: number;
-    totalPages: number;
-    hasNext: boolean;
-    hasPrev: boolean;
-}
-/**
- * Wraps an array of fetched rows with convenience methods.
- *
- * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
- */
-export declare class FetchResult<T = Record<string, unknown>> {
-    readonly records: T[];
-    readonly count: number;
-    readonly sql: string;
-    constructor(records: T[], sql?: string);
-    /** Paginate the in-memory result set. */
-    toPaginate(page?: number, perPage?: number): PaginatedResult<T>;
-    /** Return the first record or null. */
-    first(): T | null;
-    /** Return the last record or null. */
-    last(): T | null;
-    /** Check if result is empty. */
-    isEmpty(): boolean;
-    /** Convert to plain array. */
-    toArray(): T[];
-    /** Convert to JSON string. */
-    toJSON(): string;
-    /** Iterate over records. */
-    [Symbol.iterator](): Iterator<T>;
-}
 export interface QueryOptions {
     filter?: Record<string, unknown>;
     sort?: string;