tina4-nodejs 3.10.87 → 3.10.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.87",
+  "version": "3.10.89",
   "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/frond/src/engine.ts

@@ -19,6 +19,126 @@ class SafeString {
   toString() { return this.value; }
 }
 
+/**
+ * Produce a human-readable, debugger-friendly inspection of any value.
+ *
+ * Equivalent to PHP's var_dump, Python's repr, and Ruby's inspect. Unlike
+ * JSON.stringify (the previous implementation) this handles:
+ *   - Circular references (marked as [Circular])
+ *   - BigInt (shown as `123n`)
+ *   - undefined, Symbol, and function values (shown inline, not dropped)
+ *   - Date, Map, Set, Error, RegExp (shown with their type and contents)
+ *   - Class instances (shown with the class name prefix)
+ *
+ * Used by both the `|dump` filter and the `dump()` global function.
+ * Output is a plain string; callers wrap it in <pre> and mark it safe so
+ * the template engine doesn't double-escape.
+ */
+function inspectValue(value: unknown, seen: WeakSet<object> = new WeakSet(), depth = 0): string {
+  // Primitives
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") {
+    const name = value.name || "(anonymous)";
+    return `[Function: ${name}]`;
+  }
+
+  // value is now object (including arrays, Date, Map, Set, etc.)
+  const obj = value as object;
+
+  // Cycle detection
+  if (seen.has(obj)) return "[Circular]";
+  seen.add(obj);
+
+  // Depth cap — prevents runaway recursion on enormous graphs
+  if (depth > 8) return "[...]";
+
+  try {
+    // Date
+    if (obj instanceof Date) {
+      return `Date(${obj.toISOString()})`;
+    }
+
+    // RegExp
+    if (obj instanceof RegExp) {
+      return obj.toString();
+    }
+
+    // Error
+    if (obj instanceof Error) {
+      return `${obj.constructor.name}(${JSON.stringify(obj.message)})`;
+    }
+
+    // Map
+    if (obj instanceof Map) {
+      if (obj.size === 0) return "Map(0) {}";
+      const entries: string[] = [];
+      for (const [k, v] of obj) {
+        entries.push(`${inspectValue(k, seen, depth + 1)} => ${inspectValue(v, seen, depth + 1)}`);
+      }
+      return `Map(${obj.size}) { ${entries.join(", ")} }`;
+    }
+
+    // Set
+    if (obj instanceof Set) {
+      if (obj.size === 0) return "Set(0) {}";
+      const items: string[] = [];
+      for (const v of obj) {
+        items.push(inspectValue(v, seen, depth + 1));
+      }
+      return `Set(${obj.size}) { ${items.join(", ")} }`;
+    }
+
+    // Array
+    if (Array.isArray(obj)) {
+      if (obj.length === 0) return "[]";
+      const items = obj.map((v) => inspectValue(v, seen, depth + 1));
+      return `[${items.join(", ")}]`;
+    }
+
+    // Plain object or class instance
+    const keys = Object.keys(obj);
+    const className = obj.constructor && obj.constructor.name !== "Object"
+      ? `${obj.constructor.name} `
+      : "";
+    if (keys.length === 0) return `${className}{}`;
+    const props = keys.map((k) => {
+      const v = (obj as Record<string, unknown>)[k];
+      return `${k}: ${inspectValue(v, seen, depth + 1)}`;
+    });
+    return `${className}{ ${props.join(", ")} }`;
+  } finally {
+    seen.delete(obj);
+  }
+}
+
+/**
+ * Render a value as a pre-formatted, HTML-escaped dump wrapped in <pre> tags.
+ * Returns a SafeString so the template engine does not double-escape the
+ * entities. Shared by the `|dump` filter and the `dump()` global function.
+ *
+ * Gated on TINA4_DEBUG=true. In production (TINA4_DEBUG unset or false)
+ * dump output is suppressed entirely to avoid leaking internal state,
+ * stack-traceable object shapes, or sensitive values into rendered HTML.
+ */
+function renderDump(value: unknown): SafeString {
+  const debugMode = (process.env.TINA4_DEBUG ?? "").toLowerCase() === "true";
+  if (!debugMode) {
+    return new SafeString("");
+  }
+  const dumped = inspectValue(value);
+  const escaped = dumped
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+  return new SafeString(`<pre>${escaped}</pre>`);
+}
+
 type TokenType = "TEXT" | "VAR" | "BLOCK" | "COMMENT";
 type Token = [TokenType, string];
 
@@ -1167,6 +1287,11 @@ export class Frond {
     this.globals.form_token = (descriptor?: string) => _generateFormToken(descriptor || "");
     this.globals.formTokenValue = (descriptor?: string) => _generateFormTokenValue(descriptor || "");
     this.globals.form_token_value = (descriptor?: string) => _generateFormTokenValue(descriptor || "");
+
+    // Debug helper: {{ dump(x) }} — gated on TINA4_DEBUG, see renderDump().
+    // Available alongside the |dump filter so both styles work:
+    //   {{ user|dump }}   and   {{ dump(user) }}
+    this.globals.dump = (value: unknown) => renderDump(value);
   }
 
   sandbox(filters?: string[], tags?: string[], vars?: string[]): Frond {
@@ -1590,7 +1715,11 @@ export class Frond {
           case "keys":       value = (typeof value === "object" && value !== null && !Array.isArray(value)) ? Object.keys(value) : []; continue;
           case "values":     value = (typeof value === "object" && value !== null && !Array.isArray(value)) ? Object.values(value) : []; continue;
           case "json_encode": value = JSON.stringify(value); continue;
-          case "dump":       value = JSON.stringify(value); continue;
+          case "dump":
+            // Delegates to renderDump(), which is gated on TINA4_DEBUG.
+            // In production this emits an empty SafeString (no leaked state).
+            value = renderDump(value);
+            continue;
           case "nl2br":      value = String(value).replace(/\n/g, "<br>\n"); continue;
           case "unique":     value = Array.isArray(value) ? [...new Set(value)] : value; continue;
           case "sort":       value = Array.isArray(value) ? [...value].sort() : value; continue;