sjabloon 0.9.0 → 0.10.0

package/README.md

@@ -67,7 +67,7 @@ Every edition exports `template`, `render`, `isDiagnostic`, and `relocate`. They
 
 ## API
 
-### `template(str, functions?)`
+### `template(str, functions?, options?)`
 
 Compiles the template and returns a renderer. What it renders to depends on the edition you imported from (see [Editions](#editions)); everything else on this page is identical across all three. Malformed tags, unclosed blocks, and invalid expressions throw a `SyntaxError` at compile time.
 
@@ -89,6 +89,24 @@ tpl.names; // => ['title', 'items']
 tpl.functions; // => ['fmt']
 ```
 
+`options.bound` lists names your engine already has in scope — a loop variable, a handle, a `page` anchor. They are excluded from `names` and still resolve normally at render time, the same contract as xprsn's own `bound`:
+
+```js
+template("{{ run.total }} of {{ count }}", undefined, { bound: ["run"] }).names; // => ['count']
+```
+
+The renderer also carries its own `isDiagnostic(error)`: `true` only for runtime diagnostics thrown through this renderer, where the module-wide [`isDiagnostic`](#diagnostics) answers for every template. An embedder holding many compiled templates asks the one that just rendered, so a diagnostic that leaked from an unrelated template is not mistaken for this cell's.
+
+### `renderer.scoped(values)`
+
+The trusted-scope render, for an embedder whose scope chain already binds the anchors. The default call wraps `values` in a fresh scope and seeds `$` and `@` into it; `scoped` skips the wrapper: `$` and `@` resolve from `values` itself, and a chain that omits `@` leaves it unbound so `@.x` throws where there is no current item. `{{#each}}` still re-points `@` inside its body, and nothing is ever written to your objects. Rendering one template per cell per row over scopes you already build, this is the path with zero per-call allocations beyond the output.
+
+```js
+const row = Object.create(base); // base binds $ once per render
+row["@"] = item;
+tpl.scoped(row);
+```
+
 ### `render(str, values?, functions?)`
 
 Shorthand for `template(str, functions)(values)`, returning whatever its edition renders.

package/lib/core.js

@@ -5,8 +5,8 @@
  *
  * This is the shared core: the lexer, parser and diagnostics, with output left
  * to the profile each entry passes to `make()`. Exactly one copy of this module
- * backs every entry, so the WeakSet below authenticates diagnostics across all
- * of them.
+ * backs every entry, so the diagnostics store below authenticates diagnostics
+ * across all of them.
  */
 import { compile, isDiagnostic as isXprsnDiagnostic, relocate as relocateXprsn } from "xprsn";
 
@@ -30,10 +30,14 @@ import { compile, isDiagnostic as isXprsnDiagnostic, relocate as relocateXprsn }
  */
 
 const BLOCKED = /^(?:__proto__|constructor|prototype)$/;
-/** @type {WeakSet<any>} */
-const DIAGNOSTICS = new WeakSet();
-const mark = DIAGNOSTICS.add.bind(DIAGNOSTICS);
+// Error -> the `names` set of the compile that threw it. The map's keys are
+// what authenticates a diagnostic module-wide; the value is the per-template
+// origin each renderer's own `isDiagnostic` compares against.
+/** @type {WeakMap<any, any>} */
+const DIAGNOSTICS = new WeakMap();
+const mark = DIAGNOSTICS.set.bind(DIAGNOSTICS);
 const owns = DIAGNOSTICS.has.bind(DIAGNOSTICS);
+const origin = DIAGNOSTICS.get.bind(DIAGNOSTICS);
 
 /**
  * Check whether an error was produced or translated by sjabloon.
@@ -65,8 +69,9 @@ const kindOf = (p) => (p === SYNTAX ? SyntaxError : Error);
  * Copy a diagnostic into an embedder's coordinates.
  *
  * Relocation lives here, beside the authentication it has to satisfy: the copy
- * is registered in the same WeakSet as the original, so it passes
- * `isDiagnostic`. The original is never mutated, and every own field comes
+ * is registered in the same store as the original, under the original's origin,
+ * so it passes `isDiagnostic` and the owning renderer's own `isDiagnostic`
+ * alike. The original is never mutated, and every own field comes
  * across by descriptor — the frozen `blocks` context stays frozen and
  * non-writable — so a field added here is never a field an embedder forgets.
  *
@@ -86,7 +91,7 @@ export const relocate = (diag, { prefix = "", offset = 0 } = {}) => {
   // and attach would redefine a non-configurable property.
   if (isXprsnDiagnostic(diag)) {
     const moved = relocateXprsn(diag, { prefix, offset });
-    return (mark(moved), /** @type {SjabloonDiagnostic} */ (moved));
+    return (mark(moved, origin(diag)), /** @type {SjabloonDiagnostic} */ (moved));
   }
   let d = /** @type {any} */ (diag),
     props = DESCS(d),
@@ -98,7 +103,7 @@ export const relocate = (diag, { prefix = "", offset = 0 } = {}) => {
     props.end.value += offset;
   }
   DEFINE(copy, props);
-  return (mark(copy), /** @type {SjabloonDiagnostic} */ (copy));
+  return (mark(copy, origin(d)), /** @type {SjabloonDiagnostic} */ (copy));
 };
 
 // Linear scan into text/tag/raw tokens. Dashes hug braces (`{{- x -}}` trims;
@@ -219,11 +224,12 @@ let opener = (type, t) => {
  * @template {object} E
  * @param {E} e
  * @param {any} context
+ * @param {any} own The owning compile's `names` set, this diagnostic's origin.
  * @returns {E}
  */
-let attach = (e, context) => {
+let attach = (e, context, own) => {
   Object.defineProperty(e, "blocks", { value: context, enumerable: true });
-  mark(e);
+  mark(e, own);
   return e;
 };
 /**
@@ -250,21 +256,22 @@ const fault = (
   e.code = code;
   e.start = start;
   e.end = end;
-  throw attach(e, snap());
+  throw attach(e, snap(), names);
 };
 /**
  * Re-locate a diagnostic thrown by a nested compile or render into this
  * template's coordinates, then rethrow it as ours. Always throws.
  *
- * `owns` is a plain predicate rather than a type guard: `e` is retyped here,
+ * `guard` is a plain predicate rather than a type guard: `e` is retyped here,
  * not narrowed. `const` with an explicit `never` type is what lets callers
  * treat the catch block as terminal.
  *
- * @type {(e: any, start: number, context: any, owns?: (e: unknown) => boolean) => never}
+ * @type {(e: any, start: number, context: any, own: any,
+ *   guard?: (e: unknown) => boolean) => never}
  */
-const translated = (e, start, context, owns = isXprsnDiagnostic) => {
-  if (!owns(e)) throw e;
-  throw attach(relocateXprsn(e, { offset: start }), context);
+const translated = (e, start, context, own, guard = isXprsnDiagnostic) => {
+  if (!guard(e)) throw e;
+  throw attach(relocateXprsn(e, { offset: start }), context, own);
 };
 /**
  * @param {Tok} t
@@ -295,6 +302,9 @@ let run = (nodes, scope, acc) => {
  * @returns {(v: any) => any}
  */
 let compileExpr = (expr, start, context) => {
+  // The compiling template's origin, captured now: the render-time catch below
+  // runs long after the module-level `names` has moved on to other compiles.
+  const own = names;
   /** @type {ReturnType<typeof compile>} */
   let e;
   try {
@@ -305,7 +315,7 @@ let compileExpr = (expr, start, context) => {
     // than a real one — narrowing `SjabloonFunctions` would change the API.
     e = compile(expr, /** @type {any} */ (fns));
   } catch (x) {
-    translated(x, start, context);
+    translated(x, start, context, own);
   }
   e.names.forEach((n) => {
     // oxlint-disable-next-line no-unused-expressions
@@ -317,9 +327,9 @@ let compileExpr = (expr, start, context) => {
       return e(v);
     } catch (x) {
       // Read off the compiled expression to pass along, never called through
-      // `e` — xprsn's `isDiagnostic` is a closure over a WeakSet, not a method.
+      // `e` — xprsn's `isDiagnostic` is a closure over its store, not a method.
       // oxlint-disable-next-line typescript/unbound-method
-      translated(x, start, context, e.isDiagnostic);
+      translated(x, start, context, own, e.isDiagnostic);
     }
   };
 };
@@ -533,14 +543,18 @@ export const litNode = (text) => (scope, acc) => {
 /**
  * Bind the parser to an output profile. Each edition calls this once at module
  * load and gets back its own `template` and `render`; the parser itself stays
- * module-level and shared, so there is exactly one diagnostics WeakSet.
+ * module-level and shared, so there is exactly one diagnostics store.
  *
- * `template(str, funcs?)` compiles a template once, to render it many times.
+ * `template(str, funcs?, opts?)` compiles a template once, to render it many
+ * times.
  *
  * The returned renderer exposes `names`: the variables the template reads
  * from your values, deduplicated. Loop variables the template introduces are
- * not included. It also exposes `functions`: the registry functions the
- * template calls, deduplicated.
+ * not included, and neither is anything in `opts.bound` — names the embedder
+ * already has in scope (still resolved normally at render time, exactly like
+ * xprsn's own `bound`). It also exposes `functions`: the registry functions
+ * the template calls, deduplicated. `isDiagnostic(error)` recognizes runtime
+ * diagnostics thrown through this renderer alone.
  *
  * Two anchors are always in scope: `$` is the root values, and `@` is the
  * current `#each` item (the root outside any loop). They let a nested loop
@@ -552,6 +566,12 @@ export const litNode = (text) => (scope, acc) => {
  * `root` and `@` becomes `item` (two distinct objects). Omit `item` to leave
  * `@` unbound, so reading `@.x` throws through xprsn's guard.
  *
+ * An embedder whose scope chain already binds the anchors renders through
+ * `scoped(values)` instead: no wrapper scope is created, `$` and `@` resolve
+ * from `values` itself, and a chain that omits `@` leaves it unbound the same
+ * way. That is the zero-allocation seam for a host rendering one template per
+ * cell per row over scopes it already builds.
+ *
  * Render order is push order into a single accumulator: loop bodies append once
  * per iteration, untaken branches append nothing, and block expressions (`#if`
  * conditions, `#each` collections) never append at all. The token edition
@@ -575,7 +595,8 @@ export const litNode = (text) => (scope, acc) => {
  *   take: (acc: A) => T,
  * ]} profile The output profile, as above.
  * @returns {{
- *   template: (str: string, funcs?: SjabloonFunctions) => SjabloonRenderer<T>,
+ *   template: (str: string, funcs?: SjabloonFunctions,
+ *     opts?: { bound?: Iterable<string> }) => SjabloonRenderer<T>,
  *   render: (str: string, values?: SjabloonValues, funcs?: SjabloonFunctions) => T,
  * }} That edition's API.
  * @throws {SyntaxError} `template` throws on malformed tags, unclosed blocks,
@@ -585,15 +606,20 @@ export let make = ([lit, val, raw, seed, take]) => {
   /**
    * @param {string} str
    * @param {SjabloonFunctions} [funcs]
+   * @param {{ bound?: Iterable<string> }} [opts]
    * @returns {SjabloonRenderer<T>}
    */
-  function template(str, funcs) {
+  function template(str, funcs, opts) {
     // oxlint-disable-next-line no-unused-expressions
     ((LIT = lit), (VAL = val), (RAW = raw));
     fns = funcs;
     // `$` (root) and `@` (current item) are engine-bound anchors, always in
-    // scope, so they never count as caller-supplied `names`.
+    // scope, so they never count as caller-supplied `names` — and neither does
+    // anything the embedder declares bound. A loop, not a spread: the
+    // bundler's transpile turns an iterable spread into a concat that would
+    // wrap a Set instead of unpacking it.
     bound = ["$", "@"];
+    if (opts && opts.bound) for (const name of opts.bound) bound.push(name);
     names = new Set();
     functions = new Set();
     source = String(str);
@@ -604,28 +630,40 @@ export let make = ([lit, val, raw, seed, take]) => {
     // Deeply nested blocks fail as SJABLOON_TOO_DEEP at DEPTH via opener(),
     // including elif chains — well below the native stack.
     let nodes = parse([]);
-    // Wrap the values in a root scope carrying the anchors, without mutating
-    // what the caller passed: by default `$` and `@` both point at the root.
-    // An embedder can override the anchors with a `{ root, item }` second arg:
-    // `$` = root, `@` = item (distinct objects). Omitting `item` leaves `@`
-    // unbound, so `@.x` throws through xprsn's guard — a group-header band that
-    // has no current row wants exactly that.
+    // The trusted-scope render, and the one render body: the caller's chain
+    // already carries the anchors, so no wrapper is created and nothing is
+    // written anywhere. One accumulator per render, owned here and threaded
+    // down. A registry function that renders another template gets its own,
+    // so re-entrancy needs no bookkeeping.
+    const scoped = (/** @type {any} */ values) => {
+      const acc = seed();
+      run(nodes, values, acc);
+      return take(acc);
+    };
+    // The default render wraps the values in a root scope carrying the
+    // anchors, without mutating what the caller passed: by default `$` and `@`
+    // both point at the root. An embedder can override the anchors with a
+    // `{ root, item }` second arg: `$` = root, `@` = item (distinct objects).
+    // Omitting `item` leaves `@` unbound, so `@.x` throws through xprsn's
+    // guard — a group-header band that has no current row wants exactly that.
     const f = (/** @type {any} */ values, /** @type {any} */ anchors) => {
       values = values || EMPTY;
       const r = Object.create(values);
       r["$"] = anchors ? anchors.root : values;
       r["@"] = anchors ? anchors.item : values;
-      // One accumulator per render, owned here and threaded down. A registry
-      // function that renders another template gets its own, so re-entrancy
-      // needs no bookkeeping.
-      const acc = seed();
-      run(nodes, r, acc);
-      return take(acc);
+      return scoped(r);
     };
     // Array.from, not a spread: the bundler's transpile turns `[...set]` into
     // `[].concat(set)`, which wraps the Set instead of unpacking it.
     f.names = Array.from(names);
     f.functions = Array.from(functions);
+    // This compile's own `names` set doubles as its origin: every diagnostic
+    // thrown through this renderer was marked with it, at compile time by
+    // `fault` and at render time by the closures `compileExpr` built. Captured
+    // now — the module-level `names` moves on to the next compile.
+    const o = names;
+    f.isDiagnostic = (/** @type {unknown} */ x) => origin(x) === o;
+    f.scoped = scoped;
     return f;
   }
   return { template, render: (str, values, funcs) => template(str, funcs)(values) };

package/lib/html.d.ts

@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/index.d.ts

@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<Token[]>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<Token[]>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): Token[];

package/lib/text.d.ts

@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/types.d.ts

@@ -49,13 +49,25 @@ export interface SjabloonScope {
  * A compiled template: render it many times.
  *
  * `names` are the variables the template reads from your values, deduplicated;
- * loop variables the template introduces are not included. `functions` are the
- * registry functions the template calls, deduplicated.
+ * loop variables the template introduces are not included, and neither is
+ * anything the compile's `bound` option declared. `functions` are the registry
+ * functions the template calls, deduplicated.
+ *
+ * `isDiagnostic(error)` recognizes runtime diagnostics thrown through this
+ * renderer alone — the per-renderer twin of the module-wide `isDiagnostic`.
+ *
+ * `scoped(values)` renders over a scope chain that already binds the anchors:
+ * no wrapper scope is created, `$` and `@` resolve from `values` itself, and a
+ * chain that omits `@` leaves it unbound so `@.x` throws through xprsn's
+ * guard. The zero-allocation seam for an embedder rendering over scopes it
+ * already builds; `{{#each}}` still re-points `@` inside its body.
  */
 export interface SjabloonRenderer<T> {
   (values?: SjabloonValues, scope?: SjabloonScope): T;
   names: string[];
   functions: string[];
+  isDiagnostic(error: unknown): boolean;
+  scoped(values: SjabloonValues): T;
 }
 
 /** One static text run of the template, verbatim. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sjabloon",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
   "keywords": [
     "csp",