tina4-nodejs 3.13.131 → 3.13.133

package/packages/orm/src/baseModel.ts

@@ -3,8 +3,9 @@ import {
   adapterQuery, adapterFetch, adapterExecute, adapterFetchOne,
   adapterStartTransaction, adapterCommit, adapterRollback,
   adapterTableExists, adapterCreateTable, extractLastInsertId,
-  DEFAULT_ROW_CAP,
+  probeTotal, DEFAULT_ROW_CAP,
 } from "./database.js";
+import { ModelCollection } from "./modelCollection.js";
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
@@ -451,6 +452,43 @@ export class BaseModel {
     return this.getDbColumn(this.getPkField());
   }
 
+  /**
+   * Shared read tail for the collection-returning finders (where / all / select
+   * / find filter-form / withTrashed). Runs the SAME two calls `db.fetch()`
+   * makes — the page fetch AND the COUNT probe over the SAME base SQL — hydrates
+   * the rows into model instances, and returns a ModelCollection carrying the
+   * total (ADR-0064).
+   *
+   * The total is FREE: `probeTotal` is the exact `COUNT(*)` probe `db.fetch()`
+   * already runs; the ORM used to discard it. ZERO extra queries beyond that one
+   * probe. `sql` MUST NOT carry its own LIMIT/OFFSET — `adapterFetch` applies
+   * limit/offset to the page, and the probe wraps the un-limited SQL so it counts
+   * the WHOLE filtered set, not the page.
+   */
+  protected static async _collect<T extends BaseModel>(
+    this: typeof BaseModel & (new (data?: Record<string, unknown>) => T),
+    sql: string,
+    params: unknown[] | undefined,
+    limit: number,
+    offset: number,
+    include?: string[],
+  ): Promise<ModelCollection<T>> {
+    const db = this.getDb();
+    const rows = await adapterFetch(db, sql, params, limit, offset);
+    const data: Record<string, unknown>[] = Array.isArray(rows)
+      ? (rows as Record<string, unknown>[])
+      : ((rows as { data?: Record<string, unknown>[] })?.data ?? []);
+    // The total comes from the fetch COUNT probe — NOT data.length (that is only
+    // the page). probeTotal returns undefined only for an unbounded read
+    // (limit <= 0), where the page IS the whole set, so data.length is right.
+    const total = (await probeTotal(db, sql, params, limit)) ?? data.length;
+    const instances = data.map((row) => new this(row) as T);
+    if (include) {
+      await (this as typeof BaseModel)._eagerLoad(instances as BaseModel[], include);
+    }
+    return new ModelCollection<T>(instances, total, limit, offset);
+  }
+
   /**
    * Find a record by primary key.
    * @param id Primary key value.
@@ -531,7 +569,7 @@ export class BaseModel {
     offset?: number,
     orderBy?: string,
     include?: string[],
-  ): Promise<T[]>;
+  ): Promise<ModelCollection<T>>;
   static async find<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     filter?: Record<string, unknown> | number | string,
@@ -539,7 +577,7 @@ export class BaseModel {
     offset = 0,
     orderBy?: string,
     include?: string[],
-  ): Promise<T[] | T | null> {
+  ): Promise<ModelCollection<T> | T | null> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
 
     // Scalar PK lookup routes to findById. A number or a string (but NOT a
@@ -555,7 +593,6 @@ export class BaseModel {
 
     // Array form — coerce `limit` back to a number for the list path.
     const lim = typeof limit === "number" ? limit : 100;
-    const db = ModelClass.getDb();
     const conditions: string[] = [];
     const params: unknown[] = [];
 
@@ -579,18 +616,7 @@ export class BaseModel {
       sql += ` ORDER BY ${orderBy}`;
     }
 
-    const rows = await adapterFetch(db, sql, params, lim, offset);
-    const data = (rows as any)?.data ?? rows;
-    const instances = (Array.isArray(data) ? data : []).map((row: Record<string, unknown>) => {
-      const inst = new this(row) as T;
-      return inst;
-    });
-
-    if (include) {
-      await ModelClass._eagerLoad(instances as BaseModel[], include);
-    }
-
-    return instances;
+    return ModelClass._collect<T>(sql, params, lim, offset, include);
   }
 
   /**
@@ -671,9 +697,8 @@ export class BaseModel {
     offset: number = 0,
     include?: string[],
     orderBy?: string,
-  ): Promise<T[]> {
+  ): Promise<ModelCollection<T>> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
 
     const conditions: string[] = [];
     if (ModelClass.softDelete) {
@@ -685,18 +710,14 @@ export class BaseModel {
 
     const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
     const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
-    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`
-      + ` LIMIT ${limit} OFFSET ${offset}`;
+    // No LIMIT/OFFSET embedded: _collect's adapterFetch applies them to the page
+    // and the COUNT probe wraps the un-limited SQL so the total is the whole set.
+    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
 
     // No bind parameters: the only conditions left are the framework's own
     // softDelete / tableFilter literals. A caller-supplied filter belongs on
     // where(), which binds its params properly.
-    const rows = await adapterQuery(db, sql, []);
-    const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
-    if (include) {
-      await ModelClass._eagerLoad(instances, include);
-    }
-    return instances;
+    return ModelClass._collect<T>(sql, [], limit, offset, include);
   }
 
   /**
@@ -718,9 +739,8 @@ export class BaseModel {
     offset: number = 0,
     include?: string[],
     orderBy?: string,
-  ): Promise<T[]> {
+  ): Promise<ModelCollection<T>> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
 
     const parts: string[] = [];
     if (ModelClass.softDelete) {
@@ -732,14 +752,11 @@ export class BaseModel {
     parts.push(`(${conditions})`);
 
     const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
-    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause} LIMIT ${limit} OFFSET ${offset}`;
+    // No LIMIT/OFFSET embedded — _collect applies them to the page and probes
+    // the total (ADR-0064). orderBy affects the page only; COUNT is order-free.
+    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")}${orderClause}`;
 
-    const rows = await adapterQuery(db, sql, params);
-    const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
-    if (include) {
-      await ModelClass._eagerLoad(instances, include);
-    }
-    return instances;
+    return ModelClass._collect<T>(sql, params, limit, offset, include);
   }
 
   /**
@@ -1418,17 +1435,14 @@ export class BaseModel {
     params?: unknown[],
     limit: number = DEFAULT_ROW_CAP,
     offset: number = 0,
-  ): Promise<T[]> {
+  ): Promise<ModelCollection<T>> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
-    // Skip appending when the caller's SQL already carries its own LIMIT --
-    // a second one is a syntax error on every engine. SQLTranslator.appendLimit
-    // scrubs literals/comments first (a substring search here used to drop the
-    // row cap on `WHERE label != 'LIMIT'`) and appends on a new line so the
-    // clause is never swallowed by a trailing `--` comment.
-    const paged = SQLTranslator.appendLimit(sql, limit, offset);
-    const rows = await adapterQuery(db, paged, params);
-    return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    // _collect runs the page fetch — the adapter applies limit/offset via
+    // SQLTranslator.appendLimit, which scrubs literals/comments and skips when
+    // the caller's SQL already carries its own LIMIT (a second one is a syntax
+    // error on every engine) — AND the COUNT probe over the raw SQL, so the
+    // ModelCollection carries the total for the filter (ADR-0064).
+    return ModelClass._collect<T>(sql, params, limit, offset);
   }
 
   static async selectOne<T extends BaseModel>(
@@ -1518,9 +1532,8 @@ export class BaseModel {
     params?: unknown[],
     limit: number = DEFAULT_ROW_CAP,
     offset: number = 0,
-  ): Promise<T[]> {
+  ): Promise<ModelCollection<T>> {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
 
     const parts: string[] = [];
     if (ModelClass.tableFilter) {
@@ -1534,15 +1547,11 @@ export class BaseModel {
     if (parts.length > 0) {
       sql += ` WHERE ${parts.join(" AND ")}`;
     }
-    if (limit !== undefined) {
-      sql += ` LIMIT ${limit}`;
-    }
-    if (offset !== undefined) {
-      sql += ` OFFSET ${offset}`;
-    }
 
-    const rows = await adapterQuery(db, sql, params);
-    return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    // No LIMIT/OFFSET embedded — _collect applies them to the page and probes
+    // the total. No is_deleted filter here, so soft-deleted rows are INCLUDED in
+    // both the page and the total (ADR-0064).
+    return ModelClass._collect<T>(sql, params, limit, offset);
   }
 
   /**

package/packages/orm/src/index.ts

@@ -13,6 +13,8 @@ export { REQUIRED_ADAPTER_CAPABILITIES, NOT_REQUIRED_ON_ADAPTER } from "./types.
 
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
+export { ModelCollection } from "./modelCollection.js";
+export type { PaginateEnvelope } from "./modelCollection.js";
 export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
 export {
   adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterInsert,

package/packages/orm/src/modelCollection.ts

@@ -0,0 +1,149 @@
+/**
+ * ModelCollection — a list of ORM models that also carries the query total.
+ *
+ * What the ORM read queries (`where` / `select` / `find` filter-form / `all` /
+ * `withTrashed`) return. It IS an Array — iterate it, index it, slice it, `.map`
+ * it, `.filter` it, read `.length`, `JSON.stringify` it — so every existing
+ * caller keeps working unchanged (`Array.isArray(coll) === true`). It adds one
+ * thing: the TOTAL number of rows matching the query's filter, independent of
+ * `limit` / `offset`.
+ *
+ * The total is free. Every one of those methods already runs the fetch COUNT
+ * probe (`db.fetch` / `probeTotal`) that computes `SELECT COUNT(*)` for the same
+ * filter; the ORM used to hydrate the page of models and throw that count away.
+ * This class carries it instead, so a caller with 20 models on the page can
+ * still learn there are 250 rows in the set. ZERO extra queries.
+ *
+ * Uniform across all four Tina4 frameworks (ADR-0064). Same concept, language-
+ * idiomatic accessor name:
+ *
+ *     Python / Ruby : get_total_records()   to_paginate()
+ *     PHP / Node    : getTotalRecords()     toPaginate()
+ *
+ * The accessor is a METHOD, not a `.total` property, on purpose: `Array#count`
+ * exists in Ruby and `list.count()` in Python, so a `.count` would shadow a
+ * built-in. `DatabaseResult` keeps its `.count` property (it is not a list); both
+ * expose the identical seven-key `toPaginate()` envelope.
+ *
+ * ### Why a real Array subclass with `[Symbol.species] === Array`
+ *
+ * `class X extends Array` is the parity-faithful backing (the ADR-0064 table
+ * says Node is a "subclass of Array"), and it keeps `Array.isArray` true and
+ * `instanceof ModelCollection` true (mirroring Python's `isinstance`). BUT a bare
+ * Array subclass is a footgun: `map`/`filter`/`slice` build the result via
+ * `this.constructor[Symbol.species]`, calling the constructor with a single
+ * NUMBER (the length), and `new X(oneNumber)` means "length N", not "one
+ * element". Overriding `[Symbol.species]` to return `Array` makes every derived
+ * operation build a plain `Array` — so `.map`/`.filter`/`.slice`/spread never
+ * touch this constructor and can never explode. The constructor below is also
+ * defended against the numeric-length call directly, so even a path that ignores
+ * species is safe.
+ */
+
+/** The canonical pagination envelope — seven snake_case keys (ADR-0043/0064). */
+export interface PaginateEnvelope {
+  records: unknown[];
+  total: number;
+  page: number;
+  per_page: number;
+  total_pages: number;
+  limit: number;
+  offset: number;
+}
+
+export class ModelCollection<T = unknown> extends Array<T> {
+  /** Total rows matching the query's filter (ignores limit/offset). */
+  private _total = 0;
+  /** The SQL limit that produced this page. */
+  private _limit = 0;
+  /** The SQL offset that produced this page. */
+  private _offset = 0;
+
+  /**
+   * Derived array operations (`map`, `filter`, `slice`, spread, …) build a plain
+   * `Array`, never another `ModelCollection`. This is what defuses the Array-
+   * subclass constructor/species trap: the engine never calls this constructor
+   * with a length during those operations.
+   */
+  static get [Symbol.species](): ArrayConstructor {
+    return Array;
+  }
+
+  /**
+   * @param items  the page of hydrated model instances (or the length, when the
+   *               engine constructs a derived array — defended against here).
+   * @param total  total rows matching the query's filter (ignores limit/offset).
+   * @param limit  the SQL limit that produced this page.
+   * @param offset the SQL offset that produced this page.
+   */
+  constructor(items?: readonly T[] | number, total = 0, limit = 0, offset = 0) {
+    super();
+    // Defensive: a raw `new ModelCollection(5)` (or any engine path that ignores
+    // [Symbol.species]) must behave like `new Array(5)` — a length-5 array — not
+    // wedge a number into element 0. `[Symbol.species] = Array` means the built-
+    // in derived ops never reach here, but this keeps the constructor honest.
+    if (typeof items === "number") {
+      this.length = items;
+      return;
+    }
+    if (items) {
+      for (let i = 0; i < items.length; i++) {
+        this[i] = items[i];
+      }
+    }
+    this._total = Math.trunc(total) || 0;
+    this._limit = Math.trunc(limit) || 0;
+    this._offset = Math.trunc(offset) || 0;
+  }
+
+  /**
+   * Total rows matching the query's filter, ignoring limit/offset.
+   *
+   * This is the whole point of the collection: the page slice you are iterating
+   * is capped by `limit`, but this number is the full count of matching rows —
+   * what a pager needs to render "page 3 of 13".
+   */
+  getTotalRecords(): number {
+    return this._total;
+  }
+
+  /**
+   * The canonical pagination envelope — seven snake_case keys, identical to
+   * `DatabaseResult.toPaginate()` (ADR-0043) and to the other three frameworks'
+   * `toPaginate()` / `to_paginate()`.
+   *
+   *     records     the page's rows as plain objects (never re-sliced)
+   *     total       getTotalRecords() — the true total for the filter
+   *     page        floor(offset / per_page) + 1
+   *     per_page    the query's limit
+   *     total_pages ceil(total / per_page)
+   *     limit       the SQL limit actually applied
+   *     offset      the SQL offset actually applied
+   *
+   * `records` are model dicts (via `toDict()`, the same serialisation the
+   * framework applies to a model in a JSON response), so the JSON a client sees
+   * matches `DatabaseResult` exactly — the result is uniform whether the route
+   * returned a raw `db.fetch()` or an ORM query.
+   */
+  toPaginate(): PaginateEnvelope {
+    const perPage = this._limit > 0 ? this._limit : this.length;
+    const page = perPage > 0 ? Math.floor(this._offset / perPage) + 1 : 1;
+    const totalPages = perPage > 0 ? Math.max(1, Math.ceil(this._total / perPage)) : 1;
+    // `.map` returns a plain Array here (see [Symbol.species]). Each model is
+    // serialised via toDict() — the same shape the framework emits for a model
+    // in a JSON response — so the envelope matches DatabaseResult exactly.
+    const records = this.map((model) => {
+      const m = model as unknown as { toDict?: () => unknown };
+      return m && typeof m.toDict === "function" ? m.toDict() : model;
+    });
+    return {
+      records,
+      total: this._total,
+      page,
+      per_page: perPage,
+      total_pages: totalPages,
+      limit: perPage,
+      offset: this._offset,
+    };
+  }
+}