tina4-nodejs 3.13.132 → 3.13.133

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.132)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.133)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.132 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.133 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -172,6 +172,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `sqlTranslator.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|false` (fluent, false on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
 - **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(limit=100, offset=0, include?, orderBy?)`, `select(sql, params?, limit=100, offset=0)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit=100, offset=0, include?, orderBy?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit=100, offset=0)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
+- **ModelCollection (ADR-0064):** `where`, `select`, `find` (filter form), `all`, and `withTrashed` return a `ModelCollection<T>` (extends `Array<T>`, so `Array.isArray` stays true and iterate/index/`.length`/`JSON.stringify` are unchanged) that ALSO carries the filter total, independent of limit/offset: `rows.getTotalRecords()` (e.g. 250, reuses the query COUNT -- zero extra queries) and `rows.toPaginate()` (`{ records, total, page, per_page, total_pages, limit, offset }`). A method, not a `.count` property. Single-record finders (`findById`, `selectOne`) are unchanged.
 - **Foreign key auto-wire (declarative, read-side-only):** Declare a field with `type: "foreignKey"` and `references: "ModelName"` to auto-wire both `belongsTo` on the declaring model and `hasMany` on the referenced model. Optional `relatedName` overrides the has-many key. Models must be registered via `BaseModel.registerModel(name, class)` for name-based resolution. Example: `author_id: { type: "foreignKey", references: "Author", relatedName: "posts" }` attaches LAZY accessors on both sides — `await post.author` (belongsTo) and `await author.posts` (hasMany) resolve on attribute access (async, cached), and `include: ["posts"]` on `find`/`all`/`where` eager-loads them in ONE query per relation. A soft-deleted child is excluded from traversal, and the has-many read is uncapped. The auto-wire emits NO DB-level FK / ON DELETE clause (REL-DEC-01, read-side-only): referential integrity is the migration/DDL's job, so deleting a parent does not cascade to children at the engine level. (Before 3.13.99 the declarative accessors did not attach and lazy load did not exist — only the imperative `post.belongsTo(Author, "author_id")` / `author.hasMany(Post, "author_id")` worked.)
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.132",
+  "version": "3.13.133",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -37635,12 +37635,46 @@ function sanitizeSecurity(reqs, schemes) {
   });
 }
 function generate2(routes, models = []) {
+  const schemes = resolveSecuritySchemes();
+  const spec = {
+    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
+    }
+  };
+  const tableToSchema = /* @__PURE__ */ new Map();
+  buildComponentSchemas(models, spec, tableToSchema);
+  const ctx = {
+    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: /* @__PURE__ */ new Set(),
+    usedTags: [],
+    seenIds: /* @__PURE__ */ new Set()
+  };
+  for (const route of routes) {
+    buildOperation(route, spec, ctx);
+  }
+  buildRefSchemas(spec, ctx.refSchemas);
+  buildTags(spec, ctx.usedTags);
+  return spec;
+}
+function buildInfo() {
   const info = {
     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 ?? ""
   };
@@ -37657,135 +37691,134 @@ function generate2(routes, models = []) {
     const [name, url] = licenseRaw.split("|").map((s) => s.trim());
     info.license = url ? { name, url } : { name };
   }
-  const schemes = resolveSecuritySchemes();
-  const spec = {
-    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
-    }
-  };
-  const defaultScheme = process.env.TINA4_SWAGGER_DEFAULT_SCHEME ?? "bearerAuth";
-  const includePrefixes = csv(process.env.TINA4_SWAGGER_INCLUDE);
-  const excludePrefixes = csv(process.env.TINA4_SWAGGER_EXCLUDE);
-  const refSchemas = /* @__PURE__ */ new Set();
-  const tableToSchema = /* @__PURE__ */ new Map();
+  return info;
+}
+function buildComponentSchemas(models, spec, tableToSchema) {
   for (const model of models) {
     const schemaKey = schemaNameForModel(model);
     tableToSchema.set(model.tableName, schemaKey);
     spec.components.schemas[schemaKey] = modelToSchema(model);
   }
-  const usedTags = [];
-  const seenIds = /* @__PURE__ */ new Set();
-  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] = {};
-    }
-    const tags = route.meta?.tags ?? inferTags(route.pattern);
-    for (const t of tags) {
-      if (!usedTags.includes(t)) usedTags.push(t);
-    }
-    const operation = {
-      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;
-    const pathParams = extractPathParams(route.pattern);
-    if (pathParams.length > 0) {
-      operation.parameters = pathParams.map(({ name, schema }) => ({
-        name,
-        in: "path",
-        required: true,
-        schema
-      }));
+}
+function buildOperation(route, spec, ctx) {
+  if (!isIncludedPath(route.pattern, ctx.includePrefixes, ctx.excludePrefixes)) return;
+  const openApiPath = patternToOpenAPI(route.pattern);
+  const method = route.method.toLowerCase();
+  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 operation = {
+    operationId: uniqueOperationId(method, openApiPath, ctx.seenIds),
+    summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
+    tags,
+    responses: route.meta?.responses ?? {
+      "200": { description: "Successful response" }
     }
-    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 ?? [],
-          { 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)" }
-        ];
-      }
+  };
+  if (route.meta?.description) operation.description = route.meta.description;
+  if (route.meta?.deprecated) operation.deprecated = true;
+  const parameters = operationParameters(route, method, ctx.models);
+  if (parameters.length > 0) operation.parameters = parameters;
+  operationRequestBody(route, method, operation, ctx);
+  operationResponseSchemas(route, operation, ctx.refSchemas);
+  operationSecurity(route, method, operation, ctx.schemes, ctx.defaultScheme);
+  spec.paths[openApiPath][method] = operation;
+}
+function operationParameters(route, method, models) {
+  let parameters = [];
+  const pathParams = extractPathParams(route.pattern);
+  if (pathParams.length > 0) {
+    parameters = pathParams.map(({ name, schema }) => ({
+      name,
+      in: "path",
+      required: true,
+      schema
+    }));
+  }
+  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)" }
+      ];
     }
-    const reqSchemaRef = parseRequestSchema(route.meta?.requestSchema);
-    if (reqSchemaRef && (method === "post" || method === "put" || method === "patch")) {
-      refSchemas.add(reqSchemaRef.name);
-      const media = {
-        schema: { $ref: `#/components/schemas/${reqSchemaRef.name}` }
-      };
-      if (route.meta?.example !== void 0) media.example = route.meta.example;
+  }
+  return parameters;
+}
+function mediaWithExample(schema, example) {
+  const media = { schema };
+  if (example !== void 0) media.example = example;
+  return media;
+}
+function operationRequestBody(route, method, operation, ctx) {
+  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) : void 0;
+    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) : void 0;
-      if (schemaKey) {
-        const sref = `#/components/schemas/${schemaKey}`;
-        const media = { schema: { $ref: sref } };
-        if (route.meta?.example !== void 0) media.example = route.meta.example;
-        operation.requestBody = {
-          required: true,
-          content: { "application/json": media }
-        };
-        if (route.meta?.responses === void 0) {
-          operation.responses = {
-            "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
-          };
-        }
-      } else if (route.meta?.example !== void 0) {
-        operation.requestBody = {
-          content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
+      if (route.meta?.responses === void 0) {
+        operation.responses = {
+          "200": { description: "Successful response", content: { "application/json": { schema: { $ref: sref } } } }
         };
       }
+    } else if (route.meta?.example !== void 0) {
+      operation.requestBody = {
+        content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } }
+      };
     }
-    const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
-    if (respSchemas.length > 0) {
-      const responses = operation.responses;
-      for (const { status: status2, name, isList } of respSchemas) {
-        refSchemas.add(name);
-        const sref = `#/components/schemas/${name}`;
-        const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
-        responses[status2] = {
-          description: status2.startsWith("2") ? "Successful response" : "Response",
-          content: { "application/json": { schema } }
-        };
-      }
+  }
+}
+function operationResponseSchemas(route, operation, refSchemas) {
+  const respSchemas = parseResponseSchemas(route.meta?.responseSchemas);
+  if (respSchemas.length > 0) {
+    const responses = operation.responses;
+    for (const { status: status2, name, isList } of respSchemas) {
+      refSchemas.add(name);
+      const sref = `#/components/schemas/${name}`;
+      const schema = isList ? { type: "array", items: { $ref: sref } } : { $ref: sref };
+      responses[status2] = {
+        description: status2.startsWith("2") ? "Successful response" : "Response",
+        content: { "application/json": { schema } }
+      };
     }
-    const hasExplicitSecurity = route.meta?.security !== void 0 || route.meta?.scopes !== void 0 && 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;
-        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);
+  }
+}
+function operationSecurity(route, method, operation, schemes, defaultScheme) {
+  const hasExplicitSecurity = route.meta?.security !== void 0 || route.meta?.scopes !== void 0 && 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;
       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;
+    if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
   }
+}
+function buildRefSchemas(spec, refSchemas) {
   if (refSchemas.size > 0) {
     const schemas = spec.components.schemas;
     for (const name of refSchemas) {
@@ -37794,10 +37827,11 @@ function generate2(routes, models = []) {
       }
     }
   }
+}
+function buildTags(spec, usedTags) {
   if (usedTags.length > 0) {
     spec.tags = usedTags.map((name) => ({ name }));
   }
-  return spec;
 }
 function routeRequiresAuth(route, method) {
   if (route.noAuth) return false;