tina4-nodejs 3.10.90 → 3.10.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.90",
+  "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/api.ts

@@ -36,7 +36,7 @@ export class Api {
     /**
      * Add custom headers to all subsequent requests.
      */
-    addCustomHeaders(headers: Record<string, string>): void {
+    addHeaders(headers: Record<string, string>): void {
         Object.assign(this.headers, headers);
     }
 
@@ -78,36 +78,36 @@ export class Api {
      * HTTP POST request.
      */
     async post(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "POST", body, contentType);
+        return this.sendRequest("POST", path, body, contentType);
     }
 
     /**
      * HTTP PUT request.
      */
     async put(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "PUT", body, contentType);
+        return this.sendRequest("PUT", path, body, contentType);
     }
 
     /**
      * HTTP PATCH request.
      */
     async patch(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "PATCH", body, contentType);
+        return this.sendRequest("PATCH", path, body, contentType);
     }
 
     /**
      * HTTP DELETE request.
      */
     async delete(path: string, body?: unknown): Promise<ApiResult> {
-        return this.sendRequest(path, "DELETE", body);
+        return this.sendRequest("DELETE", path, body);
     }
 
     /**
      * Generic request method — public entry point for any HTTP method.
      */
     async sendRequest(
-        path: string,
         method: string,
+        path: string,
         body?: unknown,
         contentType: string = "application/json",
     ): Promise<ApiResult> {

package/packages/core/src/auth.ts

@@ -35,32 +35,45 @@ function base64urlDecode(str: string): Buffer {
  * Secret is always read from `process.env.SECRET`.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  *
- * @param payload   - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
- * @param expiresIn - Lifetime in seconds (default 3600)
+ * @param payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
+ * @param secretOrExpiresIn - Signing secret string, OR expiresIn number (back-compat with old 2-arg form)
+ * @param expiresIn         - Lifetime in seconds (default 3600). Only used when secret is a string.
  * @returns Signed JWT string: header.payload.signature
  */
 export function getToken(
   payload: Record<string, unknown>,
+  secretOrExpiresIn?: string | number,
   expiresIn: number = 3600,
+  algorithm?: string,
 ): string {
-  const secret = process.env.SECRET ?? "";
-  if (!secret) {
+  // Back-compat: if second arg is a number, treat it as expiresIn (old 2-arg form)
+  let resolvedSecret: string;
+  let resolvedExpiresIn: number;
+  if (typeof secretOrExpiresIn === "number") {
+    resolvedSecret = process.env.SECRET ?? "";
+    resolvedExpiresIn = secretOrExpiresIn;
+  } else {
+    resolvedSecret = secretOrExpiresIn ?? process.env.SECRET ?? "";
+    resolvedExpiresIn = expiresIn;
+  }
+
+  if (!resolvedSecret) {
     console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
-  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
 
-  const header = { alg: algorithm, typ: "JWT" };
+  const header = { alg: resolvedAlgorithm, typ: "JWT" };
   const now = Math.floor(Date.now() / 1000);
 
   const claims: Record<string, unknown> = { ...payload, iat: now };
-  if (expiresIn !== 0) {
-    claims.exp = now + expiresIn;
+  if (resolvedExpiresIn !== 0) {
+    claims.exp = now + resolvedExpiresIn;
   }
 
   const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
   const p = base64urlEncode(Buffer.from(JSON.stringify(claims)));
   const signingInput = `${h}.${p}`;
-  const signature = sign(signingInput, secret, algorithm);
+  const signature = sign(signingInput, resolvedSecret, resolvedAlgorithm);
 
   return `${h}.${p}.${signature}`;
 }
@@ -71,12 +84,12 @@ export function getToken(
  * Secret is always read from `process.env.SECRET`.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  */
-export function validToken(token: string): boolean {
-  const secret = process.env.SECRET ?? "";
-  if (!secret) {
+export function validToken(token: string, secret?: string, algorithm?: string): boolean {
+  const resolvedSecret = secret ?? process.env.SECRET ?? "";
+  if (!resolvedSecret) {
     console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
-  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return false;
@@ -84,7 +97,7 @@ export function validToken(token: string): boolean {
     const [h, p, sig] = parts;
     const signingInput = `${h}.${p}`;
 
-    if (!verifySignature(signingInput, sig, secret as string, algorithm)) {
+    if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
       return false;
     }
 
@@ -211,7 +224,7 @@ export function authMiddleware(secret?: string, algorithm: string = "HS256"): Mi
     }
 
     const token = authHeader.slice(7);
-    if (!validToken(token)) {
+    if (!validToken(token, secret, algorithm)) {
       res({ error: "Unauthorized" }, 401);
       return;
     }

package/packages/core/src/cache.ts

@@ -501,6 +501,15 @@ export function cacheClear(): void {
   _getBackend().clear();
 }
 
+/** Remove expired entries from the cache. Returns count removed. */
+export function sweep(): number {
+  const backend = _getBackend();
+  if (typeof (backend as any).sweep === "function") {
+    return (backend as any).sweep();
+  }
+  return 0;
+}
+
 /** Return cache statistics from the active backend. */
 export function cacheBackendStats(): { hits: number; misses: number; size: number; backend: string } {
   return _getBackend().stats();

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/fakeData.ts

@@ -68,12 +68,6 @@ const JOB_TITLES = [
   "Systems Administrator",
 ];
 
-const COLORS = [
-  "red", "blue", "green", "yellow", "purple", "orange", "pink",
-  "cyan", "magenta", "teal", "indigo", "violet", "coral", "salmon",
-  "turquoise", "maroon", "navy", "olive", "silver", "gold",
-];
-
 const CURRENCIES = [
   "USD", "EUR", "GBP", "JPY", "AUD", "CAD", "CHF", "CNY",
   "SEK", "NZD", "MXN", "SGD", "HKD", "NOK", "ZAR", "INR",
@@ -137,7 +131,7 @@ export class FakeData {
     return this.pick(LAST_NAMES);
   }
 
-  fullName(): string {
+  name(): string {
     return `${this.firstName()} ${this.lastName()}`;
   }
 
@@ -209,7 +203,7 @@ export class FakeData {
     return this.randInt(min, max + 1);
   }
 
-  float(min = 0, max = 1000, decimals = 2): number {
+  numeric(min = 0, max = 1000, decimals = 2): number {
     const raw = min + this.rng() * (max - min);
     return Number(raw.toFixed(decimals));
   }
@@ -251,11 +245,7 @@ export class FakeData {
     return `${this.randInt(1, 256)}.${this.randInt(0, 256)}.${this.randInt(0, 256)}.${this.randInt(1, 256)}`;
   }
 
-  color(): string {
-    return this.pick(COLORS);
-  }
-
-  hexColor(): string {
+  colorHex(): string {
     const hex = this.randInt(0, 0x1000000).toString(16).padStart(6, "0");
     return `#${hex}`;
   }
@@ -270,11 +260,31 @@ export class FakeData {
     return this.pick(CURRENCIES);
   }
 
+  /**
+   * Returns multi-paragraph text.
+   * Matches Python's text() method.
+   */
+  text(paragraphs = 3): string {
+    const parts: string[] = [];
+    for (let i = 0; i < paragraphs; i++) {
+      parts.push(this.paragraph(4));
+    }
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Returns a random element from the given array.
+   * Matches Python's choice() method.
+   */
+  choice<T>(items: T[]): T {
+    return items[this.randInt(0, items.length)];
+  }
+
   /**
    * Run seed files from a directory. Each file should export a default async function.
    * Returns an array of executed file paths.
    */
-  async runSeeds(seedDir?: string): Promise<string[]> {
+  async seedDir(seedDir?: string): Promise<string[]> {
     const dir = resolve(seedDir ?? "src/seeds");
     if (!existsSync(dir)) return [];
     const files = readdirSync(dir)

package/packages/core/src/graphql.ts

@@ -69,7 +69,7 @@ const TOKEN_PATTERNS: Array<[string, RegExp]> = [
   ["COMMENT", /#[^\n]*/y],
 ];
 
-function tokenize(source: string): Token[] {
+export function tokenize(source: string): Token[] {
   const tokens: Token[] = [];
   let pos = 0;
 
@@ -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/i18n.ts

@@ -85,7 +85,7 @@ export class I18n {
   }
 
   /** List available locale codes based on JSON files in the locale directory. */
-  getAvailableLocales(): string[] {
+  availableLocales(): string[] {
     if (!existsSync(this._localeDir)) {
       return [this._defaultLocale];
     }

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/mcp.ts

@@ -990,3 +990,6 @@ export function registerDevTools(server: McpServer): void {
     schemaFromParams([]),
   );
 }
+
+/** Alias for registerDevTools — parity with PHP/Ruby/Python. */
+export const register = registerDevTools;

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.
    */