tina4-nodejs 3.10.91 → 3.10.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.91",
+  "version": "3.10.92",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/ai.ts

@@ -608,7 +608,7 @@ npx tina4nodejs test      # Run all tests
 
 Add test files in \`test/\` directory. Use built-in inline testing:
 \`\`\`typescript
-import { tests, assertEqual, runAllTests } from "@tina4/core";
+import { tests, assertEqual, runAll } from "@tina4/core";
 \`\`\`
 
 ## Important

package/packages/core/src/devAdmin.ts

@@ -191,15 +191,40 @@ export class RequestInspector {
 
 export class ErrorTracker {
   private static errors: ErrorEntry[] = [];
+  private static maxErrors = 200;
+  private static registered = false;
 
+  /**
+   * Capture an error with dedup (matches PHP/Ruby/Python signature).
+   * Duplicate errors (same message) increment count and update last_seen.
+   */
+  static capture(errorType: string, message: string, traceback = "", file = "", line = 0): void {
+    const fingerprint = `${errorType}|${message}|${file}|${line}`;
+    const existing = this.errors.find((e) => (e as any).fingerprint === fingerprint);
+    const now = new Date().toISOString();
+
+    if (existing) {
+      (existing as any).count = ((existing as any).count || 1) + 1;
+      (existing as any).last_seen = now;
+      existing.resolved = false; // re-open resolved duplicates
+    } else {
+      this.errors.push({
+        id: `err_${Date.now()}_${this.errors.length}`,
+        timestamp: now,
+        message,
+        stack: traceback || undefined,
+        resolved: false,
+        ...({ fingerprint, error_type: errorType, file, line, count: 1, first_seen: now, last_seen: now } as any),
+      });
+      if (this.errors.length > this.maxErrors) {
+        this.errors = this.errors.slice(-this.maxErrors);
+      }
+    }
+  }
+
+  /** Legacy alias for capture (backward compatibility). */
   static track(message: string, stack?: string): void {
-    this.errors.push({
-      id: `err_${Date.now()}_${this.errors.length}`,
-      timestamp: new Date().toISOString(),
-      message,
-      stack,
-      resolved: false,
-    });
+    this.capture("Error", message, stack || "");
   }
 
   static get(): ErrorEntry[] {
@@ -218,6 +243,56 @@ export class ErrorTracker {
   static clearResolved(): void {
     this.errors = this.errors.filter((e) => !e.resolved);
   }
+
+  /** Remove ALL tracked errors. */
+  static clearAll(): void {
+    this.errors = [];
+  }
+
+  /** Health summary — are there unresolved errors? */
+  static health(): { healthy: boolean; total: number; unresolved: number; resolved: number } {
+    const total = this.errors.length;
+    const resolved = this.errors.filter((e) => e.resolved).length;
+    const unresolved = total - resolved;
+    return { healthy: unresolved === 0, total, unresolved, resolved };
+  }
+
+  /** Count of unresolved errors. */
+  static unresolvedCount(): number {
+    return this.errors.filter((e) => !e.resolved).length;
+  }
+
+  /** Reset all state (for testing). */
+  static reset(): void {
+    this.errors = [];
+    this.registered = false;
+  }
+
+  /**
+   * Register global error handlers to feed the tracker.
+   * Safe to call multiple times — only registers once.
+   */
+  static register(): void {
+    if (this.registered) return;
+    this.registered = true;
+
+    process.on("uncaughtException", (err: Error) => {
+      this.capture(
+        err.constructor.name,
+        err.message,
+        err.stack || "",
+      );
+    });
+
+    process.on("unhandledRejection", (reason: unknown) => {
+      const err = reason instanceof Error ? reason : new Error(String(reason));
+      this.capture(
+        err.constructor.name,
+        err.message,
+        err.stack || "",
+      );
+    });
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -355,6 +430,9 @@ export class DevAdmin {
    * Register all /__dev routes on the given router.
    */
   static register(router: Router): void {
+    // Register error handlers to feed the ErrorTracker
+    ErrorTracker.register();
+
     const routes: Array<{ method: string; pattern: string; handler: RouteHandler }> = [
       // Dashboard
       { method: "GET", pattern: "/__dev", handler: handleDashboard },

package/packages/core/src/devMailbox.ts

@@ -7,7 +7,7 @@
  *   import { DevMailbox, createMessenger } from "@tina4/core";
  *
  *   const mailbox = new DevMailbox();
- *   mailbox.capture({ to: "alice@test.com", subject: "Hello", body: "Hi!" });
+ *   mailbox.capture("alice@test.com", "Hello", "Hi!");
  *   const messages = mailbox.inbox();
  */
 import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
@@ -39,33 +39,33 @@ export class DevMailbox {
   /**
    * Capture an email to the dev mailbox instead of sending it.
    */
-  capture(options: {
-    to: string | string[];
-    subject: string;
-    body: string;
-    html?: boolean;
-    cc?: string[];
-    bcc?: string[];
-    replyTo?: string;
-    attachments?: string[];
-    from?: string;
-  }): SendResult {
+  capture(
+    to: string | string[],
+    subject: string,
+    body: string,
+    html: boolean = false,
+    cc: string[] = [],
+    bcc: string[] = [],
+    replyTo?: string,
+    attachments: string[] = [],
+    from?: string,
+  ): SendResult {
     const id = randomUUID();
-    const toList = Array.isArray(options.to) ? options.to : [options.to];
+    const toList = Array.isArray(to) ? to : [to];
     const now = new Date().toISOString();
 
     const message: EmailMessage = {
       id,
       type: "outbox",
-      from: options.from ?? process.env.SMTP_FROM ?? "dev@localhost",
+      from: from ?? process.env.SMTP_FROM ?? "dev@localhost",
       to: toList,
-      cc: options.cc ?? [],
-      bcc: options.bcc ?? [],
-      reply_to: options.replyTo,
-      subject: options.subject,
-      body: options.body,
-      html: options.html ?? false,
-      attachments: options.attachments ?? [],
+      cc,
+      bcc,
+      reply_to: replyTo,
+      subject,
+      body,
+      html,
+      attachments,
       date: now,
       read: false,
     };

package/packages/core/src/graphql.ts

@@ -932,3 +932,39 @@ export class GraphQL {
     return resolved;
   }
 }
+
+/**
+ * Lightweight GraphQL type wrapper matching Ruby's GraphQLType.
+ */
+export class GraphQLType {
+  static readonly SCALARS = ["String", "Int", "Float", "Boolean", "ID"];
+
+  name: string;
+  kind: string;
+  ofType: GraphQLType | null;
+
+  constructor(name: string, kind: string = "object", ofType: GraphQLType | null = null) {
+    this.name = name;
+    this.kind = kind;
+    this.ofType = ofType;
+  }
+
+  /**
+   * Parse a GraphQL type string like "String", "String!", "[Int!]!".
+   */
+  static parse(typeStr: string): GraphQLType {
+    const s = String(typeStr).trim();
+    if (s.endsWith("!")) {
+      const inner = GraphQLType.parse(s.slice(0, -1));
+      return new GraphQLType(s, "non_null", inner);
+    }
+    if (s.startsWith("[") && s.endsWith("]")) {
+      const inner = GraphQLType.parse(s.slice(1, -1));
+      return new GraphQLType(s, "list", inner);
+    }
+    if (GraphQLType.SCALARS.includes(s)) {
+      return new GraphQLType(s, "scalar");
+    }
+    return new GraphQLType(s, "object");
+  }
+}

package/packages/core/src/index.ts

@@ -12,15 +12,15 @@ export type {
   WebSocketRouteDefinition,
 } from "./types.js";
 
-export { startServer, resolvePortAndHost, handle } from "./server.js";
+export { startServer, resolvePortAndHost, handle, start, stop } from "./server.js";
 export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
 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, SecurityHeadersMiddleware, CsrfMiddleware } from "./middleware.js";
 export type { CorsConfig } from "./middleware.js";
-export { createRequest, parseBody } from "./request.js";
-export { createResponse, errorResponse, setDefaultTemplatesDir } from "./response.js";
+export { createRequest } from "./request.js";
+export { createResponse, errorResponse, setDefaultTemplatesDir, getFrond, setFrond, getFrameworkFrond } from "./response.js";
 export { tryServeStatic } from "./static.js";
 export { loadEnv, getEnv, requireEnv, hasEnv, allEnv, resetEnv, isTruthy } from "./dotenv.js";
 export { Log } from "./logger.js";
@@ -74,8 +74,8 @@ export { DevAdmin, MessageLog, RequestInspector, ErrorTracker, DevMailboxStore,
 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 { WSDLService, WSDLOperation } from "./wsdl.js";
+export type { WSDLOperationMeta } from "./wsdl.js";
 export { HtmlElement, htmlElement, addHtmlHelpers } from "./htmlElement.js";
 export { renderErrorOverlay, renderProductionError, isDebugMode } from "./errorOverlay.js";
 export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateContext } from "./ai.js";
@@ -96,7 +96,7 @@ export { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 export type { ValkeySessionConfig } from "./sessionHandlers/valkeyHandler.js";
 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 { tests, assertEqual, assertRaises, assertTrue, assertFalse, runAll, reset } from "./testing.js";
 export { TestClient, TestResponse } from "./testClient.js";
 export { Container, container } from "./container.js";
 export { Validator } from "./validator.js";

package/packages/core/src/messenger.ts

@@ -21,7 +21,7 @@
  *
  *   const mail = new Messenger();                                      // reads from .env
  *   const mail = new Messenger({ host: "smtp.office365.com", port: 587 }); // override
- *   await mail.send({ to: "user@test.com", subject: "Welcome", body: "<h1>Hello!</h1>", html: true, text: "Hello!" });
+ *   await mail.send("user@test.com", "Welcome", "<h1>Hello!</h1>", true, "Hello!");
  */
 import net from "node:net";
 import tls from "node:tls";
@@ -355,7 +355,19 @@ export class Messenger {
   /**
    * Send an email via SMTP.
    */
-  async send(options: SendOptions): Promise<SendResult> {
+  async send(
+    to: string | string[],
+    subject: string,
+    body: string,
+    html: boolean = false,
+    text?: string,
+    cc?: string | string[],
+    bcc?: string | string[],
+    replyTo?: string,
+    attachments?: string[],
+    headers?: Record<string, string>,
+  ): Promise<SendResult> {
+    const options: SendOptions = { to, subject, body, html, text, cc, bcc, replyTo, attachments, headers };
     const toList = Array.isArray(options.to) ? options.to : [options.to];
     const ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
     const bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
@@ -655,7 +667,24 @@ export class Messenger {
   /**
    * Search messages using IMAP search criteria.
    */
-  async search(query: string, folder: string = "INBOX"): Promise<ImapMessage[]> {
+  async search(
+    folder: string = "INBOX",
+    subject?: string,
+    sender?: string,
+    since?: string,
+    before?: string,
+    unseenOnly: boolean = false,
+    limit: number = 50,
+  ): Promise<ImapMessage[]> {
+    // Build IMAP SEARCH criteria from structured params
+    const criteria: string[] = ["ALL"];
+    if (subject) criteria.push(`SUBJECT "${subject}"`);
+    if (sender) criteria.push(`FROM "${sender}"`);
+    if (since) criteria.push(`SINCE ${since}`);
+    if (before) criteria.push(`BEFORE ${before}`);
+    if (unseenOnly) criteria.push("UNSEEN");
+
+    const query = criteria.join(" ");
     const socket = await this.imapConnect();
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
@@ -665,7 +694,7 @@ export class Messenger {
 
       uids.reverse();
       const messages: ImapMessage[] = [];
-      for (const uid of uids.slice(0, 50)) {
+      for (const uid of uids.slice(0, limit)) {
         const fetchResp = await imapCommand(socket, `FETCH ${uid} (FLAGS BODY.PEEK[HEADER.FIELDS (FROM TO SUBJECT DATE)])`);
         messages.push(parseHeaderResponse(uid, fetchResp));
       }
@@ -716,6 +745,25 @@ export class Messenger {
     }
   }
 
+  /**
+   * List available IMAP folders/mailboxes.
+   */
+  async folders(): Promise<string[]> {
+    const socket = await this.imapConnect();
+    try {
+      const resp = await imapCommand(socket, 'LIST "" "*"');
+      const result: string[] = [];
+      for (const line of resp.split("\r\n")) {
+        // Parse LIST response: * LIST (\flags) "/" "FolderName"
+        const m = line.match(/\* LIST \([^)]*\) "[^"]*" "?([^"\r\n]+)"?/i);
+        if (m) result.push(m[1]);
+      }
+      return result;
+    } finally {
+      await this.imapDisconnect(socket);
+    }
+  }
+
   /**
    * Test IMAP connectivity without reading.
    */

package/packages/core/src/middleware.ts

@@ -268,6 +268,13 @@ export class CorsMiddleware {
 
     return [req, res];
   }
+
+  /**
+   * Check if a request is an OPTIONS preflight.
+   */
+  static isPreflight(method: string): boolean {
+    return method?.toUpperCase() === "OPTIONS";
+  }
 }
 
 /**
@@ -354,6 +361,36 @@ export class RateLimiterMiddleware {
     entry.timestamps.push(now);
     return [req, res];
   }
+
+  /**
+   * Check if an IP is within rate limits without recording a request.
+   * Returns [allowed, info] matching Python/Ruby API.
+   */
+  static check(ip: string): [boolean, { limit: number; remaining: number; reset: number; window: number }] {
+    const limit = process.env.TINA4_RATE_LIMIT ? parseInt(process.env.TINA4_RATE_LIMIT, 10) : 100;
+    const windowSeconds = process.env.TINA4_RATE_WINDOW ? parseInt(process.env.TINA4_RATE_WINDOW, 10) : 60;
+    const windowMs = windowSeconds * 1000;
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    let entry = RateLimiterMiddleware.store.get(ip);
+    if (!entry) {
+      entry = { timestamps: [] };
+      RateLimiterMiddleware.store.set(ip, entry);
+    }
+    entry.timestamps = entry.timestamps.filter((t) => t > cutoff);
+
+    const remaining = Math.max(0, limit - entry.timestamps.length);
+    const reset = entry.timestamps.length > 0
+      ? Math.ceil((entry.timestamps[0] + windowMs - now) / 1000)
+      : windowSeconds;
+
+    if (entry.timestamps.length >= limit) {
+      return [false, { limit, remaining: 0, reset, window: windowSeconds }];
+    }
+
+    return [true, { limit, remaining: remaining - 1, reset: windowSeconds, window: windowSeconds }];
+  }
 }
 
 /**

package/packages/core/src/rateLimiter.ts

@@ -1,4 +1,4 @@
-import type { Middleware } from "./types.js";
+import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
 
 /** Per-IP sliding window entry */
 interface RateLimitEntry {
@@ -105,3 +105,90 @@ export function rateLimiter(config?: RateLimiterConfig): Middleware {
     next();
   };
 }
+
+/** Rate limit check result */
+export interface RateLimitResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  reset: number;
+  retryAfter?: number;
+}
+
+/**
+ * Class-based rate limiter with check/reset/apply methods.
+ * Matches the Python/PHP/Ruby API surface.
+ */
+export class RateLimiter {
+  readonly limit: number;
+  readonly window: number;
+  private store = new Map<string, number[]>();
+
+  constructor(config?: RateLimiterConfig) {
+    this.limit = config?.limit
+      ?? (process.env.TINA4_RATE_LIMIT ? parseInt(process.env.TINA4_RATE_LIMIT, 10) : 100);
+    this.window = config?.windowSeconds
+      ?? (process.env.TINA4_RATE_WINDOW ? parseInt(process.env.TINA4_RATE_WINDOW, 10) : 60);
+  }
+
+  /** Check if a request from the given IP is allowed. */
+  check(ip: string): RateLimitResult {
+    const now = Date.now();
+    const windowMs = this.window * 1000;
+    const cutoff = now - windowMs;
+
+    let timestamps = this.store.get(ip);
+    if (!timestamps) {
+      timestamps = [];
+      this.store.set(ip, timestamps);
+    }
+
+    // Prune expired
+    const filtered = timestamps.filter((t) => t > cutoff);
+    this.store.set(ip, filtered);
+
+    const resetTime = filtered.length > 0
+      ? Math.ceil((filtered[0] + windowMs) / 1000)
+      : Math.ceil((now + windowMs) / 1000);
+
+    if (filtered.length >= this.limit) {
+      const retryAfter = Math.max(1, resetTime - Math.ceil(now / 1000));
+      return { allowed: false, limit: this.limit, remaining: 0, reset: resetTime, retryAfter };
+    }
+
+    filtered.push(now);
+    return {
+      allowed: true,
+      limit: this.limit,
+      remaining: this.limit - filtered.length,
+      reset: resetTime,
+    };
+  }
+
+  /** Clear all tracked request data. */
+  reset(): void {
+    this.store.clear();
+  }
+
+  /** Apply rate limiting to a request/response pair. Sets headers and 429 if exceeded. */
+  apply(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response] {
+    const ip = (request as Record<string, unknown>).ip as string ?? "unknown";
+    const result = this.check(ip);
+
+    response.header("X-RateLimit-Limit", String(result.limit));
+    response.header("X-RateLimit-Remaining", String(result.remaining));
+    response.header("X-RateLimit-Reset", String(result.reset));
+
+    if (!result.allowed) {
+      response.header("Retry-After", String(result.retryAfter ?? 1));
+      response({ error: "Too Many Requests", retryAfter: result.retryAfter }, 429);
+    }
+
+    return [request, response];
+  }
+
+  /** Middleware hook — enforces rate limiting before the route handler. */
+  beforeRateLimit(request: Tina4Request, response: Tina4Response): [Tina4Request, Tina4Response] {
+    return this.apply(request, response);
+  }
+}

package/packages/core/src/request.ts

@@ -36,6 +36,29 @@ export function createRequest(req: IncomingMessage): Tina4Request {
     tReq.ip = req.socket?.remoteAddress ?? "127.0.0.1";
   }
 
+  // Add convenience methods
+  tReq.header = function (name: string): string | undefined {
+    const val = req.headers[name.toLowerCase()];
+    if (Array.isArray(val)) return val[0];
+    return val;
+  };
+
+  tReq.bearerToken = function (): string | null {
+    const auth = tReq.header("authorization") ?? "";
+    if (auth.toLowerCase().startsWith("bearer ")) {
+      return auth.slice(7);
+    }
+    return null;
+  };
+
+  tReq.param = function (key: string, defaultValue?: string): string | undefined {
+    return tReq.params[key] ?? tReq.query[key] ?? defaultValue;
+  };
+
+  tReq.parseBody = function (): Promise<void> {
+    return parseBody(tReq);
+  };
+
   return tReq;
 }
 
@@ -50,7 +73,7 @@ export class PayloadTooLargeError extends Error {
   }
 }
 
-export async function parseBody(req: Tina4Request): Promise<void> {
+async function parseBody(req: Tina4Request): Promise<void> {
   const method = req.method?.toUpperCase();
   if (method === "GET" || method === "HEAD" || method === "OPTIONS") return;
 

package/packages/core/src/response.ts

@@ -9,14 +9,67 @@ const _frondCache = new Map<string, InstanceType<any>>();
 /** Default templates directory — set via setDefaultTemplatesDir(). */
 let _defaultTemplatesDir: string | null = null;
 
+/** Global user Frond engine — set via setFrond(). */
+let _globalFrond: InstanceType<any> | null = null;
+
+/** Singleton framework Frond engine for built-in templates. */
+let _frameworkFrond: InstanceType<any> | null = null;
+
 /**
- * Set the default templates directory for render()/template().
+ * Set the default templates directory for render().
  * Called by server.ts during startup.
  */
 export function setDefaultTemplatesDir(dir: string): void {
   _defaultTemplatesDir = dir;
 }
 
+/**
+ * Return the global Frond engine, creating a default if needed.
+ */
+export async function getFrond(): Promise<InstanceType<any>> {
+  if (_globalFrond) return _globalFrond;
+  const dir = _defaultTemplatesDir ?? nodePath.resolve(process.cwd(), "src/templates");
+  let engine = _frondCache.get(dir);
+  if (!engine) {
+    const { Frond } = await import("@tina4/frond");
+    engine = new Frond(dir);
+    _frondCache.set(dir, engine);
+  }
+  _globalFrond = engine;
+  return engine;
+}
+
+/**
+ * Return the singleton Frond engine for built-in framework templates.
+ * Syncs custom filters/globals from the user engine.
+ */
+export async function getFrameworkFrond(): Promise<InstanceType<any> | null> {
+  const frameworkDir = nodePath.resolve(nodePath.dirname(import.meta.url.replace("file://", "")), "..", "templates");
+  if (!_frameworkFrond && fs.existsSync(frameworkDir)) {
+    try {
+      const { Frond } = await import("@tina4/frond");
+      _frameworkFrond = new Frond(frameworkDir);
+    } catch { return null; }
+  }
+  // Sync custom filters/globals from the user engine
+  if (_frameworkFrond && _globalFrond) {
+    if (typeof _globalFrond._filters === "object") {
+      Object.assign(_frameworkFrond._filters ??= {}, _globalFrond._filters);
+    }
+    if (typeof _globalFrond._globals === "object") {
+      Object.assign(_frameworkFrond._globals ??= {}, _globalFrond._globals);
+    }
+  }
+  return _frameworkFrond;
+}
+
+/**
+ * Register a pre-configured Frond engine for response.render().
+ */
+export function setFrond(engine: InstanceType<any>): void {
+  _globalFrond = engine;
+}
+
 /**
  * Creates a callable response object.
  *
@@ -233,15 +286,6 @@ export function createResponse(res: ServerResponse): Tina4Response {
     }
   };
 
-  response.template = async function (
-    name: string,
-    data?: Record<string, unknown>,
-    status?: number,
-    templateDir?: string,
-  ): Promise<Tina4Response> {
-    return response.render(name, data, status, templateDir);
-  };
-
   /**
    * Stream response from an async generator for Server-Sent Events (SSE).
    *