tina4-nodejs 3.13.95 → 3.13.96

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;