tina4-nodejs 3.13.131 → 3.13.133

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