@blamejs/core 0.8.42 → 0.8.49

package/lib/template.js

@@ -1,13 +1,37 @@
 "use strict";
 /**
- * Server-side HTML template engine — eval-free.
+ * @module b.template
+ * @nav    HTTP
+ * @title  Template
+ *
+ * @intro
+ *   Server-side HTML template engine. Handlebars-flavoured tag
+ *   syntax (`{{ expr }}` HTML-escaped, `{{{ expr }}}` raw, `{{> name }}`
+ *   partials, `{% extends "layout" %}` / `{% block name %}` inheritance,
+ *   `{% if %}` / `{% for %}` directives) parsed into a small AST and
+ *   walked at render time against an operator-supplied data scope.
+ *
+ *   No `eval`, no dynamic Function constructor, no `vm.runInThisContext`
+ *   — the expression grammar is a fixed recursive-descent Pratt parser
+ *   and member access is restricted to own properties (the parser
+ *   refuses `foo.constructor` / `foo.__proto__` walks out of the data
+ *   scope). Custom helpers are operator-provided functions in the data
+ *   scope (e.g. `{{ helpers.formatDate(d) }}`); when `opts.sandbox ===
+ *   true` each helper source string is wrapped through `b.sandbox.run`
+ *   so helper code runs in a worker-thread isolate with timeout + byte
+ *   cap.
+ *
+ *   `precompileAll()` walks `viewsDir` at boot, parsing every `.html`
+ *   file so template syntax errors fail the deploy rather than the
+ *   first user request. Compiled ASTs are cached unless `cache: false`
+ *   is set on the engine — operators turn caching off for live-reload
+ *   workflows.
  *
- * No `new Function()`, no `eval`, no `vm.runInThisContext`. Templates
- * are tokenized + parsed into a small AST and walked at render time
- * against a data scope. The trade-off vs an eval-based engine is
- * 5–50× slower per render and a restricted expression grammar; the
- * win is "an operator who renders req.query.template (or worse) can't
- * RCE the framework, period."
+ * @card
+ *   Server-side HTML template engine.
+ */
+/**
+ * Server-side HTML template engine — eval-free.
  *
  * Tag syntax:
  *
@@ -67,8 +91,14 @@
  */
 var fs = require("fs");
 var path = require("path");
+var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 
+// Lazy because b.template can be loaded before b.sandbox (which pulls
+// in node:worker_threads). Operators not opting into sandboxed helpers
+// shouldn't pay the worker_threads boot.
+var sandboxModule = lazyRequire(function () { return require("./sandbox"); });
+
 // Maximum nesting depth for layout {% extends %} chains and partial
 // {{> ... }} recursion. Hex form so the byte-literal lint doesn't trip
 // on the multiple-of-8 cap; high enough that a real template tree
@@ -82,6 +112,26 @@ var MAX_TEMPLATE_DEPTH = 0x10;
 var ESCAPE_MAP = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#x27;" };
 var ESCAPE_RE = /[&<>"']/g;
 
+/**
+ * @primitive b.template.escapeHtml
+ * @signature b.template.escapeHtml(value)
+ * @since     0.1.0
+ * @related   b.template.create, b.template.render
+ *
+ * HTML-entity escapes the five attack-relevant characters (`&`, `<`,
+ * `>`, `"`, `'`). Non-string inputs are coerced via `String(value)`;
+ * `null` and `undefined` become the empty string. Used internally by
+ * `{{ expr }}` interpolation; exported because operators occasionally
+ * reach for the same escape from non-template paths (form-error
+ * rendering, CSV-cell-as-HTML pre-escape).
+ *
+ * @example
+ *   b.template.escapeHtml("<script>alert(1)</script>");
+ *   // → "&lt;script&gt;alert(1)&lt;/script&gt;"
+ *
+ *   b.template.escapeHtml(null);   // → ""
+ *   b.template.escapeHtml(42);     // → "42"
+ */
 function escapeHtml(value) {
   if (value === null || value === undefined) return "";
   var s = typeof value === "string" ? value : String(value);
@@ -683,9 +733,41 @@ function _evalBlock(nodes, scopes, escFn) {
 // Engine instance
 // ============================================================
 
+/**
+ * @primitive b.template.create
+ * @signature b.template.create(opts)
+ * @since     0.1.0
+ * @related   b.template.render, b.template.escapeHtml
+ *
+ * Builds an engine instance bound to `opts.viewsDir`. The returned
+ * object exposes `render(viewName, data?)` for one-shot rendering,
+ * `compile(viewName)` for AST-only access (caches under viewName),
+ * `precompileAll()` for boot-time validation of every `.html` file
+ * under `viewsDir`, and `reset()` to drop the AST cache (useful in
+ * live-reload workflows).
+ *
+ * View names are resolved against `viewsDir`; names containing `..`
+ * or NUL are refused, and resolved paths outside `viewsDir` throw.
+ * Layout-extends and partial-inclusion recursion are bounded at
+ * depth 16 to defend against accidental cycles.
+ *
+ * @opts
+ *   viewsDir:        string,                       // required — absolute or cwd-relative directory of .html templates
+ *   cache:           boolean,                      // default true; set false for live-reload
+ *   escapeHtml:      function (value) → string,    // override the default 5-character HTML escape
+ *   sandbox:         boolean,                      // when true, sandboxHelpers run through b.sandbox.run
+ *   sandboxHelpers:  Object<string, string>,        // map of helperName → JS source executed inside the sandbox
+ *   sandboxOpts:     { timeoutMs, maxBytes, allowed },
+ *
+ * @example
+ *   var engine = b.template.create({ viewsDir: "./views" });
+ *   engine.precompileAll();                                   // fail boot on syntax errors
+ *   var html = engine.render("dashboard", { user: { name: "Ada" } });
+ *   // → "<h1>Hello Ada</h1>"
+ */
 function create(opts) {
   opts = opts || {};
-  validateOpts(opts, ["viewsDir", "cache", "escapeHtml"], "b.template");
+  validateOpts(opts, ["viewsDir", "cache", "escapeHtml", "sandbox", "sandboxHelpers", "sandboxOpts"], "b.template");
   if (!opts.viewsDir) {
     throw new Error("template.create({ viewsDir }) is required");
   }
@@ -697,6 +779,47 @@ function create(opts) {
   var customEscape = typeof opts.escapeHtml === "function" ? opts.escapeHtml : escapeHtml;
   var astCache = {};
 
+  // Sandbox integration. When opts.sandbox === true, every operator-
+  // supplied helper in opts.sandboxHelpers (a { name -> source-string }
+  // map) is wrapped into an async-shaped callable that delegates to
+  // b.sandbox.run with the operator's per-engine sandboxOpts (timeoutMs,
+  // maxBytes, allowed). The helper signature is `helperFn(input)` which
+  // returns a Promise; templates can pre-compute helper results in the
+  // route handler and pass the resolved values into the data scope.
+  // The template engine itself stays synchronous + eval-free.
+  var sandboxedHelpers = null;
+  if (opts.sandbox === true) {
+    var sbHelpers = opts.sandboxHelpers || {};
+    if (typeof sbHelpers !== "object" || Array.isArray(sbHelpers)) {
+      throw new Error("template.create: opts.sandboxHelpers must be a { name -> source } object");
+    }
+    var sbOpts = opts.sandboxOpts || {};
+    if (typeof sbOpts !== "object" || Array.isArray(sbOpts)) {
+      throw new Error("template.create: opts.sandboxOpts must be an object");
+    }
+    var sandbox = sandboxModule();
+    sandboxedHelpers = {};
+    var helperNames = Object.keys(sbHelpers);
+    for (var hi = 0; hi < helperNames.length; hi += 1) {
+      var hname = helperNames[hi];
+      var hsource = sbHelpers[hname];
+      if (typeof hsource !== "string" || hsource.length === 0) {
+        throw new Error("template.create: opts.sandboxHelpers[" + JSON.stringify(hname) + "] must be a non-empty string");
+      }
+      sandboxedHelpers[hname] = (function (capturedSource) {
+        return function (helperInput) {
+          return sandbox.run({
+            source:    capturedSource,
+            input:     helperInput,
+            timeoutMs: sbOpts.timeoutMs,
+            maxBytes:  sbOpts.maxBytes,
+            allowed:   sbOpts.allowed,
+          }).then(function (r) { return r.result; });
+        };
+      }(hsource));
+    }
+  }
+
   function compile(viewName) {
     if (cacheOn && astCache[viewName]) return astCache[viewName];
     var viewPath = _resolveViewPath(viewsDir, viewName);
@@ -777,6 +900,23 @@ function _ensureDefault() {
   return _default;
 }
 
+/**
+ * @primitive b.template.render
+ * @signature b.template.render(viewName, data?)
+ * @since     0.1.0
+ * @related   b.template.create
+ *
+ * Convenience renderer that lazily binds a default engine instance
+ * to `<cwd>/views` on first call, then dispatches to its `render()`.
+ * Operators with custom view directories (multi-tenant apps,
+ * non-cwd-rooted deploys) call `b.template.create({ viewsDir })`
+ * instead and keep the engine in their app scope.
+ *
+ * @example
+ *   // Project layout: ./views/welcome.html
+ *   var html = b.template.render("welcome", { name: "Ada" });
+ *   // → "<h1>Welcome, Ada</h1>"
+ */
 function render(viewName, data) {
   return _ensureDefault().render(viewName, data);
 }