tina4-nodejs 3.13.130 → 3.13.132

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,
+    };
+  }
+}

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

@@ -1,5 +1,5 @@
 export type { Tina4Request, Tina4Response, RouteHandler, RouteDefinition, RouteMeta, Tina4Config, Middleware, MiddlewareClass, MiddlewareSpec, UploadedFile, CookieOptions, WebSocketRouteHandler, WebSocketRouteDefinition, } from "./types.js";
-export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
+export { startServer, resolvePortAndHost, loopbackBindHosts, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
 export { Router, RouteGroup, RouteRef, WsRouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";

package/types/core/src/server.d.ts

@@ -249,6 +249,21 @@ export declare function buildDispatchContext(router: Router, base?: string): Pro
  * skipped for one caller and not the other (feature 131, TC-DEC-01).
  */
 export declare function runDispatch(ctx: DispatchContext, rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+/**
+ * Sibling loopback addresses to ALSO listen on, so `localhost` reaches this
+ * server whether the OS resolves it to IPv4 (127.0.0.1) or IPv6 (::1).
+ *
+ * `localhost` resolves to `::1` (IPv6) FIRST on Windows, so a server bound only
+ * to `127.0.0.1` — or `0.0.0.0`, the IPv4 wildcard, which does NOT cover IPv6 —
+ * refuses the browser with ERR_CONNECTION_REFUSED even though it is serving,
+ * because nothing listens on `::1`. Binding the sibling family closes that gap.
+ *
+ * Returns only the families a direct bind of `host` does not already cover, as
+ * UNBRACKETED addresses (Node's net/http take a bare "::1"). A host that is
+ * neither loopback nor a wildcard yields an empty list — an explicit LAN
+ * address is bound exactly as asked. Mirrors PHP `Server::loopbackBindHosts`.
+ */
+export declare function loopbackBindHosts(host: string): string[];
 export declare function startServer(config?: Tina4Config): Promise<{
     close: () => void;
     router: Router;

package/types/frond/src/engine.d.ts

@@ -257,6 +257,17 @@ export declare class Frond {
      */
     private handleImportAs;
     private handleFromImport;
+    /**
+     * Collect the body tokens of a {% <openTag> %}...{% end<openTag> %} block,
+     * starting from the token after the opening tag (start + 1). Nested same-tag
+     * blocks are kept in the body and balanced by depth; the matching closing tag is
+     * consumed but NOT included. Returns [bodyTokens, indexAfterClosingTag].
+     *
+     * canNest guards the open-tag count: handleSetBlock passes it so the inline
+     * {% set x = 1 %} form (which has no {% endset %}) never opens a nested block —
+     * only the block form {% set x %} nests. Omitted, every openTag occurrence nests.
+     */
+    private collectBlockBody;
     private handleCache;
     /**
      * Handle {% live "name" poll N | sse | ws "path" [src "url"] %}...{% endlive %}.

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

@@ -1,3 +1,4 @@
+import { ModelCollection } from "./modelCollection.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 /**
@@ -135,6 +136,20 @@ export declare class BaseModel {
      * Get the primary key database column name (applies fieldMapping).
      */
     protected static getPkColumn(): string;
+    /**
+     * 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 _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>>;
     /**
      * Find a record by primary key.
      * @param id Primary key value.
@@ -174,7 +189,7 @@ export declare class BaseModel {
      *   User.find()                        → all records
      */
     static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, pk: number | string, include?: string[]): Promise<T | null>;
-    static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, filter?: Record<string, unknown>, limit?: number, offset?: number, orderBy?: string, include?: string[]): Promise<T[]>;
+    static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, filter?: Record<string, unknown>, limit?: number, offset?: number, orderBy?: string, include?: string[]): Promise<ModelCollection<T>>;
     /**
      * Load a record into this instance via selectOne.
      * Returns true if found and loaded, false otherwise.
@@ -218,7 +233,7 @@ export declare class BaseModel {
      * @param include Relationship names to eager-load.
      * @param orderBy ORDER BY clause (e.g. "name ASC").
      */
-    static all<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<T[]>;
+    static all<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<ModelCollection<T>>;
     /**
      * Query records with a WHERE clause.
      * Matches Python/PHP/Ruby where() API.
@@ -230,7 +245,7 @@ export declare class BaseModel {
      * @param include    Relationship names to eager-load
      * @param orderBy    ORDER BY clause (e.g. "name ASC")
      */
-    static where<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions: string, params?: unknown[], limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<T[]>;
+    static where<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions: string, params?: unknown[], limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<ModelCollection<T>>;
     /**
      * Save this instance (insert or update). Returns this on success (fluent
      * self), false on failure.
@@ -354,7 +369,7 @@ export declare class BaseModel {
     /**
      * Execute a raw SQL SELECT and return results as model instances.
      */
-    static select<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]>;
+    static select<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], limit?: number, offset?: number): Promise<ModelCollection<T>>;
     static selectOne<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], include?: string[]): Promise<T | null>;
     /**
      * Permanently delete this instance, bypassing soft delete.
@@ -367,7 +382,7 @@ export declare class BaseModel {
     /**
      * Find records including soft-deleted ones.
      */
-    static withTrashed<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions?: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]>;
+    static withTrashed<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions?: string, params?: unknown[], limit?: number, offset?: number): Promise<ModelCollection<T>>;
     /**
      * Count records matching conditions (respects soft delete and table filter).
      */

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

@@ -2,6 +2,8 @@ export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, Data
 export { REQUIRED_ADAPTER_CAPABILITIES, NOT_REQUIRED_ON_ADAPTER } from "./types.js";
 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, adapterStartTransaction, adapterCommit, adapterRollback, adapterTableExists, adapterTables, adapterColumns, adapterCreateTable, extractLastInsertId, } from "./database.js";
 export type { DatabaseConfig } from "./database.js";

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

@@ -0,0 +1,101 @@
+/**
+ * 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 declare class ModelCollection<T = unknown> extends Array<T> {
+    /** Total rows matching the query's filter (ignores limit/offset). */
+    private _total;
+    /** The SQL limit that produced this page. */
+    private _limit;
+    /** The SQL offset that produced this page. */
+    private _offset;
+    /**
+     * 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;
+    /**
+     * @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?: number, limit?: number, offset?: number);
+    /**
+     * 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;
+    /**
+     * 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;
+}