tina4-nodejs 3.9.2 → 3.9.4

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.9.1)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.9.2)
 
 > 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.1 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+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.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -38,12 +38,12 @@ tina4-nodejs/
         service.ts       # Service layer helpers
         session.ts       # Session management
         testing.ts       # Inline testing framework (attach tests to functions)
-        websocket.ts     # WebSocket support
+        websocket.ts     # WebSocket support (with backplane)
         wsdl.ts          # WSDL / SOAP support
     orm/        # Database adapters, models, auto-CRUD, query builder, seeding
       src/
         adapters/
-          sqlite.ts        # SQLite via better-sqlite3 (default)
+          sqlite.ts        # SQLite via node:sqlite (default)
           postgres.ts      # PostgreSQL adapter
           mysql.ts         # MySQL adapter
           mssql.ts         # MSSQL / SQL Server adapter
@@ -69,7 +69,7 @@ This is an **npm workspaces monorepo**. All packages are in `packages/*`.
 - **Language:** TypeScript (strict mode, ES2022 target, Node16 module resolution)
 - **Runtime:** Node.js 20+ (ESM only, `"type": "module"` everywhere)
 - **HTTP:** Native `node:http` — no Express, no Fastify
-- **Database:** SQLite via `better-sqlite3` (default), with adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird
+- **Database:** SQLite via `node:sqlite` (default), with adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird
 - **Templates:** Twig via `twig` npm package (optional)
 - **Dev tooling:** `tsx` for runtime TS execution, `esbuild` for builds
 - **Testing:** 43 test files via `tsx test/run-all.ts`
@@ -120,8 +120,8 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `devAdmin.ts` — Dev toolbar (fixed bottom bar injected into HTML pages) and admin dashboard at `/_dev/`
 - `auth.ts` — Authentication helpers
 - `cache.ts` — In-memory caching
-- `session.ts` — Session management with pluggable handlers
-- `websocket.ts` — WebSocket support
+- `session.ts` — Session management with pluggable handlers. `TINA4_SESSION_SAMESITE` env var (default: Lax)
+- `websocket.ts` — WebSocket support with backplane for scaling via Redis pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`)
 - `queue.ts` — Queue system with pluggable backends
 - `graphql.ts` — GraphQL engine
 - `i18n.ts` — Internationalization / localization
@@ -139,7 +139,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 
 **Key files:**
 - `database.ts` — Adapter manager, `initDatabase()` factory
-- `adapters/sqlite.ts` — `better-sqlite3` implementation of `DatabaseAdapter` interface
+- `adapters/sqlite.ts` — `node:sqlite` implementation of `DatabaseAdapter` interface
 - `adapters/postgres.ts` — PostgreSQL adapter
 - `adapters/mysql.ts` — MySQL adapter
 - `adapters/mssql.ts` — MSSQL / SQL Server adapter (`mssql` or `sqlserver` scheme)
@@ -153,6 +153,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `fakeData.ts` — ORM-aware fake data extending core (adds `forField()` with column-name heuristics)
 - `seeder.ts` — Database seeding (`seedTable` for raw SQL, `seedOrm` for model-based)
 - `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
+- QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 
 ### @tina4/swagger (`packages/swagger/`)
 Auto-generates OpenAPI 3.0 docs.
@@ -173,7 +174,7 @@ Developer-facing CLI commands.
 
 **Key files:**
 - `bin.ts` — Entry point, command dispatch (`init`, `serve`, `--help`)
-- `commands/init.ts` — Scaffolds a new project directory with sample files
+- `commands/init.ts` — Scaffolds a new project directory with sample files, Dockerfile, and .dockerignore
 - `commands/serve.ts` — Starts dev server with hot-reload via `@tina4/core`
 
 ## Module: Events (`packages/core/src/events.ts`)
@@ -469,7 +470,7 @@ import { Router } from "./router.js";  // .js even though the file is .ts
 3. **Convention-based models** — `static fields = {}` over decorators. No special TypeScript config needed.
 4. **CDN for Swagger UI** — Keeps install under 8MB. Single HTML file loads from unpkg.com.
 5. **Process restart for hot-reload** — Simpler and more reliable than HMR with ESM.
-6. **SQLite default** — `better-sqlite3` is synchronous and fast. Full adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird.
+6. **SQLite default** — `node:sqlite` is synchronous and fast. Full adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird.
 7. **CLI named `tina4nodejs`** (primary) with `tina4` as alias — So `npx tina4nodejs init` or `npx tina4 init` both work.
 8. **Event system** — Static `Events` class, synchronous dispatch, priority ordering, zero deps.
 9. **Inline testing** — Tests as decorators on functions, no external test runner for unit-level checks.
@@ -531,7 +532,7 @@ await initDatabase({ type: "postgres", host: "localhost", port: 5432, database:
 ### Available adapters
 | Adapter | Scheme(s) | Package |
 |---------|-----------|---------|
-| SQLite | `sqlite://` | `better-sqlite3` |
+| SQLite | `sqlite://` | `node:sqlite` |
 | PostgreSQL | `postgres://`, `postgresql://` | `pg` |
 | MySQL | `mysql://` | `mysql2` |
 | MSSQL | `mssql://`, `sqlserver://` | `tedious` |
@@ -586,12 +587,16 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode
 - **`npx tina4nodejs generate`**: model, route, migration, middleware scaffolding
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), query caching (`TINA4_DB_CACHE=true`)
-- **Sessions**: file backend (default)
+- **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: memory/Redis/file backends
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)
 - **Frond pre-compilation**: 2.8x template render improvement
+- **QueryBuilder** with NoSQL/MongoDB support (`toMongo()`)
+- **WebSocket backplane** (Redis pub/sub) for horizontal scaling
+- **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
+- **`tina4 init`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/_dev/`
 
 ## Don'ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.9.2",
+  "version": "3.9.4",
   "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";
@@ -35,7 +36,7 @@ const TINA4_VERSION = "3.0.0";
  * 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 +55,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}"`);

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;