tina4-nodejs 3.13.86 → 3.13.88

package/packages/frond/src/engine.ts

@@ -34,6 +34,69 @@ class SafeString {
   toString() { return this.value; }
 }
 
+/**
+ * Serialize a value to compact JSON text that is always valid JSON.
+ *
+ * Never throws and never returns an empty string. JSON.stringify already maps a
+ * non-finite number to null, but it returns the VALUE `undefined` for undefined,
+ * a function, or a symbol, and it throws on a BigInt or a circular structure --
+ * all four of which would otherwise reach the page as nothing or as a crash.
+ */
+function jsonText(value: unknown): string {
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? "null" : text;
+  } catch {
+    // Only reached when the happy path threw, so a well-formed payload never
+    // pays for the walk.
+    const seen = new WeakSet<object>();
+    const text = JSON.stringify(value, (_key, v) => {
+      if (typeof v === "bigint") return v.toString();
+      if (typeof v === "object" && v !== null) {
+        if (seen.has(v)) return null;
+        seen.add(v);
+      }
+      return v;
+    });
+    return text === undefined ? "null" : text;
+  }
+}
+
+const JSON_UNSAFE_RE = /[<>&'\u2028\u2029]/g;
+const JSON_UNSAFE_MAP: Record<string, string> = {
+  "<": "\\u003c", ">": "\\u003e", "&": "\\u0026", "'": "\\u0027",
+  "\u2028": "\\u2028", "\u2029": "\\u2029",
+};
+
+/**
+ * Serialize to JSON that is valid JSON, valid JavaScript, and safe in HTML.
+ *
+ * THE cross-framework contract for json_encode / to_json / tojson. Keep the four
+ * implementations byte-identical; frond_expression_corpus.txt locks it.
+ *
+ * Three things this must never do, each of which was a real bug in one of the
+ * four engines:
+ *
+ * 1. Never emit a non-finite literal. Python wrote a bare `Infinity`, PHP
+ *    returned false, Ruby fell back to inspect output -- none of them parse.
+ *    Node was the one that already got this right. Reported as tina4-php#184 by
+ *    justin-k-bruce.
+ * 2. Never emit nothing, and never emit something that still parses and means
+ *    something else. "var ROWS = ;" is at least a loud SyntaxError.
+ * 3. Never HTML-escape it. Entity-encoding JSON produces {&quot;a&quot;:1}, a
+ *    SyntaxError inside <script>, which is the filter's whole point. Escape only
+ *    the dangerous characters, as JSON \uXXXX escapes: the result stays valid
+ *    JSON AND valid JavaScript, </script> cannot terminate the block, and it is
+ *    safe inside a single-quoted attribute. This is what Jinja2's tojson does,
+ *    and it is why the result is a SafeString.
+ *
+ * U+2028 and U+2029 join that escape set. Both are legal inside a JSON string and
+ * both were illegal inside a JavaScript string literal before ES2019.
+ */
+function jsonSafe(value: unknown): SafeString {
+  return new SafeString(jsonText(value).replace(JSON_UNSAFE_RE, (c) => JSON_UNSAFE_MAP[c]));
+}
+
 /**
  * Produce a human-readable, debugger-friendly inspection of any value.
  *
@@ -202,6 +265,40 @@ const filterChainCache = new Map<string, [string, [string, unknown[]][]]>();
 /** Cache for parsed dotted/bracket paths: expr string -> [parts, fromBracket] */
 const pathParseCache = new Map<string, [string[], boolean[]]>();
 
+/**
+ * Hard cap on the template caches — `compiled` and `compiledStrings`
+ * (ADR-0004, parity with PHP/Python/Ruby TEMPLATE_CACHE_MAX).
+ *
+ * An entry here is a whole token list, so the cap sits well below what a
+ * per-expression memo would justify. 256 is far above any real application's
+ * template count, so a normal app never evicts. The cap exists for the
+ * workload that genuinely grows without limit for the life of a worker:
+ * `renderString` keys on md5(source), so an app that builds template strings
+ * dynamically adds an entry per distinct string.
+ */
+export const TEMPLATE_CACHE_MAX = 256;
+
+/**
+ * Keep a memo cache bounded. Call immediately before inserting a new entry.
+ *
+ * Eviction is insertion-ordered (oldest first), not true LRU: a `Map`
+ * preserves insertion order, so dropping from the front is cheap, whereas
+ * refreshing recency on every cache HIT would add writes to the hottest path
+ * in a render and cost more than it saves. Half the cache is dropped at once
+ * so the sweep amortises to O(1) per insert.
+ *
+ * Evicting can never change what a render produces: every read site treats a
+ * miss as "recompute", so a swept entry is rebuilt on next use.
+ */
+function capCache(cache: Map<string, unknown>, maxEntries: number): void {
+  if (cache.size < maxEntries) return;
+  let drop = Math.floor(maxEntries / 2);
+  for (const key of cache.keys()) {
+    cache.delete(key);
+    if (--drop <= 0) break;
+  }
+}
+
 // ── Lexer ──────────────────────────────────────────────────────
 
 const TOKEN_RE = /(\{%-?\s*[\s\S]*?\s*-?%\})|(\{\{-?\s*[\s\S]*?\s*-?\}\})|(\{#[\s\S]*?#\})/g;
@@ -609,7 +706,21 @@ function evalExpr(expr: string, context: Record<string, unknown>): unknown {
     }
   }
 
-  // Check for comparison/logical operators
+  // Comparison/logical operators -> evalComparison, the SAME evaluator {% if %}
+  // uses, so a condition means the same thing in a condition and in an output
+  // expression.
+  //
+  // The LEADING unary `not` needs its own check: every operator below is matched
+  // WITH surrounding spaces, so `not x` (nothing to its left) matched none of
+  // them, fell through to the variable-resolution tail, and was looked up as a
+  // variable literally named "not x" -- found nothing, rendered EMPTY.
+  // `{% if not x %}` and `x and not y` always worked; only the standalone
+  // `{{ not x }}` was dropped, and before booleans rendered lowercase a dropped
+  // expression and `false -> ''` looked identical, which is why it survived.
+  // Fixed in 3.13.87 alongside the boolean contract.
+  if (expr.startsWith("not ")) {
+    return evalComparison(expr, context);
+  }
   for (const op of [" not in ", " in ", " is not ", " is ", "!=", "==", ">=", "<=", ">", "<", " and ", " or ", " not "]) {
     if (findOutsideQuotes(expr, op) >= 0) {
       return evalComparison(expr, context);
@@ -1259,7 +1370,7 @@ const BUILTIN_FILTERS: Record<string, FilterFn> = {
   int: (v) => v ? parseInt(String(v), 10) || 0 : 0,
   float: (v) => v ? parseFloat(String(v)) || 0.0 : 0.0,
   string: (v) => String(v),
-  json_encode: (v) => JSON.stringify(v),
+  json_encode: (v) => jsonSafe(v),
   json_decode: (v) => typeof v === "string" ? JSON.parse(v) : v,
   keys: (v) => (typeof v === "object" && v !== null && !Array.isArray(v)) ? Object.keys(v) : [],
   values: (v) => (typeof v === "object" && v !== null && !Array.isArray(v)) ? Object.values(v) : [],
@@ -1383,8 +1494,12 @@ const BUILTIN_FILTERS: Record<string, FilterFn> = {
   form_token: (v?: unknown) => _generateFormToken(v != null ? String(v) : ""),
   formTokenValue: (v?: unknown) => _generateFormTokenValue(v != null ? String(v) : ""),
   form_token_value: (v?: unknown) => _generateFormTokenValue(v != null ? String(v) : ""),
-  tojson: (v, indent) => new SafeString(indent !== undefined ? JSON.stringify(v, null, parseInt(String(indent), 10)) : JSON.stringify(v)),
-  to_json: (v, indent) => new SafeString(indent !== undefined ? JSON.stringify(v, null, parseInt(String(indent), 10)) : JSON.stringify(v)),
+  // Same serializer as json_encode -- the three names are one behaviour. The
+  // old indent argument is gone: PHP cannot honour an arbitrary indent
+  // (JSON_PRETTY_PRINT is fixed at four spaces), so honouring it here alone
+  // broke byte-parity for the one filter whose whole job is a wire format.
+  tojson: (v) => jsonSafe(v),
+  to_json: (v) => jsonSafe(v),
   js_escape: (v) => new SafeString(String(v).replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")),
 };
 
@@ -1685,6 +1800,7 @@ export class Frond {
     const source = readFileSync(filePath, "utf-8");
     const mtime = statSync(filePath).mtimeMs;
     const tokens = tokenize(source);
+    capCache(this.compiled as Map<string, unknown>, TEMPLATE_CACHE_MAX);
     this.compiled.set(template, { tokens, mtime, cachedAt: Date.now() });
     return this.executeWithSource(source, tokens, context);
   }
@@ -1702,6 +1818,7 @@ export class Frond {
     }
 
     const tokens = tokenize(source);
+    capCache(this.compiledStrings as Map<string, unknown>, TEMPLATE_CACHE_MAX);
     this.compiledStrings.set(key, { tokens, cachedAt: Date.now() });
     return this.executeCached(tokens, context);
   }
@@ -1977,6 +2094,9 @@ export class Frond {
         } else if (tag === "macro") {
           const skip = this.handleMacro(tokens, i, context);
           i = skip;
+        } else if (tag === "import") {
+          this.handleImportAs(content, context);
+          i++;
         } else if (tag === "from") {
           this.handleFromImport(content, context);
           i++;
@@ -2293,7 +2413,7 @@ export class Frond {
           case "last":       value = Array.isArray(value) ? value[value.length - 1] ?? null : null; continue;
           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 "json_encode": value = jsonSafe(value); continue;
           case "dump":
             // Delegates to renderDump(), which is gated on TINA4_DEBUG.
             // In production this emits an empty SafeString (no leaked state).
@@ -2587,7 +2707,7 @@ export class Frond {
     }
 
     const macroName = m[1];
-    const paramNames = m[2].split(",").map(p => p.trim()).filter(Boolean);
+    const params = Frond.parseMacroParams(m[2]);
 
     // Collect body tokens
     const bodyTokens: Token[] = [];
@@ -2606,8 +2726,9 @@ export class Frond {
     const capturedContext = { ...context };
     context[macroName] = (...args: unknown[]) => {
       const macroCtx: Record<string, unknown> = { ...capturedContext };
-      for (let pi = 0; pi < paramNames.length; pi++) {
-        macroCtx[paramNames[pi]] = pi < args.length ? args[pi] : null;
+      for (let pi = 0; pi < params.length; pi++) {
+        const [pname, pdefault] = params[pi];
+        macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
       }
       return new SafeString(engine.renderTokens([...bodyTokens], macroCtx));
     };
@@ -2615,6 +2736,104 @@ export class Frond {
     return i;
   }
 
+  /**
+   * Parse a macro parameter list into [name, default] pairs.
+   *
+   * Handles: name, name="default", name='default'. Splitting on "," alone left a
+   * defaulted parameter literally NAMED `greeting='Hello'`, so the body's
+   * {{ greeting }} matched nothing (rendered empty) AND the caller's positional
+   * argument was stored under that junk key and lost. Mirrors the Python master's
+   * _parse_macro_params. The default is null when none is declared.
+   */
+  static parseMacroParams(rawParams: string): Array<[string, string | null]> {
+    return rawParams
+      .split(",")
+      .map(p => p.trim())
+      .filter(Boolean)
+      .map(p => {
+        const eq = p.indexOf("=");
+        if (eq === -1) return [p, null] as [string, string | null];
+        const name = p.slice(0, eq).trim();
+        let dflt = p.slice(eq + 1).trim();
+        if (
+          dflt.length >= 2 &&
+          ((dflt.startsWith('"') && dflt.endsWith('"')) ||
+            (dflt.startsWith("'") && dflt.endsWith("'")))
+        ) {
+          dflt = dflt.slice(1, -1);
+        }
+        return [name, dflt] as [string, string | null];
+      });
+  }
+
+  /**
+   * {% import "file" as alias %} -- load EVERY macro in a file under one namespace.
+   *
+   * The alias is bound as a plain object of macro functions, so {{ alias.greet(x) }}
+   * resolves through the engine's existing dotted-call path and each macro keeps the
+   * same argument binding, default handling and SafeString output as any other macro.
+   * A namespace object (not a class) is deliberate: a function stored as a class
+   * attribute binds as a method and would inject the namespace as the first argument,
+   * which is exactly the argument-shift bug the Python master carried (fixed there
+   * with types.SimpleNamespace). Both import forms must render identically.
+   */
+  private handleImportAs(content: string, context: Record<string, unknown>): void {
+    const m = content.match(/^import\s+["'](.+?)["']\s+as\s+(\w+)/);
+    if (!m) return;
+
+    const filename = m[1];
+    const alias = m[2];
+    const namespace: Record<string, unknown> = {};
+
+    const source = this.load(filename);
+    const tokens = tokenize(source);
+
+    let i = 0;
+    while (i < tokens.length) {
+      const [ttype, raw] = tokens[i];
+      if (ttype === "BLOCK") {
+        const [tagContent] = stripTag(raw);
+        if ((tagContent.split(/\s+/)[0] || "") === "macro") {
+          const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
+          if (macroM) {
+            const macroName = macroM[1];
+            const params = Frond.parseMacroParams(macroM[2]);
+
+            const bodyTokens: Token[] = [];
+            i++;
+            while (i < tokens.length) {
+              if (tokens[i][0] === "BLOCK" && tokens[i][1].includes("endmacro")) {
+                i++;
+                break;
+              }
+              bodyTokens.push(tokens[i]);
+              i++;
+            }
+
+            // Own copies per macro — avoids closure-over-loop-variable sharing.
+            const capturedBody = [...bodyTokens];
+            const capturedParams = [...params];
+            const capturedCtx = { ...context };
+            const engine = this;
+
+            namespace[macroName] = (...args: unknown[]) => {
+              const macroCtx: Record<string, unknown> = { ...capturedCtx };
+              for (let pi = 0; pi < capturedParams.length; pi++) {
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
+              }
+              return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
+            };
+            continue;
+          }
+        }
+      }
+      i++;
+    }
+
+    context[alias] = namespace;
+  }
+
   private handleFromImport(content: string, context: Record<string, unknown>): void {
     const m = content.match(/^from\s+["'](.+?)["']\s+import\s+(.+)/);
     if (!m) return;
@@ -2635,7 +2854,7 @@ export class Frond {
           const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
           if (macroM && names.includes(macroM[1])) {
             const macroName = macroM[1];
-            const paramNames = macroM[2].split(",").map(p => p.trim()).filter(Boolean);
+            const paramNames = Frond.parseMacroParams(macroM[2]);
 
             const bodyTokens: Token[] = [];
             i++;
@@ -2657,7 +2876,8 @@ export class Frond {
             context[macroName] = (...args: unknown[]) => {
               const macroCtx: Record<string, unknown> = { ...capturedCtx };
               for (let pi = 0; pi < capturedParams.length; pi++) {
-                macroCtx[capturedParams[pi]] = pi < args.length ? args[pi] : null;
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
               }
               return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
             };