tina4-nodejs 3.10.38 → 3.10.41

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.24)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.41)
 
 > 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.10.24 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.10.41 — 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.
 
@@ -153,6 +153,8 @@ 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`)
+- `BaseModel.select<T>(sql, params?)` — Raw SQL query returning `T[]`
+- `BaseModel.selectOne<T>(sql, params?, include?)` — Raw SQL query returning `T | null` (first match or null, with optional eager loading)
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).
 

package/README.md

@@ -1,665 +1,115 @@
 <p align="center">
   <img src="https://tina4.com/logo.svg" alt="Tina4" width="200">
 </p>
-
 <h1 align="center">Tina4 Node.js</h1>
 <h3 align="center">This Is Now A 4Framework</h3>
-
-<p align="center">
-  Laravel joy. TypeScript speed. 10x less code. Zero third-party dependencies.
-</p>
-
+<p align="center">54 built-in features. Zero dependencies. One import, everything works.</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/tina4-nodejs"><img src="https://img.shields.io/npm/v/tina4-nodejs?color=7b1fa2&label=npm" alt="npm"></a>
-  <img src="https://img.shields.io/badge/tests-1%2C812%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/features-38-blue" alt="Features">
+  <img src="https://img.shields.io/badge/tests-1%2C950%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/features-54-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
 </p>
 
-<p align="center">
-  <a href="https://tina4.com">Documentation</a> &bull;
-  <a href="#getting-started">Getting Started</a> &bull;
-  <a href="#features">Features</a> &bull;
-  <a href="#cli-reference">CLI Reference</a> &bull;
-  <a href="https://tina4.com">tina4.com</a>
-</p>
-
 ---
 
 ## Quick Start
 
 ```bash
-# Install the Tina4 CLI
-cargo install tina4  # or download binary from https://github.com/tina4stack/tina4/releases
-
-# Create a project
-tina4 init nodejs ./my-app
-
-# Run it
-cd my-app && tina4 serve
-```
-
-Open http://localhost:7148 — your app is running.
-
-<details>
-<summary><strong>Without the Tina4 CLI</strong></summary>
-
-```bash
-# 1. Create project
-mkdir my-app && cd my-app
-npm init -y
-npm install tina4-nodejs
-
-# 2. Create entry point
-cat > app.ts << 'EOF'
-import { startServer } from "tina4-nodejs";
-startServer({ port: 7148, host: "0.0.0.0" });
-EOF
-
-# 3. Create .env
-echo 'TINA4_DEBUG=true' > .env
-echo 'TINA4_LOG_LEVEL=ALL' >> .env
-
-# 4. Create route directory
-mkdir -p src/routes
-
-# 5. Run
-npx tsx app.ts
+npx tina4nodejs init my-app
+cd my-app && npx tina4nodejs serve
 ```
 
 Open http://localhost:7148
 
-</details>
-
 ---
 
-## What's Included
-
-Every feature is built from scratch -- no npm install, no node_modules bloat, no third-party runtime dependencies in core.
-
-| Category | Features |
-|----------|----------|
-| **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, query caching (TINA4_DB_CACHE=true for 4x speedup) |
-| **Auth** | Zero-dep JWT (HS256/RS256), sessions (file/Redis/Valkey/MongoDB/database), password hashing, form tokens |
-| **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE, WSDL/SOAP with auto WSDL |
-| **Background** | Queue (SQLite/RabbitMQ/Kafka/MongoDB) 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), cache (memory/Redis/file), messenger (.env driven), HTTP constants, health check, configurable error pages |
-
-**1,812 tests across 38 built-in features. Zero dependencies. All Carbonah benchmarks rated A+.**
-
-For full documentation visit **[tina4.com](https://tina4.com)**.
-
----
-
-## Install
-
-```bash
-npm install tina4-nodejs
-```
-
-Or scaffold a new project directly:
-
-```bash
-npx tina4nodejs init my-app
-```
-
----
-
-## Getting Started
-
-### 1. Create a project
-
-```bash
-npx tina4nodejs init my-app
-cd my-app
-```
-
-This creates:
-
-```
-my-app/
-├── package.json        # Entry point
-├── tsconfig.json       # TypeScript config
-├── .env                # Configuration
-├── src/
-│   ├── routes/         # API + page routes (auto-discovered)
-│   ├── models/         # Database models (auto-CRUD)
-│   ├── templates/      # Frond/Twig templates
-│   ├── seeds/          # Database seeders
-│   ├── scss/           # SCSS (auto-compiled to public/css/)
-│   └── public/         # Static assets served at /
-├── migrations/         # SQL migration files
-├── data/               # SQLite database (auto-created)
-└── test/               # Tests
-```
-
-### 2. Create a route
-
-**File-based routing** -- the directory path becomes the URL:
-
-```
-src/routes/api/hello/get.ts  ->  GET /api/hello
-```
+## Code Examples
 
 ```typescript
 // src/routes/api/hello/get.ts
-import type { Tina4Request, Tina4Response } from "tina4-nodejs";
-
-export default async function (request: Tina4Request, response: Tina4Response) {
-    response({message: "Hello from Tina4!"}, HTTP_OK);
+export default async function(req: Tina4Request, res: Tina4Response) {
+  res.json({ message: "Hello from Tina4!" });
 }
-```
-
-**Programmatic routing** -- decorator-style in a single file:
-
-```typescript
-// src/routes/hello.ts
-import { get } from "tina4-nodejs";
-
-get("/api/hello/{name}", async (request, response) => {
-    response({message: `Hello, ${request.params.name}!`}, HTTP_OK);
-});
-```
-
-Visit `http://localhost:7148/api/hello` -- routes are auto-discovered, no imports needed.
-
-### 3. Add a database
-
-Edit `.env`:
-
-```bash
-DATABASE_URL=sqlite:///data/app.db
-```
-
-Create and run a migration:
-
-```bash
-npx tina4nodejs migrate:create "create users table"
-```
-
-Edit the generated SQL:
-
-```sql
-CREATE TABLE IF NOT EXISTS users (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    email TEXT NOT NULL,
-    created_at TEXT DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-```bash
-npx tina4nodejs migrate
-```
-
-### 4. Create an ORM model
-
-Create `src/models/User.ts`:
-
-```typescript
-export default class User {
-    static tableName = "users";
-
-    static fields = {
-        id:        { type: "integer" as const, primaryKey: true, autoIncrement: true },
-        name:      { type: "string" as const,  required: true, maxLength: 100 },
-        email:     { type: "string" as const,  required: true, pattern: "^[^@]+@[^@]+\\.[^@]+$" },
-        createdAt: { type: "datetime" as const, default: "now" },
-    };
-}
-```
-
-### 5. Build a REST API
-
-**File-based** -- create `src/routes/api/users/get.ts`:
-
-```typescript
-import type { Tina4Request, Tina4Response } from "tina4-nodejs";
-import { getAdapter } from "tina4-nodejs";
-
-export default async function (request: Tina4Request, response: Tina4Response) {
-    const db = getAdapter();
-    const users = db.query("SELECT * FROM users LIMIT 100");
-    response(users, HTTP_OK);
-}
-```
-
-Create `src/routes/api/users/[id]/get.ts`:
-
-```typescript
-export default async function (request: Tina4Request, response: Tina4Response) {
-    const db = getAdapter();
-    const user = db.query("SELECT * FROM users WHERE id = ?", [request.params.id]);
-    if (user.length) {
-        response(user[0], HTTP_OK);
-    } else {
-        response({error: "Not found"}, HTTP_NOT_FOUND);
-    }
-}
-```
-
-Create `src/routes/api/users/post.ts`:
-
-```typescript
-export default async function (request: Tina4Request, response: Tina4Response) {
-    const db = getAdapter();
-    db.execute("INSERT INTO users (name, email) VALUES (?, ?)",
-        [request.body.name, request.body.email]);
-    response({success: true}, HTTP_CREATED);
-}
-```
-
-> **Auto-CRUD alternative**: Simply define the model in `src/models/User.ts` and Tina4 auto-generates all CRUD endpoints. File routes override auto-CRUD when both exist.
-
-### 6. Add a template
-
-Create `src/templates/base.twig`:
-
-```twig
-<!DOCTYPE html>
-<html>
-<head>
-    <title>{% block title %}My App{% endblock %}</title>
-    <link rel="stylesheet" href="/css/tina4.min.css">
-    {% block stylesheets %}{% endblock %}
-</head>
-<body>
-    {% block content %}{% endblock %}
-    <script src="/js/frond.js"></script>
-    {% block javascripts %}{% endblock %}
-</body>
-</html>
-```
-
-Create `src/templates/pages/home.twig`:
-
-```twig
-{% extends "base.twig" %}
-{% block content %}
-<div class="container mt-4">
-    <h1>{{ title }}</h1>
-    <ul>
-    {% for user in users %}
-        <li>{{ user.name }} -- {{ user.email }}</li>
-    {% endfor %}
-    </ul>
-</div>
-{% endblock %}
-```
-
-Render it from a route:
-
-```typescript
-// src/routes/page/home/get.ts
-export default async function (request: Tina4Request, response: Tina4Response) {
-    const db = getAdapter();
-    const users = db.query("SELECT * FROM users LIMIT 20");
-    await response.render("pages/home.twig", {title: "Users", users});
-}
-```
-
-### 7. Seed, test, deploy
-
-```bash
-npx tina4nodejs seed                          # Run seeders from src/seeds/
-npx tina4nodejs test                          # Run test suite
-npx tina4nodejs build                         # Build distributable
-```
-
-For the complete step-by-step guide, visit **[tina4.com](https://tina4.com)**.
-
----
-
-## Features
-
-### Routing
-
-Tina4 supports both **file-based** and **programmatic** routing:
 
-```typescript
-// File-based: src/routes/api/items/get.ts
-export default async function (request: Tina4Request, response: Tina4Response) {
-    response({items: []}, HTTP_OK);
-}
-
-// Programmatic: src/routes/webhooks.ts
-import { get, post } from "tina4-nodejs";
-
-get("/api/items", async (request, response) => {
-    response({items: []}, HTTP_OK);
-});
-
-// POST routes require auth by default; GET routes are public by default.
-// Use JSDoc @noauth / @secured annotations to override:
-
-/** @noauth */
-post("/api/webhook", async (request, response) => {
-    response({ok: true}, HTTP_OK);
-});
-
-/** @secured */
-get("/api/admin/stats", async (request, response) => {
-    response({secret: true}, HTTP_OK);
-});
-```
-
-Path parameter types: `{id}` (string), `[id]` (file-based), `[...slug]` (catch-all).
-
-### ORM
-
-Active Record with typed fields, validation, soft delete, relationships, and auto-CRUD:
-
-```typescript
 // src/models/User.ts
 export default class User {
-    static tableName = "users";
-
-    static fields = {
-        id:    { type: "integer" as const, primaryKey: true, autoIncrement: true },
-        name:  { type: "string" as const,  required: true, maxLength: 100 },
-        email: { type: "string" as const,  required: true, pattern: "^[^@]+@[^@]+$" },
-        role:  { type: "string" as const,  default: "user" },
-        age:   { type: "integer" as const, min: 0, max: 150 },
-    };
-}
-
-// Auto-generates: GET/POST /api/users, GET/PUT/DELETE /api/users/{id}
-// With filtering, sorting, pagination, and validation built in
-```
-
-### Database
-
-Unified interface across multiple engines:
-
-```typescript
-import { getAdapter, initDatabase } from "tina4-nodejs";
-
-const db = initDatabase("sqlite:///data/app.db");
-
-const result = db.query("SELECT * FROM users WHERE age > ?", [18]);
-const row = db.query("SELECT * FROM users WHERE id = ?", [1]);
-db.execute("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@test.com"]);
-```
-
-### Middleware
-
-```typescript
-import { get } from "tina4-nodejs";
-
-const authCheck = async (request: Tina4Request, response: Tina4Response, next: Function) => {
-    if (!request.headers.authorization) {
-        return response({error: "Unauthorized"}, HTTP_UNAUTHORIZED);
-    }
-    return next();
-};
-
-get("/protected", async (request, response) => {
-    response({secret: true}, HTTP_OK);
-}, [authCheck]);
-```
-
-### JWT Authentication
-
-```typescript
-import { getToken, validToken } from "tina4-nodejs";
-
-const token = getToken({userId: 42}, "your-secret");
-const payload = validToken(token, "your-secret");
-```
-
-POST/PUT/PATCH/DELETE routes require `Authorization: Bearer <token>` by default. Use `noauth()` to make public, `secured()` to protect GET routes.
-
-### Sessions
-
-```typescript
-request.session.set("userId", 42);
-const userId = request.session.get("userId");
-```
-
-Backend: file (default). Set via `TINA4_SESSION_HANDLER` in `.env`.
-
-### Queues
-
-```typescript
-import { Queue } from "tina4-nodejs";
-
-const queue = new Queue({ topic: "emails" });
-queue.push({ to: "alice@example.com" });
-
-const job = queue.pop();
-if (job) {
-    sendEmail(job.data);
-    job.complete();
-}
-```
-
-### GraphQL
-
-```typescript
-import { GraphQL } from "tina4-nodejs";
-
-const gql = new GraphQL();
-gql.schema.fromModels();
-gql.registerRoute("/graphql");   // GET = GraphiQL IDE, POST = queries
-```
-
-### WebSocket
-
-```typescript
-import { WebSocketServer } from "tina4-nodejs";
-
-const wss = new WebSocketServer({ port: 8080 });
-
-wss.on("connection", (client) => {
-    client.on("message", (msg) => {
-        wss.broadcast(`User said: ${msg}`);
-    });
-});
-```
-
-### Swagger / OpenAPI
-
-Auto-generated at `/swagger`:
-
-```typescript
-// src/routes/api/users/get.ts
-export const meta = {
-    summary: "Get all users",
-    tags: ["Users"],
-};
-
-export default async function (request: Tina4Request, response: Tina4Response) {
-    const db = getAdapter();
-    response(db.query("SELECT * FROM users"), HTTP_OK);
+  static tableName = "users";
+  static fields = {
+    id: { type: "integer" as const, primaryKey: true, autoIncrement: true },
+    name: { type: "string" as const, required: true },
+    email: { type: "string" as const },
+  };
 }
 ```
 
-### Service Runner
-
-```typescript
-import { ServiceRunner } from "tina4-nodejs";
-
-const runner = new ServiceRunner();
-
-runner.register("cleanup", "0 */6 * * *", async () => {
-    // Runs every 6 hours
-    await cleanupExpiredSessions();
-});
-```
-
-### Template Engine (Frond)
-
-Twig-compatible, 53+ filters, macros, inheritance, fragment caching, sandboxing:
-
-```twig
-{% extends "base.twig" %}
-{% block content %}
-<h1>{{ title | upper }}</h1>
-{% for item in items %}
-    <p>{{ item.name }} -- {{ item.price | number_format(2) }}</p>
-{% endfor %}
-
-{% cache "sidebar" 300 %}
-    {% include "partials/sidebar.twig" %}
-{% endcache %}
-{% endblock %}
-```
-
-### REST Client
-
-```typescript
-import { Api } from "tina4-nodejs";
-
-const api = new Api("https://api.example.com", {authHeader: "Bearer xyz"});
-const result = await api.sendRequest("/users/42");
-```
-
-### Data Seeder
-
-```typescript
-import { FakeData } from "tina4-nodejs";
-
-const fake = new FakeData();
-fake.name();      // "Alice Johnson"
-fake.email();     // "alice.johnson@example.com"
-
-// Seed via ORM package:
-// import { seedOrm } from "@tina4/orm";
-// await seedOrm(User, 50);
-```
-
-### Response Cache
-
-```typescript
-import { get, responseCache } from "tina4-nodejs";
-
-// Apply response cache as middleware with 60-second TTL
-get("/api/stats", async (request, response) => {
-    response(computeExpensiveStats(), HTTP_OK);
-}, [responseCache({ ttl: 60 })]);
-```
-
-### SCSS, Localization
-
-- **SCSS**: Drop `.scss` in `src/scss/` -- auto-compiled to CSS. Variables, nesting, mixins, `@import`, `@extend`.
-- **i18n**: JSON translation files, parameter substitution.
-
 ---
 
-## Dev Mode
-
-Set `TINA4_DEBUG=true` in `.env` to enable:
+## What's Included
 
-- **Live reload** -- browser auto-refreshes on code changes
-- **CSS hot-reload** -- SCSS changes apply without page refresh
-- **Error overlay** -- rich error display in the browser
-- **Dev admin** with routes, queue, requests, errors, system tabs
+| Category | Features |
+|----------|----------|
+| **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
+| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird — unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
+| **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
+| **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
+| **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
+| **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters — service runner — event system (on/emit/once/off) |
+| **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
+| **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
+| **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
+
+**1,950 tests. Zero dependencies. Full parity across Python, PHP, Ruby, and Node.js.**
 
 ---
 
 ## CLI Reference
 
 ```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
-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"] });
+npx tina4nodejs init [dir]
+npx tina4nodejs serve [--port PORT]
+npx tina4nodejs migrate
+npx tina4nodejs seed
+npx tina4nodejs ai [--all]
+npx tina4nodejs generate model <name>
 ```
 
-### DB Query Caching
-
-Enable query caching for up to 4x speedup on read-heavy workloads:
+---
 
-```bash
-# .env
-TINA4_DB_CACHE=true
-```
+## Performance
 
-### Frond Pre-Compilation
+Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
 
-Templates are pre-compiled for 2.8x faster rendering.
+| Framework | JSON req/s | Deps | Features |
+|-----------|-----------|------|----------|
+| Raw `node:http` | 91,110 | 0 | 1 |
+| **Tina4 Node.js** | **84,771** | 0 | 54 |
 
-### Gallery
+Tina4 Node.js runs at **93% of raw Node.js speed** while providing 54 built-in features — zero overhead architecture.
 
-7 interactive examples with **Try It** deploy.
+**Across all 4 Tina4 implementations:**
 
-## Environment
+| | Python | PHP | Ruby | Node.js |
+|---|--------|-----|------|---------|
+| **JSON req/s** | 6,508 | 29,293 | 10,243 | 84,771 |
+| **Dependencies** | 0 | 0 | 0 | 0 |
+| **Features** | 54 | 54 | 54 | 54 |
 
-```bash
-SECRET=your-jwt-secret
-DATABASE_URL=sqlite:///data/app.db
-DATABASE_USERNAME=admin              # Separate credentials for networked databases
-DATABASE_PASSWORD=secret
-TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
-TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
-TINA4_LOCALE=en                      # en, fr, af, zh, ja, es
-TINA4_SESSION_HANDLER=SessionFileHandler
-SWAGGER_TITLE=My API
-```
+---
 
-## Carbonah Green Benchmarks
+## Cross-Framework Parity
 
-All benchmarks rated **A+** (South Africa grid, 1000 iterations each):
+Tina4 ships identical features across four languages — same architecture, same conventions, same 54 features:
 
-| Metric | Value |
-|--------|-------|
-| Startup time | 38ms |
-| Memory usage | 104.2MB |
-| SCI score | 0.00552 gCO2eq |
-| Grade | A+ |
+| | Python | PHP | Ruby | Node.js |
+|---|--------|-----|------|---------|
+| **Package** | `tina4-python` | `tina4stack/tina4php` | `tina4ruby` | `tina4-nodejs` |
+| **Tests** | 2,066 | 1,427 | 1,793 | 1,950 |
+| **Default port** | 7145 | 7146 | 7147 | 7148 |
 
-Run locally: `npx tina4nodejs benchmark`
+**7,236 tests** across all 4 frameworks. See [tina4.com](https://tina4.com).
 
 ---
 
@@ -674,14 +124,10 @@ https://opensource.org/licenses/MIT
 
 ---
 
-<p align="center"><b>Tina4</b> -- The framework that keeps out of the way of your coding.</p>
-
----
-
 ## Our Sponsors
 
 **Sponsored with 🩵 by Code Infinity**
 
 [<img src="https://codeinfinity.co.za/wp-content/uploads/2025/09/c8e-logo-github.png" alt="Code Infinity" width="100">](https://codeinfinity.co.za/about-open-source-policy?utm_source=github&utm_medium=website&utm_campaign=opensource_campaign&utm_id=opensource)
 
-*Supporting open source communities <span style="color: #1DC7DE;">•</span> Innovate <span style="color: #1DC7DE;">•</span> Code <span style="color: #1DC7DE;">•</span> Empower*
+*Supporting open source communities • Innovate • Code • Empower*

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.38",
+  "version": "3.10.41",
   "type": "module",
-  "description": "This is not a framework. Tina4 for Node.js/TypeScript — zero deps, 38 built-in features.",
+  "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],
   "homepage": "https://tina4.com/nodejs",
   "repository": {

package/packages/cli/src/bin.ts

@@ -7,6 +7,7 @@ import { migrateRollback } from "./commands/migrateRollback.js";
 import { listRoutes } from "./commands/routes.js";
 import { runTests } from "./commands/test.js";
 import { generate } from "./commands/generate.js";
+import { runSeeds } from "./commands/seed.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -24,6 +25,7 @@ const HELP = `
     tina4nodejs routes                List all registered routes
     tina4nodejs test [file]           Run project tests
     tina4nodejs generate <what> <name> Generate scaffolding (model, route, migration, middleware)
+    tina4nodejs seed [file]           Run database seed files from src/seeds/
     tina4nodejs ai                    Install AI coding assistant context files
     tina4nodejs help                  Show this help message
 
@@ -78,6 +80,10 @@ async function main(): Promise<void> {
       await generate(what, genName);
       break;
     }
+    case "seed": {
+      await runSeeds(args[1]);
+      break;
+    }
     case "ai": {
       const { showMenu, installSelected, installAll } = await import("../../core/src/ai.js");
       const root = args[1] || ".";

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

@@ -0,0 +1,72 @@
+/**
+ * CLI command: seed — Run database seed files.
+ *
+ * Scans src/seeds/ for .ts files and executes them with tsx in alphabetical order.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+
+export async function runSeeds(seedPath?: string): Promise<void> {
+  const cwd = process.cwd();
+  const seedDir = resolve(cwd, "src/seeds");
+
+  // If a specific seed file is provided, run it directly
+  if (seedPath) {
+    const file = resolve(seedPath);
+    if (!existsSync(file)) {
+      console.error(`  Error: Seed file not found: ${seedPath}`);
+      process.exit(1);
+    }
+    console.log(`  Running seed: ${seedPath}\n`);
+    try {
+      execSync(`npx tsx "${file}"`, { cwd, stdio: "inherit" });
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Auto-discover seed files in src/seeds/
+  if (!existsSync(seedDir)) {
+    console.log("  No seeds directory found.");
+    console.log("  Create seed files in src/seeds/ (e.g. src/seeds/001-users.ts)");
+    return;
+  }
+
+  let seedFiles: string[];
+  try {
+    seedFiles = readdirSync(seedDir)
+      .filter((f) => f.endsWith(".ts"))
+      .sort()
+      .map((f) => join(seedDir, f));
+  } catch {
+    console.log("  Could not read src/seeds/ directory.");
+    return;
+  }
+
+  if (seedFiles.length === 0) {
+    console.log("  No seed files found in src/seeds/");
+    return;
+  }
+
+  console.log(`  Found ${seedFiles.length} seed file(s)\n`);
+
+  let failed = false;
+  for (const file of seedFiles) {
+    const relative = file.replace(cwd + "/", "");
+    console.log(`  Seeding: ${relative}`);
+    try {
+      execSync(`npx tsx "${file}"`, { cwd, stdio: "inherit" });
+    } catch {
+      failed = true;
+    }
+  }
+
+  if (failed) {
+    console.error("\n  Some seeds failed.");
+    process.exit(1);
+  }
+
+  console.log("\n  All seeds completed.");
+}

package/packages/core/src/devAdmin.ts

@@ -2332,6 +2332,8 @@ function tina4VersionModal(){
                 if(l>c){isNewer=true;break;}
                 if(l<c)break;
             }
+            var isAhead=false;
+            if(!isNewer){for(var i=0;i<Math.max(cParts.length,lParts.length);i++){var c2=cParts[i]||0,l2=lParts[i]||0;if(c2>l2){isAhead=true;break;}if(c2<l2)break;}}
             if(isNewer){
                 var breaking=(lParts[0]!==cParts[0]||lParts[1]!==cParts[1]);
                 el.innerHTML='Latest: <strong style="color:#f9e2af;">v'+latest+'</strong>';
@@ -2340,6 +2342,9 @@ function tina4VersionModal(){
                 }else{
                     el.innerHTML+='<div style="color:#f9e2af;margin-top:6px;">Patch update available. Run: <code style="background:#313244;padding:2px 6px;border-radius:3px;">npm install tina4-nodejs@latest</code></div>';
                 }
+            }else if(isAhead){
+                el.innerHTML='You are running <strong style="color:#cba6f7;">v'+current+'</strong> (ahead of npm <strong>v'+latest+'</strong> &mdash; not yet published).';
+                el.style.color='#cba6f7';
             }else{
                 el.innerHTML='Latest: <strong style="color:#a6e3a1;">v'+latest+'</strong> &mdash; You are up to date!';
                 el.style.color='#a6e3a1';

package/packages/core/src/router.ts

@@ -247,6 +247,11 @@ export class Router {
     return all;
   }
 
+  /** Alias for getRoutes(). */
+  allRoutes(): RouteDefinition[] {
+    return this.getRoutes();
+  }
+
   /**
    * List all routes in a debug-friendly format for CLI output.
    */

package/packages/orm/src/baseModel.ts

@@ -167,8 +167,6 @@ export class BaseModel {
    */
   static findById<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
-    const pk = ModelClass.getPkField();
     const pkCol = ModelClass.getPkColumn();
     let sql = `SELECT * FROM "${ModelClass.tableName}" WHERE "${pkCol}" = ?`;
 
@@ -179,15 +177,38 @@ export class BaseModel {
       sql += ` AND ${ModelClass.tableFilter}`;
     }
 
-    const rows = db.query(sql, [id]);
-    if (rows.length === 0) return null;
-    const instance = new ModelClass(rows[0] as Record<string, unknown>) as T;
-    if (include) {
+    const instance = ModelClass.selectOne<T>(sql, [id]);
+    if (instance && include) {
       ModelClass._eagerLoad([instance], include);
     }
     return instance;
   }
 
+  /**
+   * Create a new instance from data, save it, and return the saved instance.
+   *
+   * Usage:
+   *   const user = User.create({ name: "Alice", email: "alice@example.com" });
+   */
+  static create<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    data: Record<string, unknown>,
+  ): T {
+    const instance = new this(data) as T;
+    instance.save();
+    return instance;
+  }
+
+  /** Alias for findById(). */
+  static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
+    return (this as unknown as typeof BaseModel).findById.call(this, id, include) as T | null;
+  }
+
+  /** Alias for findById(). */
+  static load<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
+    return (this as unknown as typeof BaseModel).findById.call(this, id, include) as T | null;
+  }
+
   /**
    * Find all records, optionally with a where clause.
    * @param where Optional WHERE clause.
@@ -508,6 +529,21 @@ export class BaseModel {
     return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
   }
 
+  static selectOne<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    sql: string,
+    params?: unknown[],
+    include?: string[],
+  ): T | null {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    const results = ModelClass.select<T>(sql, params);
+    const instance = results[0] ?? null;
+    if (instance && include) {
+      ModelClass._eagerLoad([instance], include);
+    }
+    return instance;
+  }
+
   /**
    * Permanently delete this instance, bypassing soft delete.
    */

package/packages/orm/src/database.ts

@@ -393,6 +393,44 @@ export class Database {
     return this.getNextAdapter().tables();
   }
 
+  /**
+   * Get column metadata for a table.
+   * Uses the adapter's columns() method which handles engine-specific introspection
+   * (PRAGMA table_info for SQLite, information_schema.columns for others).
+   *
+   * @param tableName - Name of the table to inspect.
+   * @returns Array of column info objects: { name, type, nullable, default, primaryKey }.
+   */
+  getColumns(tableName: string): { name: string; type: string; nullable?: boolean; default?: unknown; primaryKey?: boolean }[] {
+    return this.getNextAdapter().columns(tableName);
+  }
+
+  /**
+   * Execute a SQL statement with multiple parameter sets (batch insert/update).
+   * Wraps all executions in a single transaction for atomicity and performance.
+   *
+   * @param sql - The SQL statement with parameter placeholders.
+   * @param paramSets - Array of parameter arrays, one per execution.
+   * @returns Array of results from each execution.
+   */
+  executeMany(sql: string, paramSets: unknown[][]): unknown[] {
+    const adapter = this.getNextAdapter();
+    const results: unknown[] = [];
+
+    adapter.startTransaction();
+    try {
+      for (const params of paramSets) {
+        results.push(adapter.execute(sql, params));
+      }
+      adapter.commit();
+    } catch (e) {
+      adapter.rollback();
+      throw e;
+    }
+
+    return results;
+  }
+
   /** Get the last auto-increment id. */
   getLastId(): string | number {
     const id = this.getNextAdapter().lastInsertId();