tina4-nodejs 3.13.18 → 3.13.20

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.18)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.20)
 
 > 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.18 — 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.20 — 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,653 tests** passing across all modules
+- **3,684 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.18",
+  "version": "3.13.20",
 
   "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/core/src/server.ts

@@ -12,7 +12,7 @@ import { validToken, getPayload, refreshToken } from "./auth.js";
 import { discoverRoutes } from "./routeDiscovery.js";
 import { createRequest } from "./request.js";
 import { createResponse, setDefaultTemplatesDir } from "./response.js";
-import { MiddlewareChain, cors, requestLogger } from "./middleware.js";
+import { MiddlewareChain, MiddlewareRunner, cors, requestLogger } from "./middleware.js";
 import { tryServeStatic } from "./static.js";
 import { loadEnv, isTruthy } from "./dotenv.js";
 import { createHealthRoutes } from "./health.js";
@@ -1108,6 +1108,19 @@ ${reset}
         req.params = match.params;
         matchedPattern = match.pattern;
 
+        // Global class-based middleware registered via Router.use(...) /
+        // MiddlewareRunner.use(...) — run the beforeX hooks before the handler.
+        // beforeX may set response headers (they persist through the handler's
+        // write), mutate the request, or short-circuit on a >= 400 status.
+        // (Parity with Python/PHP/Ruby, whose Router.use class middleware runs.)
+        const globalMiddleware = [
+          ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
+        ];
+        if (globalMiddleware.length > 0) {
+          const [, , proceed] = MiddlewareRunner.runBefore(globalMiddleware, req, res);
+          if (!proceed || res.raw.writableEnded) return;
+        }
+
         // Run per-route middlewares if any
         if (match.middlewares && match.middlewares.length > 0) {
           const proceed = await runRouteMiddlewares(match.middlewares, req, res);
@@ -1198,6 +1211,13 @@ ${reset}
           await res.render(match.template, result as Record<string, unknown>);
         }
 
+        // Global class-based middleware afterX hooks (logging / post-processing).
+        // Header mutations here are no-ops once the response is flushed (Node
+        // sends headers with the body) — set response headers in beforeX.
+        if (globalMiddleware.length > 0) {
+          MiddlewareRunner.runAfter(globalMiddleware, req, res);
+        }
+
         if (!res.raw.writableEnded) {
           res.raw.end();
         }

package/packages/orm/src/baseModel.ts

@@ -95,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

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,