@jarenjs/json 0.9.2

package/src/jtlt/index.js

@@ -0,0 +1,155 @@
+//#region Jaren JTLT public API
+// JTLT: template-driven text output over the Jaren JSLT dispatcher.
+// A JTLT template is a JSLT-shaped rule document whose bodies are
+// segment lists (literal text, interpolated queries, $apply splices)
+// and whose result is a string. It compiles down to an ordinary JSLT
+// 0.1 stylesheet - inspectable as `render.stylesheet` - so dispatch,
+// modes, conflict resolution, and schema matching are inherited, not
+// reimplemented.
+
+import { deepFreezeCopy } from '../query/normalize.js';
+import {
+  compileJsltStylesheet,
+  JsltCompileError,
+  JsltRuntimeError,
+} from '../jslt/index.js';
+import { JtltCompileError, JtltRuntimeError } from './errors.js';
+import { normalizeJtltTemplate } from './template.js';
+import { desugarTemplate, remapDocPath } from './desugar.js';
+import { createWriter } from './writer.js';
+
+export { JtltCompileError, JtltRuntimeError } from './errors.js';
+
+/**
+ * Compile a Jaren JTLT 0.1 template into a reusable renderer.
+ *
+ * The returned function renders any input document to a string in the
+ * template's output method ('text' by default, 'xml' for markup with
+ * escaped interpolation). Metadata:
+ *
+ * - `render.externals` - user parameter names in first-appearance order
+ *   (`root` and `path` are engine-bound and excluded)
+ * - `render.output` - the resolved output method
+ * - `render.doc` - an independent, deeply frozen template copy
+ * - `render.stylesheet` - the frozen JSLT stylesheet it compiled to
+ *
+ * @param {any} doc - a bare rule array or `{"$jtlt":"0.1","output":...,
+ *   "rules":[]}` template envelope
+ * @param {object} [options] - compile options, passed to the JSLT layer
+ * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   [options.compileTypeTest] - validator-agnostic hook for schema
+ *   matches and schema operators inside segment expressions
+ * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @returns {function} reusable `render(data, externals?)` function
+ * @throws {JtltCompileError} when compilation fails
+ * @example
+ * const render = compileJtltStylesheet([
+ *   { match: '$.items[*]', body: ['- ', '$.name', '\n'] },
+ * ]);
+ * render({ items: [{ name: 'a' }, { name: 'b' }] });
+ * // '- a\n- b\n'
+ */
+export function compileJtltStylesheet(doc, options = {}) {
+  const frozenDoc = deepFreezeCopy(doc);
+  const model = normalizeJtltTemplate(frozenDoc);
+  const stylesheet = desugarTemplate(model);
+  let transform;
+  try {
+    transform = compileJsltStylesheet(stylesheet, options);
+  }
+  catch (error) {
+    if (!(error instanceof JsltCompileError))
+      throw error;
+    throw new JtltCompileError('TL0005', error.message,
+      remapDocPath(model, error.docPath), error);
+  }
+  const write = createWriter(model.output);
+
+  const render = (data, externals) => {
+    let value;
+    try {
+      value = transform(data, externals);
+    }
+    catch (error) {
+      if (!(error instanceof JsltRuntimeError))
+        throw error;
+      throw new JtltRuntimeError('TL2003', error.message,
+        remapDocPath(model, error.docPath), error);
+    }
+    return write(value);
+  };
+  render.externals = transform.externals;
+  render.output = model.output;
+  render.doc = frozenDoc;
+  render.stylesheet = transform.doc;
+  return render;
+}
+
+const TEMPLATE_CACHE = new WeakMap();
+
+function cachedRender(template, options) {
+  let record = TEMPLATE_CACHE.get(template);
+  if (record === undefined) {
+    record = {
+      defaultRender: null,
+      variants: null,
+    };
+    TEMPLATE_CACHE.set(template, 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.defaultRender === null)
+      record.defaultRender = compileJtltStylesheet(template);
+    return record.defaultRender;
+  }
+
+  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.render;
+  }
+  const render = compileJtltStylesheet(template, options);
+  variants.push({ compileTypeTest, maxDepth, render });
+  return render;
+}
+
+/**
+ * Render a JSON value with a JTLT template in one call. Object/array
+ * template documents are compiled once and cached by identity in a
+ * WeakMap.
+ * @param {any} template - JTLT template 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 {string} the rendered output text
+ * @throws {JtltCompileError} when compilation fails
+ * @throws {JtltRuntimeError} when rendering fails
+ * @example
+ * renderText([{ match: '$.name', body: ['Hello ', '$', '!'] }],
+ *   { name: 'world' });
+ * // 'Hello world!'
+ */
+export function renderText(template, data, externals, options = undefined) {
+  let render;
+  if (typeof template === 'object' && template !== null) {
+    render = cachedRender(template, options);
+  }
+  else {
+    render = compileJtltStylesheet(template, options);
+  }
+  return render(data, externals);
+}
+
+//#endregion

package/src/jtlt/template.js

@@ -0,0 +1,130 @@
+//#region Jaren JTLT template normalizer
+// Validates the template envelope and rule shape. Segment bodies are
+// validated during desugaring (desugar.js); everything the JSLT layer
+// checks itself (match details, mode strings inside $apply, query
+// vocabulary) is deliberately left to it so the two vocabularies cannot
+// drift apart.
+
+import { JtltCompileError } from './errors.js';
+
+const hasOwn = Object.hasOwn;
+const ENVELOPE_KEYS = new Set(['$jtlt', 'output', 'rules']);
+const RULE_KEYS = new Set(['match', 'mode', 'priority', 'body']);
+const OUTPUT_METHODS = new Set(['text', 'xml']);
+
+// Priorities at or below the floor are reserved for the injected
+// built-in rules, which sit at -1e308 - beneath every user rule.
+export const RESERVED_PRIORITY_FLOOR = -1e307;
+
+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 JtltCompileError(code, message, docPath);
+}
+
+function normalizeRule(value, index, rulesPath) {
+  const rulePath = rulesPath + '/' + index;
+  if (!isObject(value))
+    fail('TL0002', 'a template 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('TL0002', `unknown rule member '${keys[i]}'`,
+        rulePath + '/' + escapeToken(keys[i]));
+  }
+  if (!hasOwn(value, 'body'))
+    fail('TL0002', "a template rule requires 'body'", rulePath + '/body');
+  if (!Array.isArray(value.body))
+    fail('TL0002', "'body' must be a segment array", rulePath + '/body');
+  if (hasOwn(value, 'mode') && typeof value.mode !== 'string')
+    fail('TL0002', "'mode' must be a string", rulePath + '/mode');
+  const hasPriority = hasOwn(value, 'priority');
+  if (hasPriority) {
+    if (typeof value.priority !== 'number' || !Number.isFinite(value.priority))
+      fail('TL0002', "'priority' must be a finite JSON number", rulePath + '/priority');
+    if (value.priority <= RESERVED_PRIORITY_FLOOR)
+      fail('TL0003', `priorities at or below ${RESERVED_PRIORITY_FLOOR} are reserved for the built-in rules`,
+        rulePath + '/priority');
+  }
+  const hasMatch = hasOwn(value, 'match');
+  if (hasMatch && typeof value.match !== 'string' && !isObject(value.match))
+    fail('TL0002', "'match' must be a JSONPath string or an object", rulePath + '/match');
+
+  return Object.freeze({
+    index,
+    docPath: rulePath,
+    bodyDocPath: rulePath + '/body',
+    body: value.body,
+    hasMatch,
+    match: hasMatch ? value.match : null,
+    mode: hasOwn(value, 'mode') ? value.mode : '',
+    hasPriority,
+    priority: hasPriority ? value.priority : 0,
+  });
+}
+
+/**
+ * Normalize a frozen JTLT template document into a frozen model.
+ * @param {any} doc - deeply frozen template document
+ * @returns {object} frozen template model
+ * @throws {JtltCompileError} on TL0001-TL0003 and TL0006 shape errors
+ */
+export function normalizeJtltTemplate(doc) {
+  let sourceRules;
+  let rulesPath;
+  let output = 'text';
+
+  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('TL0001', `unknown template member '${keys[i]}'`,
+          '/' + escapeToken(keys[i]));
+    }
+    if (!hasOwn(doc, '$jtlt'))
+      fail('TL0001', "the template envelope requires '$jtlt'", '/$jtlt');
+    if (doc.$jtlt !== '0.1')
+      fail('TL0006', `unknown JTLT format version ${JSON.stringify(doc.$jtlt)}`, '/$jtlt');
+    if (hasOwn(doc, 'output') && !OUTPUT_METHODS.has(doc.output)) {
+      fail('TL0001',
+        `unknown output method ${JSON.stringify(doc.output)} (supported: "text", "xml")`,
+        '/output');
+    }
+    if (hasOwn(doc, 'output'))
+      output = doc.output;
+    if (!hasOwn(doc, 'rules'))
+      fail('TL0001', "the template envelope requires 'rules'", '/rules');
+    if (!Array.isArray(doc.rules))
+      fail('TL0001', "'rules' must be an array", '/rules');
+    sourceRules = doc.rules;
+    rulesPath = '/rules';
+  }
+  else {
+    fail('TL0001', 'a template must be a rule array or a version envelope', '');
+  }
+
+  const rules = new Array(sourceRules.length);
+  for (let i = 0; i < sourceRules.length; i++)
+    rules[i] = normalizeRule(sourceRules[i], i, rulesPath);
+
+  return Object.freeze({
+    output,
+    rulesPrefix: rulesPath,
+    rules: Object.freeze(rules),
+  });
+}
+
+//#endregion

package/src/jtlt/writer.js

@@ -0,0 +1,110 @@
+//#region Jaren JTLT writer
+// Serializes the tagged segment stream a desugared stylesheet produces
+// (see desugar.js for the closed grammar) into the output text. The
+// writer is chosen once per compiled template; escaping applies to
+// interpolated data only - literal template text is the author's markup
+// and passes through raw, exactly as in XSLT and T4.
+
+import { JtltRuntimeError } from './errors.js';
+
+const XML_TEST = /[&<>"']/;
+const XML_PATTERN = /[&<>"']/g;
+
+function xmlEntity(c) {
+  switch (c) {
+    case '&': return '&amp;';
+    case '<': return '&lt;';
+    case '>': return '&gt;';
+    case '"': return '&quot;';
+    default: return '&#39;';
+  }
+}
+
+function escapeXml(s) {
+  return XML_TEST.test(s) ? s.replace(XML_PATTERN, xmlEntity) : s;
+}
+
+// The text value of one interpolated item: null is empty (text
+// serialization, not the $string cast), containers are a template error
+// pointing at the segment that produced them.
+function stringifyItem(v, docPath) {
+  switch (typeof v) {
+    case 'string':
+      return v;
+    case 'number':
+      return String(v);
+    case 'boolean':
+      return v ? 'true' : 'false';
+    default:
+      if (v === null)
+        return '';
+      throw new JtltRuntimeError('TL2001',
+        `cannot interpolate ${Array.isArray(v) ? 'an array' : 'an object'} into text output; dispatch into it with $apply, or embed it with $json`,
+        docPath);
+  }
+}
+
+// Multi-item payloads (a sequence-valued expression) join with a single
+// space, the XSLT value-of separator default.
+function pushPayload(pair, parts, escape, asJson) {
+  const tag = pair[0];
+  const docPath = tag.length > 1 ? tag.slice(1) : '';
+  for (let i = 1; i < pair.length; i++) {
+    if (i > 1)
+      parts.push(' ');
+    const s = asJson ? JSON.stringify(pair[i]) : stringifyItem(pair[i], docPath);
+    parts.push(escape === null ? s : escape(s));
+  }
+}
+
+function walk(x, parts, escape) {
+  if (!Array.isArray(x)) {
+    // every dispatched node fires a rule and every rule body is a
+    // segment constructor, so a bare value here is an engine-contract
+    // break, never author error
+    throw new JtltRuntimeError('TL2002',
+      'malformed segment stream (engine contract violation)', '');
+  }
+  const head = x.length === 0 ? null : x[0];
+  if (typeof head === 'string') {
+    const kind = head.charCodeAt(0);
+    if (kind === 0x72) { // 'r'
+      parts.push(x[1]);
+      return;
+    }
+    if (kind === 0x65) { // 'e'
+      pushPayload(x, parts, escape, false);
+      return;
+    }
+    if (kind === 0x77) { // 'w'
+      pushPayload(x, parts, null, false);
+      return;
+    }
+    if (kind === 0x6A) { // 'j'
+      pushPayload(x, parts, escape, true);
+      return;
+    }
+    throw new JtltRuntimeError('TL2002',
+      `unknown segment tag ${JSON.stringify(head)}`, '');
+  }
+  for (let i = 0; i < x.length; i++)
+    walk(x[i], parts, escape);
+}
+
+/**
+ * Create the serializer for one output method.
+ * @param {'text' | 'xml'} method - the template's output method
+ * @returns {(value: any) => string} segment-stream serializer
+ */
+export function createWriter(method) {
+  const escape = method === 'xml' ? escapeXml : null;
+  return (value) => {
+    if (value === undefined)
+      return '';
+    const parts = [];
+    walk(value, parts, escape);
+    return parts.join('');
+  };
+}
+
+//#endregion