tina4-nodejs 3.13.2 → 3.13.3

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.2)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.3)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.2 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.3 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.2",
+  "version": "3.13.3",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/env.ts

@@ -0,0 +1,113 @@
+/**
+ * Typed environment-variable helpers — zero-deps.
+ *
+ * Reading env vars by hand gets old fast: every boolean flag becomes a
+ * `(process.env.X ?? "false").toLowerCase() === "true" || ...` incantation,
+ * every numeric tuning knob needs a parseInt + isNaN guard. `Env` centralises
+ * that. Same API across all four Tina4 frameworks (`Tina4\Env` in PHP,
+ * `Tina4::Env` in Ruby, `Env` in Python).
+ *
+ *     import { Env } from "@tina4/core";
+ *
+ *     const debug   = Env.bool("TINA4_DEBUG");                // default false
+ *     const workers = Env.int("WORKERS", 4);
+ *     const rate    = Env.float("RATE_LIMIT", 10.0);
+ *     const region  = Env.str("AWS_REGION", "us-east-1");
+ *
+ * Values are accepted case-insensitively after `.trim().toLowerCase()`. Truthy:
+ * `1 / true / on / yes / y / t`. Falsy: `0 / false / off / no / n / f / ""`.
+ * Anything else returns `default`. Unparseable ints/floats log a warning via
+ * `Log` (when available) and fall back to `default` — never throw.
+ */
+const TRUTHY = new Set(["1", "true", "on", "yes", "y", "t"]);
+const FALSY = new Set(["0", "false", "off", "no", "n", "f", ""]);
+
+/**
+ * Emit a warning via Log without creating a circular import at module load.
+ * Log itself depends on env parsing, so we resolve it lazily and swallow any
+ * "not yet wired" errors (very early bootstrap, ESM cycle, etc.).
+ */
+function logWarning(message: string): void {
+  try {
+    // Lazy import to avoid the env → logger → env cycle.
+    // Top-level await isn't usable here (sync API), so we fire-and-forget.
+    import("./logger.js")
+      .then((mod) => {
+        try {
+          mod.Log.warn(message);
+        } catch {
+          /* Log not ready — skip */
+        }
+      })
+      .catch(() => {
+        /* Module not yet loadable — skip */
+      });
+  } catch {
+    /* Defensive — never let logging break the caller */
+  }
+}
+
+/**
+ * Typed environment-variable helpers.
+ *
+ * All methods are static so callers can write `Env.bool(...)` without
+ * instantiating anything — matching the Python/PHP/Ruby ports.
+ */
+export class Env {
+  /**
+   * Read `name` and coerce to bool.
+   *
+   * Truthy values (case-insensitive after trim): `1`, `true`, `on`, `yes`,
+   * `y`, `t`. Falsy: `0`, `false`, `off`, `no`, `n`, `f`, empty string.
+   * Anything else returns the `defaultValue` — never throws.
+   */
+  static bool(name: string, defaultValue = false): boolean {
+    const raw = process.env[name];
+    if (raw === undefined) return defaultValue;
+    const token = raw.trim().toLowerCase();
+    if (TRUTHY.has(token)) return true;
+    if (FALSY.has(token)) return false;
+    return defaultValue;
+  }
+
+  /** Read `name` and coerce to int. Returns `defaultValue` on parse failure. */
+  static int(name: string, defaultValue = 0): number {
+    const raw = process.env[name];
+    if (raw === undefined) return defaultValue;
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (Number.isNaN(parsed)) {
+      logWarning(
+        `Env.int(${JSON.stringify(name)}): could not parse ${JSON.stringify(raw)} as int — using default ${defaultValue}`,
+      );
+      return defaultValue;
+    }
+    return parsed;
+  }
+
+  /** Read `name` and coerce to float. Returns `defaultValue` on parse failure. */
+  static float(name: string, defaultValue = 0.0): number {
+    const raw = process.env[name];
+    if (raw === undefined) return defaultValue;
+    const parsed = Number.parseFloat(raw.trim());
+    if (Number.isNaN(parsed)) {
+      logWarning(
+        `Env.float(${JSON.stringify(name)}): could not parse ${JSON.stringify(raw)} as float — using default ${defaultValue}`,
+      );
+      return defaultValue;
+    }
+    return parsed;
+  }
+
+  /**
+   * Read `name` as a string. Returns `defaultValue` if unset.
+   *
+   * Whitespace is preserved — this is a pass-through for the raw env value.
+   * `Env.str("PATH")` is exactly `process.env.PATH ?? ""` with a more
+   * discoverable name.
+   */
+  static str(name: string, defaultValue = ""): string {
+    const raw = process.env[name];
+    if (raw === undefined) return defaultValue;
+    return raw;
+  }
+}

package/packages/core/src/index.ts

@@ -24,6 +24,7 @@ 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 { Env } from "./env.js";
 export { Log } from "./logger.js";
 export { createHealthRoute, createHealthRoutes, healthPath } from "./health.js";
 export { rateLimiter } from "./rateLimiter.js";

package/packages/core/src/logger.ts

@@ -28,9 +28,67 @@ interface LogEntry {
   level: LogLevel;
   message: string;
   request_id?: string;
+  function?: string;
   context?: unknown;
 }
 
+/**
+ * Log frames we walk past when looking for the real caller of a Log.* call.
+ * Mirrors Python's `_OWN_FRAMES`. Anything matching is treated as internal.
+ */
+const OWN_FRAMES = new Set<string>([
+  "log", "Log.log",
+  "callerName", "Log.callerName",
+  "info", "debug", "warning", "warn", "error", "critical",
+  "Log.info", "Log.debug", "Log.warning", "Log.warn", "Log.error", "Log.critical",
+]);
+
+/** V8 stack-trace markers that mean "no real function name". */
+const ANON_NAMES = new Set<string>(["", "anonymous", "<anonymous>"]);
+
+/**
+ * Return the function name that called Log.{info,debug,warning,error}.
+ *
+ * Active only when `TINA4_LOG_FUNC=true` — captures `new Error().stack`,
+ * walks past Log's own frames (info / warn / error / debug / log /
+ * callerName) and returns the first user function name. Anonymous frames
+ * (`anonymous`, `<anonymous>`, bare file paths) are filtered out as noise.
+ * Returns undefined on any error — never throws. Parity feature #41 across
+ * all four Tina4 frameworks.
+ */
+function callerName(): string | undefined {
+  // Read the env directly (not via Env.bool) to keep the logger ↔ env cycle
+  // one-way: env helpers depend on Log, not the other way around.
+  const raw = (process.env.TINA4_LOG_FUNC ?? "").trim().toLowerCase();
+  if (raw !== "1" && raw !== "true" && raw !== "on" && raw !== "yes" && raw !== "y" && raw !== "t") {
+    return undefined;
+  }
+  try {
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    const lines = stack.split("\n");
+    // Skip line 0 ("Error") and walk frames. Cap at 32 to defend against
+    // pathological recursion / wrapper stacks.
+    for (let i = 1; i < lines.length && i < 32; i++) {
+      const line = lines[i];
+      // V8 frame: "    at functionName (file:line:col)"
+      //        or "    at file:line:col"           (anonymous)
+      //        or "    at async functionName (...)"
+      const m = line.match(/^\s+at\s+(?:async\s+)?([^\s(]+)\s*\(/);
+      if (!m) continue;
+      const name = m[1];
+      // Strip the leading `Object.` / class prefix some V8s emit, then check.
+      const bare = name.includes(".") ? name.split(".").pop()! : name;
+      if (OWN_FRAMES.has(name) || OWN_FRAMES.has(bare)) continue;
+      if (ANON_NAMES.has(bare)) continue;
+      return bare;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** ANSI color codes for terminal output */
 const COLORS: Record<LogLevel, string> = {
   DEBUG: "\x1b[36m",    // cyan
@@ -308,6 +366,14 @@ export class Log {
       entry.request_id = Log.requestId;
     }
 
+    // Caller-name injection — opt-in via TINA4_LOG_FUNC=true. Off by default
+    // so existing log output stays byte-identical for users who haven't asked
+    // for it. Parity feature across all four Tina4 frameworks.
+    const fnName = callerName();
+    if (fnName) {
+      entry.function = fnName;
+    }
+
     if (data !== undefined) {
       entry.context = data;
     }
@@ -315,8 +381,9 @@ export class Log {
     // Build human-readable line
     const paddedLevel = level.padEnd(8);
     const reqPart = Log.requestId ? ` [${Log.requestId}]` : "";
+    const fnPart = fnName ? ` [${fnName}]` : "";
     const dataPart = data !== undefined ? ` ${JSON.stringify(data)}` : "";
-    const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart} ${message}${dataPart}`;
+    const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart}${fnPart} ${message}${dataPart}`;
 
     // Build the file-format line based on TINA4_LOG_FORMAT
     const fileLine = cfg.format === "json" ? JSON.stringify(entry) : humanLine;