sjabloon 0.4.1 → 0.5.0

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`, and `SJABLOON_UNCLOSED_BLOCK`. 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 |

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,o,u,p,p+f.length,s,l],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)=>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[6],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[6]+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[6]+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[6]+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[6]+a.length-o.length;x(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,i,e,e+o.length)}let c=E(e[1],i[6]+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=O([]),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,o,u,p,p+f.length,s,l],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)=>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[6],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[6]+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[6]+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[6]+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[6]+a.length-o.length;S(`Bad {{`+a+`}}`,`SJABLOON_BLOCKED_BINDING`,n,e,e+o.length)}let c=D(e[1],n[6]+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=k([]),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,6 +1,6 @@
 {
 	"name": "sjabloon",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
 	"repository": "robinvdvleuten/sjabloon",
 	"license": "MIT",
@@ -29,15 +29,15 @@
 	"size-limit": [
 		{
 			"path": "dist/index.js",
-			"limit": "1.25 kB"
+			"limit": "1.7 kB"
 		},
 		{
 			"path": "dist/index.cjs",
-			"limit": "1.25 kB"
+			"limit": "1.7 kB"
 		}
 	],
 	"scripts": {
-		"bench": "node bench/index.js",
+		"bench": "node --disallow-code-generation-from-strings bench/index.js",
 		"build": "tsdown",
 		"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})\"",
@@ -50,7 +50,8 @@
 		"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": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js && npm run typecheck",
+		"typecheck": "tsc --noEmit --strict test/types.check.ts"
 	},
 	"keywords": [
 		"template",
@@ -60,7 +61,7 @@
 		"handlebars"
 	],
 	"dependencies": {
-		"xprsn": "^0.4.1"
+		"xprsn": "^0.8.0"
 	},
 	"devDependencies": {
 		"@jazzer.js/bug-detectors": "^4.0.0",
@@ -68,7 +69,7 @@
 		"@size-limit/file": "^12.1.0",
 		"npm-run-all": "^4.1.5",
 		"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,148 @@ 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, p, q, start, start + body.length, l, r];
+		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());
+let opener = (type, t) => 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[6], 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[6] + 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[6] + 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[6] + 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[6] + tag.length - idx.length;
+				fault('Bad {{' + tag + '}}', 'SJABLOON_BLOCKED_BINDING', t, p, p + idx.length);
+			}
+			const list = cp(m[1], t[6] + 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 +177,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,15 +216,12 @@ 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([]);
 	// Wrap the values in a root scope carrying the anchors, without mutating