tina4-nodejs 3.13.16 → 3.13.19

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.19)
 
 > 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.19 — 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.
 
@@ -105,7 +105,7 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `router.ts` — Pattern matching with `{id}` dynamic params and `{...slug}` catch-all
 - `routeDiscovery.ts` — Scans `src/routes/` recursively, maps files to endpoints (converts `[id]` dirs to `{id}` URL patterns)
 - `request.ts` — Wraps `IncomingMessage`, adds `.params`, `.query`, `.body`
-- `response.ts` — Wraps `ServerResponse`, adds `.json()`, `.html()`, `.status()`, `.send()`, `.redirect()`
+- `response.ts` — Wraps `ServerResponse`, adds `.json()`, `.html()`, `.status()`, `.send()`, `.redirect()`. `res.json(...)` / `response(...)` auto-serialize an ORM model (→ JSON object), an array of models, or a `DatabaseResult` (→ JSON array) — no manual `toDict()`/`toJson()`. Plain objects, arrays and strings behave exactly as before (purely additive).
 - `middleware.ts` — Chain runner, built-in CORS and request logger
 - `static.ts` — Serves files from `public/` with MIME type detection
 - `types.ts` — All shared type definitions (`Tina4Request`, `Tina4Response`, `RouteHandler`, etc.)
@@ -243,6 +243,8 @@ response.xml(content, status?): Tina4Response
 response.stream(source: AsyncIterable<string | Buffer>, contentType?: string): Promise<Tina4Response>  // SSE/streaming
 ```
 
+`res.json(model)`, `res.json(arrayOfModels)`, and `res.json(db.fetch(...))` auto-serialize to JSON — a single model becomes a JSON object, an array of models or a `DatabaseResult` becomes a JSON array. No manual `toDict()`/`toJson()` needed.
+
 ### Queue
 
 ```typescript
@@ -553,7 +555,7 @@ r.group("/api/v1", (g) => {
 Full Database API. The same instance covers all five drivers (sqlite, postgres, mysql, mssql, firebird) — pick the driver via `TINA4_DATABASE_URL` or pass a `DatabaseConfig` to `initDatabase()`.
 
 ```typescript
-import { initDatabase, Database, DatabaseResult } from "@tina4/orm";
+import { initDatabase, bindDatabase, createAdapterFromUrl, Database, DatabaseResult } from "@tina4/orm";
 
 const db = await initDatabase({ url: "sqlite:///app.db" });
 // Connection pooling: pass `pool: 4` for round-robin connections.
@@ -595,6 +597,30 @@ db.cacheClear(): void
 db.pool
 ```
 
+### Binding adapters: `bindDatabase` / `createAdapterFromUrl`
+
+There are three ways models get an adapter, in increasing order of explicitness:
+
+```typescript
+import { initDatabase, bindDatabase, createAdapterFromUrl } from "@tina4/orm";
+
+// (a) .env auto-default (unchanged) — initDatabase() auto-binds the default at boot.
+//     Most apps need nothing more than TINA4_DATABASE_URL in .env.
+const db = await initDatabase({ url: "sqlite:///app.db" });
+
+// (b) Set or override the default explicitly with bindDatabase(adapter).
+bindDatabase(adapter);
+
+// (c) Register a NAMED / secondary connection and point a model at it.
+bindDatabase(await createAdapterFromUrl("postgres://localhost:5432/analytics"), "analytics");
+// then a model selects it:
+//   class Visit extends BaseModel { static _db = "analytics"; }
+```
+
+- `bindDatabase(adapter, name?)` — public binder. With no `name` it sets/overrides the **default** connection; with a `name` it registers a **named** connection. `initDatabase()` (auto-binds the `.env` default) and the internal `setAdapter()` are unchanged — `bindDatabase` is additive and non-breaking.
+- `createAdapterFromUrl(url, user?, pass?)` — now exported. Builds a `DatabaseAdapter` from a connection URL (and optional credentials), ready to pass to `bindDatabase`.
+- A model selects a named connection via `static _db = "analytics"`. A mistyped/missing named connection (e.g. `static _db = "typo"`) now **throws** a clear error instead of silently falling back to the default.
+
 **`tina4_sequences` table** — Auto-created by `getNextId()` on first use for SQLite, MySQL, and MSSQL. Stores the current sequence value per table. Do not modify this table manually.
 
 ## Module: ORM (`packages/orm/src/baseModel.ts`)
@@ -602,7 +628,7 @@ db.pool
 Active-Record base class. Models live in `src/models/` and are auto-discovered. Use `static fields` (not decorators) — same convention across all four frameworks.
 
 ```typescript
-import { BaseModel, initDatabase, setAdapter } from "@tina4/orm";
+import { BaseModel, initDatabase, bindDatabase, createAdapterFromUrl } from "@tina4/orm";
 
 export default class User extends BaseModel {
   static tableName = "users";
@@ -612,10 +638,15 @@ export default class User extends BaseModel {
     author_id: { type: "foreignKey" as const, references: "Author" }, // auto-wires belongsTo + hasMany
   };
   static softDelete = true;   // optional — toggles is_deleted column
+  // static _db = "analytics";  // optional — bind this model to a named connection
 }
 
+// Constructor accepts an object OR a JSON object string. Passing an array throws TypeError.
+const user  = new User({ email: "alice@example.com" });
+const user2 = new User('{"email":"bob@example.com"}');  // JSON object string -> one record
+// new User([{ ... }]);  // throws TypeError — map over the list to build many records
+
 // Instance methods (chainable where it makes sense)
-const user = new User({ email: "alice@example.com" });
 user.save();              // returns this on success, false on failure
 user.delete();            // soft-delete if enabled, otherwise hard
 user.forceDelete();       // bypasses soft-delete
@@ -645,11 +676,16 @@ User.createTable();
 User.query(): QueryBuilder;
 BaseModel.registerModel(name, class);     // for foreignKey name resolution
 
-// Models bind to the active adapter, not a Database wrapper. initDatabase() sets it
-// automatically; setAdapter() lets you bind one explicitly. Models read it via getAdapter().
-await initDatabase({ url: "sqlite:///app.db" });   // sets the active adapter for all models
-// or, with an adapter you constructed yourself:
-setAdapter(adapter);
+// Models bind to the active adapter, not a Database wrapper. There are three ways:
+// (a) .env auto-default (unchanged) — initDatabase() auto-binds the default at boot:
+await initDatabase({ url: "sqlite:///app.db" });   // sets the default adapter for all models
+// (b) set/override the default explicitly:
+bindDatabase(adapter);
+// (c) register a NAMED/secondary connection, then point a model at it with `static _db`:
+bindDatabase(await createAdapterFromUrl("postgres://localhost:5432/analytics"), "analytics");
+//   class Visit extends BaseModel { static _db = "analytics"; }
+// A mistyped/missing named connection (e.g. static _db = "typo") now throws instead of
+// silently falling back to the default. (initDatabase / the internal setAdapter are unchanged.)
 ```
 
 **Soft delete:** set `static softDelete = true`. Adds an `is_deleted` INTEGER column (0/1). `delete()` flips the flag, `forceDelete()` removes the row, `restore()` clears it.
@@ -1062,7 +1098,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,679 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.19",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/response.ts

@@ -81,6 +81,38 @@ export function setFrond(engine: InstanceType<any>): void {
  *   return response.json(data, 201);                   // Method
  *   return response.redirect("/login");                // Special
  */
+/**
+ * Normalise domain objects into JSON-serialisable values so handlers can
+ * `return response(model)` / `res.json(model)` without calling .toDict() by hand:
+ *
+ *   return response(user);               // ORM model       -> object
+ *   return response(await User.all());   // model[]          -> object[]
+ *   return response(await db.fetch(sql));// DatabaseResult   -> object[]
+ *
+ * Duck-typed (no @tina4/orm import — avoids a package cycle): a callable
+ * `toDict` marks a model; a `records` array plus a `toArray` method marks a
+ * query result. Plain objects / arrays / scalars pass through unchanged.
+ */
+function toJsonable(data: unknown): unknown {
+  if (data === null || typeof data !== "object" || Buffer.isBuffer(data)) {
+    return data;
+  }
+  const obj = data as Record<string, unknown>;
+  // Query result (DatabaseResult-like): records array + toArray method.
+  if (Array.isArray(obj.records) && typeof obj.toArray === "function") {
+    return obj.records;
+  }
+  // ORM model: callable toDict().
+  if (typeof obj.toDict === "function") {
+    return (obj.toDict as () => unknown)();
+  }
+  // Collections: normalise each element (array of models -> array of objects).
+  if (Array.isArray(data)) {
+    return data.map((item) => toJsonable(item));
+  }
+  return data;
+}
+
 export function createResponse(res: ServerResponse): Tina4Response {
 
   // ── Guard: prevent writing after headers are sent ──
@@ -95,6 +127,10 @@ export function createResponse(res: ServerResponse): Tina4Response {
   const response = function (data?: unknown, statusCode?: number, contentType?: string): Tina4Response {
     if (res.headersSent) return response;
 
+    // Normalise ORM models / collections / query results so handlers can
+    // `return response(model)` without serialising by hand.
+    data = toJsonable(data);
+
     if (statusCode !== undefined) {
       res.statusCode = statusCode;
     }
@@ -143,7 +179,7 @@ export function createResponse(res: ServerResponse): Tina4Response {
     if (res.headersSent) return response;
     if (status !== undefined) res.statusCode = status;
     safeSetHeader("Content-Type", "application/json");
-    safeEnd(JSON.stringify(data));
+    safeEnd(JSON.stringify(toJsonable(data)));
     return response;
   };
 

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";
 
 /**
@@ -94,7 +95,21 @@ export class BaseModel {
   /** Relationship cache for lazy loading */
   private _relCache: Record<string, unknown> = {};
 
-  constructor(data?: Record<string, unknown>) {
+  constructor(data?: Record<string, unknown> | string) {
+    // Accept a JSON object string (parity with Python/PHP/Ruby):
+    //   new Widget('{"id":1,"name":"alpha"}')
+    if (typeof data === "string") {
+      data = JSON.parse(data) as Record<string, unknown>;
+    }
+    // A single model is one record — reject an array with a clear message
+    // (previously an array silently produced an empty model).
+    if (Array.isArray(data)) {
+      throw new TypeError(
+        `${(this.constructor as typeof BaseModel).name} expects an object, keyword data, ` +
+          `or a JSON object string for one record — got an array. ` +
+          `Map over the list to build many records.`,
+      );
+    }
     if (data) {
       const ModelClass = this.constructor as typeof BaseModel;
       // If autoMap is on, auto-generate fieldMapping from camelCase fields
@@ -1149,6 +1164,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 +1205,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 +1227,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;

package/packages/orm/src/database.ts

@@ -132,6 +132,39 @@ export function setAdapter(adapter: DatabaseAdapter): void {
   activeAdapter = adapter;
 }
 
+/**
+ * Public, user-facing API to bind a database connection.
+ *
+ * - No `name`  → registers `adapter` as the global default connection
+ *   (what `getAdapter()` returns and what every model resolves to unless it
+ *   declares `static _db`). This is the manual equivalent of the auto-binding
+ *   that `initDatabase()` performs from `.env`/`TINA4_DATABASE_URL`.
+ * - With `name` → registers `adapter` in the named registry. A model with
+ *   `static _db = name` resolves to it via `getNamedAdapter(name)`.
+ *
+ * Mirrors the Python master `bind_database(db, name=None)`.
+ *
+ *     import { bindDatabase, createAdapterFromUrl } from "@tina4/orm";
+ *
+ *     // Default connection
+ *     bindDatabase(adapter);
+ *
+ *     // Named secondary connection built from a URL (kept synchronous —
+ *     // build the adapter first, then bind it)
+ *     bindDatabase(await createAdapterFromUrl(url, user, pass), "analytics");
+ *
+ * `bindDatabase` itself is synchronous: it takes an already-constructed
+ * adapter. Use `createAdapterFromUrl()` to build a named secondary adapter
+ * from a URL without making it the default.
+ */
+export function bindDatabase(adapter: DatabaseAdapter, name?: string): void {
+  if (name === undefined) {
+    setAdapter(adapter);
+  } else {
+    namedAdapters.set(name, adapter);
+  }
+}
+
 export function getAdapter(): DatabaseAdapter {
   if (!activeAdapter) {
     throw new Error("No database adapter configured. Call setAdapter() first.");
@@ -148,13 +181,24 @@ export function setNamedAdapter(name: string, adapter: DatabaseAdapter): void {
 }
 
 /**
- * Get a named adapter. Falls back to the default adapter if name not found.
+ * Get a named adapter previously registered via `bindDatabase(adapter, name)`
+ * (or the lower-level `setNamedAdapter(name, adapter)`).
+ *
+ * Throws a clear error if the name isn't registered — a model that declares
+ * `static _db = "name"` resolves through here, so a missing name means the
+ * connection was never bound. The message tells the developer exactly how to
+ * fix it rather than silently falling back to the default connection (which
+ * would hide the mistake and write to the wrong database).
  */
 export function getNamedAdapter(name: string): DatabaseAdapter {
   const adapter = namedAdapters.get(name);
   if (adapter) return adapter;
-  // Fall back to default
-  return getAdapter();
+  throw new Error(
+    `No database adapter registered under the name "${name}". ` +
+    `Call bindDatabase(adapter, "${name}") before using a model with ` +
+    `static _db = "${name}" (build a secondary adapter with ` +
+    `createAdapterFromUrl(url, user, pass) if you need one from a URL).`,
+  );
 }
 
 export function closeDatabase(): void {
@@ -908,10 +952,19 @@ export class Database {
 }
 
 /**
- * Internal helper: create a DatabaseAdapter from a parsed URL.
- * Extracted from initDatabase so Database.create() can reuse it.
+ * Build a connected `DatabaseAdapter` from a connection URL.
+ *
+ * Used internally by `initDatabase()` and `Database.create()`, and exported so
+ * users can construct a NAMED secondary adapter without making it the default:
+ *
+ *     bindDatabase(await createAdapterFromUrl(url, user, pass), "analytics");
+ *
+ * Unlike `initDatabase()`, this does NOT call `setAdapter()` — it returns a
+ * standalone adapter that the caller decides what to do with. For async engines
+ * (Postgres/MySQL/MSSQL/Firebird/Mongo) the returned adapter is already
+ * connected; SQLite connects lazily.
  */
-async function createAdapterFromUrl(url: string, username?: string, password?: string): Promise<DatabaseAdapter> {
+export async function createAdapterFromUrl(url: string, username?: string, password?: string): Promise<DatabaseAdapter> {
   const parsed = parseDatabaseUrl(url, username, password);
 
   switch (parsed.type) {

package/packages/orm/src/index.ts

@@ -14,7 +14,7 @@ export { FetchResult } from "./types.js";
 
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
-export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons } from "./database.js";
+export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons } from "./database.js";
 export {
   adapterFetch, adapterQuery, adapterFetchOne, adapterExecute,
   adapterStartTransaction, adapterCommit, adapterRollback,