tina4-nodejs 3.13.95 → 3.13.97

package/packages/orm/src/autoCrud.ts

@@ -1,6 +1,7 @@
 import type { RouteDefinition, Tina4Request, Tina4Response } from "../../core/src/index.js";
 import type { DiscoveredModel } from "./model.js";
 import { getAdapter, adapterQuery, adapterExecute } from "./database.js";
+import { DatabaseResult } from "./databaseResult.js";
 import { buildQuery, parseQueryString } from "./query.js";
 import { validate } from "./validation.js";
 
@@ -158,20 +159,21 @@ export function generateCrudRoutes(models: DiscoveredModel[], options: AutoCrudO
         const countParams = params.slice(0, -2);
         const rows = await adapterQuery(adapter, sql, params);
 
+        // total is the TRUE total for the filter (a COUNT probe), NEVER the number
+        // of rows this page returned (ADR-0043). limit/offset are exactly what the
+        // SQL applied — buildQuery derives offset as (page - 1) * limit.
         const countRow = await adapterQuery(adapter, countSql, countParams);
         const total = Number(countRow[0]?.total ?? 0);
         const limit = qp.limit ?? 100;
         const page = qp.page ?? 1;
-
-        res.json({
-          data: rows,
-          meta: {
-            total,
-            page,
-            limit,
-            totalPages: Math.ceil(total / limit),
-          },
-        });
+        const offset = (page - 1) * limit;
+
+        // The REST list envelope IS the canonical paginate envelope: exactly the
+        // seven snake_case keys DatabaseResult.toPaginate() builds — records, total,
+        // page, per_page, total_pages, limit, offset — so this endpoint and
+        // db.fetch(...).toPaginate() can never drift (ADR-0043). No `data` alias, no
+        // camelCase `totalPages`, no nested `meta`.
+        res.json(new DatabaseResult(rows, undefined, total, limit, offset).toPaginate());
       },
     });
 

package/packages/orm/src/database.ts

@@ -113,6 +113,67 @@ export async function adapterCreateTable(
   else adapter.createTable(name, columns);
 }
 
+/**
+ * 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 async function probeTotal(
+  adapter: DatabaseAdapter,
+  sql: string,
+  params: unknown[] | undefined,
+  limit: number | undefined,
+): Promise<number | undefined> {
+  if (limit === undefined || limit <= 0) return undefined;
+  try {
+    const alias = (adapter as any).countSubqueryAlias as string | undefined;
+    const suffix = alias ? ` AS ${alias}` : "";
+    const rows = await adapterFetch(
+      adapter,
+      `SELECT COUNT(*) AS tina4_total FROM (${sql}\n)${suffix}`,
+      params,
+      undefined,
+      undefined,
+      true,
+    );
+    const row = Array.isArray(rows) ? (rows[0] as Record<string, unknown> | undefined) : undefined;
+    if (!row) return undefined;
+    const value = row["tina4_total"] ?? row["TINA4_TOTAL"] ?? Object.values(row)[0];
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Extract the engine-assigned auto-increment id from an `execute()` result.
  *
@@ -575,7 +636,7 @@ export class Database {
       // no store, run directly (mirrors the Python master's `no_cache`).
       const rows = await adapterFetch(adapter, sql, params, limit, offset, opts?.noCache);
       this.lastError = null;
-      const total = await this.countProbe(adapter, sql, params, limit);
+      const total = await probeTotal(adapter, sql, params, limit);
       return new DatabaseResult(rows, undefined, total, limit, offset, adapter, sql);
     } catch (e: any) {
       // v3.13.11 #49.2: fetch() records last_error like execute() does.
@@ -584,63 +645,6 @@ export class Database {
     }
   }
 
-  /**
-   * 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 async countProbe(
-    adapter: DatabaseAdapter,
-    sql: string,
-    params: unknown[] | undefined,
-    limit: number | undefined,
-  ): Promise<number | undefined> {
-    if (limit === undefined || limit <= 0) return undefined;
-    try {
-      const alias = (adapter as any).countSubqueryAlias as string | undefined;
-      const suffix = alias ? ` AS ${alias}` : "";
-      const rows = await adapterFetch(
-        adapter,
-        `SELECT COUNT(*) AS tina4_total FROM (${sql}\n)${suffix}`,
-        params,
-        undefined,
-        undefined,
-        true,
-      );
-      const row = Array.isArray(rows) ? (rows[0] as Record<string, unknown> | undefined) : undefined;
-      if (!row) return undefined;
-      const value = row["tina4_total"] ?? row["TINA4_TOTAL"] ?? Object.values(row)[0];
-      const n = Number(value);
-      return Number.isFinite(n) ? n : undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
   /**
    * Fetch a single row or null.
    *

package/packages/orm/src/databaseResult.ts

@@ -97,99 +97,70 @@ export class DatabaseResult implements Iterable<Record<string, unknown>> {
     return this.records;
   }
 
-  /** 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;
   } {
-    if ((page !== undefined || perPage !== undefined) && this.records.length < this.count) {
+    // No parameters (ADR-0043). `arguments` catches an argument passed anyway —
+    // including from plain JS, where the 0-arity signature is not enforced — so a
+    // caller porting the old two-argument form gets a hard error, never a silent
+    // in-memory re-slice that lies about total_pages.
+    if (arguments.length > 0) {
       throw new TypeError(
-        `toPaginate(page, perPage) slices the rows this result holds, but this ` +
-          `result holds only ${this.records.length} of ${this.count} rows - it is a ` +
-          `PARTIAL result, so any page past the rows it holds comes back empty while ` +
-          `totalPages claims it exists. MEASURED on 100,000 rows read under the ` +
-          `default cap of 100: pages 1-5 of 20 were right and pages 6 onward returned ` +
-          `NOTHING. Fetch the page you want instead: fetch(sql, params, perPage, ` +
-          `(page - 1) * perPage), then call toPaginate() with no arguments.`,
+        "toPaginate() takes no arguments and derives the page from the query that " +
+          "ran (ADR-0043). A DatabaseResult holds no connection, so an argument could " +
+          "only re-slice the rows already in memory and report total_pages for pages " +
+          "it can never reach. To read a page, FETCH it: db.fetch(sql, params, perPage, " +
+          "(page - 1) * perPage), then call toPaginate() with no arguments.",
       );
     }
 
-    let resolvedPerPage: number;
-    let resolvedPage: number;
-    let offset: number;
-    let rows: Record<string, unknown>[];
-
-    if (page === undefined && perPage === undefined) {
-      resolvedPerPage = this.limit > 0 ? this.limit : this.records.length;
-      resolvedPage = resolvedPerPage > 0 ? Math.floor(this.offset / resolvedPerPage) + 1 : 1;
-      offset = this.offset;
-      rows = this.records;
-    } else {
-      resolvedPage = page ?? 1;
-      resolvedPerPage = perPage ?? (this.limit > 0 ? this.limit : 10);
-      offset = (resolvedPage - 1) * resolvedPerPage;
-      rows = this.records.slice(offset, offset + resolvedPerPage);
-    }
-    const totalPages =
-      resolvedPerPage > 0 ? Math.max(1, Math.ceil(this.count / resolvedPerPage)) : 1;
+    const perPage = this.limit > 0 ? this.limit : this.records.length;
+    const page = perPage > 0 ? Math.floor(this.offset / perPage) + 1 : 1;
+    const totalPages = perPage > 0 ? Math.max(1, Math.ceil(this.count / perPage)) : 1;
 
     return {
-      records: rows,
-      data: rows,
-      count: this.count,
+      records: this.records,
       total: this.count,
-      limit: resolvedPerPage,
-      offset,
-      page: resolvedPage,
-      per_page: resolvedPerPage,
-      perPage: resolvedPerPage,
-      totalPages,
+      page,
+      per_page: perPage,
       total_pages: totalPages,
-      has_next: resolvedPage < totalPages,
-      has_prev: resolvedPage > 1,
+      limit: perPage,
+      offset: this.offset,
     };
   }
 

package/packages/orm/src/index.ts

@@ -7,11 +7,8 @@ export type {
   ColumnInfo,
   QueryOptions,
   RelationshipDefinition,
-  PaginatedResult,
 } from "./types.js";
 
-export { FetchResult } 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/packages/orm/src/migration.ts

@@ -1176,9 +1176,24 @@ export async function status(
  */
 export async function createMigration(
   description: string,
-  options?: { migrationsDir?: string; kind?: "sql" | "class" },
+  options?: { migrationsDir?: string; kind?: "sql" | "code" | "class" },
 ): Promise<string | { upPath: string; downPath: string }> {
-  if (options?.kind === "class") {
+  // MEASURED 2026-08-06: the accepted kind differed in every framework -
+  // python "python", php "php", ruby "ruby" OR "python", node "class" - and
+  // NONE validated it, so create_migration(..., kind="python") produced a code
+  // migration in Python and Ruby and a SILENT .sql file in PHP and Node.
+  // "code" is now the canonical spelling in all four; each keeps its own
+  // language name as a legacy alias; anything else raises.
+  const kind = (options?.kind ?? "sql").trim().toLowerCase();
+  if (!["sql", "code", "class"].includes(kind)) {
+    throw new Error(
+      `Unknown migration kind "${kind}". Use "sql" (default) or "code" ` +
+        `(alias: "class"). An unrecognised kind used to produce a .sql file ` +
+        `silently, which is why this now throws.`,
+    );
+  }
+
+  if (kind === "code" || kind === "class") {
     return createClassMigration(description, options);
   }
   const dir = resolve(options?.migrationsDir ?? "migrations");
@@ -1337,15 +1352,18 @@ export 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).
    */
-  async create(description: string, kind: "sql" | "class" = "sql"): Promise<string | { upPath: string; downPath: string }> {
-    if (kind === "class") {
-      return createClassMigration(description, { migrationsDir: this.dir });
-    }
-    return createMigration(description, { migrationsDir: this.dir });
+  async create(
+    description: string,
+    kind: "sql" | "code" | "class" = "sql",
+  ): Promise<string | { upPath: string; downPath: string }> {
+    // Route through createMigration so the validation lives in ONE place - a
+    // second copy of the accepted set is a second place for it to drift.
+    return createMigration(description, { migrationsDir: this.dir, kind });
   }
 
   /** Return list of completed (applied) migration filenames. */

package/packages/orm/src/model.ts

@@ -38,6 +38,10 @@ export async function discoverModels(modelsDir: string): Promise<DiscoveredModel
 
       const definition: ModelDefinition = {
         tableName: ModelClass.tableName,
+        // The class name is the type name a generated OpenAPI client wants
+        // (`Item`, not `items`). Carry it so Swagger keys components.schemas by
+        // it. A model exported as `default` keeps its declared class name here.
+        className: typeof ModelClass.name === "string" && ModelClass.name ? ModelClass.name : undefined,
         fields: ModelClass.fields as Record<string, FieldDefinition>,
         fieldMapping: ModelClass.fieldMapping as Record<string, string> | undefined,
         softDelete: ModelClass.softDelete ?? false,

package/packages/orm/src/queryBuilder.ts

@@ -18,7 +18,7 @@
  */
 
 import type { DatabaseAdapter } from "./types.js";
-import { getAdapter, adapterFetch, adapterFetchOne } from "./database.js";
+import { getAdapter, adapterFetch, adapterFetchOne, probeTotal } from "./database.js";
 import { DatabaseResult } from "./databaseResult.js";
 
 export class QueryBuilder {
@@ -227,22 +227,29 @@ export class QueryBuilder {
     const sql = this.toSql();
     const allParams = [...this.params, ...this.havingParams];
 
+    const queryParams = allParams.length > 0 ? allParams : undefined;
     const rows = await adapterFetch(
       this.db!,
       sql,
-      allParams.length > 0 ? allParams : undefined,
+      queryParams,
       this.limitVal,
       this.offsetVal,
     );
 
     // Constructed exactly as Database._fetchWithLimit does, so a QueryBuilder
     // result and a db.fetch() result are the same object in the same state --
-    // including leaving `count` to default to the row count and handing the
-    // adapter + sql through.
+    // INCLUDING `count`, which is the TRUE total for the filter via the shared
+    // COUNT probe (ADR-0043), not rows-returned. Python's get() -> db.fetch()
+    // and Ruby's get -> @db.fetch() already carried the true total; Node used to
+    // leave it at the row count here, so `QueryBuilder.get().toPaginate()`
+    // under-reported `total` while `db.fetch().toPaginate()` did not. The probe
+    // is best-effort (undefined on any error -> falls back to rows.length) and
+    // only runs when a limit was applied, so an unlimited get() is one query.
+    const total = await probeTotal(this.db!, sql, queryParams, this.limitVal);
     return new DatabaseResult(
       rows as Record<string, unknown>[],
       undefined,
-      undefined,
+      total,
       this.limitVal,
       this.offsetVal,
       this.db!,

package/packages/orm/src/types.ts

@@ -31,6 +31,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;
@@ -128,80 +135,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 class FetchResult<T = Record<string, unknown>> {
-  readonly records: T[];
-  readonly count: number;
-  readonly sql: string;
-
-  constructor(records: T[], sql = "") {
-    this.records = records;
-    this.count = records.length;
-    this.sql = sql;
-  }
-
-  /** Paginate the in-memory result set. */
-  toPaginate(page = 1, perPage = 20): PaginatedResult<T> {
-    const total = this.count;
-    const totalPages = Math.max(1, Math.ceil(total / perPage));
-    const offset = (page - 1) * perPage;
-    const data = this.records.slice(offset, offset + perPage);
-    return {
-      data,
-      page,
-      perPage,
-      total,
-      totalPages,
-      hasNext: page < totalPages,
-      hasPrev: page > 1,
-    };
-  }
-
-  /** Return the first record or null. */
-  first(): T | null {
-    return this.records[0] ?? null;
-  }
-
-  /** Return the last record or null. */
-  last(): T | null {
-    return this.records[this.records.length - 1] ?? null;
-  }
-
-  /** Check if result is empty. */
-  isEmpty(): boolean {
-    return this.records.length === 0;
-  }
-
-  /** Convert to plain array. */
-  toArray(): T[] {
-    return [...this.records];
-  }
-
-  /** Convert to JSON string. */
-  toJSON(): string {
-    return JSON.stringify(this.records);
-  }
-
-  /** Iterate over records. */
-  [Symbol.iterator](): Iterator<T> {
-    return this.records[Symbol.iterator]();
-  }
-}
-
 export interface QueryOptions {
   filter?: Record<string, unknown>;
   sort?: string;