jtlt 0.4.0 → 0.5.0

package/src/StringJoiningTransformer.js

@@ -13,7 +13,8 @@ import AbstractJoiningTransformer from './AbstractJoiningTransformer.js';
  *   mediaType?: string,
  *   version?: string,
  *   standalone?: boolean,
- *   method?: "xml"|"html"|"text"|"json"|"xhtml"
+ *   method?: "xml"|"html"|"text"|"json"|"xhtml",
+ *   useCharacterMaps?: string[]
  * }} OutputConfig
  */
 
@@ -434,20 +435,6 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
-  /**
-   * @param {OutputConfig} cfg
-   * @returns {StringJoiningTransformer}
-   */
-  output (cfg) {
-    // We wait until first element is set in `element()` to add
-    //   XML declaration and DOCTYPE as latter depends on root element
-    this._outputConfig = cfg;
-
-    // Use for file extension if making downloadable?
-    this.mediaType = cfg.mediaType;
-    return this;
-  }
-
   /**
    * @param {string|Element} elName - Element name or element object
    * @param {ElementAttributes} [atts] - Element attributes
@@ -570,7 +557,9 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     }
     if (childNodes && childNodes.length) {
       this._openTagState = false;
-      this.append(jml[method]({'#': childNodes}));
+      this.append(this._replaceCharacterMaps(
+        jml[method]({'#': childNodes})
+      ));
     }
     cb.call(this);
 
@@ -585,6 +574,17 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     return this;
   }
 
+  /**
+   * @param {string} prefix
+   * @param {string} namespaceURI
+   * @returns {StringJoiningTransformer}
+   */
+  namespace (prefix, namespaceURI) {
+    this.append(' xmlns:' + prefix + '="' +
+        this._replaceCharacterMaps(namespaceURI) + '"');
+    return this;
+  }
+
   /**
    * @param {string} name - Attribute name
    * @param {string|Record<string, unknown>|
@@ -648,7 +648,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     val = (this._cfg.preEscapedAttributes || avoidAttEscape)
       ? valStr
       : valStr.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
-    this.append(' ' + name + '="' + val + '"');
+    this.append(' ' + name + '="' + this._replaceCharacterMaps(val) + '"');
     return this;
   }
 
@@ -663,7 +663,11 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
       this.append('>');
       this._openTagState = false;
     }
-    this.append(txt.replaceAll('&', '&amp;').replaceAll('<', '&lt;'));
+    this.append(
+      this._replaceCharacterMaps(
+        txt
+      ).replaceAll('&', '&amp;').replaceAll('<', '&lt;')
+    );
     return this;
   }
 
@@ -734,7 +738,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
     // Save current state
     /** @type {any} */
     const oldRoot = this.root;
-    /** @type {any} */
+    /** @type {OutputConfig|undefined} */
     const oldOutputConfig = this._outputConfig;
     const oldStr = this._str;
     /** @type {any} */
@@ -742,7 +746,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
     // Reset state for new document
     this.root = undefined;
-    /** @type {any} */
+    /** @type {OutputConfig} */
     this._outputConfig = cfg;
     this._str = '';
     this._openTagState = false;
@@ -795,7 +799,7 @@ class StringJoiningTransformer extends AbstractJoiningTransformer {
 
     // Reset state for new document
     this.root = undefined;
-    /** @type {any} */
+    /** @type {OutputConfig} */
     this._outputConfig = cfg;
     this._str = '';
     this._openTagState = false;

package/src/XPathTransformer.js

@@ -83,6 +83,8 @@ class XPathTransformer {
     if (len > 1) {
       this._triggerEqualPriorityError();
     }
+    // Set up parameter context for valueOf() access in root template
+    xte._params = {0: xte._contextNode};
     const ret = templateObj.template.call(xte, undefined, {mode});
     if (typeof ret !== 'undefined') {
       /** @type {any} */ (xte)._getJoiningTransformer().append(ret);

package/src/XPathTransformerContext.js

@@ -48,6 +48,11 @@ class XPathTransformerContext {
     this.propertySets = {};
     /** @type {Record<string, {match: string, use: string}>} */
     this.keys = {};
+    /**
+     * @type {Record<string,
+     *   import('./JSONPathTransformerContext.js').DecimalFormatSymbols>}
+     */
+    this.decimalFormats = {};
     /** @type {boolean|undefined} */
     this._initialized = undefined;
     /** @type {string|undefined} */
@@ -293,7 +298,16 @@ class XPathTransformerContext {
           );
       }
       this._contextNode = node;
+
+      // Set up parameter context for valueOf() access in templates
+      const prevTemplateParams = this._params;
+      this._params = {0: node};
+
       const ret = templateObj.template.call(this, node, {mode});
+
+      // Restore previous parameter context
+      this._params = prevTemplateParams;
+
       if (typeof ret !== 'undefined') {
         this._getJoiningTransformer().append(ret);
       }
@@ -371,11 +385,269 @@ class XPathTransformerContext {
     const nodesResult = this._evalXPath(select, true);
     const nodes = /** @type {Node[]} */ (nodesResult);
     for (const n of nodes) {
-      cb.call(this, n);
+      // Set up parameter context for valueOf() access
+      const prevParams = this._params;
+      const prevContext = this._contextNode;
+      this._params = {0: n};
+      this._contextNode = n;
+      try {
+        cb.call(this, n);
+      } finally {
+        // Restore previous parameter context
+        this._params = prevParams;
+        this._contextNode = prevContext;
+      }
     }
     return this;
   }
 
+  /**
+   * Groups items and executes callback for each group.
+   * Equivalent to XSLT's xsl:for-each-group.
+   * @param {string} select - XPath selector for items to group
+   * @param {object} options - Grouping options
+   * @param {string} [options.groupBy] - XPath 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 {(
+   *   this: XPathTransformerContext, key: any, items: Node[], 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} =
+      options;
+
+    const nodesResult = this._evalXPath(select, true);
+    const nodes = /** @type {Node[]} */ (nodesResult);
+
+    /**
+     * @param {string} expr
+     * @param {Node} node
+     * @returns {any}
+     */
+    function evalInContext (expr, node) {
+      if (expr === '.' || expr === '@') {
+        return node.textContent;
+      }
+      // Temporarily set context to evaluate expression
+      const prevNode = that._contextNode;
+      that._contextNode = node;
+      try {
+        const result = that._evalXPath(expr, false);
+        // XPath v2/v3 always return arrays; handle NodeList/Array results
+        // by taking first item or its text content
+        const resultWithLength = /** @type {{length: number}} */ (result);
+        if (resultWithLength.length > 0) {
+          const firstItem = /** @type {any} */ (result)[0];
+          return firstItem?.textContent ?? firstItem;
+        }
+        return undefined;
+      } finally {
+        that._contextNode = prevNode;
+      }
+    }
+
+    /** @type {Map<string, Node[]>} */
+    const groups = new Map();
+
+    if (groupBy) {
+      // Group by computed value
+      for (const node of nodes) {
+        const key = evalInContext(groupBy, node);
+        // 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 {Node[]} */ (groups.get(keyStr)).push(node);
+      }
+
+      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 prevParams = this._params;
+        const prevContext = this._contextNode;
+        try {
+          this._contextNode = items[0];
+          /** @type {any} */ (this)._currentGroup = items;
+          /** @type {any} */ (this)._currentGroupingKey = actualKey;
+          cb.call(this, actualKey, items, this);
+        } finally {
+          this._params = prevParams;
+          this._contextNode = prevContext;
+          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;
+      /** @type {Node[]} */
+      let currentGroup = [];
+
+      for (const node of nodes) {
+        const key = evalInContext(groupAdjacent, node);
+        const keyStr = JSON.stringify(key);
+
+        if (currentKey === null || currentKey !== keyStr) {
+          if (currentGroup.length > 0) {
+            const prevParams = this._params;
+            const prevContext = this._contextNode;
+            try {
+              this._contextNode = currentGroup[0];
+              /** @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._params = prevParams;
+              this._contextNode = prevContext;
+              delete /** @type {any} */ (this)._currentGroup;
+              delete /** @type {any} */ (this)._currentGroupingKey;
+            }
+          }
+          currentKey = keyStr;
+          currentGroup = [node];
+        } else {
+          currentGroup.push(node);
+        }
+      }
+
+      // Process last group
+      if (currentGroup.length > 0) {
+        const prevParams = this._params;
+        const prevContext = this._contextNode;
+        try {
+          this._contextNode = currentGroup[0];
+          /** @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._params = prevParams;
+          this._contextNode = prevContext;
+          delete /** @type {any} */ (this)._currentGroup;
+          delete /** @type {any} */ (this)._currentGroupingKey;
+        }
+      }
+    } else if (groupStartingWith) {
+      // Start new group when expression matches
+      /** @type {Node[]} */
+      let currentGroup = [];
+
+      for (const node of nodes) {
+        const startMatch = evalInContext(groupStartingWith, node);
+
+        if (startMatch && currentGroup.length > 0) {
+          const prevParams = this._params;
+          const prevContext = this._contextNode;
+          try {
+            this._contextNode = currentGroup[0];
+            /** @type {any} */ (this)._currentGroup = currentGroup;
+            cb.call(this, null, currentGroup, this);
+          } finally {
+            this._params = prevParams;
+            this._contextNode = prevContext;
+            delete /** @type {any} */ (this)._currentGroup;
+          }
+          currentGroup = [];
+        }
+        currentGroup.push(node);
+      }
+
+      // Process last group
+      if (currentGroup.length > 0) {
+        const prevParams = this._params;
+        const prevContext = this._contextNode;
+        try {
+          this._contextNode = currentGroup[0];
+          /** @type {any} */ (this)._currentGroup = currentGroup;
+          cb.call(this, null, currentGroup, this);
+        } finally {
+          this._params = prevParams;
+          this._contextNode = prevContext;
+          delete /** @type {any} */ (this)._currentGroup;
+        }
+      }
+    } else if (groupEndingWith) {
+      // End group when expression matches
+      /** @type {Node[]} */
+      let currentGroup = [];
+
+      for (const node of nodes) {
+        currentGroup.push(node);
+        const endMatch = evalInContext(groupEndingWith, node);
+
+        if (endMatch) {
+          const prevParams = this._params;
+          const prevContext = this._contextNode;
+          try {
+            this._contextNode = currentGroup[0];
+            /** @type {any} */ (this)._currentGroup = currentGroup;
+            cb.call(this, null, currentGroup, this);
+          } finally {
+            this._params = prevParams;
+            this._contextNode = prevContext;
+            delete /** @type {any} */ (this)._currentGroup;
+          }
+          currentGroup = [];
+        }
+      }
+
+      // Process last group if not ended
+      if (currentGroup.length > 0) {
+        const prevParams = this._params;
+        const prevContext = this._contextNode;
+        try {
+          this._contextNode = currentGroup[0];
+          /** @type {any} */ (this)._currentGroup = currentGroup;
+          cb.call(this, null, currentGroup, this);
+        } finally {
+          this._params = prevParams;
+          this._contextNode = prevContext;
+          delete /** @type {any} */ (this)._currentGroup;
+        }
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Returns the current group (for use within forEachGroup callback).
+   * @returns {Node[]|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;
+  }
+
   /**
    * Append the value from an XPath expression or the context node text.
    * @param {string|object} [select]
@@ -389,11 +661,66 @@ class XPathTransformerContext {
       ? /** @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('$')) {
+          // Parameter reference
+          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 XPath
+          const trimmed = valueExpr.trim();
+          numValue = Number.isNaN(Number(trimmed))
+            ? this._evalXPath(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'
+        );
+        jt.append(formatted);
+        return this;
+      }
+    }
+
     // Check if this is a parameter reference (starts with $)
     if (selectStr && selectStr.startsWith('$')) {
       const paramName = selectStr.slice(1);
       if (this._params && paramName in this._params) {
         val = this._params[paramName];
+        // If val is a Node, extract its text content
+        if (val && typeof val === 'object' && 'nodeType' in val) {
+          if (val.nodeType === 3) {
+            // Text node: use nodeValue
+            val = val.nodeValue;
+          } else if (val.nodeType === 9) {
+            // Document node: use documentElement.textContent
+            const doc = /** @type {Document} */ (val);
+            val = doc.documentElement
+              ? doc.documentElement.textContent
+              : null;
+          } else {
+            // Other nodes: use textContent
+            val = val.textContent;
+          }
+        }
       } else {
         // Fall back to normal XPath evaluation
         const resResult = this._evalXPath(selectStr, true);
@@ -406,9 +733,19 @@ class XPathTransformerContext {
         /* c8 ignore stop */
       }
     } else if (!selectStr || selectStr === '.') {
-      val = this._contextNode.nodeType === 3
-        ? this._contextNode.nodeValue
-        : this._contextNode.textContent;
+      if (this._contextNode.nodeType === 3) {
+        // Text node: use nodeValue
+        val = this._contextNode.nodeValue;
+      } else if (this._contextNode.nodeType === 9) {
+        // Document node: use documentElement.textContent
+        const doc = /** @type {Document} */ (this._contextNode);
+        val = doc.documentElement
+          ? doc.documentElement.textContent
+          : null;
+      } else {
+        // Other nodes: use textContent
+        val = this._contextNode.textContent;
+      }
     } else {
       const resResult = this._evalXPath(selectStr, true);
       const res = /** @type {Node[]} */ (resResult);
@@ -549,6 +886,7 @@ class XPathTransformerContext {
    *   level?: 'single'|'multiple'|'any',
    *   from?: string,
    *   format?: string,
+   *   decimalFormat?: string,
    *   groupingSeparator?: string,
    *   groupingSize?: number
    * }} num - Number value, "position()" string, or options object
@@ -733,15 +1071,27 @@ class XPathTransformerContext {
    * @param {string} format - Format string (1, a, A, i, I, 01, etc.)
    * @param {string} [groupingSeparator] - Separator for grouping (e.g., ',')
    * @param {number} [groupingSize] - Size of groups (e.g., 3 for 1,000)
+   * @param {string} [decimalFormatName] - Named decimal format to use
    * @param {string} [locale]
    * @returns {string}
    * @private
    */
-  _formatNumber (num, format, groupingSeparator, groupingSize, locale = 'en') {
+  _formatNumber (
+    num, format, groupingSeparator, groupingSize, decimalFormatName, locale
+  ) {
     if (Number.isNaN(num)) {
       return String(num);
     }
 
+    // Get decimal format symbols if specified
+    const symbols = decimalFormatName !== undefined &&
+      decimalFormatName in this.decimalFormats
+      ? this.decimalFormats[decimalFormatName]
+      : undefined;
+
+    // Default locale
+    const loc = locale || 'en';
+
     let result;
     const formatChar = format.charAt(0);
 
@@ -768,7 +1118,8 @@ class XPathTransformerContext {
     }
     case '0': {
       const width = format.length;
-      result = String(num).padStart(width, '0');
+      const zeroDigit = symbols?.zeroDigit || '0';
+      result = String(num).padStart(width, zeroDigit);
 
       break;
     }
@@ -782,8 +1133,26 @@ class XPathTransformerContext {
         };
       }
       try {
-        result = new Intl.NumberFormat(locale, options).format(num);
-        if (groupingSeparator) {
+        result = new Intl.NumberFormat(loc, options).format(num);
+
+        // Apply decimal format symbols if specified
+        if (symbols) {
+          // 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 ||
+            symbols.groupingSeparator || ',';
+          const effectiveDecimalSep = symbols.decimalSeparator || '.';
+
+          result = result.replaceAll(TEMP_GROUP, effectiveGroupingSep);
+          result = result.replaceAll(TEMP_DECIMAL, effectiveDecimalSep);
+        } else if (groupingSeparator) {
           result = result.replaceAll(',', groupingSeparator);
         }
       } catch (e) {
@@ -910,6 +1279,17 @@ class XPathTransformerContext {
     return this;
   }
 
+  /**
+   * @param {string} name
+   * @param {import('./AbstractJoiningTransformer.js').
+   *   OutputCharacters} outputCharacters
+   * @returns {this}
+   */
+  characterMap (name, outputCharacters) {
+    this._getJoiningTransformer().characterMap(name, outputCharacters);
+    return this;
+  }
+
   /**
    * Append element.
    * @param {string} name Tag name
@@ -925,6 +1305,44 @@ class XPathTransformerContext {
     this._getJoiningTransformer().element(name, atts, children, cb);
     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|import('./JSONPathTransformerContext.js').
+   *   DecimalFormatSymbols} nameOrSymbols - Format name or symbols object
+   *   if defining default
+   * @param {import('./JSONPathTransformerContext.js').
+   *   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;
+  }
+
   /**
    * Append attribute.
    * @param {string} name Attribute name

package/src/index.js

@@ -380,7 +380,13 @@ class JTLT {
           );
         // eslint-disable-next-line @stylistic/max-len -- Long
         // eslint-disable-next-line unicorn/no-array-method-this-argument -- Not array
-        this.forEach(path, fn);
+        this.forEach(path, (arg) => {
+          const ret = fn.call(this, arg);
+          if (typeof ret !== 'undefined') {
+            // @ts-expect-error Ok?
+            this._getJoiningTransformer().append(ret);
+          }
+        });
       }
       : cfg.query || (
         typeof cfg.templates === 'function'