sjabloon 0.1.0 → 0.3.0

package/README.md

@@ -2,6 +2,17 @@
 
 A tiny, CSP-safe template engine for JavaScript. **~0.8KB min+gzip (~2KB 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)
+[![NPM downloads](https://img.shields.io/npm/dm/sjabloon.svg)](https://www.npmjs.com/package/sjabloon)
+[![MIT license](https://img.shields.io/github/license/robinvdvleuten/sjabloon.svg)](https://github.com/robinvdvleuten/sjabloon/blob/main/LICENSE)
+
+<a href="https://webstronauts.com?utm_source=github&utm_medium=readme&utm_campaign=sjabloon">
+	<picture>
+		<img src="https://webstronauts.com/images/sponsored-by.svg" alt="Sponsored by The Webstronauts" width="200" height="65">
+	</picture>
+</a>
+
 *Sjabloon* is Dutch for "template". It renders text templates with full [xprsn](https://github.com/robinvdvleuten/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.
 
 ```js
@@ -28,6 +39,14 @@ render(
 
 Compiles the template and returns a renderer `(values?) => string`. Malformed tags, unclosed blocks, and invalid expressions throw a `SyntaxError` at compile time.
 
+The renderer also 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']
+tpl.functions; // => ['fmt']
+```
+
 ### `render(str, values?, functions?)`
 
 Shorthand for `template(str, functions)(values)`.
@@ -38,14 +57,36 @@ Shorthand for `template(str, functions)(values)`.
 | --- | --- |
 | `{{ expr }}` | Interpolate an expression, HTML-escaped |
 | `{{{ expr }}}` | Interpolate without escaping |
-| `{{#if expr}} … {{#else}} … {{/if}}` | Conditional block |
-| `{{#each expr as item}} … {{/each}}` | Loop block |
-| `{{#each expr as item, i}} … {{/each}}` | Loop block with index |
+| `{{#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/robinvdvleuten/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.
+
+A loop body sees its loop variable plus the outer scope; reusing an outer name shadows it only inside that body. The engine keeps loop variables on a child scope, so the values you pass are never mutated.
+
+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.
 
-Every `expr` is an [xprsn expression](https://github.com/robinvdvleuten/xprsn#syntax): literals, arithmetic, 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.
+```js
+render('{{#each xs as x}}{{ x }}{{#if not loop.last}}, {{/if}}{{/each}}', { xs: ['a', 'b', 'c'] });
+// => 'a, b, c'
+```
+
+Two anchors are always in scope: `$` is the root values and `@` is the current `{{#each}}` item (the root outside a loop). They let a nested body name the level it means instead of leaning on shadowing: `$.company` reaches the top, and `@.total` is whatever the innermost loop sits on.
+
+```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 }] }
+);
+// => 'North of ACME: 1 2 South of ACME: 1 2 '
+```
 
-Loop bodies see the loop variable plus everything from the outer scope. A nested loop can reuse an outer name and shadow it for its own body. The engine sets loop variables on a child scope, so your values object comes back exactly as you passed it in.
+Here the loop variable `company` shadows the root's for a bare name, but `$.company` still returns `'ACME'`. Anchors never count as `names`, and a blocked key through one (`$.constructor`) throws like anywhere else.
 
 ## Content Security Policy
 

package/dist/index.cjs

@@ -1 +1 @@
-var t,n,r,e,u=require("xprsn"),i={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},a=/\{\{\{\s*([\s\S]*?)\s*\}\}\}|\{\{\s*([\s\S]*?)\s*\}\}/,s=function(t){throw SyntaxError(t)},o=function(a){for(var c,l,f=[],p=function(){if(null!=l.text)f.push((S=l.text,function(){return S}));else if(null!=l.raw)f.push((x=u.compile(l.raw,r),function(t){var n;return String(null!=(n=x(t))?n:"")}));else{if(a.includes(l.tag.split(" ")[0]))return e=l.tag,{v:f};if("!"===l.tag[0]);else if(l.tag.startsWith("#if ")){var t=u.compile(l.tag.slice(4),r),n=o(["#else","/if"]),c="#else"===e?o(["/if"]):[];f.push(function(r){return(t(r)?n:c).map(function(t){return t(r)}).join("")})}else if(l.tag.startsWith("#each ")){var p=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(l.tag)||s("Bad {{"+l.tag+"}}"),g=u.compile(p[1],r),h=p[2],v=p[3],m=o(["/each"]);f.push(function(t){return g(t).map(function(n,r){var e=Object.create(t);return e[h]=n,v&&(e[v]=r),m.map(function(t){return t(e)}).join("")}).join("")})}else"#"===l.tag[0]||"/"===l.tag[0]?s("Unexpected {{"+l.tag+"}}"):f.push(function(t){return function(n){var r;return function(t){return String(t).replace(/[&<>"']/g,function(t){return i[t]})}(null!=(r=t(n))?r:"")}}(u.compile(l.tag,r)))}var x,S};l=t[n++];)if(c=p())return c.v;return a.length&&s("Missing {{"+a[a.length-1]+"}}"),f};function c(e,u){r=u,t=[];for(var i=String(e).split(a),s=0;s<i.length;s++){var c=i[s];null!=c&&(s%3==0?c&&t.push({text:c}):t.push(s%3==1?{raw:c}:{tag:c}))}n=0;var l=o([]);return function(t){return l.map(function(n){return n(t||{})}).join("")}}exports.render=function(t,n,r){return c(t,r)(n)},exports.template=c;
+var t=require("xprsn");function r(t,r){(null==r||r>t.length)&&(r=t.length);for(var e=0,n=Array(r);e<r;e++)n[e]=t[e];return n}function e(t,e){var n="undefined"!=typeof Symbol&&t[Symbol.iterator]||t["@@iterator"];if(n)return(n=n.call(t)).next.bind(n);if(Array.isArray(t)||(n=function(t,e){if(t){if("string"==typeof t)return r(t,e);var n={}.toString.call(t).slice(8,-1);return"Object"===n&&t.constructor&&(n=t.constructor.name),"Map"===n||"Set"===n?Array.from(t):"Arguments"===n||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)?r(t,e):void 0}}(t))||e&&t&&"number"==typeof t.length){n&&(t=n);var a=0;return function(){return a>=t.length?{done:!0}:{done:!1,value:t[a++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var n,a,u,i,o,l,c,f={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},s=function(t){return String(t).replace(/[&<>"']/g,function(t){return f[t]})},h=/\{\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}\}|\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}/,g=function(t){throw SyntaxError(t)},p=function(t,r){return t.map(function(t){return t(r)}).join("")},v=function(t,r){return e=d(t),function(t){var n;return r(null!=(n=e(t))?n:"")};var e},d=function(r){for(var n,a=t.compile(r,u),i=e(a.names);!(n=i()).done;){var f=n.value;o.has(f)||l.add(f)}for(var s,h=e(a.functions);!(s=h()).done;)c.add(s.value);return a},m=function(t){var r=y(["#elif","#else","/if"]),e=i.startsWith("#elif ")?[m(d(i.slice(6)))]:"#else"===i?y(["/if"]):[];return function(n){return p(t(n)?r:e,n)}},y=function(t){for(var r,e,u=[],l=function(){if(null!=e.text)u.push((x=e.text,function(){return x}));else if(null!=e.raw)u.push(v(e.raw,String));else{if(t.includes(e.tag.split(" ")[0]))return i=e.tag,{v:u};if("!"===e.tag[0]);else if(e.tag.startsWith("#if "))u.push(m(d(e.tag.slice(4))));else if(e.tag.startsWith("#each ")){var r=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(e.tag)||g("Bad {{"+e.tag+"}}"),n=d(r[1]),a=r[2],l=r[3],c=function(){var t=[].slice.call(arguments).filter(function(t){return t&&!o.has(t)});return t.forEach(function(t){return o.add(t)}),function(){return t.forEach(function(t){return o.delete(t)})}}(a,l,"loop"),f=y(["#else","/each"]);c();var h="#else"===i?y(["/each"]):[];u.push(function(t){var r,e=(r=n(t),Array.isArray(r)?r.map(function(t,r){return[t,r]}):r&&"object"==typeof r?Object.keys(r).map(function(t){return[r[t],t]}):[]);return e.length?e.map(function(r,n){var u=r[0],i=r[1],o=Object.create(t);return o[a]=u,l&&(o[l]=i),o["@"]=u,o.loop={index:n+1,index0:n,first:!n,last:n===e.length-1,length:e.length},p(f,o)}).join(""):p(h,t)})}else"#"===e.tag[0]||"/"===e.tag[0]?g("Unexpected {{"+e.tag+"}}"):u.push(v(e.tag,s))}var x};e=n[a++];)if(r=l())return r.v;return t.length&&g("Missing {{"+t[t.length-1]+"}}"),u};function x(t,r){u=r,o=new Set(["$","@"]),l=new Set,c=new Set,n=[];for(var e=String(t).split(h),i=0;i<e.length&&(e[i]&&n.push({text:e[i]}),!(i+1>=e.length));i+=7){var f=null!=e[i+2],s=f?{raw:e[i+2]}:{tag:e[i+5]};s.l="-"===e[i+(f?1:4)],s.r="-"===e[i+(f?3:6)],n.push(s)}n.forEach(function(t,r){var e,a;t.l&&null!=(e=n[r-1])&&e.text&&(n[r-1].text=n[r-1].text.replace(/\s+$/,"")),t.r&&null!=(a=n[r+1])&&a.text&&(n[r+1].text=n[r+1].text.replace(/^\s+/,""))}),a=0;var g=y([]),v=function(t){t=t||{};var r=Object.create(t);return r.$=r["@"]=t,p(g,r)};return v.names=Array.from(l),v.functions=Array.from(c),v}exports.render=function(t,r,e){return x(t,e)(r)},exports.template=x;

package/dist/index.module.js

@@ -1 +1 @@
-import{compile as t}from"xprsn";var n,r,e,u,i={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},a=/\{\{\{\s*([\s\S]*?)\s*\}\}\}|\{\{\s*([\s\S]*?)\s*\}\}/,s=function(t){throw SyntaxError(t)},f=function(a){for(var o,c,l=[],g=function(){if(null!=c.text)l.push((S=c.text,function(){return S}));else if(null!=c.raw)l.push((m=t(c.raw,e),function(t){var n;return String(null!=(n=m(t))?n:"")}));else{if(a.includes(c.tag.split(" ")[0]))return u=c.tag,{v:l};if("!"===c.tag[0]);else if(c.tag.startsWith("#if ")){var n=t(c.tag.slice(4),e),r=f(["#else","/if"]),o="#else"===u?f(["/if"]):[];l.push(function(t){return(n(t)?r:o).map(function(n){return n(t)}).join("")})}else if(c.tag.startsWith("#each ")){var g=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(c.tag)||s("Bad {{"+c.tag+"}}"),p=t(g[1],e),h=g[2],v=g[3],x=f(["/each"]);l.push(function(t){return p(t).map(function(n,r){var e=Object.create(t);return e[h]=n,v&&(e[v]=r),x.map(function(t){return t(e)}).join("")}).join("")})}else"#"===c.tag[0]||"/"===c.tag[0]?s("Unexpected {{"+c.tag+"}}"):l.push(function(t){return function(n){var r;return function(t){return String(t).replace(/[&<>"']/g,function(t){return i[t]})}(null!=(r=t(n))?r:"")}}(t(c.tag,e)))}var m,S};c=n[r++];)if(o=g())return o.v;return a.length&&s("Missing {{"+a[a.length-1]+"}}"),l};function o(t,u){e=u,n=[];for(var i=String(t).split(a),s=0;s<i.length;s++){var o=i[s];null!=o&&(s%3==0?o&&n.push({text:o}):n.push(s%3==1?{raw:o}:{tag:o}))}r=0;var c=f([]);return function(t){return c.map(function(n){return n(t||{})}).join("")}}function c(t,n,r){return o(t,r)(n)}export{c as render,o as template};
+import{compile as t}from"xprsn";function r(t,r){(null==r||r>t.length)&&(r=t.length);for(var n=0,e=Array(r);n<r;n++)e[n]=t[n];return e}function n(t,n){var e="undefined"!=typeof Symbol&&t[Symbol.iterator]||t["@@iterator"];if(e)return(e=e.call(t)).next.bind(e);if(Array.isArray(t)||(e=function(t,n){if(t){if("string"==typeof t)return r(t,n);var e={}.toString.call(t).slice(8,-1);return"Object"===e&&t.constructor&&(e=t.constructor.name),"Map"===e||"Set"===e?Array.from(t):"Arguments"===e||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(e)?r(t,n):void 0}}(t))||n&&t&&"number"==typeof t.length){e&&(t=e);var a=0;return function(){return a>=t.length?{done:!0}:{done:!1,value:t[a++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var e,a,u,i,o,l,f,c={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},s=function(t){return String(t).replace(/[&<>"']/g,function(t){return c[t]})},h=/\{\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}\}|\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}/,g=function(t){throw SyntaxError(t)},p=function(t,r){return t.map(function(t){return t(r)}).join("")},v=function(t,r){return n=d(t),function(t){var e;return r(null!=(e=n(t))?e:"")};var n},d=function(r){for(var e,a=t(r,u),i=n(a.names);!(e=i()).done;){var c=e.value;o.has(c)||l.add(c)}for(var s,h=n(a.functions);!(s=h()).done;)f.add(s.value);return a},m=function(t){var r=y(["#elif","#else","/if"]),n=i.startsWith("#elif ")?[m(d(i.slice(6)))]:"#else"===i?y(["/if"]):[];return function(e){return p(t(e)?r:n,e)}},y=function(t){for(var r,n,u=[],l=function(){if(null!=n.text)u.push((x=n.text,function(){return x}));else if(null!=n.raw)u.push(v(n.raw,String));else{if(t.includes(n.tag.split(" ")[0]))return i=n.tag,{v:u};if("!"===n.tag[0]);else if(n.tag.startsWith("#if "))u.push(m(d(n.tag.slice(4))));else if(n.tag.startsWith("#each ")){var r=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(n.tag)||g("Bad {{"+n.tag+"}}"),e=d(r[1]),a=r[2],l=r[3],f=function(){var t=[].slice.call(arguments).filter(function(t){return t&&!o.has(t)});return t.forEach(function(t){return o.add(t)}),function(){return t.forEach(function(t){return o.delete(t)})}}(a,l,"loop"),c=y(["#else","/each"]);f();var h="#else"===i?y(["/each"]):[];u.push(function(t){var r,n=(r=e(t),Array.isArray(r)?r.map(function(t,r){return[t,r]}):r&&"object"==typeof r?Object.keys(r).map(function(t){return[r[t],t]}):[]);return n.length?n.map(function(r,e){var u=r[0],i=r[1],o=Object.create(t);return o[a]=u,l&&(o[l]=i),o["@"]=u,o.loop={index:e+1,index0:e,first:!e,last:e===n.length-1,length:n.length},p(c,o)}).join(""):p(h,t)})}else"#"===n.tag[0]||"/"===n.tag[0]?g("Unexpected {{"+n.tag+"}}"):u.push(v(n.tag,s))}var x};n=e[a++];)if(r=l())return r.v;return t.length&&g("Missing {{"+t[t.length-1]+"}}"),u};function x(t,r){u=r,o=new Set(["$","@"]),l=new Set,f=new Set,e=[];for(var n=String(t).split(h),i=0;i<n.length&&(n[i]&&e.push({text:n[i]}),!(i+1>=n.length));i+=7){var c=null!=n[i+2],s=c?{raw:n[i+2]}:{tag:n[i+5]};s.l="-"===n[i+(c?1:4)],s.r="-"===n[i+(c?3:6)],e.push(s)}e.forEach(function(t,r){var n,a;t.l&&null!=(n=e[r-1])&&n.text&&(e[r-1].text=e[r-1].text.replace(/\s+$/,"")),t.r&&null!=(a=e[r+1])&&a.text&&(e[r+1].text=e[r+1].text.replace(/^\s+/,""))}),a=0;var g=y([]),v=function(t){t=t||{};var r=Object.create(t);return r.$=r["@"]=t,p(g,r)};return v.names=Array.from(l),v.functions=Array.from(f),v}function S(t,r,n){return x(t,n)(r)}export{S as render,x as template};

package/dist/index.umd.js

@@ -1 +1 @@
-!function(n,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("xprsn")):"function"==typeof define&&define.amd?define(["exports","xprsn"],t):t((n||self).sjabloon={},n.xprsn)}(this,function(n,t){var e,r,i,u,a={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},o=/\{\{\{\s*([\s\S]*?)\s*\}\}\}|\{\{\s*([\s\S]*?)\s*\}\}/,s=function(n){throw SyntaxError(n)},f=function(n){for(var o,l,c=[],p=function(){if(null!=l.text)c.push((x=l.text,function(){return x}));else if(null!=l.raw)c.push((m=t.compile(l.raw,i),function(n){var t;return String(null!=(t=m(n))?t:"")}));else{if(n.includes(l.tag.split(" ")[0]))return u=l.tag,{v:c};if("!"===l.tag[0]);else if(l.tag.startsWith("#if ")){var e=t.compile(l.tag.slice(4),i),r=f(["#else","/if"]),o="#else"===u?f(["/if"]):[];c.push(function(n){return(e(n)?r:o).map(function(t){return t(n)}).join("")})}else if(l.tag.startsWith("#each ")){var p=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(l.tag)||s("Bad {{"+l.tag+"}}"),g=t.compile(p[1],i),h=p[2],d=p[3],v=f(["/each"]);c.push(function(n){return g(n).map(function(t,e){var r=Object.create(n);return r[h]=t,d&&(r[d]=e),v.map(function(n){return n(r)}).join("")}).join("")})}else"#"===l.tag[0]||"/"===l.tag[0]?s("Unexpected {{"+l.tag+"}}"):c.push(function(n){return function(t){var e;return function(n){return String(n).replace(/[&<>"']/g,function(n){return a[n]})}(null!=(e=n(t))?e:"")}}(t.compile(l.tag,i)))}var m,x};l=e[r++];)if(o=p())return o.v;return n.length&&s("Missing {{"+n[n.length-1]+"}}"),c};function l(n,t){i=t,e=[];for(var u=String(n).split(o),a=0;a<u.length;a++){var s=u[a];null!=s&&(a%3==0?s&&e.push({text:s}):e.push(a%3==1?{raw:s}:{tag:s}))}r=0;var l=f([]);return function(n){return l.map(function(t){return t(n||{})}).join("")}}n.render=function(n,t,e){return l(n,e)(t)},n.template=l});
+!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports,require("xprsn")):"function"==typeof define&&define.amd?define(["exports","xprsn"],e):e((t||self).sjabloon={},t.xprsn)}(this,function(t,e){function n(t,e){(null==e||e>t.length)&&(e=t.length);for(var n=0,r=Array(e);n<e;n++)r[n]=t[n];return r}function r(t,e){var r="undefined"!=typeof Symbol&&t[Symbol.iterator]||t["@@iterator"];if(r)return(r=r.call(t)).next.bind(r);if(Array.isArray(t)||(r=function(t,e){if(t){if("string"==typeof t)return n(t,e);var r={}.toString.call(t).slice(8,-1);return"Object"===r&&t.constructor&&(r=t.constructor.name),"Map"===r||"Set"===r?Array.from(t):"Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?n(t,e):void 0}}(t))||e&&t&&"number"==typeof t.length){r&&(t=r);var a=0;return function(){return a>=t.length?{done:!0}:{done:!1,value:t[a++]}}}throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}var a,o,i,u,l,f,s,c={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},p=function(t){return String(t).replace(/[&<>"']/g,function(t){return c[t]})},h=/\{\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}\}|\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}/,g=function(t){throw SyntaxError(t)},d=function(t,e){return t.map(function(t){return t(e)}).join("")},v=function(t,e){return n=m(t),function(t){var r;return e(null!=(r=n(t))?r:"")};var n},m=function(t){for(var n,a=e.compile(t,i),o=r(a.names);!(n=o()).done;){var u=n.value;l.has(u)||f.add(u)}for(var c,p=r(a.functions);!(c=p()).done;)s.add(c.value);return a},y=function(t){var e=x(["#elif","#else","/if"]),n=u.startsWith("#elif ")?[y(m(u.slice(6)))]:"#else"===u?x(["/if"]):[];return function(r){return d(t(r)?e:n,r)}},x=function(t){for(var e,n,r=[],i=function(){if(null!=n.text)r.push((h=n.text,function(){return h}));else if(null!=n.raw)r.push(v(n.raw,String));else{if(t.includes(n.tag.split(" ")[0]))return u=n.tag,{v:r};if("!"===n.tag[0]);else if(n.tag.startsWith("#if "))r.push(y(m(n.tag.slice(4))));else if(n.tag.startsWith("#each ")){var e=/^#each ([\s\S]+) as (\w+)(?:\s*,\s*(\w+))?$/.exec(n.tag)||g("Bad {{"+n.tag+"}}"),a=m(e[1]),o=e[2],i=e[3],f=function(){var t=[].slice.call(arguments).filter(function(t){return t&&!l.has(t)});return t.forEach(function(t){return l.add(t)}),function(){return t.forEach(function(t){return l.delete(t)})}}(o,i,"loop"),s=x(["#else","/each"]);f();var c="#else"===u?x(["/each"]):[];r.push(function(t){var e,n=(e=a(t),Array.isArray(e)?e.map(function(t,e){return[t,e]}):e&&"object"==typeof e?Object.keys(e).map(function(t){return[e[t],t]}):[]);return n.length?n.map(function(e,r){var a=e[0],u=e[1],l=Object.create(t);return l[o]=a,i&&(l[i]=u),l["@"]=a,l.loop={index:r+1,index0:r,first:!r,last:r===n.length-1,length:n.length},d(s,l)}).join(""):d(c,t)})}else"#"===n.tag[0]||"/"===n.tag[0]?g("Unexpected {{"+n.tag+"}}"):r.push(v(n.tag,p))}var h};n=a[o++];)if(e=i())return e.v;return t.length&&g("Missing {{"+t[t.length-1]+"}}"),r};function b(t,e){i=e,l=new Set(["$","@"]),f=new Set,s=new Set,a=[];for(var n=String(t).split(h),r=0;r<n.length&&(n[r]&&a.push({text:n[r]}),!(r+1>=n.length));r+=7){var u=null!=n[r+2],c=u?{raw:n[r+2]}:{tag:n[r+5]};c.l="-"===n[r+(u?1:4)],c.r="-"===n[r+(u?3:6)],a.push(c)}a.forEach(function(t,e){var n,r;t.l&&null!=(n=a[e-1])&&n.text&&(a[e-1].text=a[e-1].text.replace(/\s+$/,"")),t.r&&null!=(r=a[e+1])&&r.text&&(a[e+1].text=a[e+1].text.replace(/^\s+/,""))}),o=0;var p=x([]),g=function(t){t=t||{};var e=Object.create(t);return e.$=e["@"]=t,d(p,e)};return g.names=Array.from(f),g.functions=Array.from(s),g}t.render=function(t,e,n){return b(t,n)(e)},t.template=b});

package/index.d.ts

@@ -1,12 +1,26 @@
 /**
  * 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`.
+ *
  * @param {string} str The template, e.g. `'Hello {{ user.name }}!'`.
  * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
- * @returns {(values?: Record<string, any>) => string} Renderer for the compiled template.
+ * @returns {{(values?: Record<string, 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>) => string;
+export function template(str: string, funcs?: Record<string, Function>): {
+    (values?: Record<string, any>): string;
+    names: string[];
+    functions: string[];
+};
 /**
  * Compile and render a template in one go.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sjabloon",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
 	"repository": "robinvdvleuten/sjabloon",
 	"license": "MIT",
@@ -31,7 +31,8 @@
 	"scripts": {
 		"build": "microbundle --no-sourcemap",
 		"prepublishOnly": "npm run build",
-		"test": "node --disallow-code-generation-from-strings node_modules/tape/bin/tape test/*.test.js"
+		"test": "node --disallow-code-generation-from-strings node_modules/tape/bin/tape test/*.test.js",
+		"bench": "node bench/index.js"
 	},
 	"keywords": [
 		"template",
@@ -41,7 +42,7 @@
 		"handlebars"
 	],
 	"dependencies": {
-		"xprsn": "^0.1.0"
+		"xprsn": "^0.3.0"
 	},
 	"devDependencies": {
 		"microbundle": "^0.15.1",

package/src/index.js

@@ -8,47 +8,99 @@ import { compile } from 'xprsn';
 const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 const esc = s => String(s).replace(/[&<>"']/g, c => ESC[c]);
 
-// Split into [text, raw-tag, tag, text, raw-tag, tag, ...] triplets.
-const TAGS = /\{\{\{\s*([\s\S]*?)\s*\}\}\}|\{\{\s*([\s\S]*?)\s*\}\}/;
+// 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])
+	: [];
+
+// Split into [text, rawL, raw, rawR, tagL, tag, tagR, ...] strides of 7.
+// The dash captures hug the braces, so `{{ -price }}` stays a unary minus
+// while `{{- price -}}` trims the whitespace touching the tag.
+const TAGS = /\{\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}\}|\{\{(-)?\s*([\s\S]*?)\s*(-)?\}\}/;
 
 // Shared parser state; parsing is synchronous so this is safe.
-let toks, i, fns, last;
+// `nms` collects free variables, `fnms` the registry functions called.
+let toks, i, fns, last, bound, nms, fnms;
 
 let err = msg => { throw SyntaxError(msg) };
 
+// 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));
+};
+
+// 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);
+	for (const fn of e.functions) fnms.add(fn);
+	return e;
+};
+
+// 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'])
+		: [];
+	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((e => v => String(e(v) ?? ''))(compile(t.raw, fns)));
+			nodes.push(interp(t.raw, String));
 		} else if (stops.includes(t.tag.split(' ')[0])) {
 			last = t.tag;
 			return nodes;
 		} else if (t.tag[0] === '!') {
 			// comment
 		} else if (t.tag.startsWith('#if ')) {
-			const cond = compile(t.tag.slice(4), fns);
-			const then = parse(['#else', '/if']);
-			const els = last === '#else' ? parse(['/if']) : [];
-			nodes.push(v => (cond(v) ? then : els).map(n => n(v)).join(''));
+			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 = compile(m[1], fns), name = m[2], idx = m[3];
-			const body = parse(['/each']);
-			// Child scopes inherit the parent via the prototype chain, so
-			// outer variables stay visible inside the loop body.
-			nodes.push(v => list(v).map((item, j) => {
-				const s = Object.create(v);
-				s[name] = item;
-				if (idx) s[idx] = j;
-				return body.map(n => n(s)).join('');
-			}).join(''));
+			const list = cp(m[1]), name = m[2], idx = m[3];
+			// `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 body = parse(['#else', '/each']);
+			restore();
+			const empty = last === '#else' ? parse(['/each']) : [];
+			// 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));
+				if (!ps.length) return run(empty, v);
+				return ps.map(([item, key], j) => {
+					const s = Object.create(v);
+					s[name] = item;
+					if (idx) s[idx] = key;
+					s['@'] = item;
+					s.loop = { index: j + 1, index0: j, first: !j, last: j === ps.length - 1, length: ps.length };
+					return run(body, s);
+				}).join('');
+			});
 		} else if (t.tag[0] === '#' || t.tag[0] === '/') {
 			err('Unexpected {{' + t.tag + '}}');
 		} else {
-			nodes.push((e => v => esc(e(v) ?? ''))(compile(t.tag, fns)));
+			nodes.push(interp(t.tag, esc));
 		}
 	}
 	stops.length && err('Missing {{' + stops[stops.length - 1] + '}}');
@@ -58,25 +110,59 @@ let parse = stops => {
 /**
  * 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`.
+ *
  * @param {string} str The template, e.g. `'Hello {{ user.name }}!'`.
  * @param {Record<string, Function>} [funcs] Functions callable inside expressions.
- * @returns {(values?: Record<string, any>) => string} Renderer for the compiled template.
+ * @returns {{(values?: Record<string, 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, 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(['$', '@']);
+	nms = new Set();
+	fnms = new Set();
 	toks = [];
 	const parts = String(str).split(TAGS);
-	for (let j = 0; j < parts.length; j++) {
-		const s = parts[j];
-		if (s == null) continue;
-		if (j % 3 === 0) s && toks.push({ text: s });
-		else if (j % 3 === 1) toks.push({ raw: s });
-		else toks.push({ tag: s });
+	for (let j = 0; j < parts.length; j += 7) {
+		if (parts[j]) toks.push({ text: parts[j] });
+		if (j + 1 >= parts.length) break;
+		const raw = parts[j + 2] != null;
+		const t = raw ? { raw: parts[j + 2] } : { tag: parts[j + 5] };
+		t.l = parts[j + (raw ? 1 : 4)] === '-';
+		t.r = parts[j + (raw ? 3 : 6)] === '-';
+		toks.push(t);
 	}
+	// `{{-` / `-}}` 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.replace(/\s+$/, '');
+		if (t.r && toks[k + 1]?.text) toks[k + 1].text = toks[k + 1].text.replace(/^\s+/, '');
+	});
 	i = 0;
 	const nodes = parse([]);
-	return v => nodes.map(n => n(v || {})).join('');
+	// Wrap the values in a root scope carrying the anchors, without mutating
+	// what the caller passed: `$` and `@` both point at the root here.
+	const f = v => {
+		v = v || {};
+		const r = Object.create(v);
+		r['$'] = r['@'] = v;
+		return run(nodes, r);
+	};
+	// Array.from, not a spread: the bundler's transpile turns `[...set]` into
+	// `[].concat(set)`, which wraps the Set instead of unpacking it.
+	f.names = Array.from(nms);
+	f.functions = Array.from(fnms);
+	return f;
 }
 
 /**