tina4-nodejs 3.0.0-rc.2 → 3.1.0

package/packages/core/src/server.ts

@@ -3,6 +3,8 @@ import { resolve, dirname, join, relative } from "node:path";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { isatty } from "node:tty";
 import { fileURLToPath } from "node:url";
+import cluster from "node:cluster";
+import os from "node:os";
 import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
 import { discoverRoutes } from "./routeDiscovery.js";
@@ -280,14 +282,68 @@ export async function startServer(config?: Tina4Config): Promise<{
   router: Router;
   port: number;
 }> {
+  // Load .env early so TINA4_DEBUG is available for cluster decision
+  loadEnv();
+
   const { port, host } = resolvePortAndHost(config);
-  const routesDir = resolve(config?.routesDir ?? "src/routes");
-  const modelsDir = resolve(config?.modelsDir ?? "src/models");
-  const staticDir = resolve(config?.staticDir ?? "public");
-  const templatesDir = resolve(config?.templatesDir ?? "src/templates");
 
-  // Load .env file
-  loadEnv();
+  // Cluster mode for production: fork workers based on CPU count
+  // Only when not in dev mode and running as primary process
+  if (cluster.isPrimary && !isDevMode()) {
+    const numCPUs = os.cpus().length;
+    if (numCPUs > 1) {
+      const displayHost = host === "0.0.0.0" ? "localhost" : host;
+      const isTty = isatty(1);
+      const color = isTty ? "\x1b[32m" : "";
+      const reset = isTty ? "\x1b[0m" : "";
+      const logLevel = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
+
+      console.log(`${color}
+  ______ _             __ __
+ /_  __/(_)___  ____ _/ // /
+  / /  / / __ \\/ __ \`/ // /_
+ / /  / / / / / /_/ /__  __/
+/_/  /_/_/ /_/\\__,_/  /_/
+${reset}
+  Tina4 Node.js v${TINA4_VERSION} — This is not a framework
+
+  Server:    http://${displayHost}:${port} (cluster, ${numCPUs} workers)
+  Swagger:   http://localhost:${port}/swagger
+  Dashboard: http://localhost:${port}/__dev
+  Debug:     OFF (Log level: ${logLevel})
+`);
+
+      for (let i = 0; i < numCPUs; i++) {
+        cluster.fork();
+      }
+
+      cluster.on("exit", (worker, code, _signal) => {
+        if (code !== 0) {
+          console.log(`  Worker ${worker.process.pid} exited (code ${code}), restarting...`);
+          cluster.fork();
+        }
+      });
+
+      // Return a handle that kills all workers
+      return {
+        close: () => {
+          for (const id in cluster.workers) {
+            cluster.workers[id]?.kill();
+          }
+        },
+        router: new Router(),
+        port,
+      };
+    }
+  }
+
+  const base = config?.basePath ? resolve(config.basePath) : process.cwd();
+  const routesDir = resolve(base, config?.routesDir ?? "src/routes");
+  const modelsDir = resolve(base, config?.modelsDir ?? "src/models");
+  const staticDir = resolve(base, config?.staticDir ?? "public");
+  const templatesDir = resolve(base, config?.templatesDir ?? "src/templates");
+
+  // .env already loaded above for cluster decision
 
   const router = new Router();
   const middleware = new MiddlewareChain();
@@ -581,6 +637,9 @@ export async function startServer(config?: Tina4Config): Promise<{
       const color = isTty ? "\x1b[32m" : "";
       const reset = isTty ? "\x1b[0m" : "";
 
+      // Determine server mode label
+      const serverMode = isDebug ? "single" : (cluster.isWorker ? "cluster-worker" : "single");
+
       // Banner goes to stdout via console.log — NOT through the framework logger
       console.log(`${color}
   ______ _             __ __
@@ -591,7 +650,7 @@ export async function startServer(config?: Tina4Config): Promise<{
 ${reset}
   Tina4 Node.js v${TINA4_VERSION} — This is not a framework
 
-  Server:    http://${displayHost}:${port}
+  Server:    http://${displayHost}:${port} (${serverMode})
   Swagger:   http://localhost:${port}/swagger
   Dashboard: http://localhost:${port}/__dev
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})

package/packages/core/src/types.ts

@@ -36,7 +36,8 @@ export interface Tina4ResponseMethods {
   redirect(url: string, code?: number): Tina4Response;
   cookie(name: string, value: string, options?: CookieOptions): Tina4Response;
   clearCookie(name: string, options?: CookieOptions): Tina4Response;
-  render?(template: string, data?: Record<string, unknown>): void;
+  file(path: string, options?: { download?: boolean; contentType?: string }): Tina4Response;
+  render(template: string, data?: Record<string, unknown>): Promise<Tina4Response>;
   template(name: string, data?: Record<string, unknown>): Promise<Tina4Response>;
   /** The underlying ServerResponse for advanced use */
   raw: ServerResponse;
@@ -80,6 +81,9 @@ export interface RouteMeta {
 export interface Tina4Config {
   port?: number;
   host?: string;
+  /** Base directory for the project. When set, routesDir, modelsDir, templatesDir,
+   *  and staticDir are resolved relative to this path instead of process.cwd(). */
+  basePath?: string;
   routesDir?: string;
   modelsDir?: string;
   templatesDir?: string;
@@ -96,3 +100,18 @@ export type Middleware = (
   res: Tina4Response,
   next: () => void
 ) => void | Promise<void>;
+
+/**
+ * Handler for WebSocket routes.
+ * conn — a connection-like object with send/close methods.
+ * message — the incoming text or binary message.
+ */
+export type WebSocketRouteHandler = (
+  conn: { id: string; send: (data: string) => void; close: () => void },
+  message: string | Buffer,
+) => void | Promise<void>;
+
+export interface WebSocketRouteDefinition {
+  pattern: string;
+  handler: WebSocketRouteHandler;
+}

package/packages/core/src/websocketConnection.ts

@@ -0,0 +1,16 @@
+/**
+ * Represents a WebSocket connection with send/broadcast/close capabilities.
+ * Used by Router.websocket() route handlers.
+ */
+export interface WebSocketConnection {
+  /** Unique connection identifier */
+  id: string;
+  /** Send a message to this connection */
+  send(message: string): void;
+  /** Broadcast a message to all other connections on the same path */
+  broadcast(message: string): void;
+  /** Close this connection */
+  close(): void;
+  /** The WebSocket route path this connection is on */
+  path: string;
+}

package/packages/frond/src/engine.ts

@@ -5,7 +5,7 @@
  * extends/block, include, macro, set, comments, whitespace control, tests.
  */
 import { createHash, createHmac } from "node:crypto";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 // ── Types ──────────────────────────────────────────────────────
@@ -183,6 +183,13 @@ function evalExpr(expr: string, context: Record<string, unknown>): unknown {
     }
   }
 
+  // Jinja2-style inline if: value if condition else other_value
+  const inlineIfMatch = expr.match(/^(.+?)\s+if\s+(.+?)\s+else\s+(.+)$/);
+  if (inlineIfMatch) {
+    const cond = evalExpr(inlineIfMatch[2], context);
+    return cond ? evalExpr(inlineIfMatch[1], context) : evalExpr(inlineIfMatch[3], context);
+  }
+
   // Null coalescing: value ?? "default"
   const qqIdx = expr.indexOf("??");
   if (qqIdx !== -1) {
@@ -825,6 +832,11 @@ export class Frond {
   private _allowedTags: Set<string> | null;
   private _allowedVars: Set<string> | null;
   private fragmentCache: Map<string, [string, number]>;
+  private _autoEscape: boolean;
+  /** Token pre-compilation cache for file templates */
+  private compiled = new Map<string, { tokens: Token[]; mtime: number }>();
+  /** Token pre-compilation cache for string templates */
+  private compiledStrings = new Map<string, Token[]>();
 
   constructor(templateDir: string = "src/templates") {
     this.templateDir = resolve(templateDir);
@@ -836,6 +848,7 @@ export class Frond {
     this._allowedTags = null;
     this._allowedVars = null;
     this.fragmentCache = new Map();
+    this._autoEscape = true;
 
     // Built-in global functions
     this.globals.formToken = (descriptor?: string) => _generateFormToken(descriptor || "");
@@ -872,13 +885,54 @@ export class Frond {
 
   render(template: string, data?: Record<string, unknown>): string {
     const context = { ...this.globals, ...(data || {}) };
-    const source = this.load(template);
-    return this.execute(source, context);
+    const filePath = join(this.templateDir, template);
+
+    if (!existsSync(filePath)) {
+      throw new Error(`Template not found: ${filePath}`);
+    }
+
+    const debugMode = (process.env.TINA4_DEBUG || "").toLowerCase() === "true";
+    const cached = this.compiled.get(template);
+
+    if (cached) {
+      if (debugMode) {
+        // Dev mode: check if file changed
+        const mtime = statSync(filePath).mtimeMs;
+        if (cached.mtime === mtime) {
+          return this.executeCached(cached.tokens, context);
+        }
+      } else {
+        // Production: skip mtime check, cache is permanent
+        return this.executeCached(cached.tokens, context);
+      }
+    }
+
+    // Cache miss — load, tokenize, cache
+    const source = readFileSync(filePath, "utf-8");
+    const mtime = statSync(filePath).mtimeMs;
+    const tokens = tokenize(source);
+    this.compiled.set(template, { tokens, mtime });
+    return this.executeWithSource(source, tokens, context);
   }
 
   renderString(source: string, data?: Record<string, unknown>): string {
     const context = { ...this.globals, ...(data || {}) };
-    return this.execute(source, context);
+
+    const key = createHash("md5").update(source).digest("hex");
+    const cachedTokens = this.compiledStrings.get(key);
+    if (cachedTokens) {
+      return this.executeCached(cachedTokens, context);
+    }
+
+    const tokens = tokenize(source);
+    this.compiledStrings.set(key, tokens);
+    return this.executeCached(tokens, context);
+  }
+
+  /** Clear all compiled template caches. */
+  clearCache(): void {
+    this.compiled.clear();
+    this.compiledStrings.clear();
   }
 
   private load(name: string): string {
@@ -889,6 +943,48 @@ export class Frond {
     return readFileSync(filePath, "utf-8");
   }
 
+  /** Execute pre-tokenized template against context. */
+  private executeCached(tokens: Token[], context: Record<string, unknown>): string {
+    if (Object.keys(this.tests).length > 0) {
+      context.__frond_tests__ = this.tests;
+    }
+
+    // Check if first non-text token is an extends block
+    for (const [ttype, raw] of tokens) {
+      if (ttype === "TEXT") {
+        if (raw.trim()) break;
+        continue;
+      }
+      if (ttype === "BLOCK") {
+        const [content] = stripTag(raw);
+        if (content.startsWith("extends ")) {
+          // Extends requires source-based execution for block extraction
+          const source = tokens.map(([, v]) => v).join("");
+          return this.execute(source, context);
+        }
+      }
+      break;
+    }
+    return this.renderTokens(tokens, context);
+  }
+
+  /** Execute with both source and pre-tokenized tokens available. */
+  private executeWithSource(source: string, tokens: Token[], context: Record<string, unknown>): string {
+    if (Object.keys(this.tests).length > 0) {
+      context.__frond_tests__ = this.tests;
+    }
+
+    const extendsMatch = source.match(/\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/);
+    if (extendsMatch) {
+      const parentName = extendsMatch[1];
+      const parentSource = this.load(parentName);
+      const childBlocks = this.extractBlocks(source);
+      return this.renderWithBlocks(parentSource, context, childBlocks);
+    }
+
+    return this.renderTokens(tokens, context);
+  }
+
   private execute(source: string, context: Record<string, unknown>): string {
     // Inject custom tests into context for evalTest to find
     if (Object.keys(this.tests).length > 0) {
@@ -1015,6 +1111,14 @@ export class Frond {
           const [result, skip] = this.handleCache(tokens, i, context);
           output.push(result);
           i = skip;
+        } else if (tag === "spaceless") {
+          const [result, skip] = this.handleSpaceless(tokens, i, context);
+          output.push(result);
+          i = skip;
+        } else if (tag === "autoescape") {
+          const [result, skip] = this.handleAutoescape(tokens, i, context);
+          output.push(result);
+          i = skip;
         } else if (tag === "block" || tag === "endblock" || tag === "extends") {
           i++; // Already handled
         } else {
@@ -1092,8 +1196,8 @@ export class Frond {
       return value.value;
     }
 
-    // Auto-escape HTML unless marked safe
-    if (!isSafe && typeof value === "string") {
+    // Auto-escape HTML unless marked safe or auto-escape is disabled
+    if (!isSafe && this._autoEscape && typeof value === "string") {
       value = htmlEscape(value);
     }
 
@@ -1472,4 +1576,78 @@ export class Frond {
     this.fragmentCache.set(cacheKey, [rendered, Date.now() + ttl * 1000]);
     return [rendered, i];
   }
+
+  private handleSpaceless(tokens: Token[], start: number, context: Record<string, unknown>): [string, number] {
+    const bodyTokens: Token[] = [];
+    let i = start + 1;
+    let depth = 0;
+    while (i < tokens.length) {
+      if (tokens[i][0] === "BLOCK") {
+        const [tagContent] = stripTag(tokens[i][1]);
+        const tag = tagContent.split(/\s+/)[0] || "";
+        if (tag === "spaceless") {
+          depth++;
+          bodyTokens.push(tokens[i]);
+        } else if (tag === "endspaceless") {
+          if (depth === 0) {
+            i++;
+            break;
+          }
+          depth--;
+          bodyTokens.push(tokens[i]);
+        } else {
+          bodyTokens.push(tokens[i]);
+        }
+      } else {
+        bodyTokens.push(tokens[i]);
+      }
+      i++;
+    }
+
+    let rendered = this.renderTokens([...bodyTokens], context);
+    rendered = rendered.replace(/>\s+</g, "><");
+    return [rendered, i];
+  }
+
+  private handleAutoescape(tokens: Token[], start: number, context: Record<string, unknown>): [string, number] {
+    const [content] = stripTag(tokens[start][1]);
+    const modeMatch = content.match(/^autoescape\s+(false|true)/);
+    const autoEscapeOn = !(modeMatch && modeMatch[1] === "false");
+
+    const bodyTokens: Token[] = [];
+    let i = start + 1;
+    let depth = 0;
+    while (i < tokens.length) {
+      if (tokens[i][0] === "BLOCK") {
+        const [tagContent] = stripTag(tokens[i][1]);
+        const tag = tagContent.split(/\s+/)[0] || "";
+        if (tag === "autoescape") {
+          depth++;
+          bodyTokens.push(tokens[i]);
+        } else if (tag === "endautoescape") {
+          if (depth === 0) {
+            i++;
+            break;
+          }
+          depth--;
+          bodyTokens.push(tokens[i]);
+        } else {
+          bodyTokens.push(tokens[i]);
+        }
+      } else {
+        bodyTokens.push(tokens[i]);
+      }
+      i++;
+    }
+
+    if (!autoEscapeOn) {
+      const oldAutoEscape = this._autoEscape;
+      this._autoEscape = false;
+      const rendered = this.renderTokens([...bodyTokens], context);
+      this._autoEscape = oldAutoEscape;
+      return [rendered, i];
+    }
+
+    return [this.renderTokens([...bodyTokens], context), i];
+  }
 }