sjabloon 0.11.0 → 0.13.0

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./types.js";
-import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from "./types.js";
+import type { SjabloonRender, SjabloonTemplate, Token } from "./types.js";
 
 /**
  * Compile a template once, render it many times to a token stream.
@@ -7,18 +7,9 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues, Token } from
  * `{{ expr }}` emits a value token; escaping belongs to whoever consumes the
  * stream, so `{{{ expr }}}` has no meaning here and is a compile-time
  * `SJABLOON_RAW_TAG` error.
- *
- * @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,
-  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[];
+export const template: SjabloonTemplate<Token[]>;
+export const render: SjabloonRender<Token[]>;
 
 /**
  * Join a token stream into the string `sjabloon/text` would have produced:

package/lib/index.js

@@ -9,15 +9,19 @@ import { display, make } from "./core.js";
 export { display, 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.
-  (text) =>
-    ((token) => (scope, acc) => {
-      acc.push(token);
-    })(Object.freeze({ literal: text })),
-  (expr) => (scope, acc) => {
-    acc.push({ value: expr(scope) });
-  },
+  // Static text is a compile-time constant: the default parameter hoists and
+  // freezes one token per text node rather than allocating per loop iteration.
+  (text, token = Object.freeze({ literal: text })) =>
+    (scope, acc) =>
+      acc.push(token),
+  // A tagged interpolation spreads what the compile's `tag` returned; the
+  // value is written last, so the token's own key cannot be taken over. The
+  // branch is taken once at compile time, so an untagged template emits the
+  // exact closure it always did.
+  (expr, tagged) =>
+    tagged
+      ? (scope, acc) => acc.push({ ...tagged, value: expr(scope) })
+      : (scope, acc) => acc.push({ value: expr(scope) }),
   0,
   () => /** @type {import('./types.js').Token[]} */ ([]),
   (acc) => acc,
@@ -31,12 +35,11 @@ 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 = "";
+export const text = (tokens) =>
   // 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 ?? display(t.value);
-  return s;
-};
+  /** @type {readonly { literal?: string, value?: unknown }[]} */ (tokens).reduce(
+    (s, t) => s + (t.literal ?? display(t.value)),
+    "",
+  );

package/lib/text.d.ts

@@ -1,5 +1,5 @@
 export * from "./types.js";
-import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./types.js";
+import type { SjabloonRender, SjabloonTemplate } from "./types.js";
 
 /**
  * Compile a template once, render it many times to a plain string.
@@ -7,15 +7,6 @@ import type { SjabloonFunctions, SjabloonRenderer, SjabloonValues } from "./type
  * `{{ expr }}` interpolates unescaped — escaping belongs at the output edge —
  * so `{{{ expr }}}` has no meaning here and is a compile-time
  * `SJABLOON_RAW_TAG` error.
- *
- * @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,
-  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;
+export const template: SjabloonTemplate<string>;
+export const render: SjabloonRender<string>;

package/lib/text.js

@@ -6,13 +6,16 @@
  * Definitionally `text(template(str)(values))` from the root entry, but built
  * as a string accumulator so casual string users never allocate tokens.
  */
-import { display, litNode, make } from "./core.js";
+import { display, make } from "./core.js";
 
 export { isDiagnostic, relocate } from "./core.js";
 
+// The string accumulator is this edition's own shape, so its profile is stated
+// here rather than named in the core: every node is shorter than an import of
+// it, and the core stays the parser alone.
 export const { template, render } = make([
-  litNode,
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += display(value))),
+  (text) => (scope, acc) => (acc.text += text),
+  (expr) => (scope, acc) => (acc.text += display(expr(scope))),
   0,
   () => ({ text: "" }),
   (acc) => acc.text,

package/lib/types.d.ts

@@ -1,7 +1,12 @@
+import type { Diagnostic, Relocation } from "waarmerk";
 import type { XprsnErrorCode, XprsnRead } from "xprsn";
 
+/**
+ * The codes sjabloon itself mints. An expression fault carries xprsn's instead,
+ * which is why the diagnostic's `code` is the wider union — the same split
+ * padvinder draws between its own codes and treffer's.
+ */
 export type SjabloonErrorCode =
-  | XprsnErrorCode
   | "SJABLOON_EACH_SYNTAX"
   | "SJABLOON_BLOCKED_BINDING"
   | "SJABLOON_UNEXPECTED_TAG"
@@ -16,8 +21,17 @@ export interface SjabloonBlock {
   readonly end: number;
 }
 
-export interface SjabloonDiagnostic extends Error {
-  readonly code: SjabloonErrorCode;
+/**
+ * The fields and their meanings are waarmerk's; this names the code union they are
+ * checked against, narrows the three this module always carries from optional
+ * to required, and adds the block context a template fault sits in.
+ *
+ * `code` is widened with `XprsnErrorCode` because most diagnostics here are
+ * xprsn errors translated into template coordinates: a host can still tell a
+ * malformed tag from a fault in the expression inside it.
+ */
+export interface SjabloonDiagnostic extends Diagnostic<SjabloonErrorCode | XprsnErrorCode> {
+  readonly code: SjabloonErrorCode | XprsnErrorCode;
   readonly start: number;
   readonly end: number;
   readonly blocks: readonly SjabloonBlock[];
@@ -81,12 +95,53 @@ export interface SjabloonRenderer<T> {
   scoped(values: SjabloonValues): T;
 }
 
+/**
+ * `template` in every edition: compile once, render many times. `T` is what
+ * one render returns.
+ *
+ * @throws {SyntaxError} On malformed tags, unclosed blocks, or bad expressions.
+ */
+export type SjabloonTemplate<T> = (
+  str: string,
+  funcs?: SjabloonFunctions,
+  opts?: {
+    bound?: Iterable<string>;
+    /**
+     * Name an interpolation by what it says. Called once per `{{ }}` while
+     * compiling, with that interpolation's expression source as written and
+     * trimmed (`{{- page.number -}}` is `"page.number"`), and never again at
+     * render time. Returned keys join every value token that interpolation
+     * emits; `value` and `literal` are the stream's own, so a tag may not
+     * supply either. It runs inside the parse, which is shared synchronous
+     * state: read the expression and return, and compile no template from
+     * within it. Block expressions
+     * (`#if` conditions, `#each` collections) emit no token and are not
+     * offered. The token edition alone has tokens to carry them; the string
+     * editions ignore this.
+     */
+    tag?: (expr: string) => object | undefined;
+  },
+) => SjabloonRenderer<T>;
+
+/** Compile and render in one go. Shorthand for `template(str, funcs)(values)`. */
+export type SjabloonRender<T> = (
+  str: string,
+  values?: SjabloonValues,
+  funcs?: SjabloonFunctions,
+) => T;
+
 /** One static text run of the template, verbatim. */
 export interface LiteralToken {
   literal: string;
 }
 
-/** One `{{ }}` interpolation, pre-stringify. Nullish values are preserved. */
+/**
+ * One `{{ }}` interpolation, pre-stringify. Nullish values are preserved.
+ *
+ * A compile that passed `tag` also carries that interpolation's returned keys
+ * here, under the names the embedder chose; declare them by intersecting this
+ * type with your own, as `ValueToken & { field?: string }`.
+ */
 export interface ValueToken {
   value: unknown;
 }
@@ -113,7 +168,4 @@ export function isDiagnostic(error: unknown): error is SjabloonDiagnostic;
  *
  * @throws {TypeError} When `diag` is not a sjabloon diagnostic.
  */
-export function relocate(
-  diag: unknown,
-  opts?: { prefix?: string; offset?: number },
-): SjabloonDiagnostic;
+export function relocate(diag: unknown, opts?: Relocation): SjabloonDiagnostic;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sjabloon",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
   "keywords": [
     "csp",
@@ -17,7 +17,8 @@
   },
   "repository": "getquario/sjabloon",
   "files": [
-    "lib"
+    "lib",
+    "EMBEDDING.md"
   ],
   "type": "module",
   "module": "lib/index.js",
@@ -41,6 +42,7 @@
     "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",
+    "commitlint": "commitlint",
     "fallow": "fallow",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
@@ -61,17 +63,20 @@
     "test:unit": "c8 --100 --src lib/ node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js"
   },
   "dependencies": {
-    "xprsn": "^0.11.0"
+    "waarmerk": "^0.1.0",
+    "xprsn": "^0.11.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
     "@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",
+    "oxfmt": "^0.66.0",
     "oxlint": "^1.78.0",
     "oxlint-tsgolint": "^7.0.2001",
     "playwright": "^1.61.1",
@@ -83,6 +88,7 @@
       "name": "sjabloon",
       "path": "lib/index.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.35 kB"
@@ -91,6 +97,7 @@
       "name": "sjabloon/text",
       "path": "lib/text.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.35 kB"
@@ -99,6 +106,7 @@
       "name": "sjabloon/html",
       "path": "lib/html.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.4 kB"