sjabloon 0.4.1 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # sjabloon
 
-A tiny, CSP-safe template engine for JavaScript. **~1.2KB min+gzip (~2.5KB with [xprsn](https://www.npmjs.com/package/xprsn)), one dependency.**
+A tiny, CSP-safe template engine for JavaScript. **~1.8KB min+gzip (~3.6KB with [xprsn](https://www.npmjs.com/package/xprsn)), one dependency.**
 
 [![NPM version](https://img.shields.io/npm/v/sjabloon.svg)](https://www.npmjs.com/package/sjabloon)
 [![Build Status](https://github.com/robinvdvleuten/sjabloon/actions/workflows/test.yml/badge.svg)](https://github.com/robinvdvleuten/sjabloon/actions/workflows/test.yml)
@@ -59,6 +59,21 @@ tpl.functions; // => ['fmt']
 
 Shorthand for `template(str, functions)(values)`.
 
+### Error diagnostics
+
+Sjabloon errors keep their native `SyntaxError` or `TypeError` class and expose:
+
+- `code`: a stable `SJABLOON_*` parser category or the original `XPRSN_*` expression category;
+- `start`: a zero-based offset in the original template;
+- `end`: the exclusive template offset;
+- `blocks`: a frozen, outermost-first array of `{ type, start, end }` opener spans.
+
+Parser codes are `SJABLOON_EACH_SYNTAX`, `SJABLOON_BLOCKED_BINDING`, `SJABLOON_UNEXPECTED_TAG`, `SJABLOON_UNKNOWN_BLOCK`, `SJABLOON_UNCLOSED_BLOCK`, 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.
+
+Unauthenticated 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.
+
+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 also returns `false`.
+
 ## Syntax
 
 | Tag | Meaning |
@@ -100,13 +115,18 @@ Here the loop variable `company` shadows the root's for a bare name, but `$.comp
 
 sjabloon works under `script-src 'self'` with no `unsafe-eval`. Templates parse into a tree of closures that call other closures; xprsn compiles the expressions the same way. The test suite runs under `node --disallow-code-generation-from-strings`, which throws on any string-to-code construct exactly like a strict CSP does.
 
-This is the practical difference from engines like Handlebars (without precompilation) or tempura, which generate a JavaScript function per template and therefore need `unsafe-eval` at runtime. If you can precompile templates at build time, those engines are great and fast. If templates arrive at runtime (user-edited templates, CMS content, email templates) and your CSP is strict, sjabloon fits.
+That runtime CSP support costs some render speed. Handlebars and tempura generate specialized JavaScript, so their compiled renderers are faster but runtime compilation requires `unsafe-eval`. Build-time precompilation avoids that restriction when templates are known in advance. If templates arrive at runtime (user-edited templates, CMS content, email templates) and your CSP is strict, sjabloon fits. See the [comparison benchmarks](bench/comparison/) for cold-compile and hot-render comparisons.
 
 ## Safety
 
 - `{{ expr }}` escapes `& < > " '` by default; unescaped output requires the explicit `{{{ }}}` form.
 - Expressions inherit all of xprsn's guards: no `__proto__`/`constructor`/`prototype` access, null-prototype hash literals, and functions resolved only from your registry.
 - Templates read your values; they cannot assign to them.
+- Registered functions are host-provided capabilities, not a sandbox boundary. Only register helpers that template authors are allowed to invoke; likewise, treat explicit raw output as trusted HTML.
+
+## Environments
+
+Node.js 22 and newer are supported through the ESM and CommonJS builds. Browser use is supported through a standards-based ESM bundler in environments supporting ES2024. Direct `<script>` globals and UMD builds are not provided.
 
 ## License
 

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("xprsn");const t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`},n=e=>String(e).replace(/[&<>"']/g,e=>t[e]),r=/^(?:__proto__|constructor|prototype)$/,i=e=>Array.isArray(e)?e.map((e,t)=>[e,t]):e&&typeof e==`object`?Object.keys(e).map(t=>[e[t],t]):[];let a=e=>{let t=[];for(let n=0,r=1;n<e.length;){let i=e.indexOf(`{{`,n);if(i<0){t.push({text:e.slice(n)});break}i>n&&t.push({text:e.slice(n,i)});let a=e.charCodeAt(i+2)===123,o=i+2+a,s=e.charCodeAt(o)===45,c=-1;if(s&&o++,a&&r&&(c=e.indexOf(`}}}`,o),c<0&&(r=0)),c<0&&(a&&(a=!1,o=i+2,s=e.charCodeAt(o)===45,s&&o++),c=e.indexOf(`}}`,o)),c<0){t.push({text:e.slice(i)});break}let l=c>o&&e.charCodeAt(c-1)===45,u=e.slice(o,l?c-1:c).trim(),d=a?{raw:u}:{tag:u};d.l=s,d.r=l,t.push(d),n=c+2+a}return t},o,s,c,l,u,d,f,p=e=>{throw SyntaxError(e)},m=(e,t)=>e.map(e=>e(t)).join(``),h=(e,t)=>(e=>n=>t(e(n)??``))(_(e)),g=(...e)=>{let t=e.filter(e=>e&&!u.has(e));return t.forEach(e=>u.add(e)),()=>t.forEach(e=>u.delete(e))},_=t=>{let n=(0,e.compile)(t,c);for(let e of n.names)u.has(e)||d.add(e);for(let e of n.functions)f.add(e);return n},v=e=>{let t=y([`#elif`,`#else`,`/if`]),n=l.startsWith(`#elif `)?[v(_(l.slice(6)))]:l===`#else`?y([`/if`]):[];return r=>m(e(r)?t:n,r)},y=e=>{let t=[];for(let a;a=o[s++];)if(a.text!=null)t.push((e=>()=>e)(a.text));else if(a.raw!=null)t.push(h(a.raw,String));else if(e.includes(a.tag.split(` `)[0]))return l=a.tag,t;else if(a.tag[0]!==`!`)if(a.tag.startsWith(`#if `))t.push(v(_(a.tag.slice(4))));else if(a.tag.startsWith(`#each `)){let e=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(a.tag)||p(`Bad {{`+a.tag+`}}`),n=_(e[1]),o=e[2],s=e[3];(r.test(o)||s&&r.test(s))&&p(`Bad {{`+a.tag+`}}`);let c=g(o,s,`loop`),u=y([`#else`,`/each`]);c();let d=l===`#else`?y([`/each`]):[];t.push(e=>{let t=i(n(e));return t.length?t.map(([n,r],i)=>{let a=Object.create(e);return a[o]=n,s&&(a[s]=r),a[`@`]=n,a.loop={index:i+1,index0:i,first:!i,last:i===t.length-1,length:t.length},m(u,a)}).join(``):m(d,e)})}else a.tag[0]===`#`||a.tag[0]===`/`?p(`Unexpected {{`+a.tag+`}}`):t.push(h(a.tag,n));return e.length&&p(`Missing {{`+e[e.length-1]+`}}`),t};function b(e,t){c=t,u=new Set([`$`,`@`]),d=new Set,f=new Set,o=a(String(e)),o.forEach((e,t)=>{e.l&&o[t-1]?.text&&(o[t-1].text=o[t-1].text.trimEnd()),e.r&&o[t+1]?.text&&(o[t+1].text=o[t+1].text.trimStart())}),s=0;let n=y([]),r=(e,t)=>{e||={};let r=Object.create(e);return r.$=t?t.root:e,t?`item`in t&&(r[`@`]=t.item):r[`@`]=e,m(n,r)};return r.names=Array.from(d),r.functions=Array.from(f),r}function x(e,t,n){return b(e,n)(t)}exports.render=x,exports.template=b;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("xprsn");const t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`},n=e=>String(e).replace(/[&<>"']/g,e=>t[e]),r=/^(?:__proto__|constructor|prototype)$/,i=new WeakSet,a=i.add.bind(i),o=i.has.bind(i),s=e=>o(e);let c=e=>{let t=[];for(let n=0,r=1;n<e.length;){let i=e.indexOf(`{{`,n);if(i<0){t.push([0,e.slice(n)]);break}i>n&&t.push([0,e.slice(n,i)]);let a=e[i+2]===`{`,o=i+2+a,s=e[o]===`-`,c=-1;if(s&&o++,a&&r&&(c=e.indexOf(`}}}`,o),c<0&&(r=0)),c<0&&(a&&(a=!1,o=i+2,s=e[o]===`-`,s&&o++),c=e.indexOf(`}}`,o)),c<0){t.push([0,e.slice(i)]);break}let l=c>o&&e[c-1]===`-`,u=l?c-1:c,d=e.slice(o,u),f=d.trim(),p=o+d.length-d.trimStart().length,m=c+2+a,h=[a?1:2,f,i,m,p],g=t.at(-1);if(s&&g?.[0]===0&&g[1]&&(g[1]=g[1].trimEnd()),t.push(h),n=m,l)for(;/\s/.test(e[n]);)n++}return t},l,u,d,f,p,m,h,g,_,v=()=>Object.freeze(_.slice()),y=(e,t)=>(_.length<256||x(`Template too deeply nested`,`SJABLOON_TOO_DEEP`,t),Object.freeze({type:e,start:t[2],end:t[3]})),b=(e,t)=>(Object.defineProperty(e,"blocks",{value:t,enumerable:!0}),a(e),e),x=(e,t,n,r=n?.[2]??g.length,i=n?.[3]??g.length)=>{let a=SyntaxError(e);throw a.code=t,a.start=r,a.end=i,b(a,v())},S=(t,n,r,i=e.isDiagnostic)=>{throw i(t)?(t.start+=n,t.end+=n,b(t,r)):t},C=e=>x(`Unexpected {{`+e[1]+`}}`,`SJABLOON_UNEXPECTED_TAG`,e),w=(e,t)=>e.map(e=>e(t)).join(``),T=(e,t)=>(e=>n=>t(e(n)??``))(E(e[1],e[4],v())),E=(t,n,r)=>{let i;try{i=(0,e.compile)(t,d)}catch(e){S(e,n,r)}for(let e of i.names)p.includes(e)||m.add(e);for(let e of i.functions)h.add(e);return e=>{try{return i(e)}catch(e){S(e,n,r,i.isDiagnostic)}}},D=e=>{let t=O([`#elif`,`#else`,`/if`]),n=f[1],r=[];return n.startsWith(`#elif `)?r=[D(E(n.slice(6),f[4]+6,v()))]:n===`#else`?(r=O([`/if`]),f[1]===`/if`||C(f)):n!==`/if`&&C(f),n=>w(e(n)?t:r,n)},O=e=>{let t=[];for(let i;i=l[u++];){let a=i[1];if(!i[0])t.push((e=>()=>e)(a));else if(i[0]===1)t.push(T(i,String));else if(e.includes(a.split(` `)[0]))return f=i,t;else if(a[0]!==`!`)if(a.startsWith(`#if `))_.push(y(`if`,i)),t.push(D(E(a.slice(4),i[4]+4,v()))),_.pop();else if(/^#each(?:\s|$)/.test(a)){_.push(y(`each`,i));let e=/^#each ([\s\S]+) as ((\w+)(?:\s*,\s*(\w+))?)$/.exec(a);e||x(`Bad {{`+a+`}}`,`SJABLOON_EACH_SYNTAX`,i);let n=e[3],o=e[4],s=i[4]+a.length-e[2].length;if(r.test(n)&&x(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,i,s,s+n.length),o&&r.test(o)){let e=i[4]+a.length-o.length;x(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,i,e,e+o.length)}let c=E(e[1],i[4]+6,v()),l=p.length;p.push(n),o&&p.push(o),p.push(`loop`);let u=O([`#else`,`/each`]);p.length=l;let d=[];f[1]===`#else`?(d=O([`/each`]),f[1]===`/each`||C(f)):f[1]!==`/each`&&C(f),_.pop(),t.push(e=>{let t=c(e),r=Array.isArray(t),i=r?t.slice():t&&typeof t==`object`?Object.keys(t).map(e=>[t[e],e]):[];return i.length?i.map((t,a)=>{let s=r?t:t[0],c=r?a:t[1],l=Object.create(e);return l[n]=s,o&&(l[o]=c),l[`@`]=s,l.loop={index:a+1,index0:a,first:!a,last:a===i.length-1,length:i.length},w(u,l)}).join(``):w(d,e)})}else/^#(?:if|elif|else)(?:\s|$)/.test(a)||a[0]===`/`?C(i):a[0]===`#`?x(`Unknown {{`+a+`}}`,`SJABLOON_UNKNOWN_BLOCK`,i):t.push(T(i,n))}return e.length&&x(`Missing {{`+e[e.length-1]+`}}`,`SJABLOON_UNCLOSED_BLOCK`),t};function k(e,t){d=t,p=[`$`,`@`],m=new Set,h=new Set,g=String(e),_=[],l=c(g),u=0;let n;try{n=O([])}catch(e){throw e instanceof RangeError&&x(`Template too deeply nested`,`SJABLOON_TOO_DEEP`),e}let r=(e,t)=>{e||={};let r=Object.create(e);return r.$=t?t.root:e,t?`item`in t&&(r[`@`]=t.item):r[`@`]=e,w(n,r)};return r.names=Array.from(m),r.functions=Array.from(h),r}function A(e,t,n){return k(e,n)(t)}exports.isDiagnostic=s,exports.render=A,exports.template=k;

package/dist/index.js

@@ -1 +1 @@
-import{compile as e}from"xprsn";const t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`},n=e=>String(e).replace(/[&<>"']/g,e=>t[e]),r=/^(?:__proto__|constructor|prototype)$/,i=e=>Array.isArray(e)?e.map((e,t)=>[e,t]):e&&typeof e==`object`?Object.keys(e).map(t=>[e[t],t]):[];let a=e=>{let t=[];for(let n=0,r=1;n<e.length;){let i=e.indexOf(`{{`,n);if(i<0){t.push({text:e.slice(n)});break}i>n&&t.push({text:e.slice(n,i)});let a=e.charCodeAt(i+2)===123,o=i+2+a,s=e.charCodeAt(o)===45,c=-1;if(s&&o++,a&&r&&(c=e.indexOf(`}}}`,o),c<0&&(r=0)),c<0&&(a&&(a=!1,o=i+2,s=e.charCodeAt(o)===45,s&&o++),c=e.indexOf(`}}`,o)),c<0){t.push({text:e.slice(i)});break}let l=c>o&&e.charCodeAt(c-1)===45,u=e.slice(o,l?c-1:c).trim(),d=a?{raw:u}:{tag:u};d.l=s,d.r=l,t.push(d),n=c+2+a}return t},o,s,c,l,u,d,f,p=e=>{throw SyntaxError(e)},m=(e,t)=>e.map(e=>e(t)).join(``),h=(e,t)=>(e=>n=>t(e(n)??``))(_(e)),g=(...e)=>{let t=e.filter(e=>e&&!u.has(e));return t.forEach(e=>u.add(e)),()=>t.forEach(e=>u.delete(e))},_=t=>{let n=e(t,c);for(let e of n.names)u.has(e)||d.add(e);for(let e of n.functions)f.add(e);return n},v=e=>{let t=y([`#elif`,`#else`,`/if`]),n=l.startsWith(`#elif `)?[v(_(l.slice(6)))]:l===`#else`?y([`/if`]):[];return r=>m(e(r)?t:n,r)},y=e=>{let t=[];for(let a;a=o[s++];)if(a.text!=null)t.push((e=>()=>e)(a.text));else if(a.raw!=null)t.push(h(a.raw,String));else if(e.includes(a.tag.split(` `)[0]))return l=a.tag,t;else if(a.tag[0]!==`!`)if(a.tag.startsWith(`#if `))t.push(v(_(a.tag.slice(4))));else if(a.tag.startsWith(`#each `)){let e=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(a.tag)||p(`Bad {{`+a.tag+`}}`),n=_(e[1]),o=e[2],s=e[3];(r.test(o)||s&&r.test(s))&&p(`Bad {{`+a.tag+`}}`);let c=g(o,s,`loop`),u=y([`#else`,`/each`]);c();let d=l===`#else`?y([`/each`]):[];t.push(e=>{let t=i(n(e));return t.length?t.map(([n,r],i)=>{let a=Object.create(e);return a[o]=n,s&&(a[s]=r),a[`@`]=n,a.loop={index:i+1,index0:i,first:!i,last:i===t.length-1,length:t.length},m(u,a)}).join(``):m(d,e)})}else a.tag[0]===`#`||a.tag[0]===`/`?p(`Unexpected {{`+a.tag+`}}`):t.push(h(a.tag,n));return e.length&&p(`Missing {{`+e[e.length-1]+`}}`),t};function b(e,t){c=t,u=new Set([`$`,`@`]),d=new Set,f=new Set,o=a(String(e)),o.forEach((e,t)=>{e.l&&o[t-1]?.text&&(o[t-1].text=o[t-1].text.trimEnd()),e.r&&o[t+1]?.text&&(o[t+1].text=o[t+1].text.trimStart())}),s=0;let n=y([]),r=(e,t)=>{e||={};let r=Object.create(e);return r.$=t?t.root:e,t?`item`in t&&(r[`@`]=t.item):r[`@`]=e,m(n,r)};return r.names=Array.from(d),r.functions=Array.from(f),r}function x(e,t,n){return b(e,n)(t)}export{x as render,b as template};
+import{compile as e,isDiagnostic as t}from"xprsn";const n={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`},r=e=>String(e).replace(/[&<>"']/g,e=>n[e]),i=/^(?:__proto__|constructor|prototype)$/,a=new WeakSet,o=a.add.bind(a),s=a.has.bind(a),c=e=>s(e);let l=e=>{let t=[];for(let n=0,r=1;n<e.length;){let i=e.indexOf(`{{`,n);if(i<0){t.push([0,e.slice(n)]);break}i>n&&t.push([0,e.slice(n,i)]);let a=e[i+2]===`{`,o=i+2+a,s=e[o]===`-`,c=-1;if(s&&o++,a&&r&&(c=e.indexOf(`}}}`,o),c<0&&(r=0)),c<0&&(a&&(a=!1,o=i+2,s=e[o]===`-`,s&&o++),c=e.indexOf(`}}`,o)),c<0){t.push([0,e.slice(i)]);break}let l=c>o&&e[c-1]===`-`,u=l?c-1:c,d=e.slice(o,u),f=d.trim(),p=o+d.length-d.trimStart().length,m=c+2+a,h=[a?1:2,f,i,m,p],g=t.at(-1);if(s&&g?.[0]===0&&g[1]&&(g[1]=g[1].trimEnd()),t.push(h),n=m,l)for(;/\s/.test(e[n]);)n++}return t},u,d,f,p,m,h,g,_,v,y=()=>Object.freeze(v.slice()),b=(e,t)=>(v.length<256||S(`Template too deeply nested`,`SJABLOON_TOO_DEEP`,t),Object.freeze({type:e,start:t[2],end:t[3]})),x=(e,t)=>(Object.defineProperty(e,"blocks",{value:t,enumerable:!0}),o(e),e),S=(e,t,n,r=n?.[2]??_.length,i=n?.[3]??_.length)=>{let a=SyntaxError(e);throw a.code=t,a.start=r,a.end=i,x(a,y())},C=(e,n,r,i=t)=>{throw i(e)?(e.start+=n,e.end+=n,x(e,r)):e},w=e=>S(`Unexpected {{`+e[1]+`}}`,`SJABLOON_UNEXPECTED_TAG`,e),T=(e,t)=>e.map(e=>e(t)).join(``),E=(e,t)=>(e=>n=>t(e(n)??``))(D(e[1],e[4],y())),D=(t,n,r)=>{let i;try{i=e(t,f)}catch(e){C(e,n,r)}for(let e of i.names)m.includes(e)||h.add(e);for(let e of i.functions)g.add(e);return e=>{try{return i(e)}catch(e){C(e,n,r,i.isDiagnostic)}}},O=e=>{let t=k([`#elif`,`#else`,`/if`]),n=p[1],r=[];return n.startsWith(`#elif `)?r=[O(D(n.slice(6),p[4]+6,y()))]:n===`#else`?(r=k([`/if`]),p[1]===`/if`||w(p)):n!==`/if`&&w(p),n=>T(e(n)?t:r,n)},k=e=>{let t=[];for(let n;n=u[d++];){let a=n[1];if(!n[0])t.push((e=>()=>e)(a));else if(n[0]===1)t.push(E(n,String));else if(e.includes(a.split(` `)[0]))return p=n,t;else if(a[0]!==`!`)if(a.startsWith(`#if `))v.push(b(`if`,n)),t.push(O(D(a.slice(4),n[4]+4,y()))),v.pop();else if(/^#each(?:\s|$)/.test(a)){v.push(b(`each`,n));let e=/^#each ([\s\S]+) as ((\w+)(?:\s*,\s*(\w+))?)$/.exec(a);e||S(`Bad {{`+a+`}}`,`SJABLOON_EACH_SYNTAX`,n);let r=e[3],o=e[4],s=n[4]+a.length-e[2].length;if(i.test(r)&&S(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,n,s,s+r.length),o&&i.test(o)){let e=n[4]+a.length-o.length;S(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,n,e,e+o.length)}let c=D(e[1],n[4]+6,y()),l=m.length;m.push(r),o&&m.push(o),m.push(`loop`);let u=k([`#else`,`/each`]);m.length=l;let d=[];p[1]===`#else`?(d=k([`/each`]),p[1]===`/each`||w(p)):p[1]!==`/each`&&w(p),v.pop(),t.push(e=>{let t=c(e),n=Array.isArray(t),i=n?t.slice():t&&typeof t==`object`?Object.keys(t).map(e=>[t[e],e]):[];return i.length?i.map((t,a)=>{let s=n?t:t[0],c=n?a:t[1],l=Object.create(e);return l[r]=s,o&&(l[o]=c),l[`@`]=s,l.loop={index:a+1,index0:a,first:!a,last:a===i.length-1,length:i.length},T(u,l)}).join(``):T(d,e)})}else/^#(?:if|elif|else)(?:\s|$)/.test(a)||a[0]===`/`?w(n):a[0]===`#`?S(`Unknown {{`+a+`}}`,`SJABLOON_UNKNOWN_BLOCK`,n):t.push(E(n,r))}return e.length&&S(`Missing {{`+e[e.length-1]+`}}`,`SJABLOON_UNCLOSED_BLOCK`),t};function A(e,t){f=t,m=[`$`,`@`],h=new Set,g=new Set,_=String(e),v=[],u=l(_),d=0;let n;try{n=k([])}catch(e){throw e instanceof RangeError&&S(`Template too deeply nested`,`SJABLOON_TOO_DEEP`),e}let r=(e,t)=>{e||={};let r=Object.create(e);return r.$=t?t.root:e,t?`item`in t&&(r[`@`]=t.item):r[`@`]=e,T(n,r)};return r.names=Array.from(h),r.functions=Array.from(g),r}function j(e,t,n){return A(e,n)(t)}export{c as isDiagnostic,j as render,A as template};

package/index.d.ts

@@ -1,40 +1,68 @@
-/**
- * Compile a template once, 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.
- *
- * 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
- * reach the root (`$.company`) or the current item (`@.total`) explicitly,
- * past any shadowing. Neither counts as a `name`.
- *
- * An embedder with its own scope model can override the anchors per render by
- * passing `{ root, item }` as the renderer's second argument: `$` becomes
- * `root` and `@` becomes `item` (two distinct objects). Omit `item` to leave
- * `@` unbound, so reading `@.x` throws through xprsn's guard.
- *
- * @param {string} str The template, e.g. `'Hello {{ user.name }}!'`.
- * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
- * @returns {{(values?: Record<string, any>, scope?: { root?: any, item?: any }): string, names: string[], functions: string[]}} Renderer for the compiled template.
- * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
- */
-export function template(str: string, funcs?: Record<string, Function>): {
-    (values?: Record<string, any>, scope?: {
-        root?: any;
-        item?: any;
-    }): string;
-    names: string[];
-    functions: string[];
-};
-/**
- * Compile and render a template in one go.
- *
- * @param {string} str The template to render.
- * @param {Record<string, any>} [values] Variables available to the template.
- * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
- * @returns {string} The rendered output.
- */
-export function render(str: string, values?: Record<string, any>, funcs?: Record<string, Function>): string;
+import type { XprsnErrorCode } from 'xprsn';
+
+export type SjabloonErrorCode =
+    | XprsnErrorCode
+    | 'SJABLOON_EACH_SYNTAX'
+    | 'SJABLOON_BLOCKED_BINDING'
+    | 'SJABLOON_UNEXPECTED_TAG'
+    | 'SJABLOON_UNKNOWN_BLOCK'
+    | 'SJABLOON_UNCLOSED_BLOCK';
+
+export interface SjabloonBlock {
+    readonly type: 'if' | 'each';
+    readonly start: number;
+    readonly end: number;
+}
+
+export interface SjabloonDiagnostic extends Error {
+    readonly code: SjabloonErrorCode;
+    readonly start: number;
+    readonly end: number;
+    readonly blocks: readonly SjabloonBlock[];
+}
+
+/**
+ * Check whether an error was produced or translated by this sjabloon module instance.
+ */
+export function isDiagnostic(error: unknown): error is SjabloonDiagnostic;
+
+/**
+ * Compile a template once, 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.
+ *
+ * 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
+ * reach the root (`$.company`) or the current item (`@.total`) explicitly,
+ * past any shadowing. Neither counts as a `name`.
+ *
+ * An embedder with its own scope model can override the anchors per render by
+ * passing `{ root, item }` as the renderer's second argument: `$` becomes
+ * `root` and `@` becomes `item` (two distinct objects). Omit `item` to leave
+ * `@` unbound, so reading `@.x` throws through xprsn's guard.
+ *
+ * @param {string} str The template, e.g. `'Hello {{ user.name }}!'`.
+ * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
+ * @returns {{(values?: Record<string, any>, scope?: { root?: any, item?: any }): string, names: string[], functions: string[]}} Renderer for the compiled template.
+ * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
+ */
+export function template(str: string, funcs?: Record<string, Function>): {
+    (values?: Record<string, any>, scope?: {
+        root?: any;
+        item?: any;
+    }): string;
+    names: string[];
+    functions: string[];
+};
+/**
+ * Compile and render a template in one go.
+ *
+ * @param {string} str The template to render.
+ * @param {Record<string, any>} [values] Variables available to the template.
+ * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
+ * @returns {string} The rendered output.
+ */
+export function render(str: string, values?: Record<string, any>, funcs?: Record<string, Function>): string;

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "sjabloon",
-	"version": "0.4.1",
+	"version": "0.5.1",
 	"description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
-	"repository": "robinvdvleuten/sjabloon",
+	"repository": "getquario/sjabloon",
 	"license": "MIT",
 	"author": {
 		"name": "Robin van der Vleuten",
@@ -21,6 +21,9 @@
 			"require": "./dist/index.cjs"
 		}
 	},
+	"engines": {
+		"node": ">=22.0.0"
+	},
 	"files": [
 		"dist",
 		"src",
@@ -29,16 +32,18 @@
 	"size-limit": [
 		{
 			"path": "dist/index.js",
-			"limit": "1.25 kB"
+			"limit": "1.7 kB"
 		},
 		{
 			"path": "dist/index.cjs",
-			"limit": "1.25 kB"
+			"limit": "1.72 kB"
 		}
 	],
 	"scripts": {
-		"bench": "node bench/index.js",
+		"bench": "node --disallow-code-generation-from-strings bench/index.js",
+		"bench:comparison": "npm run build && npm --prefix bench/comparison run bench",
 		"build": "tsdown",
+		"check": "run-s build size test fuzz:regression test:browser",
 		"fuzz": "npm run fuzz:prepare && run-s fuzz:compile fuzz:render fuzz:structured",
 		"fuzz:prepare": "node -e \"for (const x of ['compile','render','structured']) require('fs').mkdirSync('.fuzz-corpus/'+x,{recursive:true})\"",
 		"fuzz:compile": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/compile.fuzz.js -i src/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync .fuzz-corpus/compile fuzz/corpus/compile -- -max_total_time=60 -use_value_profile=1 -dict=fuzz/sjabloon.dict -artifact_prefix=fuzz/",
@@ -50,7 +55,10 @@
 		"fuzz:regression:structured": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/structured.fuzz.js -i src/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/structured -- -artifact_prefix=fuzz/",
 		"prepublishOnly": "npm run build",
 		"size": "size-limit",
-		"test": "node --disallow-code-generation-from-strings node_modules/tape/bin/tape test/*.test.js"
+		"test": "run-s test:unit test:types",
+		"test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+		"test:browser": "npm run build && playwright install chromium && node test/browser/harness.js",
+		"test:types": "tsc"
 	},
 	"keywords": [
 		"template",
@@ -60,15 +68,16 @@
 		"handlebars"
 	],
 	"dependencies": {
-		"xprsn": "^0.4.1"
+		"xprsn": "^0.8.0"
 	},
 	"devDependencies": {
 		"@jazzer.js/bug-detectors": "^4.0.0",
 		"@jazzer.js/core": "^4.0.0",
 		"@size-limit/file": "^12.1.0",
 		"npm-run-all": "^4.1.5",
+		"playwright": "^1.61.1",
 		"size-limit": "^12.1.0",
-		"tape": "^5.9.0",
-		"tsdown": "^0.22.12"
+		"tsdown": "^0.22.12",
+		"typescript": "^7.0.2"
 	}
 }

package/src/index.js

@@ -3,16 +3,22 @@
  * Templates compile to a composition of closures; template text is never
  * turned into JavaScript, so strict CSP is satisfied.
  */
-import { compile } from 'xprsn';
+import { compile, isDiagnostic as isXprsnDiagnostic } from 'xprsn';
 
 const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 const esc = s => String(s).replace(/[&<>"']/g, c => ESC[c]);
 const BLOCKED = /^(?:__proto__|constructor|prototype)$/;
+const DIAGNOSTICS = new WeakSet();
+const mark = DIAGNOSTICS.add.bind(DIAGNOSTICS);
+const owns = DIAGNOSTICS.has.bind(DIAGNOSTICS);
 
-// What `#each` walks: [value, key] pairs — array indexes or own object keys.
-const pairs = lv => Array.isArray(lv) ? lv.map((x, j) => [x, j])
-	: lv && typeof lv === 'object' ? Object.keys(lv).map(k => [lv[k], k])
-	: [];
+/**
+ * Check whether an error was produced or translated by sjabloon.
+ *
+ * @param {unknown} error Any thrown value.
+ * @returns {boolean} Whether `error` is an authentic sjabloon diagnostic.
+ */
+export const isDiagnostic = error => owns(error);
 
 // Linear scan into text/tag/raw tokens. Dashes hug braces (`{{- x -}}` trims;
 // `{{ -x }}` stays unary minus). Prefer {{{ }}} over {{ }}. `triple` latches
@@ -21,98 +27,154 @@ let lex = s => {
 	const out = [];
 	for (let i = 0, triple = 1; i < s.length; ) {
 		const a = s.indexOf('{{', i);
-		if (a < 0) { out.push({ text: s.slice(i) }); break; }
-		if (a > i) out.push({ text: s.slice(i, a) });
-		let raw = s.charCodeAt(a + 2) === 123, p = a + 2 + raw, l = s.charCodeAt(p) === 45, b = -1;
+		if (a < 0) { out.push([0, s.slice(i)]); break; }
+		if (a > i) out.push([0, s.slice(i, a)]);
+		let raw = s[a + 2] === '{', p = a + 2 + raw, l = s[p] === '-', b = -1;
 		if (l) p++;
 		if (raw && triple) { b = s.indexOf('}}}', p); if (b < 0) triple = 0; }
 		if (b < 0) {
-			if (raw) { raw = !1; p = a + 2; l = s.charCodeAt(p) === 45; if (l) p++; }
+			if (raw) { raw = !1; p = a + 2; l = s[p] === '-'; if (l) p++; }
 			b = s.indexOf('}}', p);
 		}
-		if (b < 0) { out.push({ text: s.slice(a) }); break; }
-		const r = b > p && s.charCodeAt(b - 1) === 45;
-		const body = s.slice(p, r ? b - 1 : b).trim(), t = raw ? { raw: body } : { tag: body };
-		t.l = l;
-		t.r = r;
+		if (b < 0) { out.push([0, s.slice(a)]); break; }
+		const r = b > p && s[b - 1] === '-';
+		const q = r ? b - 1 : b, whole = s.slice(p, q), body = whole.trim();
+		const start = p + whole.length - whole.trimStart().length, end = b + 2 + raw;
+		const t = [raw ? 1 : 2, body, a, end, start];
+		const prev = out.at(-1);
+		if (l && prev?.[0] === 0 && prev[1]) prev[1] = prev[1].trimEnd();
 		out.push(t);
-		i = b + 2 + raw;
+		i = end;
+		if (r) while (/\s/.test(s[i])) i++;
 	}
 	return out;
 };
 
 // Shared parser state; parsing is synchronous so this is safe.
 // `nms` collects free variables, `fnms` the registry functions called.
-let toks, i, fns, last, bound, nms, fnms;
+let toks, i, fns, last, bound, nms, fnms, src, blocks;
 
-let err = msg => { throw SyntaxError(msg) };
+let snap = () => Object.freeze(blocks.slice());
+// Block nesting is capped so a pathological template fails as a deterministic
+// SyntaxError at the offending opener, far below the native stack limit.
+const DEPTH = 256;
+let opener = (type, t) => {
+	blocks.length < DEPTH || fault('Template too deeply nested', 'SJABLOON_TOO_DEEP', t);
+	return Object.freeze({ type, start: t[2], end: t[3] });
+};
+let attach = (e, context) => {
+	Object.defineProperty(e, 'blocks', { value: context, enumerable: true });
+	mark(e);
+	return e;
+};
+let fault = (msg, code, t, start = t?.[2] ?? src.length, end = t?.[3] ?? src.length) => {
+	const e = SyntaxError(msg);
+	e.code = code;
+	e.start = start;
+	e.end = end;
+	throw attach(e, snap());
+};
+let translated = (e, start, context, owns = isXprsnDiagnostic) => {
+	if (!owns(e)) throw e;
+	e.start += start;
+	e.end += start;
+	throw attach(e, context);
+};
+let unexpected = t => fault('Unexpected {{' + t[1] + '}}', 'SJABLOON_UNEXPECTED_TAG', t);
 
 // Render a list of nodes against a scope.
 let run = (nodes, v) => nodes.map(n => n(v)).join('');
 
 // A leaf interpolation node: compile `src`, render nullish as '', apply `wrap`
 // (`esc` for `{{ }}`, `String` for the raw `{{{ }}}` form).
-let interp = (src, wrap) => (e => v => wrap(e(v) ?? ''))(cp(src));
-
-// Bind `names` for a block body; returns a restore that unbinds only the names
-// this block introduced, leaving an outer scope's bindings in place.
-let scope = (...names) => {
-	const fresh = names.filter(n => n && !bound.has(n));
-	fresh.forEach(n => bound.add(n));
-	return () => fresh.forEach(n => bound.delete(n));
-};
+let interp = (t, wrap) => (e => v => wrap(e(v) ?? ''))(cp(t[1], t[4], snap()));
 
 // Compile one expression and collect its free variables (minus the loop
 // variables currently in scope, which belong to the template) and the registry
 // functions it calls.
-let cp = s => {
-	const e = compile(s, fns);
-	for (const n of e.names) bound.has(n) || nms.add(n);
+let cp = (s, start, context) => {
+	let e;
+	try {
+		e = compile(s, fns);
+	} catch (x) {
+		translated(x, start, context);
+	}
+	for (const n of e.names) bound.includes(n) || nms.add(n);
 	for (const fn of e.functions) fnms.add(fn);
-	return e;
+	return v => {
+		try {
+			return e(v);
+		} catch (x) {
+			translated(x, start, context, e.isDiagnostic);
+		}
+	};
 };
 
 // One `#if`/`#elif` link: parse its branch, then recurse on the chain tail.
 let branch = cond => {
 	const then = parse(['#elif', '#else', '/if']);
-	const els = last.startsWith('#elif ') ? [branch(cp(last.slice(6)))]
-		: last === '#else' ? parse(['/if'])
-		: [];
+	const tag = last[1];
+	let els = [];
+	if (tag.startsWith('#elif ')) els = [branch(cp(tag.slice(6), last[4] + 6, snap()))];
+	else if (tag === '#else') {
+		els = parse(['/if']);
+		last[1] === '/if' || unexpected(last);
+	} else if (tag !== '/if') unexpected(last);
 	return v => run(cond(v) ? then : els, v);
 };
 
 let parse = stops => {
 	const nodes = [];
 	for (let t; (t = toks[i++]); ) {
-		if (t.text != null) {
-			nodes.push((s => () => s)(t.text));
-		} else if (t.raw != null) {
-			nodes.push(interp(t.raw, String));
-		} else if (stops.includes(t.tag.split(' ')[0])) {
-			last = t.tag;
+		const tag = t[1];
+		if (!t[0]) {
+			nodes.push((s => () => s)(tag));
+		} else if (t[0] === 1) {
+			nodes.push(interp(t, String));
+		} else if (stops.includes(tag.split(' ')[0])) {
+			last = t;
 			return nodes;
-		} else if (t.tag[0] === '!') {
+		} else if (tag[0] === '!') {
 			// comment
-		} else if (t.tag.startsWith('#if ')) {
-			nodes.push(branch(cp(t.tag.slice(4))));
-		} else if (t.tag.startsWith('#each ')) {
-			const m = /^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(t.tag) || err('Bad {{' + t.tag + '}}');
-			const list = cp(m[1]), name = m[2], idx = m[3];
-			if (BLOCKED.test(name) || idx && BLOCKED.test(idx)) err('Bad {{' + t.tag + '}}');
+		} else if (tag.startsWith('#if ')) {
+			blocks.push(opener('if', t));
+			nodes.push(branch(cp(tag.slice(4), t[4] + 4, snap())));
+			blocks.pop();
+		} else if (/^#each(?:\s|$)/.test(tag)) {
+			blocks.push(opener('each', t));
+			const m = /^#each ([\s\S]+) as ((\w+)(?:\s*,\s*(\w+))?)$/.exec(tag);
+			m || fault('Bad {{' + tag + '}}', 'SJABLOON_EACH_SYNTAX', t);
+			const name = m[3], idx = m[4], at = t[4] + tag.length - m[2].length;
+			if (BLOCKED.test(name)) fault('Bad {{' + tag + '}}', 'SJABLOON_BLOCKED_BINDING', t, at, at + name.length);
+			if (idx && BLOCKED.test(idx)) {
+				const p = t[4] + tag.length - idx.length;
+				fault('Bad {{' + tag + '}}', 'SJABLOON_BLOCKED_BINDING', t, p, p + idx.length);
+			}
+			const list = cp(m[1], t[4] + 6, snap());
 			// `name`, `idx`, and `loop` are engine-bound inside the body, so
 			// exclude them from names there and restore outer bindings after.
-			const restore = scope(name, idx, 'loop');
+			const mark = bound.length;
+			bound.push(name);
+			if (idx) bound.push(idx);
+			bound.push('loop');
 			const body = parse(['#else', '/each']);
-			restore();
-			const empty = last === '#else' ? parse(['/each']) : [];
+			bound.length = mark;
+			let empty = [];
+			if (last[1] === '#else') {
+				empty = parse(['/each']);
+				last[1] === '/each' || unexpected(last);
+			} else if (last[1] !== '/each') unexpected(last);
+			blocks.pop();
 			// Child scopes inherit the parent via the prototype chain, so outer
 			// variables stay visible inside the loop body. `@` re-points to the
 			// current item at each level, `$` (root) rides the chain, and `loop`
 			// carries the iteration metadata (index/first/last/length).
 			nodes.push(v => {
-				const ps = pairs(list(v));
+				const lv = list(v), arr = Array.isArray(lv);
+				const ps = arr ? lv.slice() : lv && typeof lv === 'object' ? Object.keys(lv).map(k => [lv[k], k]) : [];
 				if (!ps.length) return run(empty, v);
-				return ps.map(([item, key], j) => {
+				return ps.map((x, j) => {
+					const item = arr ? x : x[0], key = arr ? j : x[1];
 					const s = Object.create(v);
 					s[name] = item;
 					if (idx) s[idx] = key;
@@ -121,13 +183,15 @@ let parse = stops => {
 					return run(body, s);
 				}).join('');
 			});
-		} else if (t.tag[0] === '#' || t.tag[0] === '/') {
-			err('Unexpected {{' + t.tag + '}}');
+		} else if (/^#(?:if|elif|else)(?:\s|$)/.test(tag) || tag[0] === '/') {
+			unexpected(t);
+		} else if (tag[0] === '#') {
+			fault('Unknown {{' + tag + '}}', 'SJABLOON_UNKNOWN_BLOCK', t);
 		} else {
-			nodes.push(interp(t.tag, esc));
+			nodes.push(interp(t, esc));
 		}
 	}
-	stops.length && err('Missing {{' + stops[stops.length - 1] + '}}');
+	stops.length && fault('Missing {{' + stops[stops.length - 1] + '}}', 'SJABLOON_UNCLOSED_BLOCK');
 	return nodes;
 };
 
@@ -158,17 +222,24 @@ export function template(str, funcs) {
 	fns = funcs;
 	// `$` (root) and `@` (current item) are engine-bound anchors, always in
 	// scope, so they never count as caller-supplied `names`.
-	bound = new Set(['$', '@']);
+	bound = ['$', '@'];
 	nms = new Set();
 	fnms = new Set();
-	toks = lex(String(str));
-	// `{{-` / `-}}` eat the whitespace touching that side of the tag.
-	toks.forEach((t, k) => {
-		if (t.l && toks[k - 1]?.text) toks[k - 1].text = toks[k - 1].text.trimEnd();
-		if (t.r && toks[k + 1]?.text) toks[k + 1].text = toks[k + 1].text.trimStart();
-	});
+	src = String(str);
+	blocks = [];
+	toks = lex(src);
 	i = 0;
-	const nodes = parse([]);
+	// Deeply nested blocks overflow the recursive-descent parser; surface that
+	// as a SyntaxError so malformed input keeps its documented compile-time
+	// contract (mirroring xprsn's XPRSN_TOO_DEEP for expressions).
+	let nodes;
+	try {
+		nodes = parse([]);
+	} catch (x) {
+		// An empty span at the end, like an unclosed block.
+		if (x instanceof RangeError) fault('Template too deeply nested', 'SJABLOON_TOO_DEEP');
+		throw x;
+	}
 	// 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: