sjabloon 0.11.0 → 0.12.0

package/lib/index.js

@@ -9,15 +9,12 @@ 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),
+  (expr) => (scope, acc) => acc.push({ value: expr(scope) }),
   0,
   () => /** @type {import('./types.js').Token[]} */ ([]),
   (acc) => acc,
@@ -31,12 +28,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,6 +95,25 @@ 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> },
+) => 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;
@@ -113,7 +146,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.12.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",
@@ -61,7 +62,8 @@
     "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",
@@ -83,6 +85,7 @@
       "name": "sjabloon",
       "path": "lib/index.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.35 kB"
@@ -91,6 +94,7 @@
       "name": "sjabloon/text",
       "path": "lib/text.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.35 kB"
@@ -99,6 +103,7 @@
       "name": "sjabloon/html",
       "path": "lib/html.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
       "limit": "2.4 kB"