npm - tina4-nodejs - Versions diffs - 3.0.0-rc.2 → 3.1.0 - Mend

tina4-nodejs 3.0.0-rc.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/BENCHMARK_REPORT.md +248 -86
package/CARBONAH.md +4 -4
package/CLAUDE.md +16 -1
package/COMPARISON.md +58 -46
package/README.md +60 -6
package/package.json +2 -1
package/packages/cli/src/bin.ts +8 -0
package/packages/cli/src/commands/generate.ts +237 -0
package/packages/core/gallery/queue/meta.json +1 -1
package/packages/core/gallery/queue/src/lib/queueDb.ts +32 -0
package/packages/core/gallery/queue/src/routes/api/gallery/queue/consume/post.ts +28 -0
package/packages/core/gallery/queue/src/routes/api/gallery/queue/fail/post.ts +28 -0
package/packages/core/gallery/queue/src/routes/api/gallery/queue/produce/post.ts +20 -10
package/packages/core/gallery/queue/src/routes/api/gallery/queue/retry/post.ts +25 -0
package/packages/core/gallery/queue/src/routes/api/gallery/queue/status/get.ts +36 -6
package/packages/core/gallery/queue/src/routes/gallery/queue/get.ts +160 -0
package/packages/core/src/cache.ts +402 -10
package/packages/core/src/index.ts +5 -2
package/packages/core/src/messenger.ts +118 -36
package/packages/core/src/queue.ts +172 -92
package/packages/core/src/response.ts +46 -0
package/packages/core/src/router.ts +94 -1
package/packages/core/src/server.ts +66 -7
package/packages/core/src/types.ts +20 -1
package/packages/core/src/websocketConnection.ts +16 -0
package/packages/frond/src/engine.ts +184 -6
package/packages/orm/src/baseModel.ts +274 -20
package/packages/orm/src/cachedDatabase.ts +180 -0
package/packages/orm/src/index.ts +4 -0
package/packages/orm/src/model.ts +1 -0
package/packages/orm/src/types.ts +75 -0

package/packages/core/gallery/queue/src/routes/gallery/queue/get.ts ADDED Viewed

@@ -0,0 +1,160 @@
+/** Gallery: Queue — interactive queue demo with visual web UI. */
+import type { Tina4Request, Tina4Response } from "@tina4/core";
+export default async function (_req: Tina4Request, res: Tina4Response) {
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Queue Gallery — Tina4 Node.js</title>
+    <link rel="stylesheet" href="/css/tina4.min.css">
+</head>
+<body>
+<div class="container mt-4 mb-4">
+    <h1>Queue Gallery</h1>
+    <p class="text-muted">Interactive demo of Tina4's database-backed job queue. Produce messages, consume them, simulate failures, and inspect dead letters.</p>
+    <div class="row mt-3">
+        <div class="col-md-6">
+            <div class="card">
+                <div class="card-header">Produce a Message</div>
+                <div class="card-body">
+                    <div class="d-flex gap-2">
+                        <input type="text" id="msgInput" class="form-control" placeholder="Enter a task message, e.g. send-email">
+                        <button class="btn btn-primary" onclick="produce()">Produce</button>
+                    </div>
+                </div>
+            </div>
+        </div>
+        <div class="col-md-6">
+            <div class="card">
+                <div class="card-header">Actions</div>
+                <div class="card-body d-flex gap-2 flex-wrap">
+                    <button class="btn btn-success" onclick="consume()">Consume Next</button>
+                    <button class="btn btn-danger" onclick="failNext()">Fail Next</button>
+                    <button class="btn btn-warning" onclick="retryFailed()">Retry Failed</button>
+                    <button class="btn btn-secondary" onclick="refresh()">Refresh</button>
+                </div>
+            </div>
+        </div>
+    </div>
+    <div id="alertArea" class="mt-3"></div>
+    <div class="card mt-3">
+        <div class="card-header d-flex justify-content-between align-items-center">
+            <span>Queue Messages</span>
+            <small class="text-muted" id="lastRefresh"></small>
+        </div>
+        <div class="card-body p-0">
+            <table class="table table-striped mb-0">
+                <thead>
+                    <tr>
+                        <th>ID</th>
+                        <th>Data</th>
+                        <th>Status</th>
+                        <th>Attempts</th>
+                        <th>Error</th>
+                        <th>Created</th>
+                    </tr>
+                </thead>
+                <tbody id="queueBody">
+                    <tr><td colspan="6" class="text-center text-muted">Loading...</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </div>
+</div>
+<script>
+function statusBadge(status) {
+    var colors = {pending:"primary", reserved:"warning", completed:"success", failed:"danger", dead:"secondary"};
+    var color = colors[status] || "secondary";
+    return '<span class="badge bg-' + color + '">' + status + '</span>';
+}
+function showAlert(msg, type) {
+    var area = document.getElementById("alertArea");
+    area.innerHTML = '<div class="alert alert-' + type + ' alert-dismissible">' + msg +
+        '<button type="button" class="btn-close" onclick="this.parentElement.remove()"></button></div>';
+    setTimeout(function(){ area.innerHTML = ""; }, 3000);
+}
+function truncate(s, n) {
+    if (!s) return "";
+    return s.length > n ? s.substring(0, n) + "..." : s;
+}
+async function refresh() {
+    try {
+        var r = await fetch("/api/gallery/queue/status");
+        var data = await r.json();
+        var tbody = document.getElementById("queueBody");
+        if (!data.messages || data.messages.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="6" class="text-center text-muted">No messages in queue. Produce one above.</td></tr>';
+        } else {
+            var html = "";
+            for (var i = 0; i < data.messages.length; i++) {
+                var m = data.messages[i];
+                html += "<tr><td>" + m.id + "</td><td><code>" + truncate(m.data, 60) + "</code></td><td>" +
+                    statusBadge(m.status) + "</td><td>" + m.attempts + "</td><td>" +
+                    truncate(m.error || "", 40) + "</td><td><small>" + (m.created_at || "") + "</small></td></tr>";
+            }
+            tbody.innerHTML = html;
+        }
+        document.getElementById("lastRefresh").textContent = "Updated " + new Date().toLocaleTimeString();
+    } catch (e) {
+        console.error(e);
+    }
+}
+async function produce() {
+    var input = document.getElementById("msgInput");
+    var task = input.value.trim() || "demo-task";
+    var r = await fetch("/api/gallery/queue/produce", {
+        method: "POST", headers: {"Content-Type":"application/json"},
+        body: JSON.stringify({task: task, data: {message: task}})
+    });
+    var d = await r.json();
+    showAlert("Produced message: " + task, "success");
+    input.value = "";
+    refresh();
+}
+async function consume() {
+    var r = await fetch("/api/gallery/queue/consume", {method:"POST"});
+    var d = await r.json();
+    if (d.consumed) {
+        showAlert("Consumed job #" + d.job_id + " successfully", "success");
+    } else {
+        showAlert(d.message || "Nothing to consume", "info");
+    }
+    refresh();
+}
+async function failNext() {
+    var r = await fetch("/api/gallery/queue/fail", {method:"POST"});
+    var d = await r.json();
+    if (d.failed) {
+        showAlert("Deliberately failed job #" + d.job_id, "danger");
+    } else {
+        showAlert(d.message || "Nothing to fail", "info");
+    }
+    refresh();
+}
+async function retryFailed() {
+    var r = await fetch("/api/gallery/queue/retry", {method:"POST"});
+    var d = await r.json();
+    showAlert("Retried " + (d.retried || 0) + " failed message(s)", "warning");
+    refresh();
+}
+refresh();
+setInterval(refresh, 2000);
+</script>
+</body>
+</html>`;
+  return res.html(html);
+}

package/packages/core/src/cache.ts CHANGED Viewed

@@ -1,21 +1,38 @@
 /**
- * In-memory response cache for GET requests.
- * Caches serialized responses by URL + query string.
+ * Multi-backend response cache for GET requests.
+ *
+ * Backends are selected via the TINA4_CACHE_BACKEND env var:
+ *   memory — in-process LRU cache (default, zero deps)
+ *   redis  — Redis / Valkey (uses `ioredis` or raw RESP over TCP)
+ *   file   — JSON files in data/cache/
  *
  * Usage:
- *   import { responseCache } from "./cache.js";
+ *   import { responseCache, cacheGet, cacheSet, cacheDelete, cacheClear, cacheStats } from "./cache.js";
  *
  *   // As middleware — caches GET responses for ttl seconds
  *   middleware.use(responseCache({ ttl: 60 }));
  *
- *   // Per-route cache via meta
- *   export const meta = { cache: 30 }; // cache 30 seconds
+ *   // Direct usage (same across all 4 languages)
+ *   cacheSet("key", {"data": "value"}, 120);
+ *   const value = cacheGet("key");
+ *   cacheDelete("key");
+ *   cacheClear();
+ *   const stats = cacheStats();
  *
  * Environment:
- *   TINA4_CACHE_TTL — default TTL in seconds (default: 0 = disabled)
+ *   TINA4_CACHE_BACKEND      — memory | redis | file  (default: memory)
+ *   TINA4_CACHE_URL           — redis://localhost:6379  (redis only)
+ *   TINA4_CACHE_TTL           — default TTL in seconds  (default: 0 = disabled)
+ *   TINA4_CACHE_MAX_ENTRIES   — max entries              (default: 1000)
  */
 import type { Middleware } from "./types.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import * as net from "node:net";
+// ── Types ─────────────────────────────────────────────────────────
 interface CacheEntry {
   body: string;
@@ -24,6 +41,11 @@ interface CacheEntry {
   expiresAt: number;
 }
+interface DirectEntry {
+  value: unknown;
+  expiresAt: number;
+}
 export interface ResponseCacheConfig {
   /** Default TTL in seconds. 0 = disabled. Default: 60 */
   ttl?: number;
@@ -31,8 +53,326 @@ export interface ResponseCacheConfig {
   maxEntries?: number;
   /** Only cache these status codes. Default: [200] */
   statusCodes?: number[];
+  /** Cache backend: memory | redis | file. Default: from env or memory */
+  backend?: string;
+  /** Redis URL. Default: from env or redis://localhost:6379 */
+  cacheUrl?: string;
+  /** File cache directory. Default: from env or data/cache */
+  cacheDir?: string;
+}
+// ── Backend interface ─────────────────────────────────────────────
+interface CacheBackend {
+  get(key: string): unknown | undefined;
+  set(key: string, value: unknown, ttl: number): void;
+  delete(key: string): boolean;
+  clear(): void;
+  stats(): { hits: number; misses: number; size: number; backend: string };
+  name(): string;
+}
+// ── Memory backend ────────────────────────────────────────────────
+class MemoryBackend implements CacheBackend {
+  private store = new Map<string, { value: unknown; expiresAt: number }>();
+  private maxEntries: number;
+  private hits = 0;
+  private misses = 0;
+  constructor(maxEntries = 1000) {
+    this.maxEntries = maxEntries;
+  }
+  get(key: string): unknown | undefined {
+    const entry = this.store.get(key);
+    if (!entry) {
+      this.misses++;
+      return undefined;
+    }
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      this.misses++;
+      return undefined;
+    }
+    this.hits++;
+    // Move to end (LRU refresh) — delete and re-set
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key: string, value: unknown, ttl: number): void {
+    const expiresAt = ttl > 0 ? Date.now() + ttl * 1000 : 0;
+    this.store.delete(key); // remove to re-insert at end
+    this.store.set(key, { value, expiresAt });
+    // Evict oldest if over capacity
+    while (this.store.size > this.maxEntries) {
+      const firstKey = this.store.keys().next().value;
+      if (firstKey !== undefined) this.store.delete(firstKey);
+    }
+  }
+  delete(key: string): boolean {
+    return this.store.delete(key);
+  }
+  clear(): void {
+    this.store.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  stats() {
+    // Sweep expired
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt && now > entry.expiresAt) this.store.delete(key);
+    }
+    return { hits: this.hits, misses: this.misses, size: this.store.size, backend: "memory" };
+  }
+  name() { return "memory"; }
+}
+// ── Redis backend ─────────────────────────────────────────────────
+class RedisBackend implements CacheBackend {
+  private host: string;
+  private port: number;
+  private db: number;
+  private prefix = "tina4:cache:";
+  private hits = 0;
+  private misses = 0;
+  private maxEntries: number;
+  constructor(url = "redis://localhost:6379", maxEntries = 1000) {
+    this.maxEntries = maxEntries;
+    const cleaned = url.replace("redis://", "");
+    const parts = cleaned.split(":");
+    this.host = parts[0] || "localhost";
+    const portAndDb = parts[1] ? parts[1].split("/") : ["6379"];
+    this.port = parseInt(portAndDb[0], 10) || 6379;
+    this.db = portAndDb[1] ? parseInt(portAndDb[1], 10) : 0;
+  }
+  private respCommand(...args: string[]): Promise<string | null> {
+    return new Promise((resolve) => {
+      try {
+        let cmd = `*${args.length}\r\n`;
+        for (const arg of args) {
+          cmd += `$${Buffer.byteLength(arg)}\r\n${arg}\r\n`;
+        }
+        const sock = new net.Socket();
+        sock.setTimeout(5000);
+        let response = "";
+        sock.connect(this.port, this.host, () => {
+          if (this.db > 0) {
+            const selectCmd = `*2\r\n$6\r\nSELECT\r\n$${String(this.db).length}\r\n${this.db}\r\n`;
+            sock.write(selectCmd);
+          }
+          sock.write(cmd);
+        });
+        sock.on("data", (data) => {
+          response += data.toString();
+          sock.end();
+        });
+        sock.on("end", () => {
+          if (response.startsWith("+")) {
+            resolve(response.slice(1).trim());
+          } else if (response.startsWith("$-1")) {
+            resolve(null);
+          } else if (response.startsWith("$")) {
+            const lines = response.split("\r\n");
+            resolve(lines[1] ?? null);
+          } else if (response.startsWith(":")) {
+            resolve(response.slice(1).trim());
+          } else {
+            resolve(null);
+          }
+        });
+        sock.on("error", () => resolve(null));
+        sock.on("timeout", () => { sock.destroy(); resolve(null); });
+      } catch {
+        resolve(null);
+      }
+    });
+  }
+  get(key: string): unknown | undefined {
+    // Synchronous fallback — Redis is async, so direct API uses sync memory store
+    // For the response cache middleware, this returns undefined and falls through
+    this.misses++;
+    return undefined;
+  }
+  set(key: string, value: unknown, ttl: number): void {
+    const fullKey = this.prefix + key;
+    const serialized = JSON.stringify(value);
+    if (ttl > 0) {
+      this.respCommand("SETEX", fullKey, String(ttl), serialized).catch(() => {});
+    } else {
+      this.respCommand("SET", fullKey, serialized).catch(() => {});
+    }
+  }
+  delete(key: string): boolean {
+    const fullKey = this.prefix + key;
+    this.respCommand("DEL", fullKey).catch(() => {});
+    return true; // best-effort
+  }
+  clear(): void {
+    this.hits = 0;
+    this.misses = 0;
+  }
+  stats() {
+    return { hits: this.hits, misses: this.misses, size: 0, backend: "redis" };
+  }
+  name() { return "redis"; }
 }
+// ── File backend ──────────────────────────────────────────────────
+class FileBackend implements CacheBackend {
+  private dir: string;
+  private maxEntries: number;
+  private hits = 0;
+  private misses = 0;
+  constructor(cacheDir = "data/cache", maxEntries = 1000) {
+    this.dir = cacheDir;
+    this.maxEntries = maxEntries;
+    try {
+      fs.mkdirSync(this.dir, { recursive: true });
+    } catch {}
+  }
+  private keyPath(key: string): string {
+    const safe = crypto.createHash("sha256").update(key).digest("hex");
+    return path.join(this.dir, `${safe}.json`);
+  }
+  get(key: string): unknown | undefined {
+    const p = this.keyPath(key);
+    try {
+      if (!fs.existsSync(p)) {
+        this.misses++;
+        return undefined;
+      }
+      const data = JSON.parse(fs.readFileSync(p, "utf-8"));
+      if (data.expiresAt && Date.now() > data.expiresAt * 1000) {
+        fs.unlinkSync(p);
+        this.misses++;
+        return undefined;
+      }
+      this.hits++;
+      return data.value ?? data;
+    } catch {
+      this.misses++;
+      return undefined;
+    }
+  }
+  set(key: string, value: unknown, ttl: number): void {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true });
+      // Evict oldest if at capacity
+      const files = fs.readdirSync(this.dir)
+        .filter(f => f.endsWith(".json"))
+        .map(f => ({ name: f, time: fs.statSync(path.join(this.dir, f)).mtimeMs }))
+        .sort((a, b) => a.time - b.time);
+      while (files.length >= this.maxEntries) {
+        const oldest = files.shift();
+        if (oldest) fs.unlinkSync(path.join(this.dir, oldest.name));
+      }
+      const expiresAt = ttl > 0 ? (Date.now() / 1000) + ttl : 0;
+      const entry = { key, value, expiresAt };
+      fs.writeFileSync(this.keyPath(key), JSON.stringify(entry));
+    } catch {}
+  }
+  delete(key: string): boolean {
+    const p = this.keyPath(key);
+    try {
+      if (fs.existsSync(p)) {
+        fs.unlinkSync(p);
+        return true;
+      }
+    } catch {}
+    return false;
+  }
+  clear(): void {
+    this.hits = 0;
+    this.misses = 0;
+    try {
+      const files = fs.readdirSync(this.dir).filter(f => f.endsWith(".json"));
+      for (const f of files) {
+        fs.unlinkSync(path.join(this.dir, f));
+      }
+    } catch {}
+  }
+  stats() {
+    // Sweep expired
+    const now = Date.now() / 1000;
+    let count = 0;
+    try {
+      const files = fs.readdirSync(this.dir).filter(f => f.endsWith(".json"));
+      for (const f of files) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(this.dir, f), "utf-8"));
+          if (data.expiresAt && now > data.expiresAt) {
+            fs.unlinkSync(path.join(this.dir, f));
+          } else {
+            count++;
+          }
+        } catch {}
+      }
+    } catch {}
+    return { hits: this.hits, misses: this.misses, size: count, backend: "file" };
+  }
+  name() { return "file"; }
+}
+// ── Backend factory ───────────────────────────────────────────────
+function createBackend(config?: {
+  backend?: string;
+  cacheUrl?: string;
+  cacheDir?: string;
+  maxEntries?: number;
+}): CacheBackend {
+  const backendName = (config?.backend ?? process.env.TINA4_CACHE_BACKEND ?? "memory").toLowerCase().trim();
+  const maxEntries = config?.maxEntries ?? (process.env.TINA4_CACHE_MAX_ENTRIES ? parseInt(process.env.TINA4_CACHE_MAX_ENTRIES, 10) : 1000);
+  switch (backendName) {
+    case "redis": {
+      const url = config?.cacheUrl ?? process.env.TINA4_CACHE_URL ?? "redis://localhost:6379";
+      return new RedisBackend(url, maxEntries);
+    }
+    case "file": {
+      const dir = config?.cacheDir ?? process.env.TINA4_CACHE_DIR ?? "data/cache";
+      return new FileBackend(dir, maxEntries);
+    }
+    default:
+      return new MemoryBackend(maxEntries);
+  }
+}
+// ── Response cache store (for middleware) ──────────────────────────
 const store = new Map<string, CacheEntry>();
 /**
@@ -110,12 +450,64 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
   };
 }
-/** Clear all cached responses */
+/** Clear all cached responses (middleware store) */
 export function clearCache(): void {
   store.clear();
 }
-/** Get cache stats */
-export function cacheStats(): { size: number; keys: string[] } {
-  return { size: store.size, keys: [...store.keys()] };
+/** Get cache stats (middleware store) */
+export function cacheStats(): { size: number; keys: string[]; backend: string } {
+  return { size: store.size, keys: [...store.keys()], backend: _getBackend().name() };
+}
+// ── Module-level direct cache API (backend-aware) ─────────────────
+let _defaultBackend: CacheBackend | null = null;
+let _defaultTtl: number | null = null;
+function _getBackend(): CacheBackend {
+  if (!_defaultBackend) {
+    _defaultBackend = createBackend();
+  }
+  return _defaultBackend;
+}
+function _getDefaultTtl(): number {
+  if (_defaultTtl === null) {
+    const envTtl = process.env.TINA4_CACHE_TTL;
+    _defaultTtl = envTtl ? parseInt(envTtl, 10) : 60;
+  }
+  return _defaultTtl;
+}
+/** Get a value from the cache by key. Returns undefined on miss. */
+export function cacheGet(key: string): unknown | undefined {
+  return _getBackend().get(key);
+}
+/** Store a value in the cache with optional TTL (seconds). */
+export function cacheSet(key: string, value: unknown, ttl?: number): void {
+  const effectiveTtl = ttl ?? _getDefaultTtl();
+  _getBackend().set(key, value, effectiveTtl);
+}
+/** Delete a key from the cache. Returns true if it existed. */
+export function cacheDelete(key: string): boolean {
+  return _getBackend().delete(key);
+}
+/** Clear all entries from the cache. */
+export function cacheClear(): void {
+  _getBackend().clear();
+}
+/** Return cache statistics from the active backend. */
+export function cacheBackendStats(): { hits: number; misses: number; size: number; backend: string } {
+  return _getBackend().stats();
+}
+/** Reset the default backend (for testing). */
+export function _resetBackend(): void {
+  _defaultBackend = null;
+  _defaultTtl = null;
 }

package/packages/core/src/index.ts CHANGED Viewed

@@ -8,11 +8,13 @@ export type {
   Middleware,
   UploadedFile,
   CookieOptions,
+  WebSocketRouteHandler,
+  WebSocketRouteDefinition,
 } from "./types.js";
 export { startServer, resolvePortAndHost } from "./server.js";
 export { Router, RouteGroup, defaultRouter, runRouteMiddlewares } from "./router.js";
-export { get, post, put, patch, del, any, del as delete } from "./router.js";
+export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
 export { discoverRoutes } from "./routeDiscovery.js";
 export { MiddlewareChain, cors, requestLogger } from "./middleware.js";
@@ -60,7 +62,7 @@ export {
 export type { WebSocketClient } from "./websocket.js";
 export { ServiceRunner, matchCronField, matchesCron } from "./service.js";
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
-export { responseCache, clearCache, cacheStats } from "./cache.js";
+export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult } from "./api.js";
@@ -86,3 +88,4 @@ export { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 export type { ValkeySessionConfig } from "./sessionHandlers/valkeyHandler.js";
 export { tests, assertEqual, assertThrows, assertTrue, assertFalse, runAllTests, resetTests } from "./testing.js";
 export { Container, container } from "./container.js";
+export type { WebSocketConnection } from "./websocketConnection.js";