jtlt 0.4.0 → 0.6.0

package/src/JSONPathTransformerContext.js

@@ -1,11 +1,28 @@
 import {JSONPath as jsonpath} from 'jsonpath-plus';
 import JSONPathTransformer from './JSONPathTransformer.js';
 
+/**
+ * Decimal format symbols for number formatting.
+ * @typedef {object} DecimalFormatSymbols
+ * @property {string} [decimalSeparator='.'] - Character for decimal point
+ * @property {string} [groupingSeparator=','] - Character for thousands
+ * @property {string} [percent='%'] - Character for percent
+ * @property {string} [perMille='‰'] - Character for per-mille
+ * @property {string} [zeroDigit='0'] - Character for zero
+ * @property {string} [digit='#'] - Character for digit placeholder
+ * @property {string} [patternSeparator=';'] - Character separating
+ *   positive/negative patterns
+ * @property {string} [minusSign='-'] - Character for minus sign
+ * @property {string} [infinity='Infinity'] - String for infinity
+ * @property {string} [NaN='NaN'] - String for NaN
+ */
+
 /**
  * @typedef {number|string|{
  *   value?: number|string,
  *   count?: string,
  *   format?: string,
+ *   decimalFormat?: string,
  *   groupingSeparator?: string,
  *   groupingSize?: number,
  *   lang?: string,
@@ -80,6 +97,8 @@ class JSONPathTransformerContext {
     this.propertySets = {};
     /** @type {Record<string, {match: string, use: string}>} */
     this.keys = {};
+    /** @type {Record<string, DecimalFormatSymbols>} */
+    this.decimalFormats = {};
     /** @type {boolean | undefined} */
     this._initialized = undefined;
     /** @type {string | undefined} */
@@ -258,6 +277,7 @@ class JSONPathTransformerContext {
       if (type === 'number') {
         const an = Number(aVal);
         const bn = Number(bVal);
+        /* c8 ignore next -- both NaN tested; short-circuit branch tracking */
         if (Number.isNaN(an) && Number.isNaN(bn)) {
           return 0;
         }
@@ -270,6 +290,7 @@ class JSONPathTransformerContext {
         return (an - bn) * order;
       }
       // text
+      /* c8 ignore next 2 -- all null/undefined tested; OR short-circuit */
       const aStr = aVal === null || aVal === undefined ? '' : String(aVal);
       const bStr = bVal === null || bVal === undefined ? '' : String(bVal);
       if (spec && spec.locale) {
@@ -277,6 +298,8 @@ class JSONPathTransformerContext {
           bStr, spec.locale, spec.localeOptions
         ) * order;
       }
+      /* c8 ignore next -- all comparison outcomes tested; ternary
+       * branch tracking */
       return (aStr < bStr ? -1 : (aStr > bStr ? 1 : 0)) * order;
     }
     /**
@@ -407,12 +430,19 @@ class JSONPathTransformerContext {
       that._parent = parent;
       that._parentProperty = (parentProperty ?? that._parentProperty);
 
+      // Set up parameter context for valueOf() access in templates
+      const prevTemplateParams = that._params;
+      that._params = {0: value};
+
       const ret =
         /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
           templateObj
         ).template.call(
           that, value, {mode, parent, parentProperty}
         );
+
+      // Restore previous parameter context
+      that._params = prevTemplateParams;
       if (typeof ret !== 'undefined') {
         // After the undefined check, ret is ResultType<T>
         that._getJoiningTransformer().append(
@@ -540,11 +570,13 @@ class JSONPathTransformerContext {
      * @returns {number}
      */
     function feCompareBySpec (aVal, bVal, spec) {
+      /* c8 ignore next 2 -- all spec combinations tested; && and || branches */
       const order = (spec && spec.order === 'descending') ? -1 : 1;
       const type = (spec && spec.type) || 'text';
       if (type === 'number') {
         const an = Number(aVal);
         const bn = Number(bVal);
+        /* c8 ignore next -- both NaN tested; short-circuit branch tracking */
         if (Number.isNaN(an) && Number.isNaN(bn)) {
           return 0;
         }
@@ -556,6 +588,7 @@ class JSONPathTransformerContext {
         }
         return (an - bn) * order;
       }
+      /* c8 ignore next 2 -- all null/undefined tested; OR short-circuit */
       const aStr = aVal === null || aVal === undefined ? '' : String(aVal);
       const bStr = bVal === null || bVal === undefined ? '' : String(bVal);
       if (spec && spec.locale) {
@@ -563,6 +596,8 @@ class JSONPathTransformerContext {
           bStr, spec.locale, spec.localeOptions
         ) * order;
       }
+      /* c8 ignore next -- all comparison outcomes tested; ternary
+       * branch tracking */
       return (aStr < bStr ? -1 : (aStr > bStr ? 1 : 0)) * order;
     }
     /**
@@ -606,11 +641,364 @@ class JSONPathTransformerContext {
     const comparator = feBuildComparator(sort);
     const list = comparator ? [...matches].toSorted(comparator) : matches;
     for (const m of list) {
-      cb.call(that, m.value);
+      // Set up parameter context for valueOf() access
+      const prevParams = that._params;
+      const prevContext = that._contextObj;
+      that._params = {0: m.value};
+      that._contextObj = m.value;
+      try {
+        cb.call(that, m.value);
+      } finally {
+        // Restore previous parameter context
+        that._params = prevParams;
+        that._contextObj = prevContext;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Groups items and executes callback for each group.
+   * Equivalent to XSLT's xsl:for-each-group.
+   * @param {string} select - JSONPath selector for items to group
+   * @param {object} options - Grouping options
+   * @param {string} [options.groupBy] - JSONPath expression to group by value
+   * @param {string} [options.groupAdjacent] - Groups adjacent items with
+   *   same value
+   * @param {string} [options.groupStartingWith] - Starts new group when
+   *   expression matches
+   * @param {string} [options.groupEndingWith] - Ends group when expression
+   *   matches
+   * @param {any} [options.sort] - Sort specification (same as forEach)
+   * @param {(
+   *   this: JSONPathTransformerContext<T>, key: any, items: any[], ctx: any
+   * ) => void} cb - Callback receives (groupingKey, groupItems, context)
+   * @returns {this}
+   */
+  forEachGroup (select, options, cb) {
+    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
+    const that = this;
+    const {groupBy, groupAdjacent, groupStartingWith, groupEndingWith, sort} =
+      options;
+
+    /** @type {{value: any}[]} */
+    const matches = /** @type {any} */ (jsonpath)({
+      path: select,
+      json: this._contextObj,
+      preventEval: this._config.preventEval,
+      wrap: true,
+      resultType: 'all'
+    });
+
+    /**
+     * @param {string} expr
+     * @param {any} ctxVal
+     * @returns {any}
+     */
+    function evalInContext (expr, ctxVal) {
+      if (expr === '.' || expr === '@') {
+        return ctxVal;
+      }
+      return /** @type {any} */ (jsonpath)({
+        path: expr,
+        json: ctxVal,
+        preventEval: that._config.preventEval,
+        wrap: false,
+        returnType: 'value'
+      });
+    }
+
+    // Apply sorting if specified
+    if (sort) {
+      const comparator = this._buildComparator(sort, evalInContext);
+      if (comparator) {
+        matches.sort(
+          /** @type {(a: {value: any}, b: {value: any}) => number} */ (
+            comparator
+          )
+        );
+      }
+    }
+
+    /** @type {Map<any, any[]>} */
+    const groups = new Map();
+
+    if (groupBy) {
+      // Group by computed value
+      for (const m of matches) {
+        const key = evalInContext(groupBy, m.value);
+        // Handle undefined by converting to null for JSON serialization
+        const keyStr = JSON.stringify(key === undefined ? null : key);
+        if (!groups.has(keyStr)) {
+          groups.set(keyStr, []);
+        }
+        /** @type {any[]} */ (groups.get(keyStr)).push(m.value);
+      }
+
+      for (const [keyStr, items] of groups) {
+        const key = JSON.parse(keyStr);
+        // Convert null back to undefined if that was the original value
+        const actualKey = key === null && keyStr === 'null' ? undefined : key;
+        const prevContext = this._contextObj;
+        const prevParams = this._params;
+        try {
+          this._contextObj = items;
+          // Provide currentGroup() and currentGroupingKey() via context
+          /** @type {any} */ (this)._currentGroup = items;
+          /** @type {any} */ (this)._currentGroupingKey = actualKey;
+          cb.call(this, actualKey, items, this);
+        } finally {
+          this._contextObj = prevContext;
+          this._params = prevParams;
+          delete /** @type {any} */ (this)._currentGroup;
+          delete /** @type {any} */ (this)._currentGroupingKey;
+        }
+      }
+    } else if (groupAdjacent) {
+      // Group adjacent items with same value
+      /** @type {string|null} */
+      let currentKey = null;
+      let currentGroup = [];
+
+      for (const m of matches) {
+        const key = evalInContext(groupAdjacent, m.value);
+        const keyStr = JSON.stringify(key);
+
+        if (currentKey === null || currentKey !== keyStr) {
+          if (currentGroup.length > 0) {
+            const prevContext = this._contextObj;
+            const prevParams = this._params;
+            try {
+              this._contextObj = currentGroup;
+              /** @type {any} */ (this)._currentGroup = currentGroup;
+              /** @type {any} */ (this)._currentGroupingKey =
+                JSON.parse(/** @type {string} */ (currentKey));
+              cb.call(
+                this,
+                JSON.parse(/** @type {string} */ (currentKey)),
+                currentGroup,
+                this
+              );
+            } finally {
+              this._contextObj = prevContext;
+              this._params = prevParams;
+              delete /** @type {any} */ (this)._currentGroup;
+              delete /** @type {any} */ (this)._currentGroupingKey;
+            }
+          }
+          currentKey = keyStr;
+          currentGroup = [m.value];
+        } else {
+          currentGroup.push(m.value);
+        }
+      }
+
+      // Process last group
+      if (currentGroup.length > 0) {
+        const prevContext = this._contextObj;
+        const prevParams = this._params;
+        try {
+          this._contextObj = currentGroup;
+          /** @type {any} */ (this)._currentGroup = currentGroup;
+          /** @type {any} */ (this)._currentGroupingKey =
+            JSON.parse(/** @type {string} */ (currentKey));
+          cb.call(
+            this,
+            JSON.parse(/** @type {string} */ (currentKey)),
+            currentGroup,
+            this
+          );
+        } finally {
+          this._contextObj = prevContext;
+          this._params = prevParams;
+          delete /** @type {any} */ (this)._currentGroup;
+          delete /** @type {any} */ (this)._currentGroupingKey;
+        }
+      }
+    } else if (groupStartingWith) {
+      // Start new group when expression matches
+      let currentGroup = [];
+
+      for (const m of matches) {
+        const startMatch = evalInContext(groupStartingWith, m.value);
+
+        if (startMatch && currentGroup.length > 0) {
+          const prevContext = this._contextObj;
+          const prevParams = this._params;
+          try {
+            this._contextObj = currentGroup;
+            /** @type {any} */ (this)._currentGroup = currentGroup;
+            cb.call(this, null, currentGroup, this);
+          } finally {
+            this._contextObj = prevContext;
+            this._params = prevParams;
+            delete /** @type {any} */ (this)._currentGroup;
+          }
+          currentGroup = [];
+        }
+        currentGroup.push(m.value);
+      }
+
+      // Process last group
+      if (currentGroup.length > 0) {
+        const prevContext = this._contextObj;
+        const prevParams = this._params;
+        try {
+          this._contextObj = currentGroup;
+          /** @type {any} */ (this)._currentGroup = currentGroup;
+          cb.call(this, null, currentGroup, this);
+        } finally {
+          this._contextObj = prevContext;
+          this._params = prevParams;
+          delete /** @type {any} */ (this)._currentGroup;
+        }
+      }
+    } else if (groupEndingWith) {
+      // End group when expression matches
+      let currentGroup = [];
+
+      for (const m of matches) {
+        currentGroup.push(m.value);
+        const endMatch = evalInContext(groupEndingWith, m.value);
+
+        if (endMatch) {
+          const prevContext = this._contextObj;
+          const prevParams = this._params;
+          try {
+            this._contextObj = currentGroup;
+            /** @type {any} */ (this)._currentGroup = currentGroup;
+            cb.call(this, null, currentGroup, this);
+          } finally {
+            this._contextObj = prevContext;
+            this._params = prevParams;
+            delete /** @type {any} */ (this)._currentGroup;
+          }
+          currentGroup = [];
+        }
+      }
+
+      // Process last group if not ended
+      if (currentGroup.length > 0) {
+        const prevContext = this._contextObj;
+        const prevParams = this._params;
+        try {
+          this._contextObj = currentGroup;
+          /** @type {any} */ (this)._currentGroup = currentGroup;
+          cb.call(this, null, currentGroup, this);
+        } finally {
+          this._contextObj = prevContext;
+          this._params = prevParams;
+          delete /** @type {any} */ (this)._currentGroup;
+        }
+      }
     }
+
     return this;
   }
 
+  /**
+   * Helper to build comparator for sorting.
+   * @param {any} sortSpec
+   * @param {(expr: string, ctxVal: any) => any} evalFn
+   * @returns {((a: {value: any}, b: {value: any}) => number)|null}
+   * @private
+   */
+  _buildComparator (sortSpec, evalFn) {
+    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
+    const that = this;
+
+    if (typeof sortSpec === 'function') {
+      return function (
+        /** @type {{value: any}} */ a,
+        /** @type {{value: any}} */ b
+      ) {
+        return sortSpec(a.value, b.value, that);
+      };
+    }
+
+    /**
+     * @param {any} aVal
+     * @param {any} bVal
+     * @param {{
+     *   order?: 'ascending'|'descending', type?: 'text'|'number',
+     *   locale?: string, localeOptions?: any
+     * }|undefined} spec
+     * @returns {number}
+     */
+    function compareBySpec (aVal, bVal, spec) {
+      /* c8 ignore next 2 -- all spec combinations tested; && and || branches */
+      const order = (spec && spec.order === 'descending') ? -1 : 1;
+      const type = (spec && spec.type) || 'text';
+      if (type === 'number') {
+        const an = Number(aVal);
+        const bn = Number(bVal);
+        /* c8 ignore next -- both NaN tested; short-circuit branch tracking */
+        if (Number.isNaN(an) && Number.isNaN(bn)) {
+          return 0;
+        }
+        if (Number.isNaN(an)) {
+          return Number(order);
+        }
+        if (Number.isNaN(bn)) {
+          return -1 * order;
+        }
+        return (an - bn) * order;
+      }
+      /* c8 ignore next 2 -- all null/undefined tested; OR short-circuit */
+      const aStr = aVal === null || aVal === undefined ? '' : String(aVal);
+      const bStr = bVal === null || bVal === undefined ? '' : String(bVal);
+      if (spec && spec.locale) {
+        return aStr.localeCompare(
+          bStr, spec.locale, spec.localeOptions
+        ) * order;
+      }
+      /* c8 ignore next 2 -- all comparison outcomes tested; ternary
+       * branch tracking */
+      return (aStr < bStr ? -1 : (aStr > bStr ? 1 : 0)) * order;
+    }
+
+    const specs = Array.isArray(sortSpec) ? sortSpec : [sortSpec];
+    return function (
+      /** @type {{value: any}} */ a,
+      /** @type {{value: any}} */ b
+    ) {
+      for (const s of specs) {
+        if (typeof s === 'string') {
+          const av = evalFn(s, a.value);
+          const bv = evalFn(s, b.value);
+          const c = compareBySpec(av, bv, {type: 'text', order: 'ascending'});
+          if (c !== 0) {
+            return c;
+          }
+        } else if (s && typeof s === 'object') {
+          const av = evalFn(s.select, a.value);
+          const bv = evalFn(s.select, b.value);
+          const c = compareBySpec(av, bv, s);
+          if (c !== 0) {
+            return c;
+          }
+        }
+      }
+      return 0;
+    };
+  }
+
+  /**
+   * Returns the current group (for use within forEachGroup callback).
+   * @returns {any[]|undefined}
+   */
+  currentGroup () {
+    return /** @type {any} */ (this)._currentGroup;
+  }
+
+  /**
+   * Returns the current grouping key (for use within forEachGroup callback).
+   * @returns {any}
+   */
+  currentGroupingKey () {
+    return /** @type {any} */ (this)._currentGroupingKey;
+  }
+
   /**
    * @param {string|object} [select] - JSONPath selector
    * @returns {this}
@@ -629,6 +1017,48 @@ class JSONPathTransformerContext {
         ? /** @type {{select?: string}} */ (select).select
         : select;
 
+      // Check for format-number() function call
+      if (selectStr && selectStr.includes('format-number(')) {
+        const match = (/format-number\((?<value>[^,\)]+)(?:,\s*["'](?<format>[^"']+)["'])?(?:,\s*["'](?<decimalFormat>[^"']*)["'])?\)/v).exec(selectStr);
+        if (match && match.groups) {
+          const {
+            value: valueExpr,
+            format: formatStr,
+            decimalFormat: decimalFormatName
+          } = match.groups;
+          // Evaluate the value expression
+          let numValue;
+          if (valueExpr.trim().startsWith('$') &&
+              !valueExpr.includes('.') && !valueExpr.includes('[')) {
+            // Parameter reference (no path components)
+            const paramName = valueExpr.trim().slice(1);
+            numValue = this._params && paramName in this._params
+              ? this._params[paramName]
+              : 0;
+          } else {
+            // Try to parse as number or evaluate as JSONPath
+            const trimmed = valueExpr.trim();
+            numValue = Number.isNaN(Number(trimmed))
+              ? this.get(trimmed, false)
+              : Number(trimmed);
+          }
+          const num = typeof numValue === 'string'
+            ? Number(numValue)
+            : numValue;
+          const format = formatStr || '1';
+          const formatted = this._formatNumber(
+            num,
+            format,
+            undefined,
+            undefined,
+            decimalFormatName || '',
+            'en'
+          );
+          /** @type {any} */ (results).append(formatted);
+          return this;
+        }
+      }
+
       // Check if this is a parameter reference (starts with $)
       if (selectStr && selectStr.startsWith('$')) {
         const paramName = selectStr.slice(1);
@@ -987,7 +1417,8 @@ class JSONPathTransformerContext {
         format,
         opts.groupingSeparator,
         opts.groupingSize,
-        locale
+        locale,
+        opts.decimalFormat
       );
 
       // Output as string if formatted, otherwise as number
@@ -1050,14 +1481,31 @@ class JSONPathTransformerContext {
    * @param {string} format - Format string (1, a, A, i, I, 01, etc.)
    * @param {string} [groupingSeparator] - Separator for grouping
    * @param {number} [groupingSize] - Size of groups
-   * @param {string} [locale]
+   * @param {string} [decimalFormatName] - Name of decimal format to use
+   * @param {string} [locale] - Locale for formatting
    * @returns {string}
    */
-  _formatNumber (num, format, groupingSeparator, groupingSize, locale = 'en') {
+  _formatNumber (
+    num,
+    format,
+    groupingSeparator,
+    groupingSize,
+    decimalFormatName,
+    locale = 'en'
+  ) {
     if (Number.isNaN(num)) {
-      return String(num);
+      // Check for custom NaN string in decimal format
+      const fmt = decimalFormatName
+        ? this.decimalFormats[decimalFormatName]
+        : this.decimalFormats[''];
+      return fmt?.NaN || String(num);
     }
 
+    // Get decimal format if specified
+    const decimalFormat = decimalFormatName
+      ? this.decimalFormats[decimalFormatName]
+      : this.decimalFormats[''];
+
     let result;
     const formatChar = format.charAt(0);
 
@@ -1084,7 +1532,8 @@ class JSONPathTransformerContext {
     }
     case '0': {
       const width = format.length;
-      result = String(num).padStart(width, '0');
+      const zeroDigit = decimalFormat?.zeroDigit || '0';
+      result = String(num).padStart(width, zeroDigit);
 
       break;
     }
@@ -1100,7 +1549,25 @@ class JSONPathTransformerContext {
 
       try {
         result = new Intl.NumberFormat(locale, options).format(num);
-        if (groupingSeparator) {
+
+        // Apply decimal format symbols if specified
+        if (decimalFormat) {
+          // Use placeholders to avoid conflicts during replacement
+          const TEMP_GROUP = '\u0000GROUPSEP\u0000';
+          const TEMP_DECIMAL = '\u0000DECIMALSEP\u0000';
+
+          // Replace with temporary placeholders first
+          result = result.replaceAll(',', TEMP_GROUP);
+          result = result.replaceAll('.', TEMP_DECIMAL);
+
+          // Now replace with actual symbols
+          const effectiveGroupingSep = groupingSeparator ||
+            decimalFormat.groupingSeparator || ',';
+          const effectiveDecimalSep = decimalFormat.decimalSeparator || '.';
+
+          result = result.replaceAll(TEMP_GROUP, effectiveGroupingSep);
+          result = result.replaceAll(TEMP_DECIMAL, effectiveDecimalSep);
+        } else if (groupingSeparator) {
           result = result.replaceAll(',', groupingSeparator);
         }
       } catch (e) {
@@ -1187,6 +1654,16 @@ class JSONPathTransformerContext {
     return this;
   }
 
+  /**
+   * Alias for propValue(). Set a key-value pair in the current map/object.
+   * @param {string} prop - Property name
+   * @param {any} val - Property value
+   * @returns {this}
+   */
+  mapEntry (prop, val) {
+    return this.propValue(prop, val);
+  }
+
   /**
    * Build an object. Mirrors the joining transformer API. All joiners now
    * support both signatures: (obj, cb, usePropertySets, propSets) with seed
@@ -1199,6 +1676,15 @@ class JSONPathTransformerContext {
     return this;
   }
 
+  /**
+   * Alias for object(). Build an object/map.
+   * @param {...any} args - Arguments to pass to joiner
+   * @returns {this}
+   */
+  map (...args) {
+    return this.object(...args);
+  }
+
   /**
    * Build an array. Mirrors the joining transformer API. All joiners now
    * support both signatures: (arr, cb) with seed array or (cb) without.
@@ -1220,6 +1706,27 @@ class JSONPathTransformerContext {
     return this;
   }
 
+  /**
+   * @param {string} name
+   * @param {import('./AbstractJoiningTransformer.js').
+   *   OutputCharacters} outputCharacters
+   * @returns {this}
+   */
+  characterMap (name, outputCharacters) {
+    this._getJoiningTransformer().characterMap(name, outputCharacters);
+    return this;
+  }
+
+  /**
+   * @param {string} name
+   * @param {Record<string, string>} attributes
+   * @returns {this}
+   */
+  attributeSet (name, attributes) {
+    this._getJoiningTransformer().attributeSet(name, attributes);
+    return this;
+  }
+
   /**
    * Create an element. Mirrors the joining transformer API so templates can
    * call `this.element()`.
@@ -1228,15 +1735,51 @@ class JSONPathTransformerContext {
    * @param {any[]} [children] - Child nodes
    * @param {import('./JSONJoiningTransformer.js').
    *   SimpleCallback<T>} [cb] - Callback function
+   * @param {string[]} [useAttributeSets] - Attribute set names to apply
    * @returns {this}
    */
-  element (name, atts, children, cb) {
+  element (name, atts, children, cb, useAttributeSets) {
     /** @type {any} */ (this._getJoiningTransformer()).element(
-      name, atts, children, cb
+      name, atts, children, cb, useAttributeSets
+    );
+    return this;
+  }
+
+  /**
+   * Adds a prefixed namespace declaration to the most recently opened
+   *  element. Mirrors the joining
+   * transformer API so templates can call `this.attribute()`.
+   * @param {string} prefix - Prefix
+   * @param {string} namespaceURI - Namespace
+   * @returns {this}
+   */
+  namespace (prefix, namespaceURI) {
+    /** @type {any} */ (this._getJoiningTransformer()).namespace(
+      prefix, namespaceURI
     );
     return this;
   }
 
+  /**
+   * Define a decimal format with custom symbols for number formatting.
+   * Equivalent to xsl:decimal-format. If no name is provided, defines
+   * the default format.
+   * @param {string|DecimalFormatSymbols} nameOrSymbols - Format name or
+   *   symbols object if defining default
+   * @param {DecimalFormatSymbols} [symbols] - Format symbols
+   * @returns {this}
+   */
+  decimalFormat (nameOrSymbols, symbols) {
+    if (typeof nameOrSymbols === 'string') {
+      // Named format
+      this.decimalFormats[nameOrSymbols] = symbols || {};
+    } else {
+      // Default format (unnamed)
+      this.decimalFormats[''] = nameOrSymbols;
+    }
+    return this;
+  }
+
   /**
    * Add an attribute to the most recently opened element. Mirrors the joining
    * transformer API so templates can call `this.attribute()`.
@@ -1424,6 +1967,26 @@ class JSONPathTransformerContext {
     }
     return this;
   }
+
+  /**
+   * Assert that a test condition is true, throwing an error if it fails.
+   * Equivalent to xsl:assert. Evaluates a JSONPath expression using the
+   * same truthiness rules as if() and choose().
+   * @param {string} test - JSONPath expression to test
+   * @param {string} [message] - Optional error message to include
+   * @returns {this}
+   * @throws {Error} When the test expression evaluates to false
+   */
+  assert (test, message) {
+    const passes = this._passesIf(test);
+    if (!passes) {
+      const errorMsg = message
+        ? `Assertion failed: ${message}`
+        : `Assertion failed: ${test}`;
+      throw new Error(errorMsg);
+    }
+    return this;
+  }
 }
 
 export default JSONPathTransformerContext;