@jarenjs/json 0.9.2

package/src/jslt/errors.js

@@ -0,0 +1,34 @@
+//#region Jaren JSLT errors
+// Error classes for the Jaren JSLT engine. Every error carries a stable
+// `code` and a `docPath`, an RFC 6901 JSON Pointer into the stylesheet
+// document. Wrapped parser/query/hook errors are exposed through `cause`.
+
+/**
+ * Error thrown when a JSLT stylesheet is rejected at compile time
+ * (`JT0xxx` codes).
+ */
+export class JsltCompileError extends Error {
+  constructor(code, message, docPath, cause = undefined) {
+    super(`${code}: ${message} at ${docPath}`,
+      cause === undefined ? undefined : { cause });
+    this.name = 'JsltCompileError';
+    this.code = code;
+    this.docPath = docPath;
+  }
+}
+
+/**
+ * Error thrown when evaluating a compiled JSLT stylesheet fails
+ * (`JT2xxx` codes).
+ */
+export class JsltRuntimeError extends Error {
+  constructor(code, message, docPath, cause = undefined) {
+    super(`${code}: ${message} at ${docPath}`,
+      cause === undefined ? undefined : { cause });
+    this.name = 'JsltRuntimeError';
+    this.code = code;
+    this.docPath = docPath;
+  }
+}
+
+//#endregion

package/src/jslt/index.js

@@ -0,0 +1,121 @@
+//#region Jaren JSLT public API
+// A compiled JSON stylesheet layer over the Jaren JSON Query engine.
+// Stylesheets normalize once, compile to ranked dispatch closures once,
+// and may then transform any number of input documents.
+
+import { deepFreezeCopy } from '../query/normalize.js';
+import { EMPTY, Seq } from '../query/runtime.js';
+import { normalizeJsltStylesheet } from './stylesheet.js';
+import { compileJsltDispatch } from './dispatch.js';
+
+export { JsltCompileError, JsltRuntimeError } from './errors.js';
+
+/**
+ * Compile a Jaren JSLT 0.1 stylesheet into a reusable transformation.
+ *
+ * The returned function maps the internal sequence result to plain JSON:
+ * `undefined` for the empty sequence, the item itself for a singleton,
+ * and an array of items for a longer sequence. Metadata:
+ *
+ * - `transform.externals` - user parameter names in first-appearance order
+ *   (`root` and `path` are engine-bound and excluded)
+ * - `transform.doc` - an independent, deeply frozen stylesheet copy
+ *
+ * @param {any} doc - a bare rule array or `{"$jslt":"0.1","rules":[]}`
+ *   stylesheet envelope
+ * @param {object} [options] - compile options
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - validator-agnostic hook compiling schema
+ *   match conditions and schema literals inside query bodies
+ * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @returns {function} reusable `transform(data, externals?)` function
+ * @throws {import('./errors.js').JsltCompileError} when compilation fails
+ * @example
+ * const transform = compileJsltStylesheet([
+ *   { match: '$..price', body: { $mul: ['$', 1.21] } }
+ * ]);
+ * transform({ item: { price: 10 } });
+ * // { item: { price: 12.1 } }
+ */
+export function compileJsltStylesheet(doc, options = {}) {
+  const frozenDoc = deepFreezeCopy(doc);
+  const model = normalizeJsltStylesheet(frozenDoc);
+  const runtime = compileJsltDispatch(model, options);
+
+  const transform = (data, externals) => {
+    const value = runtime.evaluate(data, externals);
+    if (value === EMPTY)
+      return undefined;
+    return value instanceof Seq ? value.items : value;
+  };
+  transform.externals = runtime.externals;
+  transform.doc = frozenDoc;
+  return transform;
+}
+
+const STYLESHEET_CACHE = new WeakMap();
+
+function cachedTransform(stylesheet, options) {
+  let record = STYLESHEET_CACHE.get(stylesheet);
+  if (record === undefined) {
+    record = {
+      defaultTransform: null,
+      variants: null,
+    };
+    STYLESHEET_CACHE.set(stylesheet, record);
+  }
+
+  const compileTypeTest = typeof options?.compileTypeTest === 'function'
+    ? options.compileTypeTest
+    : null;
+  const maxDepth = options?.maxDepth === undefined ? 1024 : options.maxDepth;
+  if (compileTypeTest === null && maxDepth === 1024) {
+    if (record.defaultTransform === null)
+      record.defaultTransform = compileJsltStylesheet(stylesheet);
+    return record.defaultTransform;
+  }
+
+  let variants = record.variants;
+  if (variants === null) {
+    variants = [];
+    record.variants = variants;
+  }
+  for (let i = 0; i < variants.length; i++) {
+    const variant = variants[i];
+    if (variant.compileTypeTest === compileTypeTest && variant.maxDepth === maxDepth)
+      return variant.transform;
+  }
+  const transform = compileJsltStylesheet(stylesheet, options);
+  variants.push({ compileTypeTest, maxDepth, transform });
+  return transform;
+}
+
+/**
+ * Transform a JSON value with a JSLT stylesheet in one call.
+ * Object/array stylesheet documents are compiled once and cached by
+ * identity in a WeakMap.
+ * @param {any} stylesheet - JSLT stylesheet document
+ * @param {any} data - input JSON value
+ * @param {object} [externals] - user parameter bindings
+ * @param {object} [options] - compile options used on a cache miss
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - schema type-test compiler
+ * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @returns {any} `undefined`, one JSON item, or an array of result items
+ * @throws {import('./errors.js').JsltCompileError} when compilation fails
+ * @throws {import('./errors.js').JsltRuntimeError} when dispatch fails
+ * @example
+ * transformJson([], { value: 1 }); // returns the input object by reference
+ */
+export function transformJson(stylesheet, data, externals, options = undefined) {
+  let transform;
+  if (typeof stylesheet === 'object' && stylesheet !== null) {
+    transform = cachedTransform(stylesheet, options);
+  }
+  else {
+    transform = compileJsltStylesheet(stylesheet, options);
+  }
+  return transform(data, externals);
+}
+
+//#endregion

package/src/jslt/stylesheet.js

@@ -0,0 +1,234 @@
+//#region Jaren JSLT stylesheet normalizer
+// Validates the closed stylesheet vocabulary, partitions rules by mode,
+// and precomputes conflict order. The output is frozen data only; path,
+// schema, and body closures are compiled by dispatch.js.
+
+import { JsltCompileError } from './errors.js';
+
+const hasOwn = Object.hasOwn;
+const ENVELOPE_KEYS = new Set(['$jslt', 'rules', 'unmatched', 'modes']);
+const RULE_KEYS = new Set(['match', 'mode', 'priority', 'body']);
+const MATCH_KEYS = new Set(['path', 'schema']);
+const MODE_KEYS = new Set(['unmatched']);
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function escapeToken(token) {
+  if (token.indexOf('~') < 0 && token.indexOf('/') < 0)
+    return token;
+  return token.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+function fail(code, message, docPath) {
+  throw new JsltCompileError(code, message, docPath);
+}
+
+function isDisposition(value) {
+  return value === 'share' || value === 'fresh' || value === 'error';
+}
+
+function normalizeModes(value, docPath) {
+  if (!isObject(value))
+    fail('JT0001', "'modes' must be an object", docPath);
+  const modes = new Map();
+  const names = Object.keys(value);
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i];
+    const modePath = docPath + '/' + escapeToken(name);
+    const config = value[name];
+    if (!isObject(config))
+      fail('JT0001', `mode '${name}' must be an object`, modePath);
+    const keys = Object.keys(config);
+    for (let j = 0; j < keys.length; j++) {
+      if (!MODE_KEYS.has(keys[j]))
+        fail('JT0001', `unknown mode member '${keys[j]}'`,
+          modePath + '/' + escapeToken(keys[j]));
+    }
+    if (!hasOwn(config, 'unmatched'))
+      fail('JT0001', `mode '${name}' requires 'unmatched'`, modePath + '/unmatched');
+    if (!isDisposition(config.unmatched))
+      fail('JT0001', `invalid unmatched disposition ${JSON.stringify(config.unmatched)}`,
+        modePath + '/unmatched');
+    modes.set(name, Object.freeze({
+      unmatched: config.unmatched,
+      unmatchedPath: modePath + '/unmatched',
+    }));
+  }
+  return modes;
+}
+
+function normalizeMatch(value, matchPath) {
+  if (typeof value === 'string') {
+    return Object.freeze({
+      path: value,
+      pathDocPath: matchPath,
+      schema: null,
+      schemaPresent: false,
+      schemaDocPath: '',
+    });
+  }
+  if (!isObject(value))
+    fail('JT0003', "'match' must be a JSONPath string or an object", matchPath);
+
+  const keys = Object.keys(value);
+  if (keys.length === 0)
+    fail('JT0003', "'match' cannot be an empty object", matchPath);
+  for (let i = 0; i < keys.length; i++) {
+    if (!MATCH_KEYS.has(keys[i]))
+      fail('JT0003', `unknown match member '${keys[i]}'`,
+        matchPath + '/' + escapeToken(keys[i]));
+  }
+  const hasPath = hasOwn(value, 'path');
+  const hasSchema = hasOwn(value, 'schema');
+  if (!hasPath && !hasSchema)
+    fail('JT0003', "'match' requires 'path' and/or 'schema'", matchPath);
+  if (hasPath && typeof value.path !== 'string')
+    fail('JT0003', "'match.path' must be a JSONPath string", matchPath + '/path');
+
+  return Object.freeze({
+    path: hasPath ? value.path : null,
+    pathDocPath: hasPath ? matchPath + '/path' : '',
+    schema: hasSchema ? value.schema : null,
+    schemaPresent: hasSchema,
+    schemaDocPath: hasSchema ? matchPath + '/schema' : '',
+  });
+}
+
+function normalizeRule(value, index, rulesPath) {
+  const rulePath = rulesPath + '/' + index;
+  if (!isObject(value))
+    fail('JT0002', 'a stylesheet rule must be an object', rulePath);
+
+  const keys = Object.keys(value);
+  for (let i = 0; i < keys.length; i++) {
+    if (!RULE_KEYS.has(keys[i]))
+      fail('JT0002', `unknown rule member '${keys[i]}'`,
+        rulePath + '/' + escapeToken(keys[i]));
+  }
+  if (!hasOwn(value, 'body'))
+    fail('JT0002', "a stylesheet rule requires 'body'", rulePath + '/body');
+  if (hasOwn(value, 'mode') && typeof value.mode !== 'string')
+    fail('JT0002', "'mode' must be a string", rulePath + '/mode');
+  if (hasOwn(value, 'priority')
+    && (typeof value.priority !== 'number' || !Number.isFinite(value.priority)))
+    fail('JT0002', "'priority' must be a finite JSON number", rulePath + '/priority');
+
+  const match = hasOwn(value, 'match')
+    ? normalizeMatch(value.match, rulePath + '/match')
+    : null;
+  const pathCount = match !== null && match.path !== null ? 1 : 0;
+  const schemaCount = match !== null && match.schemaPresent ? 1 : 0;
+  const defaultPriority = pathCount + schemaCount === 2
+    ? 1
+    : (pathCount + schemaCount === 1 ? 0 : -1);
+
+  return Object.freeze({
+    index,
+    docPath: rulePath,
+    bodyDocPath: rulePath + '/body',
+    body: value.body,
+    mode: hasOwn(value, 'mode') ? value.mode : '',
+    priority: hasOwn(value, 'priority') ? value.priority : defaultPriority,
+    match,
+  });
+}
+
+/**
+ * Normalize a frozen JSLT stylesheet document into a frozen, closure-free
+ * model with ranked per-mode rule arrays.
+ * @param {any} doc - deeply frozen stylesheet document
+ * @returns {object} frozen stylesheet model
+ * @throws {JsltCompileError} on JT0001-JT0004 shape errors
+ */
+export function normalizeJsltStylesheet(doc) {
+  let sourceRules;
+  let rulesPath;
+  let unmatched = 'share';
+  let unmatchedPath = '';
+  let declaredModes = new Map();
+
+  if (Array.isArray(doc)) {
+    sourceRules = doc;
+    rulesPath = '';
+  }
+  else if (isObject(doc)) {
+    const keys = Object.keys(doc);
+    for (let i = 0; i < keys.length; i++) {
+      if (!ENVELOPE_KEYS.has(keys[i]))
+        fail('JT0001', `unknown stylesheet member '${keys[i]}'`,
+          '/' + escapeToken(keys[i]));
+    }
+    if (!hasOwn(doc, '$jslt'))
+      fail('JT0001', "the stylesheet envelope requires '$jslt'", '/$jslt');
+    if (doc.$jslt !== '0.1')
+      fail('JT0004', `unknown JSLT format version ${JSON.stringify(doc.$jslt)}`, '/$jslt');
+    if (!hasOwn(doc, 'rules'))
+      fail('JT0001', "the stylesheet envelope requires 'rules'", '/rules');
+    if (!Array.isArray(doc.rules))
+      fail('JT0001', "'rules' must be an array", '/rules');
+    if (hasOwn(doc, 'unmatched')) {
+      if (!isDisposition(doc.unmatched))
+        fail('JT0001', `invalid unmatched disposition ${JSON.stringify(doc.unmatched)}`,
+          '/unmatched');
+      unmatched = doc.unmatched;
+      unmatchedPath = '/unmatched';
+    }
+    if (hasOwn(doc, 'modes'))
+      declaredModes = normalizeModes(doc.modes, '/modes');
+    sourceRules = doc.rules;
+    rulesPath = '/rules';
+  }
+  else {
+    fail('JT0001', 'a stylesheet must be a rule array or a version envelope', '');
+  }
+
+  const rules = new Array(sourceRules.length);
+  const rulesByMode = new Map();
+  rulesByMode.set('', []);
+  let anyPathRule = false;
+  for (let i = 0; i < sourceRules.length; i++) {
+    const rule = normalizeRule(sourceRules[i], i, rulesPath);
+    rules[i] = rule;
+    let modeRules = rulesByMode.get(rule.mode);
+    if (modeRules === undefined) {
+      modeRules = [];
+      rulesByMode.set(rule.mode, modeRules);
+    }
+    modeRules.push(rule);
+    if (rule.match !== null && rule.match.path !== null)
+      anyPathRule = true;
+  }
+
+  for (const name of declaredModes.keys()) {
+    if (!rulesByMode.has(name))
+      rulesByMode.set(name, []);
+  }
+
+  const modes = [];
+  for (const [name, modeRules] of rulesByMode) {
+    modeRules.sort((a, b) => b.priority - a.priority || b.index - a.index);
+    const declared = declaredModes.get(name);
+    modes.push(Object.freeze({
+      name,
+      unmatched: declared !== undefined
+        ? declared.unmatched
+        : unmatched,
+      unmatchedPath: declared !== undefined
+        ? declared.unmatchedPath
+        : unmatchedPath,
+      rules: Object.freeze(modeRules),
+    }));
+  }
+
+  return Object.freeze({
+    rules: Object.freeze(rules),
+    modes: Object.freeze(modes),
+    unmatched,
+    unmatchedPath,
+    anyPathRule,
+  });
+}
+
+//#endregion

package/src/jtlt/desugar.js

@@ -0,0 +1,231 @@
+//#region Jaren JTLT desugarer
+// Compiles the template model down to an ordinary JSLT 0.1 stylesheet.
+// Each rule body becomes an array constructor of tagged segment pairs:
+//
+//   SegTree := Pair | Array<SegTree>
+//   Pair    := ['r<docPath?>', text]        raw literal text
+//            | ['e<docPath?>', ...values]   interpolated, method-escaped
+//            | ['w<docPath?>', ...values]   interpolated, never escaped
+//            | ['j<docPath?>', ...values]   JSON.stringify'd, method-escaped
+//
+// The tag is a compile-time string constant: one kind character followed
+// by the segment's docPath in the *template* document, so runtime errors
+// point at the author's source. Literal pairs are wrapped in $const and
+// allocate nothing per render.
+//
+// A matchless catch-all rule is appended per mode at the reserved
+// priority. It guarantees every dispatched node fires *some* rule, so
+// the stream grammar above is closed: data values only ever appear as
+// pair payloads, never bare, and `typeof x[0] === 'string'` identifies a
+// pair unambiguously.
+
+import { JtltCompileError } from './errors.js';
+
+const DOLLAR = 0x24;
+const BUILTIN_PRIORITY = -1e308;
+
+function fail(code, message, docPath) {
+  throw new JtltCompileError(code, message, docPath);
+}
+
+// Collect every statically declared `$apply` target mode inside a plain
+// JSON expression tree. `$apply` mode arguments are literal strings by
+// JSLT contract, so this walk cannot under-collect; over-collection
+// (e.g. an `$apply` shape quoted inside `$const`) only compiles a spare
+// catch-all rule that is never dispatched.
+function collectApplyModes(node, modes) {
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++)
+      collectApplyModes(node[i], modes);
+    return;
+  }
+  if (typeof node !== 'object' || node === null)
+    return;
+  const keys = Object.keys(node);
+  for (let i = 0; i < keys.length; i++) {
+    const value = node[keys[i]];
+    if (keys[i] === '$apply' && Array.isArray(value)
+      && value.length === 2 && typeof value[1] === 'string')
+      modes.add(value[1]);
+    collectApplyModes(value, modes);
+  }
+}
+
+function desugarSegment(seg, path, modes) {
+  if (typeof seg === 'string') {
+    if (seg.charCodeAt(0) !== DOLLAR)
+      return { $const: ['r', seg] };
+    if (seg.charCodeAt(1) === DOLLAR) // '$$x' is the literal text '$x'
+      return { $const: ['r', seg.slice(1)] };
+    return ['e' + path, seg];
+  }
+  if (Array.isArray(seg)) {
+    const out = new Array(seg.length);
+    for (let j = 0; j < seg.length; j++)
+      out[j] = desugarSegment(seg[j], path + '/' + j, modes);
+    return out;
+  }
+  if (typeof seg === 'object' && seg !== null) {
+    const keys = Object.keys(seg);
+    if (keys.length === 1) {
+      const key = keys[0];
+      if (key === '$raw') {
+        collectApplyModes(seg.$raw, modes);
+        return ['w' + path, seg.$raw];
+      }
+      if (key === '$json') {
+        collectApplyModes(seg.$json, modes);
+        return ['j' + path, seg.$json];
+      }
+      if (key === '$apply') { // passes through: its output is spliced verbatim
+        collectApplyModes(seg, modes);
+        return seg;
+      }
+    }
+    let anyDollar = false;
+    for (let j = 0; j < keys.length; j++) {
+      if (keys[j].charCodeAt(0) === DOLLAR) {
+        anyDollar = true;
+        break;
+      }
+    }
+    if (!anyDollar) {
+      fail('TL0004',
+        'a plain object is not a template segment (map constructors cannot be serialized; use an operator phrase, $json, or $apply)',
+        path);
+    }
+    collectApplyModes(seg, modes);
+    return ['e' + path, seg];
+  }
+  fail('TL0004',
+    `${seg === null ? 'null' : typeof seg} is not a template segment; write literal text as a string`,
+    path);
+}
+
+// The built-in rule per mode: containers apply templates to every child
+// in document order, atoms interpolate their string value (the XSLT
+// built-in template rules, restated for JSON).
+function builtinRule(mode) {
+  const rule = {
+    priority: BUILTIN_PRIORITY,
+    body: {
+      $if: [
+        { $or: [{ '$is-object': '$' }, { '$is-array': '$' }] },
+        [{ $apply: '$[*]' }],
+        ['e', '$'],
+      ],
+    },
+  };
+  if (mode !== '')
+    rule.mode = mode;
+  return rule;
+}
+
+/**
+ * Desugar a normalized template model into a JSLT 0.1 stylesheet
+ * document. User rules keep their index; built-in rules are appended.
+ * @param {object} model - result of normalizeJtltTemplate
+ * @returns {object} a JSLT stylesheet envelope
+ * @throws {JtltCompileError} on TL0004 segment errors
+ */
+export function desugarTemplate(model) {
+  const modes = new Set(['']);
+  const rules = [];
+  const templateRules = model.rules;
+  for (let i = 0; i < templateRules.length; i++) {
+    const rule = templateRules[i];
+    modes.add(rule.mode);
+    const body = new Array(rule.body.length);
+    for (let j = 0; j < rule.body.length; j++)
+      body[j] = desugarSegment(rule.body[j], rule.bodyDocPath + '/' + j, modes);
+    const out = {};
+    if (rule.hasMatch)
+      out.match = rule.match;
+    if (rule.mode !== '')
+      out.mode = rule.mode;
+    if (rule.hasPriority)
+      out.priority = rule.priority;
+    out.body = body;
+    rules.push(out);
+  }
+  for (const mode of modes)
+    rules.push(builtinRule(mode));
+  return { $jslt: '0.1', rules };
+}
+
+//#region docPath remapping
+
+function appendRest(out, tokens, k) {
+  return k < tokens.length ? out + '/' + tokens.slice(k).join('/') : out;
+}
+
+/**
+ * Translate a docPath into the desugared JSLT stylesheet back into the
+ * author's template document. Best-effort: paths that cannot be walked
+ * (built-in rules, envelope members the template does not have) map to
+ * '' - the whole document - and `render.stylesheet` stays available for
+ * inspection.
+ * @param {object} model - result of normalizeJtltTemplate
+ * @param {string} docPath - pointer into the desugared stylesheet
+ * @returns {string} pointer into the template document
+ */
+export function remapDocPath(model, docPath) {
+  if (typeof docPath !== 'string' || docPath === '')
+    return '';
+  const tokens = docPath.split('/');
+  if (tokens.length < 3 || tokens[1] !== 'rules')
+    return '';
+  const index = Number(tokens[2]);
+  const rules = model.rules;
+  if (!Number.isInteger(index) || index < 0 || index >= rules.length)
+    return ''; // a built-in rule: point at the whole document
+  const base = model.rulesPrefix + '/' + index;
+  if (tokens.length === 3)
+    return base;
+  if (tokens[3] !== 'body') // match/mode/priority pass through verbatim
+    return appendRest(base, tokens, 3);
+
+  let segs = rules[index].body;
+  let out = base + '/body';
+  let k = 4;
+  while (k < tokens.length) {
+    const j = Number(tokens[k]);
+    if (!Number.isInteger(j) || j < 0 || j >= segs.length)
+      return appendRest(out, tokens, k);
+    const seg = segs[j];
+    out += '/' + j;
+    k++;
+    if (typeof seg === 'string') {
+      // an expression string desugars to a pair; drop the payload index
+      if (seg.charCodeAt(0) === DOLLAR && seg.charCodeAt(1) !== DOLLAR
+        && k < tokens.length && tokens[k] === '1')
+        k++;
+      return appendRest(out, tokens, k);
+    }
+    if (Array.isArray(seg)) { // nested segment list: keep walking
+      segs = seg;
+      continue;
+    }
+    if (typeof seg === 'object' && seg !== null) {
+      const keys = Object.keys(seg);
+      if (keys.length === 1 && (keys[0] === '$raw' || keys[0] === '$json')) {
+        if (k < tokens.length && tokens[k] === '1') {
+          k++;
+          out += '/' + keys[0];
+        }
+        return appendRest(out, tokens, k);
+      }
+      if (keys.length === 1 && keys[0] === '$apply') // verbatim
+        return appendRest(out, tokens, k);
+      if (k < tokens.length && tokens[k] === '1') // pair-wrapped expression
+        k++;
+      return appendRest(out, tokens, k);
+    }
+    return appendRest(out, tokens, k);
+  }
+  return out;
+}
+
+//#endregion
+
+//#endregion

package/src/jtlt/errors.js

@@ -0,0 +1,34 @@
+//#region Jaren JTLT errors
+// Error classes for the Jaren JTLT template engine. Every error carries a
+// stable `code` and a `docPath`, an RFC 6901 JSON Pointer into the template
+// document. Wrapped JSLT/query errors are exposed through `cause`.
+
+/**
+ * Error thrown when a JTLT template is rejected at compile time
+ * (`TL0xxx` codes).
+ */
+export class JtltCompileError extends Error {
+  constructor(code, message, docPath, cause = undefined) {
+    super(`${code}: ${message} at ${docPath}`,
+      cause === undefined ? undefined : { cause });
+    this.name = 'JtltCompileError';
+    this.code = code;
+    this.docPath = docPath;
+  }
+}
+
+/**
+ * Error thrown when rendering with a compiled JTLT template fails
+ * (`TL2xxx` codes).
+ */
+export class JtltRuntimeError extends Error {
+  constructor(code, message, docPath, cause = undefined) {
+    super(`${code}: ${message} at ${docPath}`,
+      cause === undefined ? undefined : { cause });
+    this.name = 'JtltRuntimeError';
+    this.code = code;
+    this.docPath = docPath;
+  }
+}
+
+//#endregion