tina4-nodejs 3.1.2 → 3.4.0

package/packages/core/src/router.ts

@@ -7,6 +7,8 @@ interface MatchResult {
   meta?: RouteMeta;
   middlewares?: Middleware[];
   template?: string;
+  secure?: boolean;
+  cached?: boolean;
 }
 
 interface CompiledRoute {
@@ -17,18 +19,42 @@ interface CompiledRoute {
   meta?: RouteMeta;
   filePath?: string;
   middlewares?: Middleware[];
+  secure?: boolean;
   cached?: boolean;
   cacheStore?: Map<string, { data: unknown; expires: number }>;
   cacheTtl?: number;
   template?: string;
 }
 
+/**
+ * Thin reference to a registered route, enabling chained modifiers.
+ *
+ * Usage:
+ *   router.get("/api/data", handler).secure().cache();
+ */
+export class RouteRef {
+  constructor(private route: CompiledRoute) {}
+
+  /** Mark this route as requiring bearer-token authentication. */
+  secure(): this {
+    this.route.secure = true;
+    return this;
+  }
+
+  /** Mark this route's response as cacheable. */
+  cache(): this {
+    this.route.cached = true;
+    return this;
+  }
+}
+
 export interface RouteInfo {
   method: string;
   path: string;
   handler: string;
   middlewareCount: number;
   cached: boolean;
+  secure: boolean;
 }
 
 export class Router {
@@ -38,7 +64,7 @@ export class Router {
   /**
    * Add a raw route definition (used internally and by file-based routing).
    */
-  addRoute(definition: RouteDefinition): void {
+  addRoute(definition: RouteDefinition): RouteRef {
     const method = definition.method.toUpperCase();
     const { regex, paramNames } = this.compilePattern(definition.pattern);
 
@@ -54,7 +80,7 @@ export class Router {
       routes.splice(existingIndex, 1);
     }
 
-    routes.push({
+    const compiled: CompiledRoute = {
       pattern: definition.pattern,
       regex,
       paramNames,
@@ -62,52 +88,58 @@ export class Router {
       meta: definition.meta,
       filePath: definition.filePath,
       middlewares: definition.middlewares,
+      secure: definition.secure,
+      cached: definition.cached,
       template: definition.template,
-    });
+    };
+    routes.push(compiled);
+    return new RouteRef(compiled);
   }
 
   /**
    * Register a GET route programmatically.
    */
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
+  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a POST route programmatically.
    */
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
+  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PUT route programmatically.
    */
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
+  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PATCH route programmatically.
    */
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
+  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a DELETE route programmatically.
    */
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
+  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a route that matches ANY HTTP method.
    */
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
+  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
-      this.addRoute({ method, pattern: path, handler, middlewares, meta });
+      lastRef = this.addRoute({ method, pattern: path, handler, middlewares, meta });
     }
+    return lastRef;
   }
 
   /**
@@ -142,6 +174,8 @@ export class Router {
           meta: route.meta,
           middlewares: route.middlewares,
           template: route.template,
+          secure: route.secure,
+          cached: route.cached,
         };
       }
     }
@@ -164,6 +198,8 @@ export class Router {
           filePath: route.filePath,
           middlewares: route.middlewares,
           template: route.template,
+          secure: route.secure,
+          cached: route.cached,
         });
       }
     }
@@ -183,6 +219,7 @@ export class Router {
           handler: route.filePath ?? (route.handler.name || "(anonymous)"),
           middlewareCount: route.middlewares?.length ?? 0,
           cached: route.cached ?? false,
+          secure: route.secure ?? false,
         });
       }
     }
@@ -228,43 +265,43 @@ export class Router {
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.get(path, handler, middlewares, meta);
+  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.get(path, handler, middlewares, meta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.post(path, handler, middlewares, meta);
+  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.post(path, handler, middlewares, meta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.put(path, handler, middlewares, meta);
+  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.put(path, handler, middlewares, meta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.patch(path, handler, middlewares, meta);
+  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.patch(path, handler, middlewares, meta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.delete(path, handler, middlewares, meta);
+  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.delete(path, handler, middlewares, meta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    defaultRouter.any(path, handler, middlewares, meta);
+  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return defaultRouter.any(path, handler, middlewares, meta);
   }
 
   /**
@@ -343,8 +380,8 @@ export class RouteGroup {
     return merged.length > 0 ? merged : undefined;
   }
 
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "GET",
       pattern: this.prefix + path,
       handler,
@@ -353,8 +390,8 @@ export class RouteGroup {
     });
   }
 
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "POST",
       pattern: this.prefix + path,
       handler,
@@ -363,8 +400,8 @@ export class RouteGroup {
     });
   }
 
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "PUT",
       pattern: this.prefix + path,
       handler,
@@ -373,8 +410,8 @@ export class RouteGroup {
     });
   }
 
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "PATCH",
       pattern: this.prefix + path,
       handler,
@@ -383,8 +420,8 @@ export class RouteGroup {
     });
   }
 
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-    this.router.addRoute({
+  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    return this.router.addRoute({
       method: "DELETE",
       pattern: this.prefix + path,
       handler,
@@ -393,9 +430,10 @@ export class RouteGroup {
     });
   }
 
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
+  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+    let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
-      this.router.addRoute({
+      lastRef = this.router.addRoute({
         method,
         pattern: this.prefix + path,
         handler,
@@ -403,6 +441,7 @@ export class RouteGroup {
         meta,
       });
     }
+    return lastRef;
   }
 
   /**
@@ -458,29 +497,29 @@ export const defaultRouter = new Router();
  *     res.json({ id: req.params.id }, 201);
  *   });
  */
-export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.get(path, handler, middlewares, meta);
+export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.get(path, handler, middlewares, meta);
 }
 
-export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.post(path, handler, middlewares, meta);
+export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.post(path, handler, middlewares, meta);
 }
 
-export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.put(path, handler, middlewares, meta);
+export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.put(path, handler, middlewares, meta);
 }
 
-export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.patch(path, handler, middlewares, meta);
+export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.patch(path, handler, middlewares, meta);
 }
 
 // Named "del" to avoid conflict with the "delete" keyword; also exported as "delete" alias below.
-export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.delete(path, handler, middlewares, meta);
+export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.delete(path, handler, middlewares, meta);
 }
 
-export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): void {
-  defaultRouter.any(path, handler, middlewares, meta);
+export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  return defaultRouter.any(path, handler, middlewares, meta);
 }
 
 export function websocket(path: string, handler: WebSocketRouteHandler): void {

package/packages/core/src/server.ts

@@ -29,6 +29,38 @@ const BUILTIN_PUBLIC_DIR = resolve(__dirname, "..", "public");
 
 const TINA4_VERSION = "3.0.0";
 
+/**
+ * Test-bind each port in a subprocess to find one that is available.
+ * Falls back to `start` if none of the candidates work.
+ */
+function findAvailablePort(start: number, maxTries = 10): number {
+  const { execFileSync } = require("node:child_process");
+  for (let offset = 0; offset < maxTries; offset++) {
+    const port = start + offset;
+    try {
+      execFileSync(process.execPath, ["-e", `
+        const s = require("net").createServer();
+        s.listen(${port}, "127.0.0.1", () => { s.close(); process.exit(0); });
+        s.on("error", () => process.exit(1));
+      `], { timeout: 1000 });
+      return port;
+    } catch { continue; }
+  }
+  return start;
+}
+
+/**
+ * Open the user's default browser after a short delay so the server is ready.
+ */
+function openBrowser(url: string) {
+  const { exec } = require("node:child_process");
+  setTimeout(() => {
+    if (process.platform === "darwin") exec(`open ${url}`);
+    else if (process.platform === "win32") exec(`start "" "${url}"`);
+    else exec(`xdg-open ${url}`);
+  }, 2000);
+}
+
 /**
  * Resolve port and host with priority: explicit config > ENV var > default.
  * Exported for testability.
@@ -266,8 +298,10 @@ function deployGallery(name) {
         if (d.error) {
             alert('Deploy failed: ' + d.error);
         } else {
-            alert('Deployed "' + d.deployed + '" (' + d.files.length + ' files). Reloading...');
-            window.location.reload();
+            // Brief delay to allow newly deployed routes to register before reloading
+            setTimeout(function() {
+                window.location.reload();
+            }, 500);
         }
     })
     .catch(function(e) { alert('Deploy error: ' + e.message); });
@@ -285,7 +319,16 @@ export async function startServer(config?: Tina4Config): Promise<{
   // Load .env early so TINA4_DEBUG is available for cluster decision
   loadEnv();
 
-  const { port, host } = resolvePortAndHost(config);
+  const resolved = resolvePortAndHost(config);
+  const host = resolved.host;
+  let port = resolved.port;
+
+  // Auto-increment port if the requested one is already in use
+  const availablePort = findAvailablePort(port);
+  if (availablePort !== port) {
+    console.log(`  Port ${port} in use, using ${availablePort} instead`);
+    port = availablePort;
+  }
 
   // Cluster mode for production: fork workers based on CPU count
   // Only when not in dev mode and running as primary process
@@ -553,7 +596,21 @@ ${reset}
           if (!proceed || res.raw.writableEnded) return;
         }
 
-        const result = await match.handler(req, res);
+        // Support (), (response), (request), or (request, response) handler signatures
+        // When 1 param: if named request/req, pass request; otherwise pass response
+        let result: unknown;
+        if (match.handler.length === 0) {
+          result = await (match.handler as any)();
+        } else if (match.handler.length === 1) {
+          const fnStr = match.handler.toString();
+          const paramMatch = fnStr.match(/^(?:async\s+)?(?:function\s*)?\(?\s*(\w+)/);
+          const paramName = paramMatch?.[1]?.toLowerCase() ?? "";
+          result = (paramName === "request" || paramName === "req")
+            ? await match.handler(req as any)
+            : await match.handler(res as any);
+        } else {
+          result = await match.handler(req, res);
+        }
 
         // If the route exports a template and the handler returned a plain object,
         // render it through the template engine instead of sending as JSON.
@@ -655,6 +712,7 @@ ${reset}
   Dashboard: http://localhost:${port}/__dev
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})
 `);
+      openBrowser(`http://${displayHost}:${port}`);
       resolvePromise({
         close: () => {
           server.close();

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);

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);
+  }
+}