tina4-nodejs 3.0.0-rc.2 → 3.1.0

package/README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tests-1247%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1669%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/carbonah-A%2B%20rated-00cc44" alt="Carbonah A+">
   <img src="https://img.shields.io/badge/zero--dep-core-blue" alt="Zero Dependencies">
   <img src="https://img.shields.io/badge/node-20%2B-blue" alt="Node 20+">
@@ -50,17 +50,17 @@ Every feature is built from scratch -- no npm install, no node_modules bloat, no
 | **HTTP** | Native `node:http` server, file-based + programmatic routing, path params (`{id}`, `[...slug]`), middleware pipeline, CORS, rate limiting, graceful shutdown |
 | **Templates** | Frond engine (Twig-compatible), inheritance, partials, 53+ filters, macros, fragment caching, sandboxing |
 | **ORM** | Active Record, typed fields with validation, soft delete, relationships (`hasOne`/`hasMany`/`belongsTo`), scopes, result caching, auto-CRUD |
-| **Database** | SQLite, PostgreSQL, MySQL, MSSQL/SQL Server, Firebird -- unified adapter interface, `driver://host:port/database` connection strings |
+| **Database** | SQLite, PostgreSQL, MySQL, MSSQL/SQL Server, Firebird -- unified adapter interface, query caching (TINA4_DB_CACHE=true for 4x speedup) |
 | **Auth** | Zero-dep JWT (HS256 + RS256), sessions (file backend), PBKDF2 password hashing, form tokens |
 | **API** | Swagger/OpenAPI auto-generation, GraphQL with schema builder and GraphiQL IDE |
-| **Background** | File-backed queue with priority, delayed jobs, retry, batch processing |
+| **Background** | Queue (SQLite/RabbitMQ/Kafka) with priority, delayed jobs, retry, batch processing |
 | **Real-time** | Native WebSocket (RFC 6455), per-path routing, connection manager, broadcast |
 | **Frontend** | tina4-css (~24 KB), frond.js helper, SCSS compiler, live reload, CSS hot-reload |
 | **DX** | Dev admin dashboard, error overlay, request inspector, hot-reload, Carbonah green benchmarks |
 | **Data** | Migrations with rollback, 26+ fake data generators, ORM and table seeders |
-| **Other** | Service runner, localization (i18n), in-memory cache (TTL/tags/LRU), HTTP constants, health check, configurable error pages |
+| **Other** | Service runner, localization (i18n), cache (memory/Redis/file), messenger (.env driven), HTTP constants, health check, configurable error pages |
 
-**580 tests across all modules. All Carbonah benchmarks rated A+.**
+**1,669 tests across 38 built-in features. Zero dependencies. All Carbonah benchmarks rated A+.**
 
 For full documentation visit **[tina4.com](https://tina4.com)**.
 
@@ -533,9 +533,14 @@ Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
 ```bash
 npx tina4nodejs init [dir]             # Scaffold a new project
 npx tina4nodejs serve [--port 7148]    # Start dev server (default: 7148)
+npx tina4nodejs serve --production     # Auto-use cluster mode (multi-core)
 npx tina4nodejs migrate                # Run pending migrations
 npx tina4nodejs migrate:create <desc>  # Create a migration file
 npx tina4nodejs migrate:rollback       # Rollback last batch
+npx tina4nodejs generate model <name>  # Generate model scaffold
+npx tina4nodejs generate route <name>  # Generate route scaffold
+npx tina4nodejs generate migration <d> # Generate migration file
+npx tina4nodejs generate middleware <n># Generate middleware scaffold
 npx tina4nodejs seed                   # Run seeders from src/seeds/
 npx tina4nodejs routes                 # List all registered routes
 npx tina4nodejs test                   # Run test suite
@@ -543,6 +548,55 @@ npx tina4nodejs build                  # Build distributable package
 npx tina4nodejs ai [--all]             # Detect AI tools and install context
 ```
 
+### Production Server Auto-Detection
+
+`tina4 serve` automatically detects and uses the best available production server:
+
+- **Node.js**: cluster mode with multiple workers, otherwise single http server
+- Use `npx tina4nodejs serve --production` to auto-use cluster mode
+
+### Scaffolding with `tina4 generate`
+
+Quickly scaffold new components:
+
+```bash
+npx tina4nodejs generate model User          # Creates src/models/User.ts
+npx tina4nodejs generate route users         # Creates src/routes/api/users/
+npx tina4nodejs generate migration "add age" # Creates migration SQL file
+npx tina4nodejs generate middleware AuthLog   # Creates middleware
+```
+
+### ORM Relationships & Eager Loading
+
+```typescript
+// Relationships defined in model
+static relationships = {
+  orders: { type: "hasMany", model: "Order", foreignKey: "userId" },
+  profile: { type: "hasOne", model: "Profile", foreignKey: "userId" },
+  customer: { type: "belongsTo", model: "Customer", foreignKey: "customerId" },
+};
+
+// Eager loading with include
+const users = await db.query("SELECT * FROM users", [], { include: ["orders", "profile"] });
+```
+
+### DB Query Caching
+
+Enable query caching for up to 4x speedup on read-heavy workloads:
+
+```bash
+# .env
+TINA4_DB_CACHE=true
+```
+
+### Frond Pre-Compilation
+
+Templates are pre-compiled for 2.8x faster rendering.
+
+### Gallery
+
+7 interactive examples with **Try It** deploy.
+
 ## Environment
 
 ```bash
@@ -577,7 +631,7 @@ Full guides, API reference, and examples at **[tina4.com](https://tina4.com)**.
 
 ## License
 
-MIT (c) 2007-2025 Tina4 Stack
+MIT (c) 2007-2026 Tina4 Stack
 https://opensource.org/licenses/MIT
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.0.0-rc.2",
+  "version": "3.1.0",
   "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"],
@@ -15,6 +15,7 @@
     "packages/*"
   ],
   "main": "packages/core/src/index.ts",
+  "types": "packages/core/src/index.ts",
   "exports": {
     ".": "./packages/core/src/index.ts",
     "./orm": "./packages/orm/src/index.ts",

package/packages/cli/src/bin.ts

@@ -4,6 +4,7 @@ import { runMigrations } from "./commands/migrate.js";
 import { createMigration } from "./commands/migrateCreate.js";
 import { listRoutes } from "./commands/routes.js";
 import { runTests } from "./commands/test.js";
+import { generate } from "./commands/generate.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -18,6 +19,7 @@ const HELP = `
     tina4nodejs migrate:create <desc> Create a new migration file
     tina4nodejs routes                List all registered routes
     tina4nodejs test [file]           Run project tests
+    tina4nodejs generate <what> <name> Generate scaffolding (model, route, migration, middleware)
     tina4nodejs ai                    Detect AI coding tools and install context
     tina4nodejs help                  Show this help message
 
@@ -58,6 +60,12 @@ async function main(): Promise<void> {
       await runTests(args[1]);
       break;
     }
+    case "generate": {
+      const what = args[1];
+      const genName = args[2];
+      await generate(what, genName);
+      break;
+    }
     case "ai": {
       const { detectAi, installAiContext, installAllAiContext, aiStatusReport } = await import("../../core/src/ai.js");
       const root = args[1] || ".";

package/packages/cli/src/commands/generate.ts

@@ -0,0 +1,237 @@
+/**
+ * CLI command: generate — Scaffold models, routes, migrations, and middleware.
+ *
+ * Usage:
+ *   tina4nodejs generate model User
+ *   tina4nodejs generate route /api/users
+ *   tina4nodejs generate migration create_users
+ *   tina4nodejs generate middleware Auth
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export async function generate(what: string, name: string): Promise<void> {
+  if (!what || !name) {
+    console.error("  Usage: tina4nodejs generate <what> <name>");
+    console.error("  Generators: model, route, migration, middleware");
+    process.exit(1);
+  }
+
+  switch (what) {
+    case "model":
+      generateModel(name);
+      break;
+    case "route":
+      generateRoute(name);
+      break;
+    case "migration":
+      generateMigration(name);
+      break;
+    case "middleware":
+      generateMiddleware(name);
+      break;
+    default:
+      console.error(`  Unknown generator: ${what}`);
+      console.error("  Available: model, route, migration, middleware");
+      process.exit(1);
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function writeFileSafe(path: string, content: string): void {
+  if (existsSync(path)) {
+    console.error(`  File already exists: ${path}`);
+    process.exit(1);
+  }
+  writeFileSync(path, content, "utf-8");
+  console.log(`  Created ${path}`);
+}
+
+function toSnake(name: string): string {
+  return name.replace(/([A-Z])/g, (_, ch, i) => (i > 0 ? "_" : "") + ch.toLowerCase());
+}
+
+function toPlural(name: string): string {
+  const lower = name.toLowerCase();
+  if (lower.endsWith("s")) return lower;
+  if (lower.endsWith("y")) return lower.slice(0, -1) + "ies";
+  return lower + "s";
+}
+
+function toCamel(name: string): string {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+// ── Model ────────────────────────────────────────────────────────
+
+function generateModel(name: string): void {
+  const dir = resolve("src/models");
+  ensureDir(dir);
+
+  const table = toPlural(name);
+  const path = join(dir, `${name}.ts`);
+
+  const content = `import { BaseModel } from "tina4-nodejs";
+
+export class ${name} extends BaseModel {
+  static tableName = "${table}";
+  static fields = {
+    id: { type: "integer", primaryKey: true, autoIncrement: true },
+    name: { type: "string" },
+    email: { type: "string" },
+  };
+}
+`;
+
+  writeFileSafe(path, content);
+}
+
+// ── Route ────────────────────────────────────────────────────────
+
+function generateRoute(name: string): void {
+  const routePath = name.replace(/^\//, "");
+  const base = resolve("src/routes", routePath);
+  const idDir = join(base, "[id]");
+  ensureDir(base);
+  ensureDir(idDir);
+
+  // GET list
+  writeFileSafe(
+    join(base, "get.ts"),
+    `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+export const meta = { summary: "List all", tags: ["auto-generated"] };
+
+export default async function (req: Tina4Request, res: Tina4Response) {
+  res.json({ data: [] });
+}
+`,
+  );
+
+  // POST create
+  writeFileSafe(
+    join(base, "post.ts"),
+    `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+export const meta = { summary: "Create new", tags: ["auto-generated"] };
+
+export default async function (req: Tina4Request, res: Tina4Response) {
+  res.json({ message: "created" }, 201);
+}
+`,
+  );
+
+  // GET by id
+  writeFileSafe(
+    join(idDir, "get.ts"),
+    `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+export const meta = { summary: "Get by id", tags: ["auto-generated"] };
+
+export default async function (req: Tina4Request, res: Tina4Response) {
+  const { id } = req.params;
+  res.json({ data: { id } });
+}
+`,
+  );
+
+  // PUT by id
+  writeFileSafe(
+    join(idDir, "put.ts"),
+    `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+export const meta = { summary: "Update by id", tags: ["auto-generated"] };
+
+export default async function (req: Tina4Request, res: Tina4Response) {
+  const { id } = req.params;
+  res.json({ message: "updated", id });
+}
+`,
+  );
+
+  // DELETE by id
+  writeFileSafe(
+    join(idDir, "delete.ts"),
+    `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+export const meta = { summary: "Delete by id", tags: ["auto-generated"] };
+
+export default async function (req: Tina4Request, res: Tina4Response) {
+  const { id } = req.params;
+  res.json({ message: "deleted", id });
+}
+`,
+  );
+}
+
+// ── Migration ────────────────────────────────────────────────────
+
+function generateMigration(name: string): void {
+  const dir = resolve("migrations");
+  ensureDir(dir);
+
+  const now = new Date();
+  const timestamp =
+    now.getFullYear().toString() +
+    String(now.getMonth() + 1).padStart(2, "0") +
+    String(now.getDate()).padStart(2, "0") +
+    String(now.getHours()).padStart(2, "0") +
+    String(now.getMinutes()).padStart(2, "0") +
+    String(now.getSeconds()).padStart(2, "0");
+
+  const table = toPlural(name.replace(/^create_/, ""));
+  const fileName = `${timestamp}_${name}.sql`;
+  const path = join(dir, fileName);
+
+  const content = `-- Migration: ${name}
+-- Created: ${now.toISOString().replace("T", " ").replace(/\.\d+Z$/, "")}
+
+CREATE TABLE ${table} (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+`;
+
+  writeFileSafe(path, content);
+}
+
+// ── Middleware ────────────────────────────────────────────────────
+
+function generateMiddleware(name: string): void {
+  const dir = resolve("src/middleware");
+  ensureDir(dir);
+
+  const snake = toSnake(name);
+  const camel = toCamel(name);
+  const path = join(dir, `${snake}.ts`);
+
+  const content = `import type { Tina4Request, Tina4Response } from "tina4-nodejs";
+
+/**
+ * ${name} middleware — checks for Authorization header.
+ */
+export default async function ${camel}(
+  req: Tina4Request,
+  res: Tina4Response,
+  next: () => Promise<void>,
+): Promise<void> {
+  const auth = req.headers["authorization"];
+  if (!auth) {
+    res.json({ error: "Unauthorized" }, 401);
+    return;
+  }
+  await next();
+}
+`;
+
+  writeFileSafe(path, content);
+}

package/packages/core/gallery/queue/meta.json

@@ -1 +1 @@
-{"name": "Queue", "description": "Background job producer and consumer", "try_url": "/api/gallery/queue/produce"}
+{"name": "Queue", "description": "Background job producer and consumer", "try_url": "/gallery/queue"}

package/packages/core/gallery/queue/src/lib/queueDb.ts

@@ -0,0 +1,32 @@
+/** Shared SQLite database helper for the queue gallery demo. */
+import type { DatabaseAdapter } from "@tina4/orm";
+
+let _db: DatabaseAdapter | null = null;
+
+export const MAX_RETRIES = 3;
+
+export async function getQueueDb(): Promise<DatabaseAdapter> {
+  if (_db) return _db;
+  const orm = await import("@tina4/orm");
+  _db = await orm.initDatabase({ type: "sqlite", path: "./data/gallery_queue.db" });
+  try {
+    _db.execute(`CREATE TABLE IF NOT EXISTS tina4_queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      topic TEXT NOT NULL,
+      data TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending',
+      priority INTEGER NOT NULL DEFAULT 0,
+      attempts INTEGER NOT NULL DEFAULT 0,
+      error TEXT,
+      available_at TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      completed_at TEXT,
+      reserved_at TEXT
+    )`);
+  } catch (_e) { /* table already exists */ }
+  return _db;
+}
+
+export function now(): string {
+  return new Date().toISOString();
+}

package/packages/core/gallery/queue/src/routes/api/gallery/queue/consume/post.ts

@@ -0,0 +1,28 @@
+/** Gallery: Queue — consume (complete) the next pending message. */
+import type { Tina4Request, Tina4Response } from "@tina4/core";
+import { getQueueDb, now } from "../../../../lib/queueDb.js";
+
+export default async function (_req: Tina4Request, res: Tina4Response) {
+  try {
+    const db = await getQueueDb();
+    const ts = now();
+
+    const row = db.fetchOne<Record<string, unknown>>(
+      "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
+      ["gallery-tasks", ts]
+    );
+
+    if (!row) {
+      return res.json({ consumed: false, message: "No pending messages to consume" });
+    }
+
+    db.execute(
+      "UPDATE tina4_queue SET status = 'completed', completed_at = ? WHERE id = ? AND status = 'pending'",
+      [ts, row.id]
+    );
+
+    return res.json({ consumed: true, job_id: row.id, data: row.data });
+  } catch (e: unknown) {
+    return res.json({ error: String(e) }, 500);
+  }
+}

package/packages/core/gallery/queue/src/routes/api/gallery/queue/fail/post.ts

@@ -0,0 +1,28 @@
+/** Gallery: Queue — deliberately fail the next pending message. */
+import type { Tina4Request, Tina4Response } from "@tina4/core";
+import { getQueueDb, now } from "../../../../lib/queueDb.js";
+
+export default async function (_req: Tina4Request, res: Tina4Response) {
+  try {
+    const db = await getQueueDb();
+    const ts = now();
+
+    const row = db.fetchOne<Record<string, unknown>>(
+      "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
+      ["gallery-tasks", ts]
+    );
+
+    if (!row) {
+      return res.json({ failed: false, message: "No pending messages to fail" });
+    }
+
+    db.execute(
+      "UPDATE tina4_queue SET status = 'failed', error = ?, attempts = attempts + 1 WHERE id = ?",
+      ["Deliberately failed via gallery demo", row.id]
+    );
+
+    return res.json({ failed: true, job_id: row.id, data: row.data });
+  } catch (e: unknown) {
+    return res.json({ error: String(e) }, 500);
+  }
+}

package/packages/core/gallery/queue/src/routes/api/gallery/queue/produce/post.ts

@@ -1,16 +1,26 @@
-/** Gallery: Queue — produce a background job. */
+/** Gallery: Queue — produce a message into the queue. */
 import type { Tina4Request, Tina4Response } from "@tina4/core";
+import { getQueueDb, now } from "../../../../lib/queueDb.js";
 
 export default async function (req: Tina4Request, res: Tina4Response) {
-  const body = (req.body as Record<string, unknown>) ?? {};
-  const task = (body.task as string) ?? "default-task";
-  const data = body.data ?? {};
+  try {
+    const body = (req.body as Record<string, unknown>) ?? {};
+    const task = (body.task as string) ?? "default-task";
+    const data = body.data ?? {};
+    const ts = now();
+    const payload = JSON.stringify({ task, data });
 
-  // In a real app you would use:
-  //   import { Queue, Producer } from "@tina4/core";
-  //   const queue = new Queue(db, "gallery-tasks");
-  //   const producer = new Producer(queue);
-  //   producer.produce({ task, data });
+    const db = await getQueueDb();
+    db.execute(
+      "INSERT INTO tina4_queue (topic, data, status, priority, attempts, available_at, created_at) VALUES (?, ?, 'pending', 0, 0, ?, ?)",
+      ["gallery-tasks", payload, ts, ts]
+    );
 
-  return res.json({ queued: true, task }, 201);
+    const row = db.fetchOne<{ last_id: number }>("SELECT last_insert_rowid() as last_id");
+    const jobId = row?.last_id ?? 0;
+
+    return res.json({ queued: true, task, job_id: jobId }, 201);
+  } catch (e: unknown) {
+    return res.json({ error: String(e) }, 500);
+  }
 }

package/packages/core/gallery/queue/src/routes/api/gallery/queue/retry/post.ts

@@ -0,0 +1,25 @@
+/** Gallery: Queue — retry failed messages (re-queue under max retries). */
+import type { Tina4Request, Tina4Response } from "@tina4/core";
+import { getQueueDb, now, MAX_RETRIES } from "../../../../lib/queueDb.js";
+
+export default async function (_req: Tina4Request, res: Tina4Response) {
+  try {
+    const db = await getQueueDb();
+    const ts = now();
+
+    db.execute(
+      "UPDATE tina4_queue SET status = 'pending', available_at = ? WHERE topic = ? AND status = 'failed' AND attempts < ?",
+      [ts, "gallery-tasks", MAX_RETRIES]
+    );
+
+    const row = db.fetchOne<{ cnt: number }>(
+      "SELECT COUNT(*) as cnt FROM tina4_queue WHERE topic = ? AND status = 'pending'",
+      ["gallery-tasks"]
+    );
+    const retried = row?.cnt ?? 0;
+
+    return res.json({ retried });
+  } catch (e: unknown) {
+    return res.json({ error: String(e) }, 500);
+  }
+}

package/packages/core/gallery/queue/src/routes/api/gallery/queue/status/get.ts

@@ -1,10 +1,40 @@
-/** Gallery: Queue — check queue status. */
+/** Gallery: Queue — list all messages with statuses. */
 import type { Tina4Request, Tina4Response } from "@tina4/core";
+import { getQueueDb, MAX_RETRIES } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
-  return res.json({
-    topic: "gallery-tasks",
-    size: 0,
-    note: "Connect a queue backend for live data",
-  });
+  try {
+    const db = await getQueueDb();
+
+    const rows = db.fetch<Record<string, unknown>>(
+      "SELECT * FROM tina4_queue WHERE topic = ? ORDER BY id DESC",
+      ["gallery-tasks"],
+      100
+    );
+
+    const counts: Record<string, number> = { pending: 0, reserved: 0, completed: 0, failed: 0 };
+    const messages = (rows ?? []).map((row) => {
+      const status = (row.status as string) ?? "pending";
+      const attempts = (row.attempts as number) ?? 0;
+      let displayStatus = status;
+      if (status === "failed" && attempts >= MAX_RETRIES) {
+        displayStatus = "dead";
+      }
+      if (status in counts) {
+        counts[status]++;
+      }
+      return {
+        id: row.id,
+        data: row.data ?? "",
+        status: displayStatus,
+        attempts,
+        error: row.error ?? "",
+        created_at: row.created_at ?? "",
+      };
+    });
+
+    return res.json({ topic: "gallery-tasks", messages, counts });
+  } catch (e: unknown) {
+    return res.json({ error: String(e) }, 500);
+  }
 }