tina4-nodejs 3.13.131 → 3.13.133

package/packages/swagger/src/generator.ts

@@ -157,16 +157,85 @@ function sanitizeSecurity(
   });
 }
 
+/**
+ * Shared, mutable state threaded through the per-route builders. Bundled so
+ * `generate()` reads as a flat orchestrator and each helper keeps a single
+ * responsibility (parity with the Python/PHP decomposition of `generate`).
+ */
+interface BuildContext {
+  models: ModelDefinition[];
+  tableToSchema: Map<string, string>;
+  schemes: Record<string, Record<string, unknown>>;
+  defaultScheme: string;
+  includePrefixes: string[];
+  excludePrefixes: string[];
+  refSchemas: Set<string>;
+  usedTags: string[];
+  seenIds: Set<string>;
+}
+
 export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
 ): OpenAPISpec {
+  const schemes = resolveSecuritySchemes();
+  const spec: OpenAPISpec = {
+    openapi: resolveOpenApiVersion(),
+    info: buildInfo(),
+    servers: resolveServers(),
+    paths: {},
+    components: {
+      schemas: {},
+      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
+      // apiKey scheme, plus any programmatically-registered schemes (which may
+      // override bearerAuth — e.g. an oauth2 scheme with scopes).
+      securitySchemes: schemes,
+    },
+  };
+
+  // Generate schemas from models, keyed by the model CLASS name ('Item'), which
+  // is the type name a generated client wants — never the tableName ('items').
+  // `tableToSchema` maps a path-inferred tableName back to that schema key so a
+  // POST/PUT request body $ref resolves to the same 'Item' entry.
+  const tableToSchema = new Map<string, string>();
+  buildComponentSchemas(models, spec, tableToSchema);
+
+  const ctx: BuildContext = {
+    models,
+    tableToSchema,
+    schemes,
+    // Default scheme secured routes use when no explicit meta.security is set.
+    defaultScheme: process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth",
+    // Path filters (comma-separated raw-path prefixes).
+    includePrefixes: csv(process.env.TINA4_SWAGGER_INCLUDE),
+    excludePrefixes: csv(process.env.TINA4_SWAGGER_EXCLUDE),
+    // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
+    refSchemas: new Set<string>(),
+    usedTags: [],
+    seenIds: new Set<string>(),
+  };
+
+  // Generate paths from routes
+  for (const route of routes) {
+    buildOperation(route, spec, ctx);
+  }
+
+  buildRefSchemas(spec, ctx.refSchemas);
+  buildTags(spec, ctx.usedTags);
+
+  return spec;
+}
+
+/**
+ * The `info` block: title/version/description, plus optional contact and
+ * license. The app's version defaults to 1.0.0 — NOT the framework's (Node
+ * shipped 0.0.1) — and description to the empty string, not a canned sentence;
+ * both are the settled cross-framework defaults (parity with the Python master),
+ * with TINA4_SWAGGER_VERSION / _DESCRIPTION still overriding.
+ */
+function buildInfo(): OpenAPISpecInfo {
   const info: OpenAPISpecInfo = {
     title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-    // The app's version, defaulting to 1.0.0 — NOT the framework's (Node shipped
-    // 0.0.1). description defaults to the empty string, not a canned sentence.
-    // Both are the settled cross-framework defaults (parity with the Python
-    // master); TINA4_SWAGGER_VERSION / _DESCRIPTION still override.
     version: process.env.TINA4_SWAGGER_VERSION ?? "1.0.0",
     description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "",
   };
@@ -190,183 +259,220 @@ export function generate(
     info.license = url ? { name, url } : { name };
   }
 
-  const schemes = resolveSecuritySchemes();
-  const spec: OpenAPISpec = {
-    openapi: resolveOpenApiVersion(),
-    info,
-    servers: resolveServers(),
-    paths: {},
-    components: {
-      schemas: {},
-      // Configurable security schemes (v3.13.42): bearerFormat via env, optional
-      // apiKey scheme, plus any programmatically-registered schemes (which may
-      // override bearerAuth — e.g. an oauth2 scheme with scopes).
-      securitySchemes: schemes,
-    },
-  };
-
-  // Default scheme secured routes use when no explicit meta.security is set.
-  const defaultScheme = process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth";
-
-  // Path filters (comma-separated raw-path prefixes).
-  const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
-  const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
-
-  // Reusable custom schemas referenced by routes via meta.requestSchema/responseSchemas.
-  const refSchemas = new Set<string>();
+  return info;
+}
 
-  // Generate schemas from models, keyed by the model CLASS name ('Item'), which
-  // is the type name a generated client wants — never the tableName ('items').
-  // `tableToSchema` maps a path-inferred tableName back to that schema key so a
-  // POST/PUT request body $ref resolves to the same 'Item' entry.
-  const tableToSchema = new Map<string, string>();
+/**
+ * Populate `components.schemas` from ORM models (keyed by the class name) and
+ * record the tableName -> schema-key map used to resolve request-body $refs.
+ */
+function buildComponentSchemas(
+  models: ModelDefinition[],
+  spec: OpenAPISpec,
+  tableToSchema: Map<string, string>
+): void {
   for (const model of models) {
     const schemaKey = schemaNameForModel(model);
     tableToSchema.set(model.tableName, schemaKey);
     spec.components!.schemas![schemaKey] = modelToSchema(model);
   }
+}
 
-  const usedTags: string[] = [];
-  const seenIds = new Set<string>();
+/**
+ * Build ONE path operation for a route and attach it to `spec.paths`, honouring
+ * the include/exclude filter and delegating each part of the operation to a
+ * focused sub-builder (parameters, request body, response schemas, security).
+ */
+function buildOperation(route: RouteDefinition, spec: OpenAPISpec, ctx: BuildContext): void {
+  if (!isIncludedPath(route.pattern, ctx.includePrefixes, ctx.excludePrefixes)) return;
+  const openApiPath = patternToOpenAPI(route.pattern);
+  const method = route.method.toLowerCase();
 
-  // Generate paths from routes
-  for (const route of routes) {
-    if (!isIncludedPath(route.pattern, includePrefixes, excludePrefixes)) continue;
-    const openApiPath = patternToOpenAPI(route.pattern);
-    const method = route.method.toLowerCase();
+  if (!spec.paths[openApiPath]) {
+    spec.paths[openApiPath] = {};
+  }
 
-    if (!spec.paths[openApiPath]) {
-      spec.paths[openApiPath] = {};
-    }
+  const tags = route.meta?.tags ?? inferTags(route.pattern);
+  for (const t of tags) {
+    if (!ctx.usedTags.includes(t)) ctx.usedTags.push(t);
+  }
 
-    const tags = route.meta?.tags ?? inferTags(route.pattern);
-    for (const t of tags) {
-      if (!usedTags.includes(t)) usedTags.push(t);
-    }
+  const operation: Record<string, unknown> = {
+    operationId: uniqueOperationId(method, openApiPath, ctx.seenIds),
+    summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
+    tags,
+    responses: route.meta?.responses ?? {
+      "200": { description: "Successful response" },
+    },
+  };
 
-    const operation: Record<string, unknown> = {
-      operationId: uniqueOperationId(method, openApiPath, seenIds),
-      summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
-      tags,
-      responses: route.meta?.responses ?? {
-        "200": { description: "Successful response" },
-      },
-    };
+  if (route.meta?.description) operation.description = route.meta.description;
+  if (route.meta?.deprecated) operation.deprecated = true;
 
-    if (route.meta?.description) operation.description = route.meta.description;
-    if (route.meta?.deprecated) operation.deprecated = true;
-
-    // Add path parameters. Each typed token maps to its JSON Schema fragment
-    // (int -> integer, uuid -> string+format, slug -> string+pattern, ...) via
-    // PARAM_TYPE_SCHEMA below, mirroring the Python master's _PARAM_TYPE_SCHEMA
-    // and the router's accepted token set. An unknown token degrades to string
-    // rather than dropping the parameter, and the token never reaches the key.
-    const pathParams = extractPathParams(route.pattern);
-    if (pathParams.length > 0) {
-      operation.parameters = pathParams.map(({ name, schema }) => ({
-        name,
-        in: "path",
-        required: true,
-        schema,
-      }));
-    }
+  const parameters = operationParameters(route, method, ctx.models);
+  if (parameters.length > 0) operation.parameters = parameters;
 
-    // Add query parameters for GET list endpoints
-    if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
-      const modelName = inferModelFromPath(route.pattern);
-      if (modelName && models.some((m) => m.tableName === modelName)) {
-        operation.parameters = [
-          ...(operation.parameters as unknown[] ?? []),
-          { name: "page", in: "query", schema: { type: "integer", default: 1 } },
-          { name: "limit", in: "query", schema: { type: "integer", default: 20 } },
-          { name: "sort", in: "query", schema: { type: "string" }, description: "Sort fields (prefix with - for descending)" },
-        ];
-      }
+  operationRequestBody(route, method, operation, ctx);
+  operationResponseSchemas(route, operation, ctx.refSchemas);
+  operationSecurity(route, method, operation, ctx.schemes, ctx.defaultScheme);
+
+  spec.paths[openApiPath][method] = operation;
+}
+
+/**
+ * The operation's parameters: path parameters (each typed token mapped to its
+ * JSON Schema fragment via PARAM_TYPE_SCHEMA — int -> integer, uuid ->
+ * string+format, slug -> string+pattern, ...; an unknown token degrades to
+ * string rather than dropping the parameter), followed by the page/limit/sort
+ * query parameters a GET list endpoint over a known model gets.
+ */
+function operationParameters(
+  route: RouteDefinition,
+  method: string,
+  models: ModelDefinition[]
+): Array<Record<string, unknown>> {
+  let parameters: Array<Record<string, unknown>> = [];
+
+  const pathParams = extractPathParams(route.pattern);
+  if (pathParams.length > 0) {
+    parameters = pathParams.map(({ name, schema }) => ({
+      name,
+      in: "path",
+      required: true,
+      schema,
+    }));
+  }
+
+  // Add query parameters for GET list endpoints
+  if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
+    const modelName = inferModelFromPath(route.pattern);
+    if (modelName && models.some((m) => m.tableName === modelName)) {
+      parameters = [
+        ...parameters,
+        { name: "page", in: "query", schema: { type: "integer", default: 1 } },
+        { name: "limit", in: "query", schema: { type: "integer", default: 20 } },
+        { name: "sort", in: "query", schema: { type: "string" }, description: "Sort fields (prefix with - for descending)" },
+      ];
     }
+  }
 
-    // Request body — a registered custom schema $ref (meta.requestSchema) wins,
-    // else the inferred-from-model body (POST/PUT to a resource), else an
-    // example-only body.
-    const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
-    if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
-      refSchemas.add(reqSchemaRef.name);
-      const media: Record<string, unknown> = {
-        schema: { $ref: `#/components/schemas/${reqSchemaRef.name}` },
-      };
-      if (route.meta?.example !== undefined) media.example = route.meta.example;
+  return parameters;
+}
+
+/** A media-type object: the schema, plus meta.example only when one was given.
+ *  Key order (schema, then example) matches the emitted document. */
+function mediaWithExample(schema: unknown, example: unknown): Record<string, unknown> {
+  const media: Record<string, unknown> = { schema };
+  if (example !== undefined) media.example = example;
+  return media;
+}
+
+/**
+ * Attach the request body (and, for a path-inferred model write, its 200
+ * response schema). A registered custom schema $ref (meta.requestSchema) wins,
+ * else the inferred-from-model body (POST/PUT to a resource), else an
+ * example-only body.
+ */
+function operationRequestBody(
+  route: RouteDefinition,
+  method: string,
+  operation: Record<string, unknown>,
+  ctx: BuildContext
+): void {
+  const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
+  if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
+    ctx.refSchemas.add(reqSchemaRef.name);
+    const media = mediaWithExample({ $ref: `#/components/schemas/${reqSchemaRef.name}` }, route.meta?.example);
+    operation.requestBody = {
+      content: { [reqSchemaRef.contentType]: media },
+    };
+  } else if (method === "post" || method === "put") {
+    const modelName = inferModelFromPath(route.pattern);
+    const schemaKey = modelName ? ctx.tableToSchema.get(modelName) : undefined;
+    if (schemaKey) {
+      const sref = `#/components/schemas/${schemaKey}`;
       operation.requestBody = {
-        content: { [reqSchemaRef.contentType]: media },
+        required: true,
+        content: { "application/json": mediaWithExample({ $ref: sref }, route.meta?.example) },
       };
-    } else if (method === "post" || method === "put") {
-      const modelName = inferModelFromPath(route.pattern);
-      const schemaKey = modelName ? tableToSchema.get(modelName) : undefined;
-      if (schemaKey) {
-        const sref = `#/components/schemas/${schemaKey}`;
-        const media: Record<string, unknown> = { schema: { $ref: sref } };
-        if (route.meta?.example !== undefined) media.example = route.meta.example;
-        operation.requestBody = {
-          required: true,
-          content: { "application/json": media },
-        };
 
-        // Response documents 200 with the resource schema — parity with the
-        // Python master, which emits ONLY 200 for a model write. The old code
-        // stamped an unconditional 422 and a 201 the generator has no way to know
-        // a given route returns; both were fiction on a path-inferred write. A
-        // route that genuinely answers another code declares it via
-        // meta.responses, which is honoured above and never clobbered here.
-        if (route.meta?.responses === undefined) {
-          operation.responses = {
-            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } },
-          };
-        }
-      } else if (route.meta?.example !== undefined) {
-        // Non-model body with an explicit example.
-        operation.requestBody = {
-          content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } },
+      // Response documents 200 with the resource schema — parity with the
+      // Python master, which emits ONLY 200 for a model write. The old code
+      // stamped an unconditional 422 and a 201 the generator has no way to know
+      // a given route returns; both were fiction on a path-inferred write. A
+      // route that genuinely answers another code declares it via
+      // meta.responses, which is honoured above and never clobbered here.
+      if (route.meta?.responses === undefined) {
+        operation.responses = {
+          "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } },
         };
       }
+    } else if (route.meta?.example !== undefined) {
+      // Non-model body with an explicit example.
+      operation.requestBody = {
+        content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } },
+      };
     }
+  }
+}
 
-    // Registered response schemas ($ref) — explicit and authoritative, keyed by status.
-    const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
-    if (respSchemas.length > 0) {
-      const responses = operation.responses as Record<string, unknown>;
-      for (const { status, name, isList } of respSchemas) {
-        refSchemas.add(name);
-        const sref = `#/components/schemas/${name}`;
-        const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
-        responses[status] = {
-          description: status.startsWith("2") ? "Successful response" : "Response",
-          content: { "application/json": { schema } },
-        };
-      }
+/**
+ * Registered response schemas ($ref) — explicit and authoritative, keyed by
+ * status; each maps to the resource, or an array of it when marked as a list.
+ */
+function operationResponseSchemas(
+  route: RouteDefinition,
+  operation: Record<string, unknown>,
+  refSchemas: Set<string>
+): void {
+  const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
+  if (respSchemas.length > 0) {
+    const responses = operation.responses as Record<string, unknown>;
+    for (const { status, name, isList } of respSchemas) {
+      refSchemas.add(name);
+      const sref = `#/components/schemas/${name}`;
+      const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
+      responses[status] = {
+        description: status.startsWith("2") ? "Successful response" : "Response",
+        content: { "application/json": { schema } },
+      };
     }
+  }
+}
 
-    // Security (v3.13.42) — explicit meta.security wins (empty list = explicitly
-    // public); otherwise a secured route gets the default scheme. Scopes are kept
-    // valid (only oauth2/openIdConnect carry them).
-    const hasExplicitSecurity =
-      route.meta?.security !== undefined || (route.meta?.scopes !== undefined && route.meta.scopes.length > 0);
-    if (hasExplicitSecurity) {
-      const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
-      operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
-      if (normalized.length > 0) {
-        const responses = operation.responses as Record<string, unknown>;
-        if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
-      }
-    } else if (routeRequiresAuth(route, method)) {
-      const requirements = [{ [defaultScheme]: [] }];
-      if (defaultScheme === "bearerAuth" && schemes.ssoSession) requirements.push({ ssoSession: [] });
-      operation.security = sanitizeSecurity(requirements, schemes);
+/**
+ * Per-route security (v3.13.42). Explicit meta.security wins (empty list =
+ * explicitly public); otherwise a secured route gets the default scheme (plus
+ * ssoSession when bearer + SSO is configured). A secured op also documents a
+ * 401. Scopes are kept valid (only oauth2/openIdConnect carry them).
+ */
+function operationSecurity(
+  route: RouteDefinition,
+  method: string,
+  operation: Record<string, unknown>,
+  schemes: Record<string, Record<string, unknown>>,
+  defaultScheme: string
+): void {
+  const hasExplicitSecurity =
+    route.meta?.security !== undefined || (route.meta?.scopes !== undefined && route.meta.scopes.length > 0);
+  if (hasExplicitSecurity) {
+    const normalized = normalizeSecurity(route.meta?.security, route.meta?.scopes);
+    operation.security = normalized.length > 0 ? sanitizeSecurity(normalized, schemes) : [];
+    if (normalized.length > 0) {
       const responses = operation.responses as Record<string, unknown>;
       if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
     }
-
-    spec.paths[openApiPath][method] = operation;
+  } else if (routeRequiresAuth(route, method)) {
+    const requirements = [{ [defaultScheme]: [] }];
+    if (defaultScheme === "bearerAuth" && schemes.ssoSession) requirements.push({ ssoSession: [] });
+    operation.security = sanitizeSecurity(requirements, schemes);
+    const responses = operation.responses as Record<string, unknown>;
+    if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
   }
+}
 
-  // Registered component schemas referenced via meta.requestSchema/responseSchemas.
+/** Registered component schemas referenced via meta.requestSchema/responseSchemas. */
+function buildRefSchemas(spec: OpenAPISpec, refSchemas: Set<string>): void {
   if (refSchemas.size > 0) {
     const schemas = spec.components!.schemas!;
     for (const name of refSchemas) {
@@ -375,12 +481,13 @@ export function generate(
       }
     }
   }
+}
 
+/** Top-level tags[] from the tags collected across operations (registration order). */
+function buildTags(spec: OpenAPISpec, usedTags: string[]): void {
   if (usedTags.length > 0) {
     spec.tags = usedTags.map((name) => ({ name }));
   }
-
-  return spec;
 }
 
 function routeRequiresAuth(route: RouteDefinition, method: string): boolean {

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";