tina4-nodejs 3.1.1 → 3.1.2

package/README.md

@@ -27,17 +27,22 @@
 
 ---
 
-## Quickstart
+## Quick Start
 
 ```bash
-npm install tina4-nodejs
-npx tina4nodejs init my-app
-cd my-app
-npx tina4nodejs serve
-# -> http://localhost:7148
+# 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
 ```
 
-That's it. Zero configuration, zero classes, zero boilerplate.
+Open http://localhost:7148 — your app is running.
+
+> **Alternative** (without Rust CLI): `npm install tina4-nodejs` then create `app.ts`
 
 ---
 
@@ -298,23 +303,24 @@ export default async function (request: Tina4Request, response: Tina4Response) {
 }
 
 // Programmatic: src/routes/webhooks.ts
-import { get, post, noauth, secured, middleware } from "tina4-nodejs";
+import { get, post } from "tina4-nodejs";
 
 get("/api/items", async (request, response) => {
     response({items: []}, HTTP_OK);
 });
 
-noauth(
-    post("/api/webhook", async (request, response) => {
-        response({ok: true}, HTTP_OK);
-    })
-);
+// POST routes require auth by default; GET routes are public by default.
+// Use JSDoc @noauth / @secured annotations to override:
 
-secured(
-    get("/api/admin/stats", async (request, response) => {
-        response({secret: true}, HTTP_OK);
-    })
-);
+/** @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).
@@ -358,7 +364,7 @@ db.execute("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@tes
 ### Middleware
 
 ```typescript
-import { middleware } from "tina4-nodejs";
+import { get } from "tina4-nodejs";
 
 const authCheck = async (request: Tina4Request, response: Tina4Response, next: Function) => {
     if (!request.headers.authorization) {
@@ -367,21 +373,18 @@ const authCheck = async (request: Tina4Request, response: Tina4Response, next: F
     return next();
 };
 
-middleware(authCheck,
-    get("/protected", async (request, response) => {
-        response({secret: true}, HTTP_OK);
-    })
-);
+get("/protected", async (request, response) => {
+    response({secret: true}, HTTP_OK);
+}, [authCheck]);
 ```
 
 ### JWT Authentication
 
 ```typescript
-import { Auth } from "tina4-nodejs";
+import { createToken, validateToken } from "tina4-nodejs";
 
-const auth = new Auth({secret: "your-secret"});
-const token = auth.createToken({userId: 42});
-const payload = auth.validateToken(token);
+const token = createToken({userId: 42}, "your-secret");
+const payload = validateToken(token, "your-secret");
 ```
 
 POST/PUT/PATCH/DELETE routes require `Authorization: Bearer <token>` by default. Use `noauth()` to make public, `secured()` to protect GET routes.
@@ -398,13 +401,16 @@ Backend: file (default). Set via `TINA4_SESSION_HANDLER` in `.env`.
 ### Queues
 
 ```typescript
-import { Queue, Producer, Consumer } from "tina4-nodejs";
+import { Queue } from "tina4-nodejs";
 
-new Producer(new Queue({topic: "emails"})).produce({to: "alice@example.com"});
+const queue = new Queue({ topic: "emails" });
+queue.push({ to: "alice@example.com" });
 
-new Consumer(new Queue({topic: "emails"})).onMessage((msg) => {
-    sendEmail(msg.data);
-});
+const job = queue.pop();
+if (job) {
+    sendEmail(job.data);
+    job.complete();
+}
 ```
 
 ### GraphQL
@@ -420,12 +426,14 @@ gql.registerRoute("/graphql");   // GET = GraphiQL IDE, POST = queries
 ### WebSocket
 
 ```typescript
-import { WebSocketManager } from "tina4-nodejs";
+import { WebSocketServer } from "tina4-nodejs";
 
-const ws = new WebSocketManager();
+const wss = new WebSocketServer({ port: 8080 });
 
-ws.route("/ws/chat", async (connection, message) => {
-    await ws.broadcast("/ws/chat", `User said: ${message}`);
+wss.on("connection", (client) => {
+    client.on("message", (msg) => {
+        wss.broadcast(`User said: ${msg}`);
+    });
 });
 ```
 
@@ -489,25 +497,26 @@ const result = await api.sendRequest("/users/42");
 ### Data Seeder
 
 ```typescript
-import { Fake, seedModel } from "tina4-nodejs";
+import { FakeData } from "tina4-nodejs";
 
-const fake = new Fake();
+const fake = new FakeData();
 fake.name();      // "Alice Johnson"
 fake.email();     // "alice.johnson@example.com"
 
-seedModel(User, {count: 50});
+// Seed via ORM package:
+// import { seedOrm } from "@tina4/orm";
+// await seedOrm(User, 50);
 ```
 
 ### Response Cache
 
 ```typescript
-import { cached } from "tina4-nodejs";
+import { get, responseCache } from "tina4-nodejs";
 
-cached(60,
-    get("/api/stats", async (request, response) => {
-        response(computeExpensiveStats(), HTTP_OK);
-    })
-);
+// Apply response cache as middleware with 60-second TTL
+get("/api/stats", async (request, response) => {
+    response(computeExpensiveStats(), HTTP_OK);
+}, [responseCache({ ttl: 60 })]);
 ```
 
 ### SCSS, Localization
@@ -519,7 +528,7 @@ cached(60,
 
 ## Dev Mode
 
-Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
+Set `TINA4_DEBUG=true` in `.env` to enable:
 
 - **Live reload** -- browser auto-refreshes on code changes
 - **CSS hot-reload** -- SCSS changes apply without page refresh
@@ -604,7 +613,8 @@ SECRET=your-jwt-secret
 DATABASE_URL=sqlite:///data/app.db
 DATABASE_USERNAME=admin              # Separate credentials for networked databases
 DATABASE_PASSWORD=secret
-TINA4_DEBUG_LEVEL=DEBUG              # DEBUG, INFO, WARNING, ERROR, ALL
+TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
+TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LANGUAGE=en                    # en, fr, af, zh, ja, es
 TINA4_SESSION_HANDLER=SessionFileHandler
 SWAGGER_TITLE=My API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "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/BENCHMARK_REPORT.md

@@ -1,258 +0,0 @@
-# Tina4 v3 — Comprehensive Benchmark Report
-
-**Date:** 2026-03-21 | **Machine:** Apple M3, macOS, 16GB RAM
-**Tool:** hey (https://github.com/rakyll/hey) | **Config:** 5000 requests, 50 concurrent, 5 runs (median)
-**Warm-up:** 500 requests discarded before each test | **Mode:** All frameworks in production mode
-
----
-
-## Overall Ranking — JSON Endpoint
-
-| # | Framework | Language | JSON req/s | List req/s | Deploy Size | Deps | Features |
-|---|-----------|---------|:---------:|:---------:|:----------:|:----:|:--------:|
-| 1 | Node.js raw http | Node.js | 86,662 | 24,598 | 0 KB | 0 | 1/38 |
-| 2 | Fastify | Node.js | 79,505 | 23,395 | 2 MB | 10+ | 5/38 |
-| 3 | Koa | Node.js | 60,400 | 23,433 | 1 MB | 5 | 3/38 |
-| 4 | **Tina4 Node.js** | **Node.js** | **57,035** | **25,088** | **1.8 MB** | **0** | **38/38** |
-| 5 | Express | Node.js | 56,687 | 20,720 | 2 MB | 3 | 4/38 |
-| 6 | **Tina4 PHP** | **PHP** | **27,299** | **16,555** | **1.0 MB** | **0** | **38/38** |
-| 7 | **Tina4 Python** | **Python** | **16,233** | **5,858** | **2.4 MB** | **0** | **38/38** |
-| 8 | Starlette | Python | 15,978 | 7,493 | 505 KB | 4 | 6/38 |
-| 9 | FastAPI | Python | 11,886 | 2,464 | 4.8 MB | 12+ | 8/38 |
-| 10 | Sinatra | Ruby | 9,732 | 5,996 | 5 MB | 5 | 4/38 |
-| 11 | **Tina4 Ruby** | **Ruby** | **9,504** | **7,648** | **892 KB** | **0** | **38/38** |
-| 12 | Slim | PHP | 5,033 | 4,520 | 1.3 MB | 10+ | 6/38 |
-| 13 | Flask | Python | 4,767 | 1,644 | 4.2 MB | 6 | 7/38 |
-| 14 | Django | Python | 3,747 | 3,305 | 25 MB | 20+ | 22/38 |
-| 15 | Symfony | PHP | 1,840 | 1,702 | 11 MB | 30+ | 8/38 |
-| 16 | Bottle | Python | 1,251 | 676 | 200 KB | 0 | 5/38 |
-| 17 | Laravel | PHP | 370 | 364 | 77 MB | 50+ | 25/38 |
-
----
-
-## Per-Language Breakdown
-
-### Python
-
-| Framework | JSON req/s | List req/s | Deploy | Deps | Features | vs Tina4 |
-|-----------|:---------:|:---------:|:------:|:----:|:--------:|:--------:|
-| **Tina4 Python** | **16,233** | **5,858** | **2.4 MB** | **0** | **38/38** | **baseline** |
-| Starlette | 15,978 | 7,493 | 505 KB | 4 | 6/38 | 0.98x |
-| FastAPI | 11,886 | 2,464 | 4.8 MB | 12+ | 8/38 | 0.73x |
-| Flask | 4,767 | 1,644 | 4.2 MB | 6 | 7/38 | 0.29x |
-| Django | 3,747 | 3,305 | 25 MB | 20+ | 22/38 | 0.23x |
-| Bottle | 1,251 | 676 | 200 KB | 0 | 5/38 | 0.08x |
-
-**Tina4 Python** is #1 in Python. Matches Starlette (which uses uvicorn's C parser), 3.4x faster than Flask, 4.3x faster than Django.
-
-### PHP
-
-| Framework | JSON req/s | List req/s | Deploy | Deps | Features | vs Tina4 |
-|-----------|:---------:|:---------:|:------:|:----:|:--------:|:--------:|
-| **Tina4 PHP** | **27,299** | **16,555** | **1.0 MB** | **0** | **38/38** | **baseline** |
-| Slim | 5,033 | 4,520 | 1.3 MB | 10+ | 6/38 | 0.18x |
-| Symfony | 1,840 | 1,702 | 11 MB | 30+ | 8/38 | 0.07x |
-| Laravel | 370 | 364 | 77 MB | 50+ | 25/38 | 0.01x |
-
-**Tina4 PHP** dominates. 5.4x faster than Slim, 14.8x faster than Symfony, 73.8x faster than Laravel. 77x smaller than Laravel.
-
-### Ruby
-
-| Framework | JSON req/s | List req/s | Deploy | Deps | Features | vs Tina4 |
-|-----------|:---------:|:---------:|:------:|:----:|:--------:|:--------:|
-| Sinatra | 9,732 | 5,996 | 5 MB | 5 | 4/38 | 1.02x |
-| **Tina4 Ruby** | **9,504** | **7,648** | **892 KB** | **0** | **38/38** | **baseline** |
-
-**Tina4 Ruby** matches Sinatra on JSON (within noise), beats it on large payloads (7,648 vs 5,996). Ships 38 features vs 4.
-
-### Node.js
-
-| Framework | JSON req/s | List req/s | Deploy | Deps | Features | vs Tina4 |
-|-----------|:---------:|:---------:|:------:|:----:|:--------:|:--------:|
-| Node.js raw | 86,662 | 24,598 | 0 KB | 0 | 1/38 | 1.52x |
-| Fastify | 79,505 | 23,395 | 2 MB | 10+ | 5/38 | 1.39x |
-| Koa | 60,400 | 23,433 | 1 MB | 5 | 3/38 | 1.06x |
-| **Tina4 Node.js** | **57,035** | **25,088** | **1.8 MB** | **0** | **38/38** | **baseline** |
-| Express | 56,687 | 20,720 | 2 MB | 3 | 4/38 | 0.99x |
-
-**Tina4 Node.js** beats Express (57K vs 57K), matches Koa. Fastest on large payloads (25,088 — highest of all Node.js frameworks).
-
----
-
-## Deployment Size Comparison
-
-| Framework | Size | vs Tina4 | Files |
-|-----------|:----:|:--------:|:-----:|
-| **Tina4 Ruby** | **892 KB** | — | ~65 |
-| **Tina4 PHP** | **1.0 MB** | — | ~52 |
-| **Tina4 Node.js** | **1.8 MB** | — | ~71 |
-| **Tina4 Python** | **2.4 MB** | — | ~65 |
-| Bottle | 200 KB | 0.08x | 1 |
-| Starlette | 505 KB | 0.2x | ~30 |
-| Slim | 1.3 MB | 1x | ~100 |
-| Express | 2 MB | 1x | ~50 |
-| Flask + deps | 4.2 MB | 2x | ~200 |
-| FastAPI + deps | 4.8 MB | 2x | ~300 |
-| Sinatra + deps | 5 MB | 2x | ~100 |
-| Symfony | 11 MB | 10x | ~2000 |
-| Django | 25 MB | 10x | ~5000 |
-| Laravel | 77 MB | 77x | ~10000 |
-
----
-
-## CO2 Emissions per 1000 Requests
-
-Based on: 15W TDP × (1000/req_per_sec) seconds × 475g CO2/kWh grid average
-
-| Framework | JSON req/s | Time for 1000 req | Energy (Wh) | CO2 (g) | vs Tina4 |
-|-----------|:---------:|:----------------:|:----------:|:------:|:--------:|
-| Node.js raw | 86,662 | 0.012s | 0.00005 | 0.023 | 0.3x |
-| Fastify | 79,505 | 0.013s | 0.00005 | 0.025 | 0.3x |
-| **Tina4 Node.js** | **57,035** | **0.018s** | **0.00007** | **0.035** | **baseline** |
-| Express | 56,687 | 0.018s | 0.00007 | 0.035 | 1.0x |
-| **Tina4 PHP** | **27,299** | **0.037s** | **0.00015** | **0.073** | **baseline** |
-| **Tina4 Python** | **16,233** | **0.062s** | **0.00026** | **0.122** | **baseline** |
-| Starlette | 15,978 | 0.063s | 0.00026 | 0.124 | 1.0x |
-| FastAPI | 11,886 | 0.084s | 0.00035 | 0.167 | 1.4x |
-| Sinatra | 9,732 | 0.103s | 0.00043 | 0.204 | 1.7x |
-| **Tina4 Ruby** | **9,504** | **0.105s** | **0.00044** | **0.209** | **baseline** |
-| Slim | 5,033 | 0.199s | 0.00083 | 0.394 | 5.4x |
-| Flask | 4,767 | 0.210s | 0.00087 | 0.416 | 3.4x |
-| Django | 3,747 | 0.267s | 0.00111 | 0.529 | 4.3x |
-| Symfony | 1,840 | 0.543s | 0.00226 | 1.076 | 14.7x |
-| Bottle | 1,251 | 0.799s | 0.00333 | 1.584 | 13.0x |
-| Laravel | 370 | 2.703s | 0.01126 | 5.349 | 73.3x |
-
-**Laravel emits 73x more CO2 per request than Tina4 PHP.**
-
-At scale (1M requests/day):
-- Tina4 PHP: **73g CO2/day** (26.6 kg/year)
-- Laravel: **5,349g CO2/day** (1,952 kg/year) — **1.9 tonnes of CO2 per year more**
-
----
-
-## Feature Comparison (38 features)
-
-| Feature | Tina4 | Django | Laravel | Flask | FastAPI | Express | Sinatra | Slim | Symfony |
-|---------|:-----:|:------:|:-------:|:-----:|:-------:|:-------:|:-------:|:----:|:-------:|
-| **Total** | **38** | **22** | **25** | **7** | **8** | **4** | **4** | **6** | **8** |
-| Zero deps | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| ORM | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| 5 DB drivers | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| JWT auth | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Queue system | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| WebSocket | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| GraphQL | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| SOAP/WSDL | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Swagger/OpenAPI | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Template engine | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
-| CSS framework | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Dev dashboard | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
-| Gallery/examples | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| AI assistant | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| 4 languages | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-
----
-
-## Methodology
-
-### How to reproduce
-```bash
-cd tina4-python
-python benchmarks/benchmark.py --runs 5
-```
-
-### What we measured
-- **JSON endpoint**: Returns `{"message": "Hello, World!", "framework": "..."}` — tests routing + JSON serialization
-- **List endpoint**: Returns 100 items with id/name/price — tests JSON serialization of larger payloads
-
-### Production mode
-All frameworks run with debug/development mode OFF:
-- Tina4: `TINA4_DEBUG=false`
-- Flask: `FLASK_ENV=production`
-- Django: `DEBUG=False`
-- Laravel: `APP_DEBUG=false`
-- Express/Fastify/Koa: `NODE_ENV=production`
-- Sinatra: `environment=production`
-- PHP: `display_errors=Off`
-
-### Server types
-- **Tina4 Python**: built-in asyncio (zero deps)
-- **Tina4 PHP**: PHP built-in server (`php -S`)
-- **Tina4 Ruby**: WEBrick
-- **Tina4 Node.js**: Node.js http.createServer
-- **Flask**: Werkzeug
-- **Starlette/FastAPI**: uvicorn (with httptools C parser)
-- **Django**: runserver
-- **Laravel**: artisan serve (PHP built-in)
-- **Symfony**: PHP built-in server
-- **Slim**: PHP built-in server
-- **Express/Fastify/Koa**: Node.js http
-- **Sinatra**: Puma
-
-### Variance
-Individual run values are reported alongside medians. Variance of >20% between runs is flagged. The median of 5 runs provides a reliable central estimate.
-
-### Limitations
-- All tests use development servers (not production WSGI/ASGI servers)
-- Production deployments with gunicorn/uvicorn/php-fpm/puma would improve all frameworks
-- Results are specific to Apple M3 — different hardware will produce different absolute numbers
-- Relative rankings should be consistent across hardware
-
----
-
-## Cross-Platform Support
-
-All 4 Tina4 frameworks run on:
-- ✅ macOS (Intel + Apple Silicon)
-- ✅ Linux (x86_64 + ARM64)
-- ✅ Windows (10/11)
-- ✅ Docker (any base image)
-- ✅ WSL2
-
-No C extensions. No native binaries. No compile step. Pure Python/PHP/Ruby/JavaScript.
-
----
-
-*Generated by Tina4 Benchmark Suite v3.0.0 — https://tina4.com*
-
----
-
-## Ruby — Updated Results (2026-03-21)
-
-| Framework | JSON req/s | List req/s | Server | Deps | Features |
-|-----------|:---------:|:---------:|--------|:----:|:--------:|
-| Roda | 20,964 | 12,265 | Puma | 1 | 3/38 |
-| Sinatra | 9,909 | 7,229 | Puma | 5 | 4/38 |
-| **Tina4 Ruby** | **8,139** | **6,427** | **WEBrick** | **0** | **38/38** |
-| Rails | 4,754 | 4,052 | Puma | 69 | 24/38 |
-
-**Tina4 Ruby on WEBrick is 1.7x faster than Rails on Puma** — with 38 features vs 24, zero deps vs 69.
-
----
-
-## Dev vs Production — Tina4 All Frameworks (2026-03-21)
-
-| Framework | Dev Server | Dev JSON/s | Prod Server | Prod JSON/s | Prod List/s | Change |
-|-----------|-----------|:---------:|-------------|:---------:|:---------:|:------:|
-| **Tina4 PHP** | php -S | 27,299 | php + OPcache | **27,486** | **16,628** | ~same |
-| **Tina4 Ruby** | WEBrick | 8,139 | Puma | **22,784** | **12,504** | **2.8x ↑** |
-| **Tina4 Node.js** | http single | 57,035 | cluster (8 workers) | 12,488 | **16,958** | ↓ burst |
-| **Tina4 Python** | asyncio | 16,233 | uvicorn | 9,801 | 5,221 | ↓ burst |
-
-### Key Insights
-
-1. **Ruby benefits most from production server** — Puma's multi-threaded C-optimized HTTP parser gives 2.8x improvement over WEBrick
-2. **PHP is already fast** — built-in `php -S` is surprisingly competitive; OPcache helps with complex apps but not simple JSON endpoints
-3. **Python's asyncio server is faster than uvicorn for bursts** — our hand-rolled asyncio server has less overhead than uvicorn's libuv event loop for short-lived connections
-4. **Node.js cluster adds IPC overhead** — for burst benchmarks on a single machine, the inter-process communication cost of 8 workers outweighs the parallelism benefit
-
-### When production servers help
-
-Production servers excel under **sustained high concurrency** (thousands of simultaneous connections), **long-running requests** (database queries, file uploads), and **multi-core utilization** (real traffic from many clients). Burst benchmarks from a single client on localhost don't show these advantages.
-
-### Recommendation
-
-- `tina4 serve` — for development (toolbar, reload, gallery)
-- `tina4 serve --production` — for deployment (auto-installs best server)
-- Production benchmarks should use sustained load tests (wrk2, k6) not burst tests (hey, ab)

package/CARBONAH.md

@@ -1,140 +0,0 @@
-# Carbonah Green Benchmark Report
-
-> Tina4 Node.js v3 — Test Results
-> Date: 2026-03-21
-> Rating: **A+**
-
----
-
-## Summary
-
-| Metric | Value |
-|--------|-------|
-| Total Tests | 1,669 |
-| Passed | 1,669 |
-| Failed | 0 |
-| Errors | 0 |
-| Status | **PASS** |
-
----
-
-## Per-Module Breakdown
-
-| Module | Tests | Status |
-|--------|-------|--------|
-| Integration (end-to-end) | 37 | PASS |
-| Smoke | 97 | PASS |
-| Router | 30 | PASS |
-| Auth | 45 | PASS |
-| ORM | 28 | PASS |
-| Database | 26 | PASS |
-| Migration | 27 | PASS |
-| Session | 30 | PASS |
-| Session Handlers | 18 | PASS |
-| Queue | 28 | PASS |
-| Queue Backends | 20 | PASS |
-| Swagger | 54 | PASS |
-| WSDL | 42 | PASS |
-| GraphQL | 36 | PASS |
-| WebSocket | 74 | PASS |
-| I18n | 18 | PASS |
-| FakeData/Seeder | 51 | PASS |
-| SCSS | 19 | PASS |
-| Frond | 130 | PASS |
-| Events | 39 | PASS |
-| AI | 30 | PASS |
-| Response | 47 | PASS |
-| SQL Translation | 54 | PASS |
-| HtmlElement | 24 | PASS |
-| Form Token | 19 | PASS |
-| Post Protection | 29 | PASS |
-| DotEnv | 19 | PASS |
-| CORS | 5 | PASS |
-| Rate Limiter | 8 | PASS |
-| Health | 6 | PASS |
-| Log | 13 | PASS |
-| Service Runner | 49 | PASS |
-| Messenger | 48 | PASS |
-| DevAdmin | 47 | PASS |
-
----
-
-## Feature Parity
-
-78/78 features implemented — 100% parity with Python, PHP, and Ruby.
-
-| Category | Features |
-|----------|----------|
-| Core | Router, Middleware, CORS, Rate Limiter, Health Check, DotEnv, Logging |
-| Database | Multi-driver abstraction, ORM, Migrations, Seeder/FakeData, SQL Translation |
-| Auth | JWT tokens, Password hashing, API key validation, POST protection, Form tokens |
-| API | Swagger/OpenAPI, GraphQL, WSDL/SOAP |
-| Templates | Frond (Twig-compatible), SCSS compilation, HtmlElement builder |
-| Communication | Queue (memory/RabbitMQ/Kafka), WebSocket, Messenger, Session (file/Redis/Mongo) |
-| Dev Tools | Error Overlay, DevAdmin, Hot reload (via Rust CLI), AI context scaffolding |
-| Architecture | Events (pub/sub), DI Container, Response Cache, Inline Testing, Service Runner |
-| I18n | Localization with JSON translation files |
-
----
-
-## CO2 Report
-
-| Metric | Value |
-|--------|-------|
-| Test Execution Time | 18.00s |
-| CPU Time (user+sys) | ~12s (34 separate tsx processes) |
-| Peak Memory | ~64 MB |
-| Platform | Apple Silicon (ARM64) |
-| Estimated TDP | 15W |
-| Energy per Run | 0.0000750 kWh |
-| CO2 per Run (world avg 475g/kWh) | 0.038g CO2 |
-| CO2 per Test | 0.000030g CO2 |
-| Annual CI Estimate (10 runs/day) | 0.139g CO2/year |
-| Equivalent | ~0.7m of driving a car |
-
-### Efficiency Metrics
-
-| Metric | Value |
-|--------|-------|
-| Tests per Second | 89.5 |
-| Tests per Watt-second | 5.97 |
-| Zero-dep Core | No unnecessary computation |
-| Note | Higher time due to 34 separate tsx process starts; single-process would be faster |
-
-### Carbon Comparison (per full test suite run)
-
-| Framework | Time | CO2/Run | Tests/sec |
-|-----------|------|---------|-----------|
-| Python | 12.83s | 0.025g | 118.2 |
-| PHP | 8.25s | 0.017g | 152.1 |
-| Ruby | 6.86s | 0.014g | 221.0 |
-| Node.js | 18.00s | 0.038g | 89.5 |
-| **Total (6,183 tests)** | **45.94s** | **0.094g** | — |
-
----
-
-## Carbonah Rating Criteria
-
-| Criterion | Score | Notes |
-|-----------|-------|-------|
-| Test Coverage | 1,669 tests | All passing |
-| Zero Dependencies | Core has no third-party deps | stdlib only |
-| Feature Parity | 78/78 | 100% cross-framework |
-| Code Quality | Clean, DRY, separation of concerns | Enforced via CLAUDE.md |
-| Documentation | CLAUDE.md + plan docs | Up to date |
-
-**Overall Rating: A+**
-
----
-
-## How to Reproduce
-
-```bash
-cd tina4-nodejs
-npm install
-for f in test/*.ts; do npx tsx "$f"; done
-```
-
----
-
-*Generated by Tina4 v3 CI — https://tina4.com*

package/COMPARISON.md

@@ -1,206 +0,0 @@
-# Tina4 v3 — Framework Feature & Performance Report
-
-**Date:** 2026-03-21 | **Goal:** Outperform the competition on features and close the performance gap
-
----
-
-## Performance Benchmarks
-
-### Python — Tina4 vs Competition
-
-Real HTTP benchmarks — identical JSON endpoint, 5000 requests, 50 concurrent.
-
-| Framework | JSON req/s | 100-item list req/s | Server | Deps |
-|-----------|:---------:|:-------------------:|--------|:----:|
-| **Tina4 Python 3.0** | **16,233** | **5,858** | **built-in** | **0** |
-| Starlette 0.52 | 15,978 | 7,493 | uvicorn (C) | 4 |
-| FastAPI 0.115 | 11,886 | 2,464 | uvicorn (C) | 12+ |
-| Flask 3.1 | 4,767 | 1,644 | Werkzeug | 6 |
-| Django 5.2 | 3,747 | 3,305 | runserver | 20+ |
-| Bottle 0.13 | 1,251 | 676 | built-in | 0 |
-
-### PHP — Tina4 vs Competition
-
-Real HTTP benchmarks — identical JSON endpoint, 5000 requests, 50 concurrent.
-
-| Framework | JSON req/s | 100-item list req/s | Server | Deps |
-|-----------|:---------:|:-------------------:|--------|:----:|
-| **Tina4 PHP 3.0** | **27,299** | **16,555** | **built-in** | **0** |
-| Slim 4 | 5,033 | 4,520 | built-in | 10+ |
-| Symfony 7 | 1,840 | 1,702 | built-in | 30+ |
-| Laravel 11 | 370 | 364 | artisan | 50+ |
-
-### Ruby — Tina4 vs Competition
-
-Real HTTP benchmarks — identical JSON endpoint, 5000 requests, 50 concurrent.
-
-| Framework | JSON req/s | 100-item list req/s | Server | Deps |
-|-----------|:---------:|:-------------------:|--------|:----:|
-| Roda | 20,964 | 12,265 | Puma | 1 |
-| Sinatra | 9,909 | 7,229 | Puma | 5 |
-| **Tina4 Ruby 3.0** | **9,504** | **7,648** | **WEBrick** | **0** |
-| Rails 7 | 4,754 | 4,052 | Puma | 69 |
-
-### Node.js — Tina4 vs Competition
-
-Real HTTP benchmarks — identical JSON endpoint, 5000 requests, 50 concurrent.
-
-| Framework | JSON req/s | 100-item list req/s | Server | Deps |
-|-----------|:---------:|:-------------------:|--------|:----:|
-| Node.js raw http | 86,662 | 24,598 | http | 0 |
-| Fastify | 79,505 | 23,395 | http | 10+ |
-| Koa | 60,400 | 23,433 | http | 5 |
-| **Tina4 Node.js 3.0** | **57,035** | **25,088** | **http** | **0** |
-| Express 5 | 56,687 | 20,720 | http | 3 |
-
-### Production Server Results
-
-| Framework | Dev Server | Dev JSON/s | Prod Server | Prod JSON/s | Change |
-|-----------|-----------|:---------:|-------------|:---------:|:------:|
-| **Tina4 PHP** | php -S | 27,299 | php + OPcache | **27,486** | ~same |
-| **Tina4 Ruby** | WEBrick | 8,139 | Puma | **22,784** | **2.8x** |
-| **Tina4 Node.js** | http single | 57,035 | cluster (8 workers) | 12,488 | see note |
-| **Tina4 Python** | asyncio | 16,233 | uvicorn | 9,801 | see note |
-
-Note: Production servers excel under sustained high concurrency. Burst benchmarks from localhost don't show their full advantage.
-
----
-
-## Out-of-Box Feature Comparison (38 features)
-
-✅ = ships with core install, no extra packages | ❌ = requires additional install
-
-### Python Frameworks
-
-| Feature | Tina4 | Flask | FastAPI | Django | Starlette | Bottle |
-|---------|:-----:|:-----:|:-------:|:------:|:---------:|:------:|
-| **CORE WEB** | | | | | | |
-| Routing (decorators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Typed path parameters | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Middleware system | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Static file serving | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| CORS built-in | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
-| Rate limiting | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| WebSocket | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
-| **DATA** | | | | | | |
-| ORM | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| 5 database drivers | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| Migrations | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| Seeder / fake data | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Sessions | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
-| Response caching | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| **AUTH** | | | | | | |
-| JWT built-in | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Password hashing | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| CSRF protection | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| **FRONTEND** | | | | | | |
-| Template engine | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ |
-| CSS framework | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| SCSS compiler | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Frontend JS helpers | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **API** | | | | | | |
-| Swagger/OpenAPI | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
-| GraphQL | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| SOAP/WSDL | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| HTTP client | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Queue system | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **DEV EXPERIENCE** | | | | | | |
-| CLI scaffolding | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| Dev admin dashboard | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| Error overlay | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
-| Live reload | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| Auto-CRUD generator | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| Gallery / examples | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| AI assistant context | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| Inline testing | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **ARCHITECTURE** | | | | | | |
-| Zero dependencies | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
-| Dependency injection | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
-| Event system | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
-| i18n / translations | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
-| HTML builder | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
-
-### Feature Count — Python
-
-| Framework | Features | Deps | JSON req/s |
-|-----------|:-------:|:----:|:---------:|
-| **Tina4** | **38/38** | **0** | **16,233** |
-| Django | 22/38 | 20+ | 3,747 |
-| Flask | 7/38 | 6 | 4,767 |
-| FastAPI | 8/38 | 12+ | 11,886 |
-| Starlette | 6/38 | 4 | 15,978 |
-| Bottle | 5/38 | 0 | 1,251 |
-
-### Cross-Language Feature Count
-
-| Framework | Language | Features | Deps |
-|-----------|---------|:-------:|:----:|
-| **Tina4** | Python/PHP/Ruby/Node.js | **38/38** | **0** |
-| Laravel | PHP | 25/38 | 50+ |
-| Rails | Ruby | 24/38 | 40+ |
-| Django | Python | 22/38 | 20+ |
-| NestJS | Node.js | 16/38 | 20+ |
-| FastAPI | Python | 8/38 | 12+ |
-| Flask | Python | 7/38 | 6 |
-| Starlette | Python | 6/38 | 4 |
-| Bottle | Python | 5/38 | 0 |
-| Express | Node.js | 4/38 | 3 |
-| Sinatra | Ruby | 4/38 | 5 |
-
----
-
-## Tina4 Performance Roadmap
-
-### v3.0 — Achieved
-- [x] Pre-compile Frond templates (2.8x render improvement)
-- [x] Production server auto-detection (uvicorn/Puma/cluster)
-- [x] DB query caching (TINA4_DB_CACHE=true, 4x speedup)
-- [x] ORM relationships with eager loading
-
-### v3.1 — Next
-- [ ] Compiled template bytecode (match Jinja2 speed)
-- [ ] Connection pooling for database adapters
-- [ ] HTTP/2 support in built-in server
-- [ ] Response streaming for large payloads
-
-### v3.2 — Future
-- [ ] HTTP/3 (QUIC) support
-- [ ] gRPC built-in
-- [ ] Edge runtime support (Cloudflare Workers, Deno Deploy)
-
----
-
-## Deployment Size
-
-| Framework | Core Size | With Deps | Competitors |
-|-----------|:---------:|:---------:|------------|
-| Tina4 Python | ~2.4 MB | 2.4 MB (0 deps) | Django 25 MB, Flask 4.2 MB |
-| Tina4 PHP | ~1.0 MB | 1.0 MB (0 deps) | Laravel 50+ MB, Symfony 30+ MB |
-| Tina4 Ruby | ~892 KB | 892 KB (0 deps) | Rails 40+ MB, Sinatra 5 MB |
-| Tina4 Node.js | ~1.8 MB | 1.8 MB (0 deps) | Express 2 MB, NestJS 20+ MB |
-
-Zero dependencies means core size **is** deployment size. No `node_modules` bloat, no `vendor/` sprawl, no `site-packages` explosion.
-
----
-
-## Cross-Platform Support
-
-All 4 Tina4 frameworks run on:
-
-- **macOS** (Intel + Apple Silicon)
-- **Linux** (x86_64 + ARM64)
-- **Windows** (10/11)
-- **Docker** (any base image with the language runtime)
-- **WSL2**
-
-No C extensions, no native binaries, no compile step required. Pure Python/PHP/Ruby/JavaScript.
-
----
-
-## Notes
-
-- Performance numbers are from `hey` benchmarks (5000 requests, 50 concurrent) on Apple M3
-- Production server results included: `tina4 serve --production` auto-installs the best server per language
-- Tina4's competitive advantage is **features per dependency** — 38 features with 0 deps
-- Total test suite: **6,183 tests** across all 4 languages (Python 1633, PHP 1304, Ruby 1577, Node.js 1669)
-- The zero-dep philosophy means Tina4 works anywhere Python/PHP/Ruby/Node.js runs — no compiler needed, no native extensions, no build step