sjabloon 0.8.0 → 0.10.0

package/lib/html.d.ts

@@ -1,5 +1,5 @@
-export * from './types.js';
-import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from './types.js';
+export * from "./types.js";
+import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./types.js";
 
 /**
  * Compile a template once, render it many times to an HTML string.
@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from './type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/html.js

@@ -3,19 +3,19 @@
  * 0.6's behaviour, kept for templates that target HTML directly. Everything
  * else in sjabloon is output-neutral; escaping lives here and nowhere else.
  */
-import { make } from './core.js';
+import { litNode, make } from "./core.js";
 
 /** @type {Record<string, string>} */
-const ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
 /** @param {any} s */
-const esc = s => String(s).replace(/[&<>"']/g, c => ESC[c]);
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ESC[c]);
 
-export { isDiagnostic } from './core.js';
+export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
-	s => (v, o) => { o.s += s; },
-	e => (v, o, x) => (x = e(v), o.s += esc(x ?? '')),
-	e => (v, o, x) => (x = e(v), o.s += String(x ?? '')),
-	() => ({ s: '' }),
-	o => o.s,
+  litNode,
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += esc(value ?? ""))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  () => ({ text: "" }),
+  (acc) => acc.text,
 ]);

package/lib/index.d.ts

@@ -1,5 +1,5 @@
-export * from './types.js';
-import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from './types.js';
+export * from "./types.js";
+import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from "./types.js";
 
 /**
  * Compile a template once, render it many times to a token stream.
@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<Token[]>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<Token[]>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): Token[];

package/lib/index.js

@@ -4,18 +4,23 @@
  * so nothing here is HTML-aware and `{{{ }}}` has no meaning — `{{ }}` is
  * already raw.
  */
-import { make } from './core.js';
+import { make } from "./core.js";
 
-export { isDiagnostic } from './core.js';
+export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
-	// Static text is a compile-time constant: hoist and freeze one token per
-	// text node rather than allocating a fresh object every loop iteration.
-	s => (t => (v, o) => { o.push(t); })(Object.freeze({ literal: s })),
-	e => (v, o) => { o.push({ value: e(v) }); },
-	0,
-	() => /** @type {import('./types.js').Token[]} */ ([]),
-	o => o,
+  // Static text is a compile-time constant: hoist and freeze one token per
+  // text node rather than allocating a fresh object every loop iteration.
+  (text) =>
+    ((token) => (scope, acc) => {
+      acc.push(token);
+    })(Object.freeze({ literal: text })),
+  (expr) => (scope, acc) => {
+    acc.push({ value: expr(scope) });
+  },
+  0,
+  () => /** @type {import('./types.js').Token[]} */ ([]),
+  (acc) => acc,
 ]);
 
 /**
@@ -25,11 +30,15 @@ export const { template, render } = make([
  * @param {readonly import('./types.js').Token[]} tokens A render's output.
  * @returns {string} The joined text.
  */
-export const text = tokens => {
-	let s = '';
-	// One `?? ''` per token, so a literal never stringifies and a nullish value
-	// still renders empty. Widened here because each token carries one key or
-	// the other, which the public union deliberately does not model.
-	for (const t of /** @type {readonly { literal?: string, value?: unknown }[]} */ (tokens)) s += t.literal ?? String(t.value ?? '');
-	return s;
+export const text = (tokens) => {
+  let s = "";
+  // One `?? ''` per token, so a literal never stringifies and a nullish value
+  // still renders empty. Widened here because each token carries one key or
+  // the other, which the public union deliberately does not model.
+  for (const t of /** @type {readonly { literal?: string, value?: unknown }[]} */ (tokens))
+    // Stringifying an arbitrary value is this helper's documented contract, so
+    // `no-base-to-string` is describing the feature rather than a mistake.
+    // oxlint-disable-next-line typescript/no-base-to-string
+    s += t.literal ?? String(t.value ?? "");
+  return s;
 };

package/lib/text.d.ts

@@ -1,5 +1,5 @@
-export * from './types.js';
-import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from './types.js';
+export * from "./types.js";
+import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./types.js";
 
 /**
  * Compile a template once, render it many times to a plain string.
@@ -11,7 +11,11 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from './type
  * @see SjabloonRenderer for `names`/`functions`, SjabloonScope for `$` and `@`.
  * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
  */
-export function template(str: string, funcs?: SjabloonFunctions): SjabloonRenderer<string>;
+export function template(
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: { bound?: Iterable<string> },
+): SjabloonRenderer<string>;
 
 /** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
 export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFunctions): string;

package/lib/text.js

@@ -6,14 +6,14 @@
  * Definitionally `text(template(str)(values))` from the root entry, but built
  * as a string accumulator so casual string users never allocate tokens.
  */
-import { make } from './core.js';
+import { litNode, make } from "./core.js";
 
-export { isDiagnostic } from './core.js';
+export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
-	s => (v, o) => { o.s += s; },
-	e => (v, o, x) => (x = e(v), o.s += String(x ?? '')),
-	0,
-	() => ({ s: '' }),
-	o => o.s,
+  litNode,
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  0,
+  () => ({ text: "" }),
+  (acc) => acc.text,
 ]);

package/lib/types.d.ts

@@ -1,26 +1,26 @@
-import type { XprsnErrorCode } from 'xprsn';
+import type { XprsnErrorCode } from "xprsn";
 
 export type SjabloonErrorCode =
-    | XprsnErrorCode
-    | 'SJABLOON_EACH_SYNTAX'
-    | 'SJABLOON_BLOCKED_BINDING'
-    | 'SJABLOON_UNEXPECTED_TAG'
-    | 'SJABLOON_UNKNOWN_BLOCK'
-    | 'SJABLOON_UNCLOSED_BLOCK'
-    | 'SJABLOON_TOO_DEEP'
-    | 'SJABLOON_RAW_TAG';
+  | XprsnErrorCode
+  | "SJABLOON_EACH_SYNTAX"
+  | "SJABLOON_BLOCKED_BINDING"
+  | "SJABLOON_UNEXPECTED_TAG"
+  | "SJABLOON_UNKNOWN_BLOCK"
+  | "SJABLOON_UNCLOSED_BLOCK"
+  | "SJABLOON_TOO_DEEP"
+  | "SJABLOON_RAW_TAG";
 
 export interface SjabloonBlock {
-    readonly type: 'if' | 'each';
-    readonly start: number;
-    readonly end: number;
+  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[];
+  readonly code: SjabloonErrorCode;
+  readonly start: number;
+  readonly end: number;
+  readonly blocks: readonly SjabloonBlock[];
 }
 
 export type SjabloonValues = Record<string, any>;
@@ -41,31 +41,43 @@ export type SjabloonFunctions = Record<string, Function>;
  * band that has no current row wants exactly that.
  */
 export interface SjabloonScope {
-    root?: any;
-    item?: any;
+  root?: any;
+  item?: any;
 }
 
 /**
  * A compiled template: render it many times.
  *
  * `names` are the variables the template reads from your values, deduplicated;
- * loop variables the template introduces are not included. `functions` are the
- * registry functions the template calls, deduplicated.
+ * loop variables the template introduces are not included, and neither is
+ * anything the compile's `bound` option declared. `functions` are the registry
+ * functions the template calls, deduplicated.
+ *
+ * `isDiagnostic(error)` recognizes runtime diagnostics thrown through this
+ * renderer alone — the per-renderer twin of the module-wide `isDiagnostic`.
+ *
+ * `scoped(values)` renders over a scope chain that already binds the anchors:
+ * no wrapper scope is created, `$` and `@` resolve from `values` itself, and a
+ * chain that omits `@` leaves it unbound so `@.x` throws through xprsn's
+ * guard. The zero-allocation seam for an embedder rendering over scopes it
+ * already builds; `{{#each}}` still re-points `@` inside its body.
  */
 export interface SjabloonRenderer<T> {
-    (values?: SjabloonValues, scope?: SjabloonScope): T;
-    names: string[];
-    functions: string[];
+  (values?: SjabloonValues, scope?: SjabloonScope): T;
+  names: string[];
+  functions: string[];
+  isDiagnostic(error: unknown): boolean;
+  scoped(values: SjabloonValues): T;
 }
 
 /** One static text run of the template, verbatim. */
 export interface LiteralToken {
-    literal: string;
+  literal: string;
 }
 
 /** One `{{ }}` interpolation, pre-stringify. Nullish values are preserved. */
 export interface ValueToken {
-    value: unknown;
+  value: unknown;
 }
 
 /**
@@ -81,3 +93,16 @@ export type Token = LiteralToken | ValueToken;
  * through all of them.
  */
 export function isDiagnostic(error: unknown): error is SjabloonDiagnostic;
+
+/**
+ * Copy a diagnostic into an embedder's coordinates: `prefix` is prepended to
+ * the message verbatim, `offset` shifts the span, every other field — the
+ * frozen `blocks` context included — is carried over, and the copy is
+ * authenticated exactly as the original was.
+ *
+ * @throws {TypeError} When `diag` is not a sjabloon diagnostic.
+ */
+export function relocate(
+  diag: unknown,
+  opts?: { prefix?: string; offset?: number },
+): SjabloonDiagnostic;

package/package.json

@@ -1,101 +1,110 @@
 {
-	"name": "sjabloon",
-	"version": "0.8.0",
-	"description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
-	"repository": "getquario/sjabloon",
-	"license": "Apache-2.0",
-	"author": {
-		"name": "Robin van der Vleuten",
-		"email": "robin@webstronauts.com",
-		"url": "https://robinvdvleuten.nl"
-	},
-	"type": "module",
-	"module": "lib/index.js",
-	"types": "lib/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./lib/index.d.ts",
-			"default": "./lib/index.js"
-		},
-		"./text": {
-			"types": "./lib/text.d.ts",
-			"default": "./lib/text.js"
-		},
-		"./html": {
-			"types": "./lib/html.d.ts",
-			"default": "./lib/html.js"
-		},
-		"./package.json": "./package.json"
-	},
-	"engines": {
-		"node": ">=22.12.0"
-	},
-	"files": [
-		"lib"
-	],
-	"size-limit": [
-		{
-			"name": "sjabloon",
-			"path": "lib/index.js",
-			"ignore": [
-				"xprsn"
-			],
-			"limit": "1.95 kB"
-		},
-		{
-			"name": "sjabloon/text",
-			"path": "lib/text.js",
-			"ignore": [
-				"xprsn"
-			],
-			"limit": "1.9 kB"
-		},
-		{
-			"name": "sjabloon/html",
-			"path": "lib/html.js",
-			"ignore": [
-				"xprsn"
-			],
-			"limit": "1.97 kB"
-		}
-	],
-	"scripts": {
-		"bench": "node --disallow-code-generation-from-strings bench/index.js",
-		"bench:comparison": "npm --prefix bench/comparison run bench",
-		"check": "run-s 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 lib/ --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/",
-		"fuzz:render": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/render.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync .fuzz-corpus/render fuzz/corpus/render -- -max_total_time=60 -use_value_profile=1 -dict=fuzz/sjabloon.dict -artifact_prefix=fuzz/",
-		"fuzz:structured": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/structured.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync .fuzz-corpus/structured fuzz/corpus/structured -- -max_total_time=60 -use_value_profile=1 -dict=fuzz/sjabloon.dict -artifact_prefix=fuzz/",
-		"fuzz:regression": "run-s fuzz:regression:compile fuzz:regression:render fuzz:regression:structured",
-		"fuzz:regression:compile": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/compile.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/compile -- -artifact_prefix=fuzz/",
-		"fuzz:regression:render": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/render.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/render -- -artifact_prefix=fuzz/",
-		"fuzz:regression:structured": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/structured.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/structured -- -artifact_prefix=fuzz/",
-		"size": "size-limit",
-		"test": "run-s test:unit test:types",
-		"test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
-		"test:browser": "playwright install chromium && node test/browser/harness.js",
-		"test:types": "tsc && attw --pack . --profile esm-only"
-	},
-	"keywords": [
-		"template",
-		"template-engine",
-		"csp",
-		"render",
-		"handlebars"
-	],
-	"dependencies": {
-		"xprsn": "^0.9.0"
-	},
-	"devDependencies": {
-		"@arethetypeswrong/cli": "^0.18.3",
-		"@jazzer.js/bug-detectors": "^4.0.0",
-		"@jazzer.js/core": "^4.0.0",
-		"@size-limit/preset-small-lib": "^12.1.0",
-		"npm-run-all": "^4.1.5",
-		"playwright": "^1.61.1",
-		"size-limit": "^12.1.0",
-		"typescript": "7.0.2"
-	}
+  "name": "sjabloon",
+  "version": "0.10.0",
+  "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
+  "keywords": [
+    "csp",
+    "handlebars",
+    "render",
+    "template",
+    "template-engine"
+  ],
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Robin van der Vleuten",
+    "email": "robin@webstronauts.com",
+    "url": "https://robinvdvleuten.nl"
+  },
+  "repository": "getquario/sjabloon",
+  "files": [
+    "lib"
+  ],
+  "type": "module",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./text": {
+      "types": "./lib/text.d.ts",
+      "default": "./lib/text.js"
+    },
+    "./html": {
+      "types": "./lib/html.d.ts",
+      "default": "./lib/html.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "bench": "node --disallow-code-generation-from-strings bench/index.js",
+    "bench:comparison": "npm --prefix bench/comparison run bench",
+    "check": "run-s fmt:check lint fallow size test fuzz:regression test:browser",
+    "fallow": "fallow",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "fuzz": "npm run fuzz:prepare && run-s fuzz:compile fuzz:render fuzz:structured",
+    "fuzz:compile": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/compile.fuzz.js -i lib/ --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/",
+    "fuzz:prepare": "node -e \"for (const x of ['compile','render','structured']) require('fs').mkdirSync('.fuzz-corpus/'+x,{recursive:true})\"",
+    "fuzz:regression": "run-s fuzz:regression:compile fuzz:regression:render fuzz:regression:structured",
+    "fuzz:regression:compile": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/compile.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/compile -- -artifact_prefix=fuzz/",
+    "fuzz:regression:render": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/render.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/render -- -artifact_prefix=fuzz/",
+    "fuzz:regression:structured": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/structured.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync --mode=regression fuzz/corpus/structured -- -artifact_prefix=fuzz/",
+    "fuzz:render": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/render.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync .fuzz-corpus/render fuzz/corpus/render -- -max_total_time=60 -use_value_profile=1 -dict=fuzz/sjabloon.dict -artifact_prefix=fuzz/",
+    "fuzz:structured": "NODE_OPTIONS=--disallow-code-generation-from-strings jazzer fuzz/structured.fuzz.js -i lib/ --customHooks fuzz/hooks.js --disableBugDetectors='command-injection|path-traversal|ssrf' --sync .fuzz-corpus/structured fuzz/corpus/structured -- -max_total_time=60 -use_value_profile=1 -dict=fuzz/sjabloon.dict -artifact_prefix=fuzz/",
+    "lint": "oxlint",
+    "size": "size-limit",
+    "test": "run-s test:unit test:types",
+    "test:browser": "playwright install chromium && node test/browser/harness.js",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "c8 --100 --src lib/ node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js"
+  },
+  "dependencies": {
+    "xprsn": "^0.10.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@jazzer.js/bug-detectors": "^4.0.0",
+    "@jazzer.js/core": "^4.0.0",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "c8": "^12.0.0",
+    "fallow": "^3.17.0",
+    "npm-run-all": "^4.1.5",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.78.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "playwright": "^1.61.1",
+    "size-limit": "^13.0.3",
+    "typescript": "7.0.2"
+  },
+  "size-limit": [
+    {
+      "name": "sjabloon",
+      "path": "lib/index.js",
+      "ignore": [
+        "xprsn"
+      ],
+      "limit": "2.25 kB"
+    },
+    {
+      "name": "sjabloon/text",
+      "path": "lib/text.js",
+      "ignore": [
+        "xprsn"
+      ],
+      "limit": "2.25 kB"
+    },
+    {
+      "name": "sjabloon/html",
+      "path": "lib/html.js",
+      "ignore": [
+        "xprsn"
+      ],
+      "limit": "2.3 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  }
 }