tina4-nodejs 3.2.1 → 3.5.0

package/packages/core/src/session.ts

@@ -2,6 +2,7 @@
  * Tina4 Session — Pluggable session backends, zero core dependencies.
  *
  * File-based sessions by default. Redis backend available via raw TCP (no ioredis needed).
+ * Database (SQLite) backend available via better-sqlite3.
  *
  *   import { Session, RedisSessionHandler } from "@tina4/core";
  *
@@ -14,6 +15,10 @@
  *     redisPort: 6379,
  *   });
  *
+ *   // Database backend (SQLite via better-sqlite3)
+ *   const session = new Session("database");
+ *   // or: new Session("db");
+ *
  *   const id = session.start();
  *   session.set("user", { name: "Alice" });
  *   session.get("user");  // { name: "Alice" }
@@ -27,7 +32,7 @@ import { execFileSync } from "node:child_process";
 // ── Types ─────────────────────────────────────────────────────────
 
 export interface SessionConfig {
-  /** Session backend type: "file" or "redis" */
+  /** Session backend type: "file", "redis", "valkey", "mongo", "database" (or "db") */
   backend?: string;
   /** File storage path (default: "data/sessions") */
   path?: string;
@@ -297,6 +302,11 @@ export class Session {
       case "redis":
         this.handler = new RedisSessionHandler(config);
         break;
+      case "redis-npm": {
+        const { RedisNpmSessionHandler } = require("./sessionHandlers/redisHandler.js");
+        this.handler = new RedisNpmSessionHandler(config);
+        break;
+      }
       case "valkey": {
         const { ValkeySessionHandler } = require("./sessionHandlers/valkeyHandler.js");
         this.handler = new ValkeySessionHandler(config);
@@ -308,6 +318,12 @@ export class Session {
         this.handler = new MongoSessionHandler(config);
         break;
       }
+      case "database":
+      case "db": {
+        const { DatabaseSessionHandler } = require("./sessionHandlers/databaseHandler.js");
+        this.handler = new DatabaseSessionHandler(config);
+        break;
+      }
       case "file":
       default:
         this.handler = new FileSessionHandler(config?.path);
@@ -382,6 +398,18 @@ export class Session {
     this.save();
   }
 
+  /**
+   * Clear all session data without destroying the session.
+   * The session ID and cookie remain — only the data is wiped.
+   */
+  clear(): void {
+    if (!this.data) return;
+    for (const key of Object.keys(this.data)) {
+      delete this.data[key];
+    }
+    this.save();
+  }
+
   /**
    * Destroy the entire session.
    */

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -0,0 +1,134 @@
+/**
+ * Tina4 Database Session Handler — SQLite via better-sqlite3, zero extra dependencies.
+ *
+ * Uses the same `better-sqlite3` library the ORM already depends on.
+ * Stores sessions in a `tina4_session` table with JSON data and expiry.
+ *
+ * Configure via environment variables:
+ *   DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
+ *
+ * The handler dynamically imports `better-sqlite3` and throws a clear
+ * error if the package is not installed.
+ */
+import { createRequire } from "node:module";
+import type { SessionHandler } from "../session.js";
+
+const _require = createRequire(import.meta.url);
+
+interface SessionData {
+  _created: number;
+  _accessed: number;
+  [key: string]: unknown;
+}
+
+export interface DatabaseSessionConfig {
+  /** SQLite database file path (default: extracted from DATABASE_URL or "data/tina4_sessions.db") */
+  dbPath?: string;
+}
+
+/**
+ * Database session handler using better-sqlite3 (synchronous SQLite).
+ *
+ * Stores session data as JSON in a `tina4_session` table.
+ * Expiry is checked on read; expired rows are cleaned up lazily.
+ */
+export class DatabaseSessionHandler implements SessionHandler {
+  private db: any;
+  private initialized = false;
+
+  constructor(config?: DatabaseSessionConfig) {
+    const dbPath = config?.dbPath ?? this.resolveDbPath();
+
+    let Database: any;
+    try {
+      Database = _require("better-sqlite3");
+    } catch {
+      throw new Error(
+        "DatabaseSessionHandler requires 'better-sqlite3'. " +
+        "Install it with: npm install better-sqlite3"
+      );
+    }
+
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+  }
+
+  /**
+   * Resolve the database file path from DATABASE_URL or use the default.
+   */
+  private resolveDbPath(): string {
+    const url = process.env.DATABASE_URL;
+    if (url && url.startsWith("sqlite://")) {
+      // sqlite:///path/to/db  or  sqlite://./relative/path
+      return url.replace(/^sqlite:\/\//, "");
+    }
+    return "data/tina4_sessions.db";
+  }
+
+  /**
+   * Ensure the session table exists (called once on first use).
+   */
+  private ensureTable(): void {
+    if (this.initialized) return;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS tina4_session (
+          session_id TEXT PRIMARY KEY,
+          data TEXT NOT NULL,
+          expires_at REAL NOT NULL
+      )
+    `);
+    this.initialized = true;
+  }
+
+  read(sessionId: string): SessionData | null {
+    this.ensureTable();
+
+    const row = this.db
+      .prepare("SELECT data, expires_at FROM tina4_session WHERE session_id = ?")
+      .get(sessionId) as { data: string; expires_at: number } | undefined;
+
+    if (!row) return null;
+
+    // Check expiry
+    const now = Date.now() / 1000;
+    if (row.expires_at < now) {
+      // Expired — clean up and return null
+      this.destroy(sessionId);
+      return null;
+    }
+
+    try {
+      return JSON.parse(row.data) as SessionData;
+    } catch {
+      return null;
+    }
+  }
+
+  write(sessionId: string, data: SessionData, ttl: number): void {
+    this.ensureTable();
+
+    const json = JSON.stringify(data);
+    const expiresAt = (Date.now() / 1000) + (ttl > 0 ? ttl : 3600);
+
+    const existing = this.db
+      .prepare("SELECT 1 FROM tina4_session WHERE session_id = ?")
+      .get(sessionId);
+
+    if (existing) {
+      this.db
+        .prepare("UPDATE tina4_session SET data = ?, expires_at = ? WHERE session_id = ?")
+        .run(json, expiresAt, sessionId);
+    } else {
+      this.db
+        .prepare("INSERT INTO tina4_session (session_id, data, expires_at) VALUES (?, ?, ?)")
+        .run(sessionId, json, expiresAt);
+    }
+  }
+
+  destroy(sessionId: string): void {
+    this.ensureTable();
+    this.db
+      .prepare("DELETE FROM tina4_session WHERE session_id = ?")
+      .run(sessionId);
+  }
+}

package/packages/core/src/sessionHandlers/redisHandler.ts

@@ -0,0 +1,230 @@
+/**
+ * Tina4 Redis Session Handler — Redis via `redis` npm package (optional dependency).
+ *
+ * Provides a session handler backed by the official `redis` npm package,
+ * complementing the built-in raw-TCP RedisSessionHandler in session.ts.
+ *
+ * This handler uses synchronous child-process execution (same pattern as
+ * valkeyHandler.ts) so it fits the synchronous SessionHandler interface
+ * without requiring async refactoring.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_REDIS_HOST     (default: "127.0.0.1")
+ *   TINA4_SESSION_REDIS_PORT     (default: 6379)
+ *   TINA4_SESSION_REDIS_URL      (optional — full redis:// URL, overrides host/port)
+ *   TINA4_SESSION_REDIS_PASSWORD  (optional)
+ *   TINA4_SESSION_REDIS_PREFIX   (default: "tina4:session:")
+ *   TINA4_SESSION_REDIS_DB       (default: 0)
+ */
+import { execFileSync } from "node:child_process";
+import type { SessionHandler } from "../session.js";
+
+interface SessionData {
+  _created: number;
+  _accessed: number;
+  [key: string]: unknown;
+}
+
+export interface RedisNpmSessionConfig {
+  host?: string;
+  port?: number;
+  url?: string;
+  password?: string;
+  prefix?: string;
+  db?: number;
+}
+
+/**
+ * Redis session handler using the `redis` npm package.
+ *
+ * Falls back to raw TCP (RESP protocol) if the `redis` package is not
+ * installed, matching the approach used by the Valkey handler.
+ *
+ * Stores session data as JSON strings with Redis TTL for automatic expiry.
+ */
+export class RedisNpmSessionHandler implements SessionHandler {
+  private host: string;
+  private port: number;
+  private url: string;
+  private password: string;
+  private prefix: string;
+  private db: number;
+
+  constructor(config?: RedisNpmSessionConfig) {
+    this.url = config?.url
+      ?? process.env.TINA4_SESSION_REDIS_URL
+      ?? "";
+    this.host = config?.host
+      ?? process.env.TINA4_SESSION_REDIS_HOST
+      ?? "127.0.0.1";
+    this.port = config?.port
+      ?? (process.env.TINA4_SESSION_REDIS_PORT
+        ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
+        : 6379);
+    this.password = config?.password
+      ?? process.env.TINA4_SESSION_REDIS_PASSWORD
+      ?? "";
+    this.prefix = config?.prefix
+      ?? process.env.TINA4_SESSION_REDIS_PREFIX
+      ?? "tina4:session:";
+    this.db = config?.db
+      ?? (process.env.TINA4_SESSION_REDIS_DB
+        ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
+        : 0);
+  }
+
+  /**
+   * Execute a Redis command synchronously via a short-lived child process.
+   *
+   * Attempts to use the `redis` npm package first. If unavailable, falls
+   * back to raw TCP (RESP protocol) — same as valkeyHandler.ts.
+   */
+  private execSync(args: string[]): string {
+    const script = `
+      const net = require("node:net");
+      const host = ${JSON.stringify(this.url || this.host)};
+      const port = ${this.port};
+      const password = ${JSON.stringify(this.password)};
+      const db = ${this.db};
+      const useUrl = ${JSON.stringify(!!this.url)};
+      const url = ${JSON.stringify(this.url)};
+      const args = ${JSON.stringify(args)};
+
+      // Try the redis npm package first
+      let redisAvailable = false;
+      try {
+        require.resolve("redis");
+        redisAvailable = true;
+      } catch {}
+
+      if (redisAvailable) {
+        const redis = require("redis");
+        (async () => {
+          try {
+            const clientOpts = useUrl
+              ? { url }
+              : { socket: { host, port }, password: password || undefined, database: db };
+            const client = redis.createClient(clientOpts);
+            client.on("error", () => {});
+            await client.connect();
+
+            const cmd = args[0].toUpperCase();
+            let result;
+            if (cmd === "GET") {
+              result = await client.get(args[1]);
+            } else if (cmd === "SET") {
+              result = await client.set(args[1], args[2]);
+            } else if (cmd === "SETEX") {
+              result = await client.setEx(args[1], parseInt(args[2], 10), args[3]);
+            } else if (cmd === "DEL") {
+              result = await client.del(args[1]);
+            }
+            await client.quit();
+
+            if (result === null || result === undefined) {
+              process.stdout.write("__NULL__");
+            } else {
+              process.stdout.write(String(result));
+            }
+          } catch (err) {
+            process.stderr.write(err.message);
+            process.exit(1);
+          }
+        })();
+      } else {
+        // Fallback: raw TCP RESP protocol (no redis package needed)
+        const actualHost = useUrl ? (() => {
+          try { const u = new URL(url); return u.hostname || "127.0.0.1"; } catch { return "127.0.0.1"; }
+        })() : host;
+        const actualPort = useUrl ? (() => {
+          try { const u = new URL(url); return parseInt(u.port, 10) || 6379; } catch { return 6379; }
+        })() : port;
+
+        function buildCommand(a) {
+          let cmd = "*" + a.length + "\\r\\n";
+          for (const s of a) cmd += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
+          return cmd;
+        }
+
+        const sock = net.createConnection({ host: actualHost, port: actualPort }, () => {
+          let commands = "";
+          if (password) commands += buildCommand(["AUTH", password]);
+          if (db !== 0) commands += buildCommand(["SELECT", String(db)]);
+          commands += buildCommand(args);
+          sock.write(commands);
+        });
+
+        let buffer = Buffer.alloc(0);
+        sock.on("data", (chunk) => {
+          buffer = Buffer.concat([buffer, chunk]);
+        });
+        sock.on("end", () => {
+          const lines = buffer.toString("utf-8").split("\\r\\n");
+          let responses = [];
+          let i = 0;
+          while (i < lines.length) {
+            const line = lines[i];
+            if (!line) { i++; continue; }
+            if (line.startsWith("+") || line.startsWith("-") || line.startsWith(":")) {
+              responses.push(line);
+              i++;
+            } else if (line.startsWith("$")) {
+              const len = parseInt(line.slice(1), 10);
+              if (len === -1) { responses.push(null); i++; }
+              else { responses.push(lines[i+1] || ""); i += 2; }
+            } else { i++; }
+          }
+          const result = responses[responses.length - 1];
+          if (result === null) process.stdout.write("__NULL__");
+          else if (typeof result === "string" && result.startsWith("-")) process.stdout.write("__ERR__" + result);
+          else process.stdout.write(String(result ?? "__NULL__"));
+        });
+        sock.on("error", (err) => {
+          process.stderr.write(err.message);
+          process.exit(1);
+        });
+        setTimeout(() => { sock.destroy(); process.exit(1); }, 3000);
+      }
+    `;
+
+    try {
+      const result = execFileSync(process.execPath, ["-e", script], {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      if (result === "__NULL__") return "";
+      if (result.startsWith("__ERR__")) return "";
+      return result;
+    } catch {
+      return "";
+    }
+  }
+
+  private key(sessionId: string): string {
+    return `${this.prefix}${sessionId}`;
+  }
+
+  read(sessionId: string): SessionData | null {
+    const raw = this.execSync(["GET", this.key(sessionId)]);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as SessionData;
+    } catch {
+      return null;
+    }
+  }
+
+  write(sessionId: string, data: SessionData, ttl: number): void {
+    const json = JSON.stringify(data);
+    if (ttl > 0) {
+      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
+    } else {
+      this.execSync(["SET", this.key(sessionId), json]);
+    }
+  }
+
+  destroy(sessionId: string): void {
+    this.execSync(["DEL", this.key(sessionId)]);
+  }
+}

package/packages/core/src/types.ts

@@ -3,8 +3,8 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 export interface UploadedFile {
   fieldName: string;
   filename: string;
-  contentType: string;
-  data: Buffer;
+  type: string;
+  content: Buffer;
   size: number;
 }
 
@@ -69,6 +69,10 @@ export interface RouteDefinition {
   middlewares?: Middleware[];
   /** Template file to render when handler returns a plain object */
   template?: string;
+  /** Whether this route requires bearer-token authentication */
+  secure?: boolean;
+  /** Whether this route's response should be cached */
+  cached?: boolean;
 }
 
 export interface RouteMeta {
@@ -103,12 +107,14 @@ export type Middleware = (
 
 /**
  * Handler for WebSocket routes.
- * conn — a connection-like object with send/close methods.
- * message — the incoming text or binary message.
+ * connection — object with send/broadcast/close methods and route params.
+ * event — one of "open", "message", or "close".
+ * data — the incoming text message (only present for "message" events).
  */
 export type WebSocketRouteHandler = (
-  conn: { id: string; send: (data: string) => void; close: () => void },
-  message: string | Buffer,
+  connection: import("./websocketConnection.js").WebSocketConnection,
+  event: "open" | "message" | "close",
+  data: string,
 ) => void | Promise<void>;
 
 export interface WebSocketRouteDefinition {

package/packages/core/src/websocket.ts

@@ -52,6 +52,8 @@ export interface WebSocketClient {
   ip: string;
   connectedAt: number;
   closed: boolean;
+  /** The URL path this client connected on (e.g. "/chat", "/notifications"). */
+  path: string;
 }
 
 type EventHandler = (...args: unknown[]) => void;
@@ -185,14 +187,20 @@ export class WebSocketServer {
 
   /**
    * Broadcast a message to all connected clients.
+   *
+   * When `path` is provided, only clients connected on that specific path
+   * receive the message (matching PHP's WebSocket::broadcast behaviour).
+   * When `path` is omitted/undefined, all clients receive the message
+   * (backward compatible).
    */
-  broadcast(message: string, excludeIds?: string[]): void {
+  broadcast(message: string, excludeIds?: string[], path?: string): void {
     const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
     const exclude = new Set(excludeIds ?? []);
 
     for (const [id, client] of this.clients) {
       if (exclude.has(id)) continue;
       if (client.closed) continue;
+      if (path !== undefined && client.path !== path) continue;
       try {
         client.socket.write(frame);
       } catch {
@@ -310,7 +318,7 @@ export class WebSocketServer {
 
     socket.write(response);
 
-    // Create client
+    // Create client — track the URL path for path-scoped broadcast
     const clientId = randomUUID().slice(0, 8);
     const client: WebSocketClient = {
       id: clientId,
@@ -318,6 +326,7 @@ export class WebSocketServer {
       ip: (socket.remoteAddress ?? "unknown"),
       connectedAt: Date.now(),
       closed: false,
+      path: req.url ?? "/",
     };
 
     this.clients.set(clientId, client);

package/packages/core/src/websocketConnection.ts

@@ -5,12 +5,14 @@
 export interface WebSocketConnection {
   /** Unique connection identifier */
   id: string;
-  /** Send a message to this connection */
+  /** Send a message to this connection only */
   send(message: string): void;
-  /** Broadcast a message to all other connections on the same path */
+  /** Broadcast a message to all connections on the same path (path-scoped) */
   broadcast(message: string): void;
   /** Close this connection */
   close(): void;
   /** The WebSocket route path this connection is on */
   path: string;
+  /** Route parameters extracted from `{param}` segments in the path */
+  params: Record<string, string>;
 }

package/packages/frond/src/engine.ts

@@ -757,8 +757,16 @@ const BUILTIN_FILTERS: Record<string, FilterFn> = {
   slug: (v) => String(v).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
   md5: (v) => createHash("md5").update(String(v)).digest("hex"),
   sha256: (v) => createHash("sha256").update(String(v)).digest("hex"),
-  base64_encode: (v) => Buffer.from(String(v)).toString("base64"),
+  base64_encode: (v) => Buffer.isBuffer(v) ? v.toString("base64") : Buffer.from(String(v)).toString("base64"),
   base64_decode: (v) => Buffer.from(String(v), "base64").toString("utf-8"),
+  data_uri: (v) => {
+    if (v && typeof v === "object" && "content" in v) {
+      const ct = (v as any).type ?? "application/octet-stream";
+      const raw = Buffer.isBuffer((v as any).content) ? (v as any).content : Buffer.from(String((v as any).content));
+      return `data:${ct};base64,${raw.toString("base64")}`;
+    }
+    return String(v);
+  },
   url_encode: (v) => encodeURIComponent(String(v)),
   format: (v, ...args) => {
     let s = String(v);
@@ -1155,6 +1163,63 @@ export class Frond {
   }
 
   private evalVar(expr: string, context: Record<string, unknown>): unknown {
+    // Check for top-level ternary BEFORE splitting filters so that
+    // expressions like ``products|length != 1 ? "s" : ""`` work correctly.
+    const ternaryIdx = findTernary(expr);
+    if (ternaryIdx !== -1) {
+      const condPart = expr.slice(0, ternaryIdx).trim();
+      const rest = expr.slice(ternaryIdx + 1);
+      const colonIdx = findColon(rest);
+      if (colonIdx !== -1) {
+        const truePart = rest.slice(0, colonIdx).trim();
+        const falsePart = rest.slice(colonIdx + 1).trim();
+        const cond = this.evalVarRaw(condPart, context);
+        return cond ? this.evalVar(truePart, context) : this.evalVar(falsePart, context);
+      }
+    }
+
+    return this.evalVarInner(expr, context);
+  }
+
+  private evalVarRaw(expr: string, context: Record<string, unknown>): unknown {
+    const [varName, filters] = parseFilterChain(expr);
+    let value = evalExpr(varName, context);
+    for (const [fname, args] of filters) {
+      if (fname === "raw" || fname === "safe") continue;
+      const fn = this.filters[fname];
+      if (fn) {
+        value = fn(value, ...args);
+      } else {
+        // The filter name may include a trailing comparison operator,
+        // e.g. "length != 1".  Extract the real filter name and the
+        // comparison suffix, apply the filter, then evaluate the comparison.
+        const m = fname.match(/^(\w+)\s*(!=|==|>=|<=|>|<)\s*(.+)$/);
+        if (m) {
+          const realFilter = m[1];
+          const op = m[2];
+          const rightExpr = m[3].trim();
+          const fn2 = this.filters[realFilter];
+          if (fn2) {
+            value = fn2(value, ...args);
+          }
+          const right = evalExpr(rightExpr, context);
+          switch (op) {
+            case "!=": value = value !== right; break;
+            case "==": value = value === right; break;
+            case ">=": value = (value as number) >= (right as number); break;
+            case "<=": value = (value as number) <= (right as number); break;
+            case ">":  value = (value as number) > (right as number); break;
+            case "<":  value = (value as number) < (right as number); break;
+          }
+        } else {
+          value = evalExpr(fname, context);
+        }
+      }
+    }
+    return value;
+  }
+
+  private evalVarInner(expr: string, context: Record<string, unknown>): unknown {
     const [varName, filters] = parseFilterChain(expr);
 
     // Sandbox: check variable access