tina4-nodejs 3.0.0-rc.2

package/packages/core/src/health.ts

@@ -0,0 +1,31 @@
+import type { RouteDefinition } from "./types.js";
+
+/** Server start time, set when health route is created */
+let startTime: number;
+
+/**
+ * Create the /health route definition.
+ * Returns a RouteDefinition that can be added to the router.
+ */
+export function createHealthRoute(version: string = "3.0.0"): RouteDefinition {
+  startTime = Date.now();
+
+  return {
+    method: "GET",
+    pattern: "/health",
+    handler: (_req, res) => {
+      const uptimeSeconds = (Date.now() - startTime) / 1000;
+      res.json({
+        status: "ok",
+        version,
+        uptime: Math.round(uptimeSeconds * 100) / 100,
+        framework: "tina4-nodejs",
+      });
+    },
+    meta: {
+      summary: "Health check",
+      description: "Returns server health status, version, and uptime.",
+      tags: ["System"],
+    },
+  };
+}

package/packages/core/src/htmlElement.ts

@@ -0,0 +1,172 @@
+/**
+ * Programmatic HTML builder — avoids string concatenation.
+ *
+ * Usage:
+ *   const el = new HtmlElement("div", { class: "card" }, ["Hello"]);
+ *   el.toString();  // '<div class="card">Hello</div>'
+ *
+ *   // Builder pattern
+ *   const el = htmlElement("div")(htmlElement("p")("Text"));
+ *
+ *   // Helper functions
+ *   const h: Record<string, any> = {};
+ *   addHtmlHelpers(h);
+ *   const html = h._div({ class: "card" }, h._p("Hello"));
+ */
+
+const VOID_TAGS: ReadonlySet<string> = new Set([
+  "area", "base", "br", "col", "embed", "hr", "img", "input",
+  "link", "meta", "param", "source", "track", "wbr",
+]);
+
+const HTML_TAGS: readonly string[] = [
+  "a", "abbr", "address", "area", "article", "aside", "audio",
+  "b", "base", "bdi", "bdo", "blockquote", "body", "br", "button",
+  "canvas", "caption", "cite", "code", "col", "colgroup",
+  "data", "datalist", "dd", "del", "details", "dfn", "dialog", "div", "dl", "dt",
+  "em", "embed",
+  "fieldset", "figcaption", "figure", "footer", "form",
+  "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup", "hr", "html",
+  "i", "iframe", "img", "input", "ins",
+  "kbd",
+  "label", "legend", "li", "link",
+  "main", "map", "mark", "menu", "meta", "meter",
+  "nav", "noscript",
+  "object", "ol", "optgroup", "option", "output",
+  "p", "param", "picture", "pre", "progress",
+  "q",
+  "rp", "rt", "ruby",
+  "s", "samp", "script", "section", "select", "slot", "small", "source", "span",
+  "strong", "style", "sub", "summary", "sup",
+  "table", "tbody", "td", "template", "textarea", "tfoot", "th", "thead", "time",
+  "title", "tr", "track",
+  "u", "ul",
+  "var", "video",
+  "wbr",
+];
+
+type Attrs = Record<string, string | number | boolean | null | undefined>;
+type Child = string | number | HtmlElement;
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function isAttrs(arg: unknown): arg is Attrs {
+  return typeof arg === "object" && arg !== null && !(arg instanceof HtmlElement) && !Array.isArray(arg);
+}
+
+/**
+ * HtmlElement — a single HTML tag with attributes and children.
+ */
+export class HtmlElement {
+  readonly tag: string;
+  readonly attrs: Attrs;
+  readonly children: Child[];
+
+  constructor(tag: string, attrs: Attrs = {}, children: Child[] = []) {
+    this.tag = tag.toLowerCase();
+    this.attrs = { ...attrs };
+    this.children = [...children];
+  }
+
+  /**
+   * Render to HTML string.
+   */
+  toString(): string {
+    let html = `<${this.tag}`;
+
+    for (const [key, value] of Object.entries(this.attrs)) {
+      if (value === true) {
+        html += ` ${key}`;
+      } else if (value !== false && value !== null && value !== undefined) {
+        html += ` ${key}="${escapeAttr(String(value))}"`;
+      }
+    }
+
+    if (VOID_TAGS.has(this.tag)) {
+      return html + ">";
+    }
+
+    html += ">";
+
+    for (const child of this.children) {
+      html += String(child);
+    }
+
+    html += `</${this.tag}>`;
+    return html;
+  }
+}
+
+/**
+ * Create a callable HTML element builder.
+ * Returns a function that, when called with children/attrs, produces a new HtmlElement.
+ *
+ * Usage:
+ *   const div = htmlElement("div");
+ *   const el = div({ class: "card" }, "Hello");
+ *   console.log(el.toString());  // '<div class="card">Hello</div>'
+ */
+export function htmlElement(tag: string, attrs: Attrs = {}, children: Child[] = []) {
+  const el = new HtmlElement(tag, attrs, children);
+
+  const builder = (...args: (Child | Attrs | Child[])[]) => {
+    const newAttrs: Attrs = { ...el.attrs };
+    const newChildren: Child[] = [...el.children];
+
+    for (const arg of args) {
+      if (isAttrs(arg)) {
+        Object.assign(newAttrs, arg);
+      } else if (Array.isArray(arg)) {
+        newChildren.push(...arg);
+      } else {
+        newChildren.push(arg as Child);
+      }
+    }
+
+    return htmlElement(tag, newAttrs, newChildren);
+  };
+
+  // Expose HtmlElement properties and toString on the builder function
+  builder.tag = el.tag;
+  builder.attrs = el.attrs;
+  builder.children = el.children;
+  builder.toString = () => el.toString();
+  builder._isHtmlElement = true;
+
+  return builder;
+}
+
+/**
+ * Injects helper functions (_div, _p, _a, _span, etc.) into the target object.
+ *
+ * Usage:
+ *   const h: Record<string, any> = {};
+ *   addHtmlHelpers(h);
+ *   const html = h._div({ class: "card" }, h._p("Hello"));
+ */
+export function addHtmlHelpers(target: Record<string, unknown>): void {
+  for (const tag of HTML_TAGS) {
+    target[`_${tag}`] = (...args: (Child | Attrs | Child[])[]) => {
+      const attrs: Attrs = {};
+      const children: Child[] = [];
+
+      for (const arg of args) {
+        if (isAttrs(arg)) {
+          Object.assign(attrs, arg);
+        } else if (Array.isArray(arg)) {
+          children.push(...arg);
+        } else {
+          children.push(arg as Child);
+        }
+      }
+
+      return new HtmlElement(tag, attrs, children);
+    };
+  }
+}

package/packages/core/src/i18n.ts

@@ -0,0 +1,136 @@
+// Tina4 i18n — Internationalization and localization, zero dependencies.
+// Load JSON translation files, support nested keys, parameter substitution, locale fallback.
+
+import { readFileSync, readdirSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export class I18n {
+  private _localeDir: string;
+  private _defaultLocale: string;
+  private _currentLocale: string;
+  private _translations: Map<string, Record<string, string>> = new Map();
+
+  constructor(localeDir?: string, defaultLocale?: string) {
+    this._localeDir = resolve(
+      localeDir ?? process.env.TINA4_LOCALE_DIR ?? "src/locales"
+    );
+    this._defaultLocale = defaultLocale ?? process.env.TINA4_LOCALE ?? "en";
+    this._currentLocale = this._defaultLocale;
+    this._loadLocale(this._defaultLocale);
+  }
+
+  setLocale(locale: string): void {
+    this._currentLocale = locale;
+    this._loadLocale(locale);
+  }
+
+  getLocale(): string {
+    return this._currentLocale;
+  }
+
+  /**
+   * Translate a key. Supports {placeholder} interpolation.
+   * Falls back to default locale, then returns the key itself.
+   */
+  t(key: string, params?: Record<string, string>, locale?: string): string {
+    const effectiveLocale = locale ?? this._currentLocale;
+
+    // Ensure locale is loaded
+    if (locale) {
+      this._loadLocale(locale);
+    }
+
+    // Try effective locale
+    const translations = this._translations.get(effectiveLocale) ?? {};
+    let value: string | undefined = translations[key];
+
+    // Fallback to default locale
+    if (value === undefined && effectiveLocale !== this._defaultLocale) {
+      const fallback = this._translations.get(this._defaultLocale) ?? {};
+      value = fallback[key];
+    }
+
+    // Fallback to key itself
+    if (value === undefined) {
+      value = key;
+    }
+
+    // Interpolate parameters: {name} → value
+    if (params) {
+      for (const [pKey, pVal] of Object.entries(params)) {
+        value = value.replace(new RegExp(`\\{${pKey}\\}`, "g"), pVal);
+      }
+    }
+
+    return value;
+  }
+
+  /** Alias for t() */
+  translate(key: string, params?: Record<string, string>, locale?: string): string {
+    return this.t(key, params, locale);
+  }
+
+  /** Load and return translations for a locale. */
+  loadTranslations(locale: string): Record<string, string> {
+    this._loadLocale(locale);
+    return { ...(this._translations.get(locale) ?? {}) };
+  }
+
+  /** Add a single translation key/value to a locale (in-memory only). */
+  addTranslation(locale: string, key: string, value: string): void {
+    if (!this._translations.has(locale)) {
+      this._translations.set(locale, {});
+    }
+    this._translations.get(locale)![key] = value;
+  }
+
+  /** List available locale codes based on JSON files in the locale directory. */
+  getAvailableLocales(): string[] {
+    if (!existsSync(this._localeDir)) {
+      return [this._defaultLocale];
+    }
+    try {
+      const files = readdirSync(this._localeDir);
+      const locales = files
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => f.replace(/\.json$/, ""))
+        .sort();
+      return locales.length > 0 ? locales : [this._defaultLocale];
+    } catch {
+      return [this._defaultLocale];
+    }
+  }
+
+  /** Load a locale file if not already loaded. */
+  private _loadLocale(locale: string): void {
+    if (this._translations.has(locale)) {
+      return;
+    }
+    const filePath = join(this._localeDir, `${locale}.json`);
+    if (existsSync(filePath)) {
+      try {
+        const raw = readFileSync(filePath, "utf-8");
+        const data = JSON.parse(raw);
+        this._translations.set(locale, I18n._flatten(data));
+      } catch {
+        this._translations.set(locale, {});
+      }
+    } else {
+      this._translations.set(locale, {});
+    }
+  }
+
+  /** Flatten nested objects: {"a": {"b": "c"}} → {"a.b": "c"} */
+  private static _flatten(data: Record<string, unknown>, prefix = ""): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(data)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        Object.assign(result, I18n._flatten(value as Record<string, unknown>, fullKey));
+      } else {
+        result[fullKey] = String(value);
+      }
+    }
+    return result;
+  }
+}

package/packages/core/src/index.ts

@@ -0,0 +1,88 @@
+export type {
+  Tina4Request,
+  Tina4Response,
+  RouteHandler,
+  RouteDefinition,
+  RouteMeta,
+  Tina4Config,
+  Middleware,
+  UploadedFile,
+  CookieOptions,
+} 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 type { RouteInfo } from "./router.js";
+export { discoverRoutes } from "./routeDiscovery.js";
+export { MiddlewareChain, cors, requestLogger } from "./middleware.js";
+export type { CorsConfig } from "./middleware.js";
+export { createRequest, parseBody } from "./request.js";
+export { createResponse } from "./response.js";
+export { tryServeStatic } from "./static.js";
+export { loadEnv, getEnv, requireEnv, hasEnv, allEnv, resetEnv, isTruthy } from "./dotenv.js";
+export { Log } from "./logger.js";
+export { createHealthRoute } from "./health.js";
+export { rateLimiter } from "./rateLimiter.js";
+export type { RateLimiterConfig } from "./rateLimiter.js";
+export {
+  HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT,
+  HTTP_MOVED, HTTP_REDIRECT, HTTP_NOT_MODIFIED,
+  HTTP_BAD_REQUEST, HTTP_UNAUTHORIZED, HTTP_FORBIDDEN,
+  HTTP_NOT_FOUND, HTTP_METHOD_NOT_ALLOWED, HTTP_CONFLICT,
+  HTTP_GONE, HTTP_UNPROCESSABLE, HTTP_TOO_MANY,
+  HTTP_SERVER_ERROR, HTTP_BAD_GATEWAY, HTTP_UNAVAILABLE,
+  APPLICATION_JSON, APPLICATION_XML, APPLICATION_FORM,
+  APPLICATION_OCTET, TEXT_HTML, TEXT_PLAIN, TEXT_CSV, TEXT_XML,
+} from "./constants.js";
+export {
+  createToken, validateToken, getPayload,
+  hashPassword, checkPassword,
+  authMiddleware,
+  refreshToken, authenticateRequest, validateApiKey,
+} from "./auth.js";
+export { Session, FileSessionHandler, RedisSessionHandler } from "./session.js";
+export type { SessionConfig, SessionHandler } from "./session.js";
+export { I18n } from "./i18n.js";
+export { FakeData } from "./fakeData.js";
+export { ScssCompiler } from "./scss.js";
+export type { ScssConfig } from "./scss.js";
+export { Queue } from "./queue.js";
+export type { QueueConfig, QueueJob, ProcessOptions } from "./queue.js";
+export { GraphQL, ParseError } from "./graphql.js";
+export type { GraphQLField, ResolverFn, GraphQLResult } from "./graphql.js";
+export {
+  WebSocketServer,
+  computeAcceptKey, parseUpgradeHeaders, buildFrame, parseFrame,
+  OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG,
+  CLOSE_NORMAL, CLOSE_PROTOCOL_ERROR,
+} from "./websocket.js";
+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 type { ResponseCacheConfig } from "./cache.js";
+export { Api } from "./api.js";
+export type { ApiResult } from "./api.js";
+export { Events } from "./events.js";
+export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore, DevQueue, WsTracker } from "./devAdmin.js";
+export { Messenger } from "./messenger.js";
+export type { SendResult, EmailMessage } from "./messenger.js";
+export { DevMailbox, createMessenger } from "./devMailbox.js";
+export { WSDLService, WSDLOp } from "./wsdl.js";
+export type { WSDLOperation } from "./wsdl.js";
+export { HtmlElement, htmlElement, addHtmlHelpers } from "./htmlElement.js";
+export { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
+export { detectAi, detectAiNames, generateContext, installAiContext, installAllAiContext, aiStatusReport } from "./ai.js";
+export type { AiTool, AiDetection } from "./ai.js";
+export type { ImapMessage, ImapFullMessage } from "./messenger.js";
+export { RabbitMQBackend } from "./queueBackends/rabbitmqBackend.js";
+export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
+export { KafkaBackend } from "./queueBackends/kafkaBackend.js";
+export type { KafkaConfig } from "./queueBackends/kafkaBackend.js";
+export { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
+export type { MongoSessionConfig } from "./sessionHandlers/mongoHandler.js";
+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";

package/packages/core/src/logger.ts

@@ -0,0 +1,226 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { isTruthy } from "./dotenv.js";
+
+/** Log level severity */
+type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+
+/** Log level priority for filtering */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  DEBUG: 0,
+  INFO: 1,
+  WARNING: 2,
+  ERROR: 3,
+};
+
+/** Structured log entry for JSON output */
+interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  message: string;
+  request_id?: string;
+  context?: unknown;
+}
+
+/** ANSI color codes for terminal output */
+const COLORS: Record<LogLevel, string> = {
+  DEBUG: "\x1b[36m",   // cyan
+  INFO: "\x1b[32m",    // green
+  WARNING: "\x1b[33m", // yellow
+  ERROR: "\x1b[31m",   // red
+};
+const RESET = "\x1b[0m";
+
+/** Regex to strip ANSI escape codes */
+const ANSI_RE = /\033\[[0-9;]*m/g;
+
+/** Default log directory */
+const DEFAULT_LOG_DIR = "logs";
+
+/** Default log filename */
+const DEFAULT_LOG_FILE = "tina4.log";
+
+/** Strip ANSI escape codes from a string */
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_RE, "");
+}
+
+/**
+ * Structured logger for Tina4.
+ *
+ * Production (TINA4_DEBUG not truthy): JSON lines to logs/tina4.log
+ * Development (TINA4_DEBUG=true): Colorized human-readable to stdout + file
+ *
+ * Log rotation: numbered scheme (tina4.log -> tina4.log.1 -> ... -> tina4.log.{keep})
+ * Raw log file always writes ALL levels (no filtering), plain text (no ANSI codes).
+ * Console output respects TINA4_LOG_LEVEL.
+ */
+export class Log {
+  private static requestId: string | undefined;
+  private static logDir: string = DEFAULT_LOG_DIR;
+  private static logFile: string = DEFAULT_LOG_FILE;
+  private static maxFileSize: number = 10 * 1024 * 1024;
+  private static keepFiles: number = 5;
+  private static minLevel: number = 0;
+
+  /**
+   * Set the current request ID for log correlation.
+   */
+  static setRequestId(id: string | undefined): void {
+    Log.requestId = id;
+  }
+
+  /**
+   * Get the current request ID.
+   */
+  static getRequestId(): string | undefined {
+    return Log.requestId;
+  }
+
+  /**
+   * Configure the log directory, filename, and rotation settings.
+   */
+  static configure(options: { logDir?: string; logFile?: string }): void {
+    if (options.logDir) Log.logDir = options.logDir;
+    if (options.logFile) Log.logFile = options.logFile;
+
+    // Read rotation config from env (with defaults)
+    const maxSizeMb = parseInt(process.env.TINA4_LOG_MAX_SIZE ?? "10", 10);
+    Log.maxFileSize = (isNaN(maxSizeMb) ? 10 : maxSizeMb) * 1024 * 1024;
+    const keep = parseInt(process.env.TINA4_LOG_KEEP ?? "5", 10);
+    Log.keepFiles = isNaN(keep) ? 5 : keep;
+
+    // Resolve minimum console log level
+    const levelEnv = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
+    Log.minLevel = LEVEL_PRIORITY[levelEnv as LogLevel] ?? 0;
+  }
+
+  /** Log an informational message. */
+  static info(message: string, data?: unknown): void {
+    Log.log("INFO", message, data);
+  }
+
+  /** Log a debug message. */
+  static debug(message: string, data?: unknown): void {
+    Log.log("DEBUG", message, data);
+  }
+
+  /** Log a warning message. */
+  static warning(message: string, data?: unknown): void {
+    Log.log("WARNING", message, data);
+  }
+
+  /** Log an error message. */
+  static error(message: string, data?: unknown): void {
+    Log.log("ERROR", message, data);
+  }
+
+  /** Check if running in production mode (TINA4_DEBUG is not truthy). */
+  private static isProduction(): boolean {
+    return !isTruthy(process.env.TINA4_DEBUG);
+  }
+
+  /** Get current ISO timestamp */
+  private static timestamp(): string {
+    return new Date().toISOString();
+  }
+
+  /** Get the full path to the current log file */
+  private static logFilePath(): string {
+    return join(Log.logDir, Log.logFile);
+  }
+
+  /** Ensure the log directory exists */
+  private static ensureLogDir(): void {
+    const dir = dirname(Log.logFilePath());
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Rotate using numbered scheme: tina4.log.{keep} is deleted, all others shift up by 1.
+   */
+  private static rotateIfNeeded(): void {
+    const filePath = Log.logFilePath();
+    if (!existsSync(filePath)) return;
+
+    try {
+      const stats = statSync(filePath);
+      if (stats.size < Log.maxFileSize) return;
+    } catch {
+      return;
+    }
+
+    const keep = Log.keepFiles;
+
+    // Delete the oldest rotated file if it exists
+    const oldest = `${filePath}.${keep}`;
+    if (existsSync(oldest)) {
+      try { unlinkSync(oldest); } catch { /* ignore */ }
+    }
+
+    // Shift existing rotated files: .{n} -> .{n+1}
+    for (let n = keep - 1; n >= 1; n--) {
+      const src = `${filePath}.${n}`;
+      const dst = `${filePath}.${n + 1}`;
+      if (existsSync(src)) {
+        try { renameSync(src, dst); } catch { /* ignore */ }
+      }
+    }
+
+    // Rename current log to .1
+    try { renameSync(filePath, `${filePath}.1`); } catch { /* ignore */ }
+  }
+
+  /** Write a line to the log file, stripping ANSI codes */
+  private static writeToFile(line: string): void {
+    try {
+      Log.ensureLogDir();
+      Log.rotateIfNeeded();
+      appendFileSync(Log.logFilePath(), stripAnsi(line) + "\n", "utf-8");
+    } catch {
+      // Silently fail — logging should never crash the app
+    }
+  }
+
+  /** Core log method */
+  private static log(level: LogLevel, message: string, data?: unknown): void {
+    const entry: LogEntry = {
+      timestamp: Log.timestamp(),
+      level,
+      message,
+    };
+
+    if (Log.requestId) {
+      entry.request_id = Log.requestId;
+    }
+
+    if (data !== undefined) {
+      entry.context = data;
+    }
+
+    // Build human-readable line for file/console
+    const paddedLevel = level.padEnd(7);
+    const reqPart = Log.requestId ? ` [${Log.requestId}]` : "";
+    const dataPart = data !== undefined ? ` ${JSON.stringify(data)}` : "";
+    const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart} ${message}${dataPart}`;
+
+    // Console output respects TINA4_LOG_LEVEL
+    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= Log.minLevel;
+    if (!Log.isProduction() && shouldLog) {
+      const color = COLORS[level];
+      console.log(`${color}${humanLine}${RESET}`);
+    }
+
+    // File always gets ALL levels (raw log, no filtering), plain text (no ANSI)
+    Log.writeToFile(humanLine);
+  }
+}