sjabloon 0.10.0 → 0.12.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,21 +7,21 @@ 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:
- * literals verbatim, values as `String(value ?? '')`.
+ * literals verbatim, values through `display()`.
  */
 export function text(tokens: readonly Token[]): string;
+
+/**
+ * Display text for one interpolated value — the scalar rule `text()` and the
+ * string editions share. A valid `Date` renders as ISO 8601 UTC
+ * (`toISOString()`), deterministically across machines; an invalid `Date`
+ * stays `"Invalid Date"`; nullish displays empty; everything else is
+ * `String(value)`.
+ */
+export function display(value: unknown): string;

package/lib/index.js

@@ -4,20 +4,17 @@
  * so nothing here is HTML-aware and `{{{ }}}` has no meaning — `{{ }}` is
  * already raw.
  */
-import { make } from "./core.js";
+import { display, make } from "./core.js";
 
-export { isDiagnostic, relocate } 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,
@@ -25,20 +22,17 @@ export const { template, render } = make([
 
 /**
  * Join a token stream into the string `sjabloon/text` would have produced:
- * literals verbatim, values as `String(value ?? '')`.
+ * literals verbatim, values through `display()` — the one scalar rule, so a
+ * `Date` joins as ISO 8601 UTC here exactly as the string editions render it.
  *
  * @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))
-    // 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;
-};
+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.
+  /** @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 { 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 += String(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 { XprsnErrorCode } from "xprsn";
+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,14 +21,30 @@ 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[];
 }
 
 export type SjabloonValues = Record<string, any>;
+
+/**
+ * One root-name read, with its span in the template source — xprsn's read
+ * record, forwarded with only its coordinates shifted.
+ */
+export type SjabloonRead = XprsnRead;
+
 export type SjabloonFunctions = Record<string, Function>;
 
 /**
@@ -50,8 +71,11 @@ export interface SjabloonScope {
  *
  * `names` are the variables the template reads from your values, 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.
+ * anything the compile's `bound` option declared. `reads` are every root-name
+ * read with its span in the template source, in source order — duplicates,
+ * anchors, loop variables and bound names kept, so `names` is its free,
+ * deduplicated view. `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`.
@@ -65,11 +89,31 @@ export interface SjabloonScope {
 export interface SjabloonRenderer<T> {
   (values?: SjabloonValues, scope?: SjabloonScope): T;
   names: string[];
+  reads: SjabloonRead[];
   functions: string[];
   isDiagnostic(error: unknown): boolean;
   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;
@@ -102,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.10.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.10.0"
+    "waarmerk": "^0.1.0",
+    "xprsn": "^0.11.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
@@ -83,25 +85,28 @@
       "name": "sjabloon",
       "path": "lib/index.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/text",
       "path": "lib/text.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/html",
       "path": "lib/html.js",
       "ignore": [
+        "waarmerk",
         "xprsn"
       ],
-      "limit": "2.3 kB"
+      "limit": "2.4 kB"
     }
   ],
   "engines": {