sjabloon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Robin van der Vleuten <robin@webstronauts.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# sjabloon
+
+A tiny, CSP-safe template engine for JavaScript. **~0.8KB min+gzip (~2KB with [xprsn](https://www.npmjs.com/package/xprsn)), one dependency.**
+
+*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
+import { template, render } from 'sjabloon';
+
+// Compile once, render many times:
+const greet = template('Hello {{ user.name.toUpperCase() }}!');
+greet({ user: { name: 'Robin' } }); // => 'Hello ROBIN!'
+
+// Blocks, expressions, and custom functions:
+render(
+  `<ul>{{#each items as it, i}}
+    <li>{{ i + 1 }}. {{ it.name }}: {{ fmt(it.price * it.qty) }}</li>
+  {{/each}}</ul>
+  {{#if total >= 100 and "vip" in user.roles}}Free shipping!{{#else}}Shipping: {{ fmt(5) }}{{/if}}`,
+  { items: [{ name: 'Koffie', price: 8, qty: 2 }], total: 120, user: { roles: ['vip'] } },
+  { fmt: n => '€' + n.toFixed(2) }
+);
+```
+
+## API
+
+### `template(str, functions?)`
+
+Compiles the template and returns a renderer `(values?) => string`. Malformed tags, unclosed blocks, and invalid expressions throw a `SyntaxError` at compile time.
+
+### `render(str, values?, functions?)`
+
+Shorthand for `template(str, functions)(values)`.
+
+## Syntax
+
+| Tag | Meaning |
+| --- | --- |
+| `{{ 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 |
+| `{{! anything }}` | Comment, removed from output |
+
+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.
+
+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.
+
+## Content Security Policy
+
+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.
+
+## 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.
+
+## License
+
+MIT © [Robin van der Vleuten](https://robinvdvleuten.nl)

package/dist/index.cjs

@@ -0,0 +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;

package/dist/index.module.js

@@ -0,0 +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};

package/dist/index.umd.js

@@ -0,0 +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});

package/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compile a template once, render it many times.
+ *
+ * @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.
+ * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
+ */
+export function template(str: string, funcs?: Record<string, Function>): (values?: Record<string, any>) => 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

@@ -0,0 +1,50 @@
+{
+	"name": "sjabloon",
+	"version": "0.1.0",
+	"description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
+	"repository": "robinvdvleuten/sjabloon",
+	"license": "MIT",
+	"author": {
+		"name": "Robin van der Vleuten",
+		"email": "robin@webstronauts.com",
+		"url": "https://robinvdvleuten.nl"
+	},
+	"type": "module",
+	"source": "src/index.js",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.module.js",
+	"unpkg": "./dist/index.umd.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./dist/index.module.js",
+			"require": "./dist/index.cjs",
+			"default": "./dist/index.module.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src",
+		"index.d.ts"
+	],
+	"scripts": {
+		"build": "microbundle --no-sourcemap",
+		"prepublishOnly": "npm run build",
+		"test": "node --disallow-code-generation-from-strings node_modules/tape/bin/tape test/*.test.js"
+	},
+	"keywords": [
+		"template",
+		"template-engine",
+		"csp",
+		"render",
+		"handlebars"
+	],
+	"dependencies": {
+		"xprsn": "^0.1.0"
+	},
+	"devDependencies": {
+		"microbundle": "^0.15.1",
+		"tape": "^5.9.0"
+	}
+}

package/src/index.js

@@ -0,0 +1,92 @@
+/**
+ * Tiny, CSP-safe template engine powered by xprsn expressions.
+ * Templates compile to a composition of closures; template text is never
+ * turned into JavaScript, so strict CSP is satisfied.
+ */
+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*\}\}/;
+
+// Shared parser state; parsing is synchronous so this is safe.
+let toks, i, fns, last;
+
+let err = msg => { throw SyntaxError(msg) };
+
+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)));
+		} 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(''));
+		} 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(''));
+		} else if (t.tag[0] === '#' || t.tag[0] === '/') {
+			err('Unexpected {{' + t.tag + '}}');
+		} else {
+			nodes.push((e => v => esc(e(v) ?? ''))(compile(t.tag, fns)));
+		}
+	}
+	stops.length && err('Missing {{' + stops[stops.length - 1] + '}}');
+	return nodes;
+};
+
+/**
+ * Compile a template once, render it many times.
+ *
+ * @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.
+ * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
+ */
+export function template(str, funcs) {
+	fns = funcs;
+	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 });
+	}
+	i = 0;
+	const nodes = parse([]);
+	return v => nodes.map(n => n(v || {})).join('');
+}
+
+/**
+ * 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, values, funcs) {
+	return template(str, funcs)(values);
+}