tina4-nodejs 3.13.1 → 3.13.3

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.1)
+# 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.1 — 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.1",
+  "version": "3.13.3",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/ai.ts

@@ -424,7 +424,7 @@ npx tina4nodejs routes    # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\` (e.g. \`postgres://localhost:5432/mydb\`).
+Set \`TINA4_DATABASE_URL\` in \`.env\` (e.g. \`postgres://localhost:5432/mydb\`).
 
 ## Auth
 
@@ -485,7 +485,7 @@ npx tina4nodejs routes    # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\`.
+Set \`TINA4_DATABASE_URL\` in \`.env\`.
 `;
 }
 
@@ -593,7 +593,7 @@ npx tina4nodejs routes          # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\` (e.g. \`sqlite:///path/to/db.sqlite\`, \`postgres://localhost:5432/mydb\`).
+Set \`TINA4_DATABASE_URL\` in \`.env\` (e.g. \`sqlite:///path/to/db.sqlite\`, \`postgres://localhost:5432/mydb\`).
 
 ## Auth
 
@@ -693,7 +693,7 @@ npx tina4nodejs routes          # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\`.
+Set \`TINA4_DATABASE_URL\` in \`.env\`.
 
 ## Auth
 

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;

package/packages/core/src/scss.ts

@@ -251,30 +251,70 @@ function resolveIncludes(
 // ── Math Evaluation ──────────────────────────────────────────────
 
 function evalMath(scss: string): string {
-  return scss.replace(
+  // Mixed-unit arithmetic is left verbatim — that is exactly what CSS calc()
+  // is for, and folding it silently produces invalid output (see tina4-nodejs#1).
+  // Math inside calc(...) is preserved untouched on the same principle: the
+  // author asked the browser to compute it.
+  //
+  // Rules for folding:
+  //   * Both operands unitless                  → fold
+  //   * Same unit on both operands              → fold, keep unit
+  //   * One operand unitless for * or /         → fold, keep the other unit
+  //   * Anything else (mixed units on +/-, etc) → leave verbatim
+
+  // Step 1 — mask calc(...) ranges so the math regex cannot eat into them.
+  const placeholders: string[] = [];
+  const masked = scss.replace(/calc\([^()]*\)/g, (m) => {
+    placeholders.push(m);
+    return `\x00CALC${placeholders.length - 1}\x00`;
+  });
+
+  // Step 2 — run the math fold on what remains.
+  const folded = masked.replace(
     /([\d.]+)([a-z%]*)\s*([+\-*/])\s*([\d.]+)([a-z%]*)/g,
-    (_m, n1: string, u1: string, op: string, n2: string, _u2: string) => {
-      try {
-        const num1 = parseFloat(n1);
-        const num2 = parseFloat(n2);
-        let result: number;
-        switch (op) {
-          case "+": result = num1 + num2; break;
-          case "-": result = num1 - num2; break;
-          case "*": result = num1 * num2; break;
-          case "/": result = num2 !== 0 ? num1 / num2 : 0; break;
-          default: return _m;
-        }
-        const unit = u1 || "";
-        if (result === Math.floor(result)) {
-          return `${Math.floor(result)}${unit}`;
-        }
-        return `${result.toFixed(2)}${unit}`;
-      } catch {
-        return _m;
+    (full, n1: string, u1: string, op: string, n2: string, u2: string) => {
+      const num1 = parseFloat(n1);
+      const num2 = parseFloat(n2);
+      if (Number.isNaN(num1) || Number.isNaN(num2)) return full;
+
+      const unit1 = u1 || "";
+      const unit2 = u2 || "";
+
+      // Decide result unit; bail if units are incompatible.
+      let unit: string;
+      if (unit1 === unit2) {
+        unit = unit1;
+      } else if ((op === "*" || op === "/") && unit1 === "") {
+        unit = unit2;
+      } else if ((op === "*" || op === "/") && unit2 === "") {
+        unit = unit1;
+      } else {
+        return full;
       }
+
+      let result: number;
+      switch (op) {
+        case "+": result = num1 + num2; break;
+        case "-": result = num1 - num2; break;
+        case "*": result = num1 * num2; break;
+        case "/":
+          if (num2 === 0) return full;
+          result = num1 / num2;
+          break;
+        default: return full;
+      }
+
+      if (result === Math.floor(result)) {
+        return `${Math.floor(result)}${unit}`;
+      }
+      return `${result.toFixed(2)}${unit}`;
     }
   );
+
+  // Step 3 — restore the calc() ranges verbatim.
+  return folded.replace(/\x00CALC(\d+)\x00/g, (_m, idx: string) => {
+    return placeholders[parseInt(idx, 10)];
+  });
 }
 
 // ── Nesting Flattener ────────────────────────────────────────────

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -5,7 +5,7 @@
  * Stores sessions in a `tina4_session` table with JSON data and expiry.
  *
  * Configure via environment variables:
- *   DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
+ *   TINA4_DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
  *
  * The handler dynamically imports `better-sqlite3` and throws a clear
  * error if the package is not installed.
@@ -20,7 +20,7 @@ interface SessionData {
 }
 
 export interface DatabaseSessionConfig {
-  /** SQLite database file path (default: extracted from DATABASE_URL or "data/tina4_sessions.db") */
+  /** SQLite database file path (default: extracted from TINA4_DATABASE_URL or "data/tina4_sessions.db") */
   dbPath?: string;
 }
 

package/packages/orm/src/baseModel.ts

@@ -206,7 +206,7 @@ export class BaseModel {
 
   /**
    * Get the database adapter for this model.
-   * If no adapter is registered, attempts auto-discovery from DATABASE_URL.
+   * If no adapter is registered, attempts auto-discovery from TINA4_DATABASE_URL.
    * SQLite URLs are initialised synchronously. Other engines require initDatabase()
    * to be called before first use.
    */
@@ -229,12 +229,12 @@ export class BaseModel {
           return adapter;
         }
         throw new Error(
-          `DATABASE_URL is set to a non-SQLite engine ("${parsed.type}"). ` +
+          `TINA4_DATABASE_URL is set to a non-SQLite engine ("${parsed.type}"). ` +
           `Call await initDatabase() at startup before using ORM models.`,
         );
       }
       throw new Error(
-        "No database adapter configured. Call initDatabase() or set DATABASE_URL in .env.",
+        "No database adapter configured. Call initDatabase() or set TINA4_DATABASE_URL in .env.",
       );
     }
   }

package/packages/orm/src/database.ts

@@ -60,7 +60,7 @@ export interface DatabaseConfig {
 }
 
 /**
- * Parsed result from a DATABASE_URL connection string.
+ * Parsed result from a TINA4_DATABASE_URL connection string.
  */
 export interface ParsedDatabaseUrl {
   type: "sqlite" | "postgres" | "mysql" | "mssql" | "firebird" | "mongodb" | "odbc";
@@ -75,7 +75,7 @@ export interface ParsedDatabaseUrl {
 }
 
 /**
- * Parse a DATABASE_URL connection string into its components.
+ * Parse a TINA4_DATABASE_URL connection string into its components.
  *
  * Supported formats:
  *   sqlite:///path/to/db.sqlite
@@ -325,10 +325,10 @@ 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 envKey - Name of the env var holding the connection URL. Defaults to "TINA4_DATABASE_URL".
    * @param pool - Number of pooled connections (0 = single, N>0 = round-robin)
    */
-  static async fromEnv(envKey = "DATABASE_URL", pool: number = 0): Promise<Database> {
+  static async fromEnv(envKey = "TINA4_DATABASE_URL", pool: number = 0): Promise<Database> {
     const url = process.env[envKey];
     if (!url) {
       throw new Error(`Environment variable "${envKey}" is not set.`);