sjabloon 0.10.0 → 0.11.0

package/README.md

@@ -95,6 +95,13 @@ tpl.functions; // => ['fmt']
 template("{{ run.total }} of {{ count }}", undefined, { bound: ["run"] }).names; // => ['count']
 ```
 
+The renderer also carries `reads`: every root-name read with its span in the template source, in source order. Duplicates, anchors, loop variables and bound names are all kept — `names` is the free, deduplicated view. This is what an editor squiggles, hovers, and jumps from:
+
+```js
+template("{{ title }}: {{ total }}").reads;
+// => [{ name: 'title', start: 3, end: 8 }, { name: 'total', start: 16, end: 21 }]
+```
+
 The renderer also carries its own `isDiagnostic(error)`: `true` only for runtime diagnostics thrown through this renderer, where the module-wide [`isDiagnostic`](#diagnostics) answers for every template. An embedder holding many compiled templates asks the one that just rendered, so a diagnostic that leaked from an unrelated template is not mistaken for this cell's.
 
 ### `renderer.scoped(values)`
@@ -113,7 +120,11 @@ Shorthand for `template(str, functions)(values)`, returning whatever its edition
 
 ### `text(tokens)` (root entry only)
 
-Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values as `String(value ?? '')`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values. The test suite and the fuzzer both check that.
+Joins a token stream the way `sjabloon/text` would have rendered it: literals verbatim, values through `display()`. `text(template(str)(values))` and `sjabloon/text`'s `template(str)(values)` are equal for every template and every set of values. The test suite and the fuzzer both check that.
+
+### `display(value)` (root entry only)
+
+The scalar display rule every edition and `text()` share, exported for embedders that stringify token values themselves. A valid `Date` renders as ISO 8601 UTC (`toISOString()`) — the same bytes on every machine, where `String(date)` would bake in the host's timezone and locale. An invalid `Date` keeps its deterministic `'Invalid Date'` form, nullish displays empty, and everything else is `String(value)`.
 
 ```js
 import { template, text } from "sjabloon";

package/lib/core.js

@@ -132,6 +132,8 @@ let last;
 let bound;
 /** @type {Set<string>} */
 let names;
+/** @type {{ name: string, start: number, end: number }[]} */
+let reads;
 /** @type {Set<string>} */
 let functions;
 /** @type {string} */
@@ -321,6 +323,9 @@ let compileExpr = (expr, start, context) => {
     // oxlint-disable-next-line no-unused-expressions
     bound.includes(n) || names.add(n);
   });
+  // Every read, shifted into template coordinates — bound names and loop
+  // variables included; `names` above stays the free, deduplicated view.
+  for (const r of e.reads) reads.push({ name: r.name, start: start + r.start, end: start + r.end });
   for (const fn of e.functions) functions.add(fn);
   return (v) => {
     try {
@@ -540,6 +545,25 @@ export const litNode = (text) => (scope, acc) => {
   acc.text += text;
 };
 
+/**
+ * Display text for one interpolated value — the scalar rule every edition and
+ * the root `text()` join share. A valid `Date` renders as ISO 8601 UTC
+ * (`toISOString()`), the same on every machine, where `String(date)` would
+ * bake in the host's timezone and locale; an invalid `Date` keeps its
+ * deterministic `"Invalid Date"` form. Nullish displays empty; everything
+ * else is `String(value)`.
+ *
+ * @param {unknown} value One rendered value.
+ * @returns {string} The display text.
+ */
+export const display = (value) =>
+  value instanceof Date && Number.isFinite(value.getTime())
+    ? value.toISOString()
+    : // Stringifying an arbitrary value is this rule'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
+      String(value ?? "");
+
 /**
  * Bind the parser to an output profile. Each edition calls this once at module
  * load and gets back its own `template` and `render`; the parser itself stays
@@ -552,8 +576,10 @@ export const litNode = (text) => (scope, acc) => {
  * from your values, deduplicated. Loop variables the template introduces are
  * not included, and neither is anything in `opts.bound` — names the embedder
  * already has in scope (still resolved normally at render time, exactly like
- * xprsn's own `bound`). It also exposes `functions`: the registry functions
- * the template calls, deduplicated. `isDiagnostic(error)` recognizes runtime
+ * xprsn's own `bound`). It also exposes `reads`: 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.
+ * And `functions`: the registry functions the template calls, deduplicated. `isDiagnostic(error)` recognizes runtime
  * diagnostics thrown through this renderer alone.
  *
  * Two anchors are always in scope: `$` is the root values, and `@` is the
@@ -621,6 +647,7 @@ export let make = ([lit, val, raw, seed, take]) => {
     bound = ["$", "@"];
     if (opts && opts.bound) for (const name of opts.bound) bound.push(name);
     names = new Set();
+    reads = [];
     functions = new Set();
     source = String(str);
     blocks = [];
@@ -656,6 +683,7 @@ export let make = ([lit, val, raw, seed, take]) => {
     // Array.from, not a spread: the bundler's transpile turns `[...set]` into
     // `[].concat(set)`, which wraps the Set instead of unpacking it.
     f.names = Array.from(names);
+    f.reads = reads;
     f.functions = Array.from(functions);
     // This compile's own `names` set doubles as its origin: every diagnostic
     // thrown through this renderer was marked with it, at compile time by

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 { litNode, make } from "./core.js";
+import { display, litNode, make } from "./core.js";
 
 /** @type {Record<string, string>} */
 const ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
-/** @param {any} s */
-const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ESC[c]);
+/** @param {string} s Already display text — both call sites pass `display()`. */
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ESC[c]);
 
 export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
   litNode,
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += esc(value ?? ""))),
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += esc(display(value)))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += display(value))),
   () => ({ text: "" }),
   (acc) => acc.text,
 ]);

package/lib/index.d.ts

@@ -22,6 +22,15 @@ export function render(str: string, values?: SjabloonValues, funcs?: SjabloonFun
 
 /**
  * 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,9 +4,9 @@
  * 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
@@ -25,20 +25,18 @@ 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.
+  // 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 ?? "");
+    s += t.literal ?? display(t.value);
   return s;
 };

package/lib/text.js

@@ -6,13 +6,13 @@
  * 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, litNode, make } from "./core.js";
 
 export { isDiagnostic, relocate } from "./core.js";
 
 export const { template, render } = make([
   litNode,
-  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += String(value ?? ""))),
+  (expr) => (scope, acc, value) => ((value = expr(scope)), (acc.text += display(value))),
   0,
   () => ({ text: "" }),
   (acc) => acc.text,

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { XprsnErrorCode } from "xprsn";
+import type { XprsnErrorCode, XprsnRead } from "xprsn";
 
 export type SjabloonErrorCode =
   | XprsnErrorCode
@@ -24,6 +24,13 @@ export interface SjabloonDiagnostic extends Error {
 }
 
 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 +57,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,6 +75,7 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sjabloon",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Tiny, CSP-safe template engine for JavaScript, powered by xprsn expressions. No eval, no new Function.",
   "keywords": [
     "csp",
@@ -61,7 +61,7 @@
     "test:unit": "c8 --100 --src lib/ node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js"
   },
   "dependencies": {
-    "xprsn": "^0.10.0"
+    "xprsn": "^0.11.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
@@ -85,7 +85,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/text",
@@ -93,7 +93,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.25 kB"
+      "limit": "2.35 kB"
     },
     {
       "name": "sjabloon/html",
@@ -101,7 +101,7 @@
       "ignore": [
         "xprsn"
       ],
-      "limit": "2.3 kB"
+      "limit": "2.4 kB"
     }
   ],
   "engines": {