tina4-nodejs 3.13.16 → 3.13.18

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.16)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.18)
 
 > 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.16 — 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.18 — 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.
 
@@ -1062,7 +1062,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,644 tests** passing across all modules
+- **3,653 tests** passing across all modules
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.16",
+  "version": "3.13.18",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/orm/src/adapters/postgres.ts

@@ -10,12 +10,14 @@ import { SQLTranslator } from "../sqlTranslation.js";
 import { createRequire } from "node:module";
 
 let pg: typeof import("pg") | null = null;
+let typeParsersRegistered = false;
 
 function requirePg(): typeof import("pg") {
   if (pg) return pg;
   try {
     const req = createRequire(import.meta.url);
     pg = req("pg");
+    registerTypeParsers(pg!);
     return pg!;
   } catch {
     throw new Error(
@@ -28,6 +30,33 @@ function requirePg(): typeof import("pg") {
   }
 }
 
+/**
+ * Register global pg type parsers so int8 and numeric/decimal columns decode to
+ * JS numbers instead of strings. node-postgres returns int8 (OID 20) and
+ * numeric (OID 1700) as strings by default to preserve full precision; Python,
+ * Ruby and PHP all return native numerics for aggregates (SUM, AVG, COUNT, …),
+ * so this brings Node to cross-framework parity. count() and getNextId() already
+ * coerce via Number(), so this is purely additive for them.
+ *
+ * PRECISION CAVEAT: values beyond Number.MAX_SAFE_INTEGER (2^53 - 1) lose
+ * precision when coerced to a JS double. That is the accepted trade-off for
+ * parity — Python and Ruby return native numerics (and lose precision the same
+ * way for floats) too. Applications that need exact 64-bit/arbitrary-precision
+ * values should select the column with an explicit ::text cast.
+ *
+ * Idempotent — registration runs once per process.
+ */
+function registerTypeParsers(pgModule: typeof import("pg")): void {
+  if (typeParsersRegistered) return;
+  const types = pgModule.types ?? (pgModule as any).default?.types;
+  if (!types?.setTypeParser) return;
+  // OID 20  = int8 (bigint)  → Number  (NULL passes through untouched by pg)
+  types.setTypeParser(20, (v: string) => Number(v));
+  // OID 1700 = numeric / decimal → parseFloat
+  types.setTypeParser(1700, (v: string) => parseFloat(v));
+  typeParsersRegistered = true;
+}
+
 export interface PostgresConfig {
   host?: string;
   port?: number;

package/packages/orm/src/baseModel.ts

@@ -8,6 +8,7 @@ import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
 import { QueryCache } from "./sqlTranslation.js";
+import { Log } from "@tina4/core";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 
 /**
@@ -1149,6 +1150,28 @@ export class BaseModel {
 
   static registerModel(name: string, modelClass: typeof BaseModel): void {
     BaseModel._modelRegistry[name] = modelClass;
+    // Eagerly process this model's foreignKey fields so the cross-model
+    // _fkRegistry is populated as soon as the model is known — not only when
+    // the *declaring* model happens to be touched first. This is what makes
+    // eager loading work standalone (without server-boot auto-discovery):
+    // a parent's hasMany is registered by the child's _processForeignKeys(),
+    // so we must run it for every registered model proactively.
+    modelClass._processForeignKeys();
+  }
+
+  /**
+   * Process foreignKey fields on every registered model so the cross-model
+   * _fkRegistry (and each model's belongsTo/hasMany) is fully wired regardless
+   * of which model was used first. Idempotent — _processForeignKeys() and
+   * _applyFkRegistry() both guard against duplicates.
+   */
+  private static _processAllForeignKeys(): void {
+    for (const modelClass of Object.values(BaseModel._modelRegistry)) {
+      modelClass._processForeignKeys();
+    }
+    for (const modelClass of Object.values(BaseModel._modelRegistry)) {
+      modelClass._applyFkRegistry();
+    }
   }
 
   /**
@@ -1168,9 +1191,13 @@ export class BaseModel {
 
     const ModelClass = instances[0].constructor as typeof BaseModel;
 
-    // Apply FK registry so foreignKey fields auto-wire hasMany on referenced models
-    ModelClass._processForeignKeys();
-    ModelClass._applyFkRegistry();
+    // Wire FK relationships across ALL registered models, not just the parent.
+    // A parent's hasMany is declared by the CHILD's foreignKey field, so we must
+    // process every registered model's FKs before resolving includes — otherwise
+    // a standalone Author.findById(id, ["posts"]) silently finds nothing because
+    // Post._processForeignKeys() never ran. _applyFkRegistry() then merges the
+    // registered hasMany entries onto each model.
+    BaseModel._processAllForeignKeys();
 
     // Group includes: top-level and nested
     const topLevel: Record<string, string[]> = {};
@@ -1186,28 +1213,54 @@ export class BaseModel {
     }
 
     for (const [relName, nested] of Object.entries(topLevel)) {
-      // Find the relationship definition
+      // Find the relationship definition.
+      //
+      // Include names are resolved case-insensitively against each candidate
+      // relation. Accepted forms (for a relation to model "Post" on table "posts"):
+      //   - the model name           → "Post" / "post"
+      //   - the auto/related key     → "post" (singular) or "posts" (when
+      //                                 TINA4_ORM_PLURAL_TABLE_NAMES is enabled)
+      //   - the table name           → "posts"
+      // All matching is lower-cased so "Post", "post" and "posts" all resolve.
+      const want = relName.toLowerCase();
       let relDef: RelationshipDefinition | undefined;
       let relType: "hasOne" | "hasMany" | "belongsTo" | null = null;
 
+      const matchesModel = (r: RelationshipDefinition): boolean => {
+        const base = r.model.toLowerCase();
+        const related = BaseModel._modelRegistry[r.model];
+        const table = related?.tableName?.toLowerCase();
+        return (
+          base === want ||
+          base + "s" === want ||
+          (table !== undefined && table === want)
+        );
+      };
+
       if (ModelClass.hasOne) {
-        relDef = ModelClass.hasOne.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+        relDef = ModelClass.hasOne.find(matchesModel);
         if (relDef) relType = "hasOne";
       }
       if (!relDef && ModelClass.hasMany) {
-        relDef = ModelClass.hasMany.find((r) => {
-          const base = r.model.toLowerCase();
-          const key = _pluralRelKeys() ? base + "s" : base;
-          return key === relName || base === relName || r.model === relName;
-        });
+        relDef = ModelClass.hasMany.find(matchesModel);
         if (relDef) relType = "hasMany";
       }
       if (!relDef && ModelClass.belongsTo) {
-        relDef = ModelClass.belongsTo.find((r) => r.model.toLowerCase() === relName || r.model === relName);
+        relDef = ModelClass.belongsTo.find(matchesModel);
         if (relDef) relType = "belongsTo";
       }
 
-      if (!relDef || !relType) continue;
+      if (!relDef || !relType) {
+        // Don't silently skip — a typo'd or unknown include name is almost
+        // always a developer mistake. Surface it so it's visible.
+        Log.warn(
+          `eager-load: include "${relName}" did not match any relationship on ` +
+            `${ModelClass.name} (table "${ModelClass.tableName}"). ` +
+            `Accepted forms are the related model name, its singular/plural ` +
+            `key, or the related table name (case-insensitive).`,
+        );
+        continue;
+      }
 
       const relatedClass = BaseModel._modelRegistry[relDef.model];
       if (!relatedClass) continue;