sjabloon 0.8.0 → 0.10.0

package/README.md

@@ -13,31 +13,41 @@ A tiny, CSP-safe, target-neutral template engine for JavaScript. **~1.9KB min+br
 	</picture>
 </a>
 
-*Sjabloon* is Dutch for "template". It renders templates with full [xprsn](https://github.com/getquario/xprsn) expressions inside every tag, without turning template text into JavaScript. There is no `eval` and no `new Function`, so it runs under a strict Content Security Policy where engines that compile templates to code cannot.
+_Sjabloon_ is Dutch for "template". It renders templates with full [xprsn](https://github.com/getquario/xprsn) expressions inside every tag, without turning template text into JavaScript. There is no `eval` and no `new Function`, so it runs under a strict Content Security Policy where engines that compile templates to code cannot.
 
-The engine emits **tokens**, not text. A render gives you the literal runs and the interpolated values, interleaved in render order — because different targets need different things from the same template. HTML wants escaped text; a spreadsheet wants the number `1000` and a cell format; a PDF wants styled runs. Escaping belongs at the output edge, not in the engine, so a string is just one way to consume the stream.
+The engine emits **tokens**, not text. A render gives you the literal runs and the interpolated values, interleaved in render order. Different targets need different things from the same template: HTML wants escaped text, a spreadsheet wants the number `1000` and a cell format. Escaping belongs at the output edge, not in the engine, so a string is just one way to consume the stream.
+
+## Install
+
+```bash
+npm install sjabloon
+```
+
+Node.js 22.12 or newer, ESM only.
+
+## Usage
 
 ```js
-import { template, text } from 'sjabloon';
+import { template, text } from "sjabloon";
 
-const cell = template('{{ total * 1.21 }}');
+const cell = template("{{ total * 1.21 }}");
 
-cell({ total: 1000 });        // => [{ value: 1210 }]      — still a number
-text(cell({ total: 1000 }));  // => '1210'                 — when you want the string
+cell({ total: 1000 }); // => [{ value: 1210 }]      // still a number
+text(cell({ total: 1000 })); // => '1210'                 // when you want the string
 ```
 
 If you only want a string, import the edition that produces one directly:
 
 ```js
-import { render } from 'sjabloon/html';   // {{ }} HTML-escapes, {{{ }}} is raw
+import { render } from "sjabloon/html"; // {{ }} HTML-escapes, {{{ }}} is raw
 
 render(
   `<ul>{{#each items as it, i}}
     <li>{{ i + 1 }}. {{ it.name }}: {{ fmt(it.price * it.qty) }}</li>
   {{/each}}</ul>
   {{#if total >= 100 and "vip" in user.roles}}Free shipping!{{#else}}Shipping: {{ fmt(5) }}{{/if}}`,
-  { items: [{ name: 'Koffie', price: 8, qty: 2 }], total: 120, user: { roles: ['vip'] } },
-  { fmt: n => '€' + n.toFixed(2) }
+  { items: [{ name: "Koffie", price: 8, qty: 2 }], total: 120, user: { roles: ["vip"] } },
+  { fmt: (n) => "€" + n.toFixed(2) },
 );
 ```
 
@@ -45,50 +55,70 @@ render(
 
 Three entry points, one engine. They share a parser, a syntax, and a diagnostics contract, and differ only in what a render produces.
 
-| Import | `template(str, funcs?)` returns | `{{ expr }}` | `{{{ expr }}}` |
-| --- | --- | --- | --- |
-| `sjabloon` | `(values?, scope?) => Token[]` | value token | `SyntaxError` |
-| `sjabloon/text` | `(values?, scope?) => string` | unescaped | `SyntaxError` |
-| `sjabloon/html` | `(values?, scope?) => string` | HTML-escaped | raw |
+| Import          | `template(str, funcs?)` returns | `{{ expr }}` | `{{{ expr }}}` |
+| --------------- | ------------------------------- | ------------ | -------------- |
+| `sjabloon`      | `(values?, scope?) => Token[]`  | value token  | `SyntaxError`  |
+| `sjabloon/text` | `(values?, scope?) => string`   | unescaped    | `SyntaxError`  |
+| `sjabloon/html` | `(values?, scope?) => string`   | HTML-escaped | raw            |
 
-`{{{ }}}` exists only in the HTML edition, where "raw" means something. Everywhere else `{{ }}` is already raw, so the triple form is a compile-time `SJABLOON_RAW_TAG` error rather than a silent synonym.
+`{{{ }}}` exists only in the HTML edition, where "raw" means something. Everywhere else `{{ }}` is already raw, so the triple form is a compile-time `SJABLOON_RAW_TAG` error.
 
-Every edition exports `template`, `render`, and `isDiagnostic`. They all resolve to one shared core, so a diagnostic thrown through any of them authenticates through all of them.
+Every edition exports `template`, `render`, `isDiagnostic`, and `relocate`. They all resolve to one shared core, so a diagnostic thrown through any of them authenticates through all of them.
 
 ## 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.
 
-The anchors `$` (root) and `@` (current `{{#each}}` item) work as [described below](#syntax) with no extra arguments — at the root, before any loop, both point at `values`. If you're embedding sjabloon under an engine with its own scope model, pass `{ root, item }` as the second argument to seed the two root anchors from distinct objects: `$` becomes `root` and `@` becomes `item`. Omit `item` and `@` stays unbound at the root, so reading `@.x` throws where there is no current item. Either way, `{{#each}}` still re-points `@` to the current item inside its body.
+The anchors `$` (root) and `@` (current `{{#each}}` item) work as [described below](#syntax) with no extra arguments. At the root, before any loop, both point at `values`. If you're embedding sjabloon under an engine with its own scope model, pass `{ root, item }` as the second argument to seed the two root anchors from distinct objects: `$` becomes `root` and `@` becomes `item`. Omit `item` and `@` stays unbound at the root, so reading `@.x` throws where there is no current item. Either way, `{{#each}}` still re-points `@` to the current item inside its body.
 
 ```js
-const tpl = template('{{ $.report }} — {{ @.row }}');
+const tpl = template("{{ $.report }} / {{ @.row }}");
 tpl(base, { root: reportRoot, item: currentRow }); // $ = reportRoot, @ = currentRow
-tpl(base, { root: reportRoot });                   // no item → @.x throws
+tpl(base, { root: reportRoot }); // no item → @.x throws
 ```
 
 The renderer carries `names` (every variable the template reads from your values, loop variables excluded) and `functions` (the registry functions it calls, methods excluded), both deduplicated. Check a stored template against your data model and its allowed functions before you render it, or fetch only the fields it needs.
 
 ```js
-const tpl = template('{{ fmt(title) }}{{#each items as it}}{{ it.name }}{{/each}}', { fmt: s => s });
-tpl.names;     // => ['title', 'items']
+const tpl = template("{{ fmt(title) }}{{#each items as it}}{{ it.name }}{{/each}}", {
+  fmt: (s) => s,
+});
+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.
 
-### `text(tokens)` — root entry only
+### `text(tokens)` (root entry only)
 
-Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values as `String(value ?? '')`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values — a property the test suite and the fuzzer both check.
+Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values as `String(value ?? '')`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values. The test suite and the fuzzer both check that.
 
 ```js
-import { template, text } from 'sjabloon';
+import { template, text } from "sjabloon";
 
-const tokens = template('{{ qty }} × {{ name }}')({ qty: 2, name: 'Koffie' });
+const tokens = template("{{ qty }} × {{ name }}")({ qty: 2, name: "Koffie" });
 // => [{ value: 2 }, { literal: ' × ' }, { value: 'Koffie' }]
 
 text(tokens); // => '2 × Koffie'
@@ -96,9 +126,9 @@ text(tokens); // => '2 × Koffie'
 
 A `Token` is either `{ literal: string }` or `{ value: unknown }`:
 
-- **Values are pre-stringify.** `{{ total }}` holding `1000` yields the number `1000`, not `"1000"`, and nullish stays nullish. Stringification is deferred to `text()` — so a value with no primitive conversion reaches the stream intact and only fails when something asks for text.
-- **Order is render order.** Loop bodies append once per iteration, untaken branches append nothing, and block expressions (`#if` conditions, `#each` collections) never appear — they steer the render rather than being part of it.
-- **Literals are the template's static runs**, one token each, never merged and never empty. So the interleaving tells you the shape: a bare `{{ amount }}` is exactly one value token, while `Total: {{ amount }}` is a literal followed by a value. That distinction is why the engine emits tokens instead of a string plus a list of values — a spreadsheet cell that is *only* a number is a different thing from one that happens to contain one.
+- **Values are pre-stringify.** `{{ total }}` holding `1000` yields the number `1000`, not `"1000"`, and nullish stays nullish. Stringification is deferred to `text()`, so a value with no primitive conversion reaches the stream intact and only fails when something asks for text.
+- **Order is render order.** Loop bodies append once per iteration, untaken branches append nothing, and block expressions (`#if` conditions, `#each` collections) never appear. They steer the render; they are not part of the stream.
+- **Literals are the template's static runs**, one token each, never merged and never empty. The interleaving tells you the shape: a bare `{{ amount }}` is exactly one value token, while `Total: {{ amount }}` is a literal followed by a value. That is why the engine emits tokens instead of a string plus a list of values. A spreadsheet cell that is _only_ a number is a different thing from one that happens to contain one.
 
 Literal tokens are frozen and shared across loop iterations; value tokens are fresh per emit.
 
@@ -117,19 +147,36 @@ Unauthenticated errors thrown by registered functions, getters, methods, or valu
 
 Use `isDiagnostic(error)` when a host needs to distinguish those errors. It returns `true` only for errors produced or translated by the same sjabloon module instance. Copying a documented `code`, `start`, `end`, and `blocks` onto another error does not authenticate it. A diagnostic from another installed copy or module instance returns `false`. All three editions share one core, so mixing them in a single process is safe: an error thrown through `sjabloon/html` authenticates through `sjabloon`.
 
+#### Relocating a diagnostic
+
+An embedder that compiles templates out of a larger document — a cell in a report, a field in a form — reports the fault in its own coordinates, not the template's. `relocate(diagnostic, { prefix, offset })` returns the copy to re-throw:
+
+```js
+import { isDiagnostic, relocate, template } from "sjabloon";
+
+try {
+  template(cell.value);
+} catch (error) {
+  if (!isDiagnostic(error)) throw error;
+  throw relocate(error, { prefix: "detail.cells[0].value: " });
+}
+```
+
+The copy keeps the original's class, prepends `prefix` to the message verbatim, shifts `start` and `end` by `offset`, and carries every other field across by descriptor — including the frozen `blocks` context, which stays frozen and non-writable on the copy. `blocks` is the same array, so its openers' own `start`/`end` stay in template coordinates while the error's span moves. It is registered exactly as the original was, so it passes `isDiagnostic` — and an expression fault, which is an xprsn diagnostic sjabloon translated into template coordinates, is relocated by xprsn so the copy stays authentic to both packages just as the original is. The original is left untouched. Relocation belongs here rather than in the embedder because authentication is by identity: a copy an embedder builds itself cannot be authenticated, and a field added to a diagnostic here would be a field the embedder's copy silently drops. Passing anything but a sjabloon diagnostic throws a `TypeError`.
+
 ## Syntax
 
-| Tag | Meaning |
-| --- | --- |
-| `{{ expr }}` | Interpolate an expression — a value token, or text escaped per edition |
-| `{{{ expr }}}` | Interpolate raw. **`sjabloon/html` only**; a `SyntaxError` elsewhere |
-| `{{#if expr}} … {{#elif expr}} … {{#else}} … {{/if}}` | Conditional block, with as many `{{#elif}}` links as you need |
-| `{{#each expr as item}} … {{/each}}` | Loop over an array or an object's values |
-| `{{#each expr as item, key}} … {{/each}}` | Second name binds the index (arrays) or the key (objects) |
-| `{{#each expr as item}} … {{#else}} … {{/each}}` | The `{{#else}}` branch renders when the collection is empty or missing |
-| `{{ loop.last }}` (inside `{{#each}}`) | Iteration metadata: `index` (1-based), `index0`, `first`, `last`, `length` |
-| `{{! anything }}` | Comment, removed from output |
-| `{{- expr -}}` | A dash hugging either brace trims the whitespace on that side, newlines included; works on every tag form |
+| Tag                                                   | Meaning                                                                                                   |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `{{ expr }}`                                          | Interpolate an expression: a value token, or text escaped per edition                                     |
+| `{{{ expr }}}`                                        | Interpolate raw. **`sjabloon/html` only**; a `SyntaxError` elsewhere                                      |
+| `{{#if expr}} … {{#elif expr}} … {{#else}} … {{/if}}` | Conditional block, with as many `{{#elif}}` links as you need                                             |
+| `{{#each expr as item}} … {{/each}}`                  | Loop over an array or an object's values                                                                  |
+| `{{#each expr as item, key}} … {{/each}}`             | Second name binds the index (arrays) or the key (objects)                                                 |
+| `{{#each expr as item}} … {{#else}} … {{/each}}`      | The `{{#else}}` branch renders when the collection is empty or missing                                    |
+| `{{ loop.last }}` (inside `{{#each}}`)                | Iteration metadata: `index` (1-based), `index0`, `first`, `last`, `length`                                |
+| `{{! anything }}`                                     | Comment, removed from output                                                                              |
+| `{{- expr -}}`                                        | A dash hugging either brace trims the whitespace on that side, newlines included; works on every tag form |
 
 Every `expr` is an [xprsn expression](https://github.com/getquario/xprsn#syntax): literals, arithmetic, string concatenation with `~` (`{{ first ~ " " ~ last }}`), comparisons, `and`/`or`/`not`/`in`, ternaries, property and method access, and functions from the registry you pass in. `null` and `undefined` render as empty strings.
 
@@ -138,7 +185,7 @@ A loop body sees its loop variable plus the outer scope; reusing an outer name s
 Inside `{{#each}}`, a `loop` object holds the iteration state: `index` (1-based), `index0`, `first`, `last`, and `length`. Use `loop.last` for separators and trailing borders, or `loop.index` with `loop.length` for "row X of Y". Each nested loop gets its own.
 
 ```js
-render('{{#each xs as x}}{{ x }}{{#if not loop.last}}, {{/if}}{{/each}}', { xs: ['a', 'b', 'c'] });
+render("{{#each xs as x}}{{ x }}{{#if not loop.last}}, {{/if}}{{/each}}", { xs: ["a", "b", "c"] });
 // => 'a, b, c'
 ```
 
@@ -146,8 +193,8 @@ Two anchors are always in scope: `$` is the root values and `@` is the current `
 
 ```js
 render(
-  '{{#each regions as company}}{{ company }} of {{ $.company }}: {{#each rows as r}}{{ @.n }} {{/each}}{{/each}}',
-  { company: 'ACME', regions: ['North', 'South'], rows: [{ n: 1 }, { n: 2 }] }
+  "{{#each regions as company}}{{ company }} of {{ $.company }}: {{#each rows as r}}{{ @.n }} {{/each}}{{/each}}",
+  { company: "ACME", regions: ["North", "South"], rows: [{ n: 1 }, { n: 2 }] },
 );
 // => 'North of ACME: 1 2 South of ACME: 1 2 '
 ```
@@ -171,7 +218,18 @@ That runtime CSP support costs some render speed. Handlebars and tempura generat
 
 Node.js 22.12 and newer, ESM only. Browser use is supported through a standards-based ESM bundler in environments supporting ES2024. Direct `<script>` globals, UMD, and CommonJS builds are not provided.
 
-Shipping CommonJS alongside ESM would put two copies of the core in any process that mixed `require` and `import`, and therefore two diagnostic identities — `isDiagnostic` would silently return `false` across the seam. One format removes that failure mode instead of documenting it.
+Shipping CommonJS alongside ESM would put two copies of the core in any process that mixed `require` and `import`. Each copy would have its own diagnostic identity, so `isDiagnostic` would return `false` across the seam.
+
+## Contributing
+
+```bash
+git clone https://github.com/getquario/sjabloon.git
+cd sjabloon
+npm install
+npm run check
+```
+
+`npm run check` is the local gate. Conventions for this repo live in [AGENTS.md](AGENTS.md).
 
 ## License