tina4-nodejs 3.9.3 → 3.10.1

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.9.2)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.1)
 
 > 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.9.2 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.10.1 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.9.3",
+  "version": "3.10.1",
   "type": "module",
   "description": "This is not a framework. Tina4 for Node.js/TypeScript — zero deps, 38 built-in features.",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/queue.ts

@@ -31,6 +31,9 @@
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { RabbitMQBackend } from "./queueBackends/rabbitmqBackend.js";
+import { KafkaBackend } from "./queueBackends/kafkaBackend.js";
+import { MongoBackend } from "./queueBackends/mongoBackend.js";
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -137,13 +140,10 @@ export class Queue {
 
     // Initialize external backends
     if (this.backendName === "rabbitmq") {
-      const { RabbitMQBackend } = require("./queueBackends/rabbitmqBackend.js");
       this.externalBackend = new RabbitMQBackend();
     } else if (this.backendName === "kafka") {
-      const { KafkaBackend } = require("./queueBackends/kafkaBackend.js");
       this.externalBackend = new KafkaBackend();
     } else if (this.backendName === "mongodb" || this.backendName === "mongo") {
-      const { MongoBackend } = require("./queueBackends/mongoBackend.js");
       this.externalBackend = new MongoBackend();
     }
   }

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -9,6 +9,7 @@
  *   TINA4_KAFKA_GROUP_ID  (default: "tina4_consumer_group")
  */
 import net from "node:net";
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import type { QueueJob } from "../queue.js";
 
@@ -72,7 +73,7 @@ export class KafkaBackend implements QueueBackend {
    * Execute a Kafka operation synchronously via a child process.
    */
   private execSync(operation: string, topic: string, data?: string): string {
-    const { execFileSync } = require("node:child_process");
+    // execFileSync imported at top level
     const broker = this.parseBroker();
 
     const script = `

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -12,6 +12,7 @@
  *   TINA4_RABBITMQ_VHOST    (default: "/")
  */
 import net from "node:net";
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import type { QueueJob } from "../queue.js";
 
@@ -144,7 +145,7 @@ export class RabbitMQBackend implements QueueBackend {
    * Execute an AMQP operation synchronously via a child process.
    */
   private execSync(operation: string, queue: string, data?: string): string {
-    const { execFileSync } = require("node:child_process");
+    // execFileSync imported at top level
 
     const script = `
       const net = require("node:net");

package/packages/core/src/server.ts

@@ -3,6 +3,7 @@ import { resolve, dirname, join, relative } from "node:path";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { isatty } from "node:tty";
 import { fileURLToPath } from "node:url";
+import { execFileSync, exec } from "node:child_process";
 import cluster from "node:cluster";
 import os from "node:os";
 import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
@@ -30,12 +31,15 @@ const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
 const TINA4_VERSION = "3.0.0";
 
+/** Cache Frond instances by template directory to avoid repeated instantiation. */
+const frondCache = new Map<string, InstanceType<any>>();
+
 /**
  * Test-bind each port in a subprocess to find one that is available.
  * Falls back to `start` if none of the candidates work.
  */
 function findAvailablePort(start: number, maxTries = 10): number {
-  const { execFileSync } = require("node:child_process");
+  // execFileSync imported at top of file (ESM)
   for (let offset = 0; offset < maxTries; offset++) {
     const port = start + offset;
     try {
@@ -54,7 +58,7 @@ function findAvailablePort(start: number, maxTries = 10): number {
  * Open the user's default browser after a short delay so the server is ready.
  */
 function openBrowser(url: string) {
-  const { exec } = require("node:child_process");
+  // exec imported at top of file (ESM)
   setTimeout(() => {
     if (process.platform === "darwin") exec(`open ${url}`);
     else if (process.platform === "win32") exec(`start "" "${url}"`);
@@ -93,18 +97,26 @@ async function renderErrorPage(
     const { Frond } = await import("@tina4/frond");
     const templateFile = `errors/${code}.twig`;
 
+    // Helper: get-or-create a cached Frond instance for a directory
+    const getCachedFrond = (dir: string) => {
+      let instance = frondCache.get(dir);
+      if (!instance) {
+        instance = new Frond(dir);
+        frondCache.set(dir, instance);
+      }
+      return instance;
+    };
+
     // 1. Try user override in the project's templates directory
     const userTemplatePath = join(templatesDir, templateFile);
     if (existsSync(userTemplatePath)) {
-      const frond = new Frond(templatesDir);
-      return frond.render(templateFile, data);
+      return getCachedFrond(templatesDir).render(templateFile, data);
     }
 
     // 2. Try built-in framework default
     const builtinTemplatePath = join(BUILTIN_ERROR_TEMPLATES_DIR, templateFile);
     if (existsSync(builtinTemplatePath)) {
-      const frond = new Frond(BUILTIN_ERROR_TEMPLATES_DIR);
-      return frond.render(templateFile, data);
+      return getCachedFrond(BUILTIN_ERROR_TEMPLATES_DIR).render(templateFile, data);
     }
 
     // 3. No template found

package/packages/core/src/session.ts

@@ -28,6 +28,10 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
+import { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
+import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
+import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
+import { DatabaseSessionHandler } from "./sessionHandlers/databaseHandler.js";
 
 // ── Types ─────────────────────────────────────────────────────────
 
@@ -303,24 +307,20 @@ export class Session {
         this.handler = new RedisSessionHandler(config);
         break;
       case "redis-npm": {
-        const { RedisNpmSessionHandler } = require("./sessionHandlers/redisHandler.js");
         this.handler = new RedisNpmSessionHandler(config);
         break;
       }
       case "valkey": {
-        const { ValkeySessionHandler } = require("./sessionHandlers/valkeyHandler.js");
         this.handler = new ValkeySessionHandler(config);
         break;
       }
       case "mongo":
       case "mongodb": {
-        const { MongoSessionHandler } = require("./sessionHandlers/mongoHandler.js");
         this.handler = new MongoSessionHandler(config);
         break;
       }
       case "database":
       case "db": {
-        const { DatabaseSessionHandler } = require("./sessionHandlers/databaseHandler.js");
         this.handler = new DatabaseSessionHandler(config);
         break;
       }

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -10,11 +10,9 @@
  * The handler dynamically imports `better-sqlite3` and throws a clear
  * error if the package is not installed.
  */
-import { createRequire } from "node:module";
+import { DatabaseSync } from "node:sqlite";
 import type { SessionHandler } from "../session.js";
 
-const _require = createRequire(import.meta.url);
-
 interface SessionData {
   _created: number;
   _accessed: number;
@@ -39,7 +37,6 @@ export class DatabaseSessionHandler implements SessionHandler {
   constructor(config?: DatabaseSessionConfig) {
     const dbPath = config?.dbPath ?? this.resolveDbPath();
 
-    const { DatabaseSync } = require("node:sqlite");
     this.db = new DatabaseSync(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
   }

package/packages/core/src/websocketBackplane.ts

@@ -53,25 +53,26 @@ export class RedisBackplane implements WebSocketBackplane {
   constructor(url?: string) {
     this.url = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "redis://localhost:6379";
 
-    let redis: any;
-    try {
-      redis = require("redis");
-    } catch {
-      throw new Error(
-        "The 'redis' package is required for RedisBackplane. " +
-        "Install it with: npm install redis"
-      );
-    }
+    this.ready = (async () => {
+      let redis: any;
+      try {
+        redis = await import("redis");
+      } catch {
+        throw new Error(
+          "The 'redis' package is required for RedisBackplane. " +
+          "Install it with: npm install redis"
+        );
+      }
 
-    this.publisher = redis.createClient({ url: this.url });
-    this.subscriber = this.publisher.duplicate();
+      this.publisher = redis.createClient({ url: this.url });
+      this.subscriber = this.publisher.duplicate();
 
-    this.ready = Promise.all([
-      this.publisher.connect(),
-      this.subscriber.connect(),
-    ]).then(() => {
+      await Promise.all([
+        this.publisher.connect(),
+        this.subscriber.connect(),
+      ]);
       console.log(`[Tina4] RedisBackplane connected to ${this.url}`);
-    });
+    })();
   }
 
   async publish(channel: string, message: string): Promise<void> {

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

@@ -6,13 +6,13 @@
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslation.js";
+import { createRequire } from "node:module";
 
 let firebird: any = null;
 
 function requireFirebird(): any {
   if (firebird) return firebird;
   try {
-    const { createRequire } = require("node:module") as typeof import("node:module");
     const req = createRequire(import.meta.url);
     firebird = req("node-firebird");
     return firebird;

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

@@ -6,13 +6,13 @@
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslation.js";
+import { createRequire } from "node:module";
 
 let tedious: any = null;
 
 function requireTedious(): any {
   if (tedious) return tedious;
   try {
-    const { createRequire } = require("node:module") as typeof import("node:module");
     const req = createRequire(import.meta.url);
     tedious = req("tedious");
     return tedious;

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

@@ -6,13 +6,13 @@
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslation.js";
+import { createRequire } from "node:module";
 
 let mysql2: any = null;
 
 function requireMysql2(): any {
   if (mysql2) return mysql2;
   try {
-    const { createRequire } = require("node:module") as typeof import("node:module");
     const req = createRequire(import.meta.url);
     mysql2 = req("mysql2");
     return mysql2;

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

@@ -7,15 +7,15 @@
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
 import { SQLTranslator } from "../sqlTranslation.js";
 
+import { createRequire } from "node:module";
+
 let pg: typeof import("pg") | null = null;
 
 function requirePg(): typeof import("pg") {
   if (pg) return pg;
   try {
-    // Dynamic require via createRequire for ESM compatibility
-    const { createRequire } = await_import_module();
-    const require = createRequire(import.meta.url);
-    pg = require("pg");
+    const req = createRequire(import.meta.url);
+    pg = req("pg");
     return pg!;
   } catch {
     throw new Error(
@@ -24,13 +24,6 @@ function requirePg(): typeof import("pg") {
   }
 }
 
-/** Synchronous helper to get createRequire — we call this at connection time. */
-function await_import_module() {
-  // node:module is always available
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  return require("node:module") as typeof import("node:module");
-}
-
 export interface PostgresConfig {
   host?: string;
   port?: number;

package/packages/orm/src/baseModel.ts

@@ -3,6 +3,20 @@ import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 
+/**
+ * Convert a snake_case name to camelCase.
+ */
+export function snakeToCamel(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Convert a camelCase name to snake_case.
+ */
+export function camelToSnake(name: string): string {
+  return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+
 /**
  * BaseModel provides instance methods for ORM models.
  * Models extend this class and define static properties.
@@ -17,6 +31,7 @@ import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from ".
  *     static hasMany = [{ model: "Post", foreignKey: "author_id" }];
  *     static _db = "secondary";
  *     static fieldMapping = { firstName: "first_name", lastName: "last_name" };
+ *     static autoMap = true; // auto-generate fieldMapping from camelCase → snake_case
  *   }
  */
 export class BaseModel {
@@ -29,6 +44,12 @@ export class BaseModel {
   static belongsTo?: RelationshipDefinition[];
   static _db?: string;
 
+  /**
+   * When true, auto-generates fieldMapping entries from camelCase field names
+   * to snake_case DB column names. Explicit fieldMapping entries always win.
+   */
+  static autoMap: boolean = false;
+
   /**
    * Maps JS property names to database column names.
    * Example: { firstName: "first_name" } means the JS property `firstName`
@@ -46,6 +67,18 @@ export class BaseModel {
   constructor(data?: Record<string, unknown>) {
     if (data) {
       const ModelClass = this.constructor as typeof BaseModel;
+      // If autoMap is on, auto-generate fieldMapping from camelCase fields
+      if (ModelClass.autoMap) {
+        const fields = ModelClass.fields || {};
+        for (const key of Object.keys(fields)) {
+          if (!ModelClass.fieldMapping[key]) {
+            const snaked = camelToSnake(key);
+            if (snaked !== key) {
+              ModelClass.fieldMapping[key] = snaked;
+            }
+          }
+        }
+      }
       const reverseMapping = ModelClass.getReverseMapping();
       for (const [key, value] of Object.entries(data)) {
         // If this DB column has a mapping, use the JS property name instead

package/packages/orm/src/index.ts

@@ -38,7 +38,7 @@ export { generateCrudRoutes } from "./autoCrud.js";
 export { buildQuery, parseQueryString } from "./query.js";
 export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
-export { BaseModel } from "./baseModel.js";
+export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslation.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";