sjabloon 0.12.0 → 0.13.0

package/EMBEDDING.md

@@ -191,6 +191,42 @@ on:
   fresh per emit. Do not mutate or key a cache on a literal token's identity
   across iterations.
 
+### Naming an interpolation with `tag`
+
+A value token carries its value and nothing about where it came from, so an
+embedder that has to treat one interpolation differently from the rest — a page
+number a word processor writes as a live field, rather than the number the
+render happened to see — cannot tell them apart from the stream. `tag` is that
+seam:
+
+```js
+const FIELD = { "page.number": { field: "page.number" } };
+const tpl = template("Page {{ page.number }} of {{ page.total }}", fns, {
+  tag: (expr) => FIELD[expr],
+});
+tpl({ page: { number: 1, total: 2 } });
+// [{ literal: 'Page ' }, { value: 1, field: 'page.number' }, { literal: ' of ' }, { value: 2 }]
+```
+
+- **Called once per interpolation, while compiling.** Never at render time, so
+  what a token carries is a compile-time constant and a hot render pays nothing
+  for the keys it does not have. A template compiled without `tag` emits the
+  exact closure and the exact stream it always did.
+- **The argument is the expression source as written and trimmed.** `{{ x }}`,
+  `{{x}}` and `{{- x -}}` all arrive as `'x'`, so an equality test against the
+  spelling you are looking for is exact. Match it, or return `undefined` and the
+  token is untouched.
+- **The returned keys join every value token that interpolation emits** — once
+  per loop iteration, under the names you chose. `value` and `literal` are the
+  stream's own: `value` is written last so a tag cannot take it over, and
+  returning `literal` would make a token answer to both kinds, so do not.
+- **It runs inside the parse**, which is shared, synchronous state. Read the
+  expression and return; do not compile another template from within it.
+- **Block expressions are not offered.** `#if` conditions and `#each`
+  collections steer the render and emit no token, so there is nothing to name.
+- The token edition alone has tokens to carry the keys; `sjabloon/text` and
+  `sjabloon/html` ignore the option.
+
 `text(tokens)` joins a stream the way `sjabloon/text` would have rendered it, and
 the two are equal for every template and every set of values. The test suite and
 the fuzzer both check that.

package/README.md

@@ -93,7 +93,7 @@ sjabloon renders a template against a values object. Templates can interpolate,
 
 ## Related packages
 
-sjabloon is the template layer of a three-package set that share one approach — parse to closures, never to code — and no runtime dependencies beyond each other:
+sjabloon is the template layer of a set that shares one approach — parse to closures, never to code — and whose only runtime dependencies are each other and [waarmerk](https://github.com/getquario/waarmerk), the located-diagnostic module they mint through:
 
 - **[xprsn](https://github.com/getquario/xprsn)** — the expression language sjabloon runs inside every tag, usable on its own if you need to evaluate _one_ expression against data rather than render text. Its [syntax reference](https://github.com/getquario/xprsn#syntax) is the reference for everything between the braces here.
 - **[padvinder](https://github.com/getquario/padvinder)** — a JSONPath engine, if you need to _select nodes_ out of a document. Filter evaluation is the part of JSONPath that has produced real code-injection CVEs elsewhere; padvinder parses filters to closures with no route to code execution, and passes the full RFC 9535 compliance suite.
@@ -214,7 +214,7 @@ try {
 }
 ```
 
-Parser codes are `SJABLOON_EACH_SYNTAX`, `SJABLOON_BLOCKED_BINDING`, `SJABLOON_UNEXPECTED_TAG`, `SJABLOON_UNKNOWN_BLOCK`, `SJABLOON_UNCLOSED_BLOCK`, `SJABLOON_RAW_TAG` (a `{{{ }}}` tag outside the HTML edition, located at the whole tag), and `SJABLOON_TOO_DEEP` (block nesting past 256 levels, located at the opener that crossed the cap). A missing closer uses an empty span at the end of the template. Expression offsets refer to the original template, so surrounding braces, whitespace, and trim markers contribute to their absolute position.
+Parser codes are `SJABLOON_EACH_SYNTAX`, `SJABLOON_BLOCKED_BINDING`, `SJABLOON_UNEXPECTED_TAG`, `SJABLOON_UNKNOWN_BLOCK`, `SJABLOON_UNCLOSED_BLOCK`, `SJABLOON_RAW_TAG` (a `{{{ }}}` tag outside the HTML edition, located at the whole tag), and `SJABLOON_TOO_DEEP` (block nesting past 256 levels, located at the opener that crossed the cap; `#elif` links are not nesting and do not count). A missing closer uses an empty span at the end of the template. Expression offsets refer to the original template, so surrounding braces, whitespace, and trim markers contribute to their absolute position.
 
 Errors thrown by registered functions, getters, methods, or value coercion hooks are host errors. Sjabloon passes them through unchanged and does not attach template diagnostic fields. `isDiagnostic(error)` is how you tell the two apart; it authenticates by identity rather than by shape, which has consequences worth knowing if you embed sjabloon — see [EMBEDDING.md](EMBEDDING.md#diagnostic-identity).
 
@@ -268,6 +268,7 @@ If you compile templates out of a larger document — a cell in a report, a fiel
 git clone https://github.com/getquario/sjabloon.git
 cd sjabloon
 npm install
+git config core.hooksPath .githooks   # enable the commit-msg hook
 npm run check
 ```
 

package/lib/core.js

@@ -95,10 +95,14 @@ const EMPTY = Object.freeze({});
 // Shared parser state; parsing is synchronous so this is safe.
 // LIT/VAL/RAW are the compiling profile's node builders — read only while
 // parsing, never at render time, so the hot path stays free of indirection.
-// `nest` is the nesting budget shared by `#if`/`#each`/`#elif` (see opener).
 let /** @type {Tok[]} */ tokens, /** @type {Tok} */ last, /** @type {string} */ source;
-let /** @type {number} */ i, /** @type {number} */ nest;
+let /** @type {number} */ i;
 let /** @type {SjabloonFunctions | undefined} */ fns, /** @type {string[]} */ bound;
+// The compile's `tag`, read once per interpolation while parsing and never at
+// render time. Always callable, so the parse has no branch to take for the
+// embedders that do not ask: this one names nothing.
+let NO_TAG = () => undefined;
+let /** @type {(expr: string) => object | undefined} */ tagOf = NO_TAG;
 let /** @type {Set<string>} */ names, /** @type {Set<string>} */ functions;
 /** @type {{ name: string, start: number, end: number }[]} */
 let reads;
@@ -134,7 +138,8 @@ let takeScanned = (a) => {
   const r = +(lxB > lxP) & +(source[lxB - 1] === "-"),
     whole = source.slice(lxP, lxB - r),
     body = whole.trim(),
-    start = lxP + whole.length - whole.trimStart().length,
+    // search returns -1 on all-whitespace, so start sits on the last `{`.
+    start = lxP + whole.search(/\S/),
     end = lxB + 2 + lxRaw;
   // oxlint-disable-next-line no-unused-expressions
   lxL && trimPrev();
@@ -173,8 +178,7 @@ let snap = () => Object.freeze(blocks.slice());
  */
 let opener = (type, t) => {
   // oxlint-disable-next-line no-unused-expressions
-  nest < 256 || fault("Template too deeply nested", "SJABLOON_TOO_DEEP", t);
-  nest++;
+  blocks.length < 256 || fault("Template too deeply nested", "SJABLOON_TOO_DEEP", t);
   return Object.freeze({ type, start: t[2], end: t[3] });
 };
 /**
@@ -289,10 +293,10 @@ let elseTail = (close, nodes = []) => {
 /**
  * One `#if` branch and whatever hangs off it. An `{{#elif}}` link is itself a
  * branch, so the chain tail recurses straight back in here rather than through
- * a helper. Elif links share the nest budget so they fail closed before the
- * native stack, and the block `opener` mints for one is discarded, never
- * pushed: an elif link must not appear as an extra `#if` frame in diagnostic
- * context. `t` doubles as the scratch slot for the link it builds.
+ * a helper. The block `opener` mints for one is discarded, never pushed: an
+ * elif link is not an extra `#if` frame in diagnostic context and does not
+ * count toward the nesting cap. `t` doubles as the scratch slot for the link
+ * it builds.
  *
  * @param {(v: any) => any} cond
  * @param {Node<any>[]} [then]
@@ -306,7 +310,7 @@ let branch =
     then = parse(["/if", "#elif", "#else"]),
     t = last,
     els = t[1].startsWith("#elif ")
-      ? (opener("elif", t), (t = branch(compileExpr(t[1].slice(6), t[4] + 6))), nest--, [t])
+      ? (opener("elif", t), (t = branch(compileExpr(t[1].slice(6), t[4] + 6))), [t])
       : elseTail("/if"),
   ) =>
   (scope, acc) =>
@@ -368,7 +372,6 @@ let parseEach = (t, tag, nodes) => {
   bound.length = mark;
   const empty = elseTail("/each");
   blocks.pop();
-  nest--;
   nodes.push((scope, acc) => {
     const listValue = list(scope),
       arr = Array.isArray(listValue);
@@ -424,7 +427,6 @@ let emitBlock = (t, tag, nodes) => {
     blocks.push(opener("if", t));
     nodes.push(branch(compileExpr(tag.slice(4), t[4] + 4)));
     blocks.pop();
-    nest--;
     return;
   }
   if (/^#each(?:\s|$)/.test(tag)) return parseEach(t, tag, nodes);
@@ -441,7 +443,7 @@ let emitTag = (t, tag, nodes) => {
   if (tag[0] === "!") return;
   if (tag[0] === "#") return emitBlock(t, tag, nodes);
   if (tag[0] === "/") unexpected(t);
-  nodes.push(VAL(compileExpr(t[1], t[4])));
+  nodes.push(VAL(compileExpr(t[1], t[4]), tagOf(t[1])));
 };
 
 /**
@@ -536,7 +538,8 @@ export const display = (value) =>
  *
  * A profile is `[lit, val, raw, seed, take]`:
  *   lit(text)  node emitting one static text run
- *   val(expr)  node emitting a `{{ }}` interpolation
+ *   val(expr, tagged)  node emitting a `{{ }}` interpolation, carrying what
+ *              the compile's `tag` returned for it (undefined when untagged)
  *   raw(expr)  node emitting a `{{{ }}}` interpolation
  *   seed()     a fresh output accumulator, one per render
  *   take(acc)  the render's return value
@@ -546,7 +549,7 @@ export const display = (value) =>
  * @template T What one render returns.
  * @param {[
  *   lit: (text: string) => Node<A>,
- *   val: (expr: (scope: any) => any) => Node<A>,
+ *   val: (expr: (scope: any) => any, tagged: object | undefined) => Node<A>,
  *   raw: ((expr: (scope: any) => any) => Node<A>) | 0,
  *   seed: () => A,
  *   take: (acc: A) => T,
@@ -563,7 +566,7 @@ export let make = ([lit, val, raw, seed, take]) => {
   /**
    * @param {string} str
    * @param {SjabloonFunctions} [funcs]
-   * @param {{ bound?: Iterable<string> }} [opts]
+   * @param {{ bound?: Iterable<string>, tag?: (expr: string) => object | undefined }} [opts]
    * @returns {SjabloonRenderer<T>}
    */
   function template(str, funcs, opts) {
@@ -576,15 +579,14 @@ export let make = ([lit, val, raw, seed, take]) => {
     // bundler's transpile turns an iterable spread into a concat that would
     // wrap a Set instead of unpacking it. `Object(opts)` stands in for the
     // missing-opts check; nothing iterable comes out of an empty string.
-    bound = ["$", "@"].concat(
-      Array.from(/** @type {Iterable<string>} */ (Object(opts).bound || "")),
-    );
+    let { bound: declared = "", tag = NO_TAG } = Object(opts);
+    bound = ["$", "@"].concat(Array.from(/** @type {Iterable<string>} */ (declared)));
+    tagOf = tag;
     names = new Set();
     reads = [];
     functions = new Set();
     source = String(str);
     blocks = [];
-    nest = 0;
     // The lexer's own state, then one linear pass: inline here because it runs
     // exactly once per compile and the parser rewinds `i` straight after.
     tokens = [];
@@ -593,7 +595,7 @@ export let make = ([lit, val, raw, seed, take]) => {
     while (i < source.length && lexStep());
     i = 0;
     // Deeply nested blocks fail as SJABLOON_TOO_DEEP at the cap in opener(),
-    // including elif chains — well below the native stack.
+    // well below the native stack.
     let nodes = parse([]);
     // 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

package/lib/index.js

@@ -14,7 +14,14 @@ export const { template, render } = make([
   (text, token = Object.freeze({ literal: text })) =>
     (scope, acc) =>
       acc.push(token),
-  (expr) => (scope, acc) => acc.push({ value: expr(scope) }),
+  // A tagged interpolation spreads what the compile's `tag` returned; the
+  // value is written last, so the token's own key cannot be taken over. The
+  // branch is taken once at compile time, so an untagged template emits the
+  // exact closure it always did.
+  (expr, tagged) =>
+    tagged
+      ? (scope, acc) => acc.push({ ...tagged, value: expr(scope) })
+      : (scope, acc) => acc.push({ value: expr(scope) }),
   0,
   () => /** @type {import('./types.js').Token[]} */ ([]),
   (acc) => acc,

package/lib/types.d.ts

@@ -104,7 +104,23 @@ export interface SjabloonRenderer<T> {
 export type SjabloonTemplate<T> = (
   str: string,
   funcs?: SjabloonFunctions,
-  opts?: { bound?: Iterable<string> },
+  opts?: {
+    bound?: Iterable<string>;
+    /**
+     * Name an interpolation by what it says. Called once per `{{ }}` while
+     * compiling, with that interpolation's expression source as written and
+     * trimmed (`{{- page.number -}}` is `"page.number"`), and never again at
+     * render time. Returned keys join every value token that interpolation
+     * emits; `value` and `literal` are the stream's own, so a tag may not
+     * supply either. It runs inside the parse, which is shared synchronous
+     * state: read the expression and return, and compile no template from
+     * within it. Block expressions
+     * (`#if` conditions, `#each` collections) emit no token and are not
+     * offered. The token edition alone has tokens to carry them; the string
+     * editions ignore this.
+     */
+    tag?: (expr: string) => object | undefined;
+  },
 ) => SjabloonRenderer<T>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
@@ -119,7 +135,13 @@ export interface LiteralToken {
   literal: string;
 }
 
-/** One `{{ }}` interpolation, pre-stringify. Nullish values are preserved. */
+/**
+ * One `{{ }}` interpolation, pre-stringify. Nullish values are preserved.
+ *
+ * A compile that passed `tag` also carries that interpolation's returned keys
+ * here, under the names the embedder chose; declare them by intersecting this
+ * type with your own, as `ValueToken & { field?: string }`.
+ */
 export interface ValueToken {
   value: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sjabloon",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
   "keywords": [
     "csp",
@@ -42,6 +42,7 @@
     "bench": "node --disallow-code-generation-from-strings bench/index.js",
     "bench:comparison": "npm --prefix bench/comparison run bench",
     "check": "run-s fmt:check lint fallow size test fuzz:regression test:browser",
+    "commitlint": "commitlint",
     "fallow": "fallow",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
@@ -67,13 +68,15 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@jazzer.js/bug-detectors": "^4.0.0",
     "@jazzer.js/core": "^4.0.0",
     "@size-limit/preset-small-lib": "^13.0.3",
     "c8": "^12.0.0",
     "fallow": "^3.17.0",
     "npm-run-all": "^4.1.5",
-    "oxfmt": "^0.64.0",
+    "oxfmt": "^0.66.0",
     "oxlint": "^1.78.0",
     "oxlint-tsgolint": "^7.0.2001",
     "playwright": "^1.61.1",