tina4-nodejs 3.8.1 → 3.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.8.1",
+  "version": "3.8.3",
   "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/packages/core/src/index.ts

@@ -17,10 +17,10 @@ export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from
 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, MiddlewareRunner, cors, requestLogger, CorsMiddleware, RateLimiterMiddleware, RequestLogger } from "./middleware.js";
+export { MiddlewareChain, MiddlewareRunner, cors, requestLogger, CorsMiddleware, RateLimiterMiddleware, RequestLogger, SecurityHeadersMiddleware } from "./middleware.js";
 export type { CorsConfig } from "./middleware.js";
 export { createRequest, parseBody } from "./request.js";
-export { createResponse } from "./response.js";
+export { createResponse, errorResponse } from "./response.js";
 export { tryServeStatic } from "./static.js";
 export { loadEnv, getEnv, requireEnv, hasEnv, allEnv, resetEnv, isTruthy } from "./dotenv.js";
 export { Log } from "./logger.js";
@@ -95,4 +95,6 @@ export { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
 export type { RedisNpmSessionConfig } from "./sessionHandlers/redisHandler.js";
 export { tests, assertEqual, assertThrows, assertTrue, assertFalse, runAllTests, resetTests } from "./testing.js";
 export { Container, container } from "./container.js";
+export { Validator } from "./validator.js";
+export type { ValidationError } from "./validator.js";
 export type { WebSocketConnection } from "./websocketConnection.js";

package/packages/core/src/middleware.ts

@@ -349,6 +349,59 @@ export class RequestLogger {
   }
 }
 
+/**
+ * Class-based security headers middleware using the before/after convention.
+ * Auto-injects security headers on every response.
+ *
+ * Configuration via env vars:
+ *   TINA4_FRAME_OPTIONS       — X-Frame-Options (default: "SAMEORIGIN")
+ *   TINA4_HSTS                — Strict-Transport-Security max-age value
+ *                                (default: "" = off; set to "31536000" to enable)
+ *   TINA4_CSP                 — Content-Security-Policy (default: "default-src 'self'")
+ *   TINA4_REFERRER_POLICY     — Referrer-Policy (default: "strict-origin-when-cross-origin")
+ *   TINA4_PERMISSIONS_POLICY  — Permissions-Policy (default: "camera=(), microphone=(), geolocation=()")
+ *
+ * Usage:
+ *   Router.use(SecurityHeadersMiddleware);
+ */
+export class SecurityHeadersMiddleware {
+  static beforeSecurity(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
+    res.header(
+      "X-Frame-Options",
+      process.env.TINA4_FRAME_OPTIONS ?? "SAMEORIGIN",
+    );
+
+    res.header("X-Content-Type-Options", "nosniff");
+
+    const hsts = process.env.TINA4_HSTS ?? "";
+    if (hsts) {
+      res.header(
+        "Strict-Transport-Security",
+        `max-age=${hsts}; includeSubDomains`,
+      );
+    }
+
+    res.header(
+      "Content-Security-Policy",
+      process.env.TINA4_CSP ?? "default-src 'self'",
+    );
+
+    res.header(
+      "Referrer-Policy",
+      process.env.TINA4_REFERRER_POLICY ?? "strict-origin-when-cross-origin",
+    );
+
+    res.header("X-XSS-Protection", "0");
+
+    res.header(
+      "Permissions-Policy",
+      process.env.TINA4_PERMISSIONS_POLICY ?? "camera=(), microphone=(), geolocation=()",
+    );
+
+    return [req, res];
+  }
+}
+
 // Built-in request logger middleware (function form — kept for backwards compat)
 export function requestLogger(): Middleware {
   return (req, res, next) => {

package/packages/core/src/request.ts

@@ -27,10 +27,27 @@ export function createRequest(req: IncomingMessage): Tina4Request {
   return tReq;
 }
 
+/** Maximum upload size in bytes (default 10 MB). Override via TINA4_MAX_UPLOAD_SIZE env var. */
+const TINA4_MAX_UPLOAD_SIZE = parseInt(process.env.TINA4_MAX_UPLOAD_SIZE ?? "10485760", 10);
+
+export class PayloadTooLargeError extends Error {
+  public statusCode = 413;
+  constructor(actual: number, limit: number) {
+    super(`Request body (${actual} bytes) exceeds TINA4_MAX_UPLOAD_SIZE (${limit} bytes)`);
+    this.name = "PayloadTooLargeError";
+  }
+}
+
 export async function parseBody(req: Tina4Request): Promise<void> {
   const method = req.method?.toUpperCase();
   if (method === "GET" || method === "HEAD" || method === "OPTIONS") return;
 
+  // Check content-length header against upload size limit before reading body
+  const declaredLength = parseInt(req.headers["content-length"] ?? "0", 10);
+  if (declaredLength > TINA4_MAX_UPLOAD_SIZE) {
+    throw new PayloadTooLargeError(declaredLength, TINA4_MAX_UPLOAD_SIZE);
+  }
+
   const contentType = req.headers["content-type"] ?? "";
   const chunks: Buffer[] = [];
 
@@ -43,6 +60,11 @@ export async function parseBody(req: Tina4Request): Promise<void> {
   const raw = Buffer.concat(chunks);
   if (raw.length === 0) return;
 
+  // Check actual body size against upload size limit
+  if (raw.length > TINA4_MAX_UPLOAD_SIZE) {
+    throw new PayloadTooLargeError(raw.length, TINA4_MAX_UPLOAD_SIZE);
+  }
+
   if (contentType.includes("multipart/form-data")) {
     const boundary = extractBoundary(contentType);
     if (boundary) {

package/packages/core/src/response.ts

@@ -128,6 +128,11 @@ export function createResponse(res: ServerResponse): Tina4Response {
     return response.cookie(name, "", { ...options, maxAge: 0, expires: new Date(0) });
   };
 
+  response.error = function (code: string, message: string, status?: number): Tina4Response {
+    const statusCode = status ?? 400;
+    return response.json({ error: true, code, message, status: statusCode }, statusCode);
+  };
+
   response.file = function (filePath: string, options?: { download?: boolean; contentType?: string }): Tina4Response {
     if (!fs.existsSync(filePath)) {
       res.statusCode = 404;
@@ -190,3 +195,13 @@ export function createResponse(res: ServerResponse): Tina4Response {
 
   return response;
 }
+
+/**
+ * Build a standard error response envelope (standalone helper).
+ *
+ * Usage:
+ *   return response(errorResponse("VALIDATION_FAILED", "Email is required", 400), 400);
+ */
+export function errorResponse(code: string, message: string, status: number = 400): Record<string, unknown> {
+  return { error: true, code, message, status };
+}

package/packages/core/src/types.ts

@@ -37,6 +37,7 @@ export interface Tina4ResponseMethods {
   cookie(name: string, value: string, options?: CookieOptions): Tina4Response;
   clearCookie(name: string, options?: CookieOptions): Tina4Response;
   file(path: string, options?: { download?: boolean; contentType?: string }): Tina4Response;
+  error(code: string, message: string, status?: number): 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 */

package/packages/core/src/validator.ts

@@ -0,0 +1,145 @@
+/**
+ * Tina4 Validator — Request body validation.
+ *
+ * Usage:
+ *   import { Validator } from "@tina4/core";
+ *
+ *   const validator = new Validator(req.body as Record<string, unknown>);
+ *   validator.required("name", "email");
+ *   validator.email("email");
+ *   validator.minLength("name", 2);
+ *   validator.maxLength("name", 100);
+ *   validator.integer("age");
+ *   validator.min("age", 0);
+ *   validator.max("age", 150);
+ *   validator.inList("role", ["admin", "user", "guest"]);
+ *   validator.regex("phone", /^\+?[\d\s\-]+$/);
+ *
+ *   if (!validator.isValid()) {
+ *     return res.error("VALIDATION_FAILED", validator.errors()[0].message, 400);
+ *   }
+ */
+
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+const EMAIL_REGEX = /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/;
+
+export class Validator {
+  private data: Record<string, unknown>;
+  private validationErrors: ValidationError[] = [];
+
+  constructor(data?: Record<string, unknown> | null) {
+    this.data = data && typeof data === "object" && !Array.isArray(data)
+      ? data as Record<string, unknown>
+      : {};
+  }
+
+  /** Check that one or more fields are present and non-empty. */
+  required(...fields: string[]): this {
+    for (const field of fields) {
+      const value = this.data[field];
+      if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
+        this.validationErrors.push({ field, message: `${field} is required` });
+      }
+    }
+    return this;
+  }
+
+  /** Check that a field contains a valid email address. */
+  email(field: string): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    if (typeof value !== "string" || !EMAIL_REGEX.test(value)) {
+      this.validationErrors.push({ field, message: `${field} must be a valid email address` });
+    }
+    return this;
+  }
+
+  /** Check that a string field has at least `length` characters. */
+  minLength(field: string, length: number): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    if (typeof value !== "string" || value.length < length) {
+      this.validationErrors.push({ field, message: `${field} must be at least ${length} characters` });
+    }
+    return this;
+  }
+
+  /** Check that a string field has at most `length` characters. */
+  maxLength(field: string, length: number): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    if (typeof value !== "string" || value.length > length) {
+      this.validationErrors.push({ field, message: `${field} must be at most ${length} characters` });
+    }
+    return this;
+  }
+
+  /** Check that a field is an integer (or can be parsed as one). */
+  integer(field: string): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    if (typeof value === "boolean" || !Number.isInteger(Number(value)) || String(value).trim() === "") {
+      this.validationErrors.push({ field, message: `${field} must be an integer` });
+    }
+    return this;
+  }
+
+  /** Check that a numeric field is >= `minimum`. */
+  min(field: string, minimum: number): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    const num = Number(value);
+    if (isNaN(num)) return this;
+    if (num < minimum) {
+      this.validationErrors.push({ field, message: `${field} must be at least ${minimum}` });
+    }
+    return this;
+  }
+
+  /** Check that a numeric field is <= `maximum`. */
+  max(field: string, maximum: number): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    const num = Number(value);
+    if (isNaN(num)) return this;
+    if (num > maximum) {
+      this.validationErrors.push({ field, message: `${field} must be at most ${maximum}` });
+    }
+    return this;
+  }
+
+  /** Check that a field's value is one of the allowed values. */
+  inList(field: string, allowed: unknown[]): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    if (!allowed.includes(value)) {
+      this.validationErrors.push({ field, message: `${field} must be one of ${JSON.stringify(allowed)}` });
+    }
+    return this;
+  }
+
+  /** Check that a field matches a regular expression. */
+  regex(field: string, pattern: RegExp | string): this {
+    const value = this.data[field];
+    if (value === undefined || value === null) return this;
+    const re = pattern instanceof RegExp ? pattern : new RegExp(pattern);
+    if (typeof value !== "string" || !re.test(value)) {
+      this.validationErrors.push({ field, message: `${field} does not match the required format` });
+    }
+    return this;
+  }
+
+  /** Return the list of validation errors (empty if valid). */
+  errors(): ValidationError[] {
+    return [...this.validationErrors];
+  }
+
+  /** Return true if no validation errors have been recorded. */
+  isValid(): boolean {
+    return this.validationErrors.length === 0;
+  }
+}

package/packages/orm/src/database.ts

@@ -185,9 +185,25 @@ export function parseDatabaseUrl(url: string, username?: string, password?: stri
  *   db.update("users", { name: "Bob" }, { id: 1 });
  *   db.delete("users", { id: 1 });
  *   db.close();
+ *
+ * Connection pooling:
+ *   const db = await Database.create("sqlite:///data/app.db", undefined, undefined, 4);
+ *   // 4 connections, round-robin rotation
  */
 export class Database {
-  private adapter: DatabaseAdapter;
+  private adapter: DatabaseAdapter | null;
+
+  /** Connection pool — array of adapters with lazy creation */
+  private pool: (DatabaseAdapter | null)[] = [];
+
+  /** Pool size (0 = single connection) */
+  private poolSize: number = 0;
+
+  /** Round-robin index */
+  private poolIndex: number = 0;
+
+  /** Factory for creating new adapters (used by pool) */
+  private adapterFactory: (() => Promise<DatabaseAdapter>) | null = null;
 
   /**
    * Create a Database wrapping an existing adapter.
@@ -201,8 +217,33 @@ export class Database {
   /**
    * Async factory: creates a Database from a connection URL.
    * Works with all adapter types (sqlite, postgres, mysql, mssql, firebird).
+   *
+   * @param url - Connection URL
+   * @param username - Optional username
+   * @param password - Optional password
+   * @param pool - Number of pooled connections (0 = single, N>0 = round-robin)
    */
-  static async create(url: string, username?: string, password?: string): Promise<Database> {
+  static async create(url: string, username?: string, password?: string, pool: number = 0): Promise<Database> {
+    if (pool > 0) {
+      // Pooled mode — create all adapters eagerly
+      const adapters: DatabaseAdapter[] = [];
+      for (let i = 0; i < pool; i++) {
+        adapters.push(await createAdapterFromUrl(url, username, password));
+      }
+
+      // Set the first adapter as the global default
+      setAdapter(adapters[0]);
+
+      const db = new Database(adapters[0]);
+      db.poolSize = pool;
+      db.pool = adapters;
+      db.poolIndex = 0;
+      db.adapter = null;  // Don't use single-adapter path
+      db.adapterFactory = () => createAdapterFromUrl(url, username, password);
+      return db;
+    }
+
+    // Single-connection mode — current behavior
     const adapter = await createAdapterFromUrl(url, username, password);
     setAdapter(adapter);
     return new Database(adapter);
@@ -211,84 +252,119 @@ export class Database {
   /**
    * Create a Database from an environment variable.
    * @param envKey - Name of the env var holding the connection URL. Defaults to "DATABASE_URL".
+   * @param pool - Number of pooled connections (0 = single, N>0 = round-robin)
    */
-  static async fromEnv(envKey = "DATABASE_URL"): Promise<Database> {
+  static async fromEnv(envKey = "DATABASE_URL", pool: number = 0): Promise<Database> {
     const url = process.env[envKey];
     if (!url) {
       throw new Error(`Environment variable "${envKey}" is not set.`);
     }
-    return Database.create(url);
+    return Database.create(url, undefined, undefined, pool);
+  }
+
+  /**
+   * Get the next adapter — from pool (round-robin) or single connection.
+   */
+  private getNextAdapter(): DatabaseAdapter {
+    if (this.poolSize > 0) {
+      const idx = this.poolIndex;
+      this.poolIndex = (this.poolIndex + 1) % this.poolSize;
+      return this.pool[idx] as DatabaseAdapter;
+    }
+
+    return this.adapter!;
   }
 
   /** Get the underlying adapter (for advanced / escape-hatch usage). */
   getAdapter(): DatabaseAdapter {
-    return this.adapter;
+    return this.getNextAdapter();
+  }
+
+  /** Get the pool size (0 = single connection mode). */
+  getPoolSize(): number {
+    return this.poolSize;
+  }
+
+  /** Get the number of active (created) connections in the pool. */
+  getActivePoolCount(): number {
+    if (this.poolSize === 0) return this.adapter ? 1 : 0;
+    return this.pool.filter(a => a !== null).length;
   }
 
   /** Query rows with optional pagination. Returns a DatabaseResult wrapper. */
   fetch(sql: string, params?: unknown[], limit?: number, offset?: number): DatabaseResult {
-    const rows = this.adapter.fetch<Record<string, unknown>>(sql, params, limit, offset);
-    return new DatabaseResult(rows, undefined, undefined, limit, offset, this.adapter, sql);
+    const adapter = this.getNextAdapter();
+    const rows = adapter.fetch<Record<string, unknown>>(sql, params, limit, offset);
+    return new DatabaseResult(rows, undefined, undefined, limit, offset, adapter, sql);
   }
 
   /** Fetch a single row or null. */
   fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
-    return this.adapter.fetchOne<T>(sql, params);
+    return this.getNextAdapter().fetchOne<T>(sql, params);
   }
 
   /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
   execute(sql: string, params?: unknown[]): unknown {
-    return this.adapter.execute(sql, params);
+    return this.getNextAdapter().execute(sql, params);
   }
 
   /** Insert a row into a table. */
   insert(table: string, data: Record<string, unknown>): DatabaseWriteResult {
-    return this.adapter.insert(table, data);
+    return this.getNextAdapter().insert(table, data);
   }
 
   /** Update rows in a table matching filter. */
   update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>): DatabaseWriteResult {
-    return this.adapter.update(table, data, filter ?? {});
+    return this.getNextAdapter().update(table, data, filter ?? {});
   }
 
   /** Delete rows from a table matching filter. */
   delete(table: string, filter?: Record<string, unknown>): DatabaseWriteResult {
-    return this.adapter.delete(table, filter ?? {});
+    return this.getNextAdapter().delete(table, filter ?? {});
   }
 
-  /** Close the database connection. */
+  /** Close all database connections (pool or single). */
   close(): void {
-    this.adapter.close();
+    if (this.poolSize > 0) {
+      for (let i = 0; i < this.pool.length; i++) {
+        if (this.pool[i] !== null) {
+          this.pool[i]!.close();
+          this.pool[i] = null;
+        }
+      }
+    } else if (this.adapter) {
+      this.adapter.close();
+    }
   }
 
   /** Start a transaction. */
   startTransaction(): void {
-    this.adapter.startTransaction();
+    this.getNextAdapter().startTransaction();
   }
 
   /** Commit the current transaction. */
   commit(): void {
-    this.adapter.commit();
+    this.getNextAdapter().commit();
   }
 
   /** Rollback the current transaction. */
   rollback(): void {
-    this.adapter.rollback();
+    this.getNextAdapter().rollback();
   }
 
   /** Check if a table exists. */
   tableExists(name: string): boolean {
-    return this.adapter.tableExists(name);
+    return this.getNextAdapter().tableExists(name);
   }
 
   /** List all tables in the database. */
   getTables(): string[] {
-    return this.adapter.tables();
+    return this.getNextAdapter().tables();
   }
 
   /** Get the last auto-increment id. */
   getLastId(): string | number {
-    const id = this.adapter.lastInsertId();
+    const id = this.getNextAdapter().lastInsertId();
     if (id === null) return 0;
     return typeof id === "bigint" ? id.toString() : id;
   }