jtlt 0.2.0 → 0.4.0

package/src/XPathTransformerContext.js

@@ -1,51 +1,62 @@
 import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
-// xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js
+// eslint-disable-next-line @stylistic/max-len -- Long
+// xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js, 3 => fontoxpath
+import fontoxpath from 'fontoxpath';
+
+/**
+ * @typedef {object} XPathTransformerContextConfig
+ * @property {unknown} [data] - XML/DOM root to transform
+ * @property {number} [xpathVersion] - 1, 2, 3.1 (default 1)
+ * @property {import('./index.js').
+ *   JoiningTransformer} joiningTransformer Joiner
+ * @property {boolean} [errorOnEqualPriority]
+ * @property {(path: string) => number} [specificityPriorityResolver]
+ */
 
 /**
  * Execution context for XPath-driven template application.
  *
  * Similar to JSONPathTransformerContext but uses XPath expressions on a
- * DOM/XML-like tree. Supports XPath 1.0 (default) or 2.0 when
- * `xpathVersion: 2`.
+ * DOM/XML-like tree. Supports XPath 1.0 (default), 2.0 when
+ * `xpathVersion: 2`, or 3.1 when `xpathVersion: 3.1`.
  *
  * Expected config:
  * - data: A Document, Element, or XML-like root node.
  * - joiningTransformer: joiner with append(), string(), object(), array(), etc.
- * - xpathVersion: 1|2 (default 1)
+ * - xpathVersion: 1|2|3.1 (default 1)
  * - errorOnEqualPriority, specificityPriorityResolver (same semantics).
  */
 class XPathTransformerContext {
   /**
-   * @param {object} config - Configuration object
-   * @param {Document|Element|any} config.data - XML/DOM root to transform
-   * @param {number} [config.xpathVersion] - 1 or 2 (default 1)
-  * @param {object} config.joiningTransformer Joiner
-  * @param {Function} config.joiningTransformer.append Append output
-  * @param {Function} config.joiningTransformer.get Get output
-  * @param {Function} config.joiningTransformer.string Emit string
-  * @param {Function} config.joiningTransformer.object Emit object
-  * @param {Function} config.joiningTransformer.array Emit array
-   * @param {boolean} [config.errorOnEqualPriority]
-   * @param {Function} [config.specificityPriorityResolver]
-   * @param {any[]} templates - Template objects
+   * @param {XPathTransformerContextConfig} config
+   * @param {import('./index.js').
+   *   XPathTemplateObject<any>[]} templates - Template objects
    */
   constructor (config, templates) {
     this._config = config;
     this._templates = templates;
-    this._contextNode = this._origNode = config.data;
-    /** @type {Record<string, any>} */
+    if (!config.data) {
+      throw new Error('XPathTransformerContext requires config.data');
+    }
+    /** @type {Document|Element|Node} */
+    this._contextNode = this._origNode = /** @type {Document|Element|Node} */ (
+      config.data
+    );
+    /** @type {Record<string, unknown>} */
     this.vars = {};
-    /** @type {Record<string, any>} */
+    /** @type {Record<string, Record<string, unknown>>} */
     this.propertySets = {};
-    /** @type {Record<string, any>} */
+    /** @type {Record<string, {match: string, use: string}>} */
     this.keys = {};
     /** @type {boolean|undefined} */
     this._initialized = undefined;
     /** @type {string|undefined} */
     this._currPath = undefined; // XPath string of current context
+    /** @type {Record<string, any> | undefined} */
+    this._params = undefined;
   }
 
-  /** @returns {any} */
+  /** @returns {import('./index.js').JoiningTransformer} */
   _getJoiningTransformer () {
     return this._config.joiningTransformer;
   }
@@ -53,24 +64,26 @@ class XPathTransformerContext {
   /**
    * Evaluate an XPath expression against the current context node.
    * @param {string} expr - XPath expression
-  * @param {boolean} [asNodes] Return nodes (array) instead of scalar
-   * @returns {any}
+   * @param {boolean} [asNodes] Return nodes (array) instead of scalar
+   * @returns {unknown}
    */
   _evalXPath (expr, asNodes) {
     if (!expr) {
       return this._contextNode;
     }
-    const version = this._config.xpathVersion === 2 ? 2 : 1;
+    const version = this._config.xpathVersion ?? 1;
     if (version === 1) {
       // Use native XPath (browser-like); rely on DOM doc if available.
       const doc = this._contextNode && this._contextNode.ownerDocument
         ? this._contextNode.ownerDocument
         : (this._contextNode.nodeType === 9 ? this._contextNode : undefined);
-      if (!doc || typeof doc.evaluate !== 'function') {
+      if (!doc || doc.nodeType !== 9) {
         throw new Error(
           'Native XPath unavailable for xpathVersion=1'
         );
       }
+      /** @type {Document} */
+      const docTyped = /** @type {Document} */ (doc);
       // Evaluate relative to current node. Namespace support optional.
       const resolver = null; // Placeholder for future namespaceResolver config
       /* c8 ignore start -- environment-dependent XPathResult availability */
@@ -86,31 +99,33 @@ class XPathTransformerContext {
             : 0
         );
       /* c8 ignore stop */
-      const resultObj = doc.evaluate(
+      const resultObj = docTyped.evaluate(
         expr, this._contextNode, resolver, type, null
       );
       if (asNodes) {
+        /** @type {Node[]} */
         const arr = [];
         for (let i = 0; i < resultObj.snapshotLength; i++) {
-          arr.push(resultObj.snapshotItem(i));
+          const item = resultObj.snapshotItem(i);
+          if (item) {
+            arr.push(item);
+          }
         }
         return arr;
       }
       // Handle primitive types from XPathResult
-      const XR = globalThis.XPathResult || {};
-      /* c8 ignore start -- JSDOM's XPath implementation does not properly
-       * set resultType for STRING_TYPE, NUMBER_TYPE, or BOOLEAN_TYPE. These
-       * branches work in real browsers but cannot be tested in JSDOM. */
+      const XR = docTyped.defaultView?.XPathResult ||
+        globalThis.XPathResult || {};
       switch (resultObj.resultType) {
       case XR.STRING_TYPE: return resultObj.stringValue;
       case XR.NUMBER_TYPE: return resultObj.numberValue;
-      case XR.BOOLEAN_TYPE: return resultObj.booleanValue;
-        /* c8 ignore stop */
-        /* c8 ignore start -- iterator result branch env-dependent */
+      case XR.BOOLEAN_TYPE:
+        return resultObj.booleanValue;
       case XR.UNORDERED_NODE_ITERATOR_TYPE:
       case XR.ORDERED_NODE_ITERATOR_TYPE: {
         /* c8 ignore start -- jsdom yields snapshots; iterator traversal
          * validated logically but not triggered in this environment. */
+        /** @type {Node[]} */
         const nodes = [];
         let n = resultObj.iterateNext();
         while (n) {
@@ -118,8 +133,8 @@ class XPathTransformerContext {
           n = resultObj.iterateNext();
         }
         return nodes;
+        /* c8 ignore stop */
       }
-      /* c8 ignore stop */
       /* c8 ignore start -- Default fallback for unsupported XPathResult
        * types; environment-dependent and not hit under jsdom. */
       default:
@@ -128,8 +143,25 @@ class XPathTransformerContext {
       /* c8 ignore stop */
       }
     }
-    // Version 2: xpath2.js
-    const result = xpath2.evaluate(expr, this._contextNode);
+    if (version === 2) {
+      // Version 2: xpath2.js
+      const result = xpath2.evaluate(expr, this._contextNode);
+      if (asNodes) {
+        // eslint-disable-next-line @stylistic/max-len -- Long
+        /* c8 ignore next -- array wrap/identity branch counted in other tests */
+        return Array.isArray(result) ? result : [result];
+      }
+      /* c8 ignore next -- scalar return trivial; wrap behavior tested */
+      return result;
+    }
+
+    // eslint-disable-next-line @stylistic/max-len -- Long
+    // eslint-disable-next-line import/no-named-as-default-member -- Only as default
+    const result = fontoxpath.evaluateXPath(
+      expr, this._contextNode, undefined, undefined,
+      // Non-deprecated, predictable all results
+      14 // ReturnType.ALL_RESULTS
+    );
     if (asNodes) {
       /* c8 ignore next -- array wrap/identity branch counted in other tests */
       return Array.isArray(result) ? result : [result];
@@ -140,15 +172,18 @@ class XPathTransformerContext {
 
   /**
    * Append raw item to output.
-   * @param {*} item
+   * @param {unknown} item
    * @returns {XPathTransformerContext}
    */
   appendOutput (item) {
-    this._getJoiningTransformer().append(item);
+    // Cast item since we trust the caller provides valid append types
+    this._getJoiningTransformer().append(
+      /** @type {string | Node} */ (item)
+    );
     return this;
   }
 
-  /** @returns {*} */
+  /** @returns {unknown} */
   getOutput () {
     return this._getJoiningTransformer().get();
   }
@@ -157,16 +192,16 @@ class XPathTransformerContext {
    * Get value(s) by XPath relative to current context.
    * @param {string} select - XPath expression
    * @param {boolean} [asNodes]
-   * @returns {*}
+   * @returns {Node[]}
    */
   get (select, asNodes) {
-    return this._evalXPath(select, Boolean(asNodes));
+    return /** @type {Node[]} */ (this._evalXPath(select, Boolean(asNodes)));
   }
 
   /**
    * Set current context's parent property (for parity with JSONPath context).
    * Mostly placeholder for object-mirroring behavior.
-   * @param {*} v
+   * @param {Document|Element|Node} v
    * @returns {XPathTransformerContext}
    */
   set (v) {
@@ -176,7 +211,7 @@ class XPathTransformerContext {
 
   /**
    * Apply templates to nodes matched by an XPath expression.
-   * @param {string} select - XPath expression (default '.')
+   * @param {string} [select] - XPath expression (default '.')
    * @param {string} [mode]
    * @returns {XPathTransformerContext}
    */
@@ -189,17 +224,28 @@ class XPathTransformerContext {
     } else {
       select = select || '*';
     }
-    const nodes = this._evalXPath(select, true);
-    const modeMatched = this._templates.filter((t) => (
-      mode ? t.mode === mode : !t.mode
-    ));
+    const nodesResult = this._evalXPath(select, true);
+    const nodes = /** @type {Node[]} */ (nodesResult);
+    const modeMatched = this._templates.filter((t) => {
+      // Exclude named-only templates (those with name but no path)
+      if (t.name && !t.path) {
+        return false;
+      }
+      return mode ? t.mode === mode : !t.mode;
+    });
     // Process each node
     for (const node of nodes) {
     // Path resolution simplified (could track full XPath if needed)
       const pathMatchedTemplates = modeMatched.filter((t) => {
         // Basic matching: template.path is XPath tested for existence
+        // At this point, we know t.path exists because we filtered
+        // out named-only templates in modeMatched
+        if (!t.path) {
+          return false;
+        }
         try {
-          const res = this._evalXPath(t.path, true);
+          const resResult = this._evalXPath(t.path, true);
+          const res = /** @type {Node[]} */ (resResult);
           return res.includes(node);
         } catch {
           return false;
@@ -226,12 +272,12 @@ class XPathTransformerContext {
         pathMatchedTemplates.sort((a, b) => {
           const aPr = typeof a.priority === 'number'
             ? a.priority
-            : (this._config.specificityPriorityResolver
+            : (this._config.specificityPriorityResolver && a.path
               ? this._config.specificityPriorityResolver(a.path)
               : 0);
           const bPr = typeof b.priority === 'number'
             ? b.priority
-            : (this._config.specificityPriorityResolver
+            : (this._config.specificityPriorityResolver && b.path
               ? this._config.specificityPriorityResolver(b.path)
               : 0);
           if (aPr === bPr && this._config.errorOnEqualPriority) {
@@ -239,7 +285,12 @@ class XPathTransformerContext {
           }
           return aPr > bPr ? -1 : 1;
         });
-        templateObj = pathMatchedTemplates.shift();
+        templateObj =
+          /**
+           * @type {import('./index.js').XPathTemplateObject<any>}
+           */ (
+            pathMatchedTemplates.shift()
+          );
       }
       this._contextNode = node;
       const ret = templateObj.template.call(this, node, {mode});
@@ -251,14 +302,74 @@ class XPathTransformerContext {
     return this;
   }
 
+  /**
+   * @param {string|
+   *   {name: string, withParam?: any[]}} name - Template name or
+   *   options object
+   * @param {any[]} [withParams] - Parameters to pass to template
+   * @returns {this}
+   */
+  callTemplate (name, withParams) {
+    // Invokes a named template, optionally passing values via withParam.
+    if (name && typeof name === 'object') {
+      withParams = name.withParam || withParams;
+      ({name} = name);
+    }
+    withParams = withParams || /* c8 ignore next */ [];
+
+    // Store parameters in a temporary context for valueOf() access
+    const prevParams = this._params;
+    /** @type {Record<string, any>} */
+    const params = {};
+    this._params = params;
+
+    withParams.forEach((withParam, index) => {
+      const value = withParam.value !== undefined
+        ? withParam.value
+        : this.get(withParam.select, false);
+
+      // Store by name if provided, otherwise by index
+      if (withParam.name) {
+        params[withParam.name] = value;
+      } else {
+        params[String(index)] = value;
+      }
+    });
+
+    const results = this._getJoiningTransformer();
+    const templateObj = this._templates.find((template) => {
+      return template.name === name;
+    });
+    if (!templateObj) {
+      throw new Error(
+        'Template, ' + name + ', cannot be called as it was not found.'
+      );
+    }
+
+    // @ts-expect-error Todo: Fix
+    const result = templateObj.template.call(this, this._contextNode, {});
+    if (typeof result !== 'undefined') {
+      /** @type {any} */ (results).append(result);
+    }
+
+    // Restore previous parameter context
+    this._params = prevParams;
+
+    return this;
+  }
+
+
   /**
    * Iterate over nodes selected by XPath.
    * @param {string} select - XPath expression
-   * @param {Function} cb - Callback invoked per node
+   * @param {(this: XPathTransformerContext,
+   *   node: Node
+   * )=>void} cb - Callback invoked per node
    * @returns {XPathTransformerContext}
    */
   forEach (select, cb) {
-    const nodes = this._evalXPath(select, true);
+    const nodesResult = this._evalXPath(select, true);
+    const nodes = /** @type {Node[]} */ (nodesResult);
     for (const n of nodes) {
       cb.call(this, n);
     }
@@ -273,19 +384,128 @@ class XPathTransformerContext {
   valueOf (select) {
     const jt = this._getJoiningTransformer();
     let val;
-    if (!select || (
-      typeof select === 'object' && /** @type {any} */ (select).select === '.'
-    )) {
+
+    const selectStr = typeof select === 'object'
+      ? /** @type {{select?: string}} */ (select).select
+      : select;
+
+    // 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];
+      } else {
+        // Fall back to normal XPath evaluation
+        const resResult = this._evalXPath(selectStr, true);
+        const res = /** @type {Node[]} */ (resResult);
+        const first = res[0];
+        /* c8 ignore start */
+        val = first && first.nodeType
+          ? first.textContent
+          : first;
+        /* c8 ignore stop */
+      }
+    } else if (!selectStr || selectStr === '.') {
       val = this._contextNode.nodeType === 3
         ? this._contextNode.nodeValue
         : this._contextNode.textContent;
     } else {
-      const res = this._evalXPath(/** @type {string} */ (select), true);
+      const resResult = this._evalXPath(selectStr, true);
+      const res = /** @type {Node[]} */ (resResult);
       // Simplify: use textContent of first match if node, else raw
       const first = res[0];
       val = first && first.nodeType ? first.textContent : first;
     }
-    jt.append(val);
+    // Ensure val is not null before appending
+    if (val !== null) {
+      jt.append(val);
+    }
+    return this;
+  }
+
+  /**
+   * Deep copy selection or current context when omitted.
+   * For DOM nodes uses cloneNode(true); for scalars copies the value.
+   * @param {string} [select] XPath expression selecting nodes (optional)
+   * @returns {XPathTransformerContext}
+   */
+  copyOf (select) {
+    /** @type {Node[]} */ let nodes = [];
+    if (select) {
+      try {
+        const res = this.get(select, true);
+        nodes = Array.isArray(res) ? res : /* c8 ignore next */ [];
+      } catch { /* c8 ignore next */
+        nodes = /* c8 ignore next */ [];
+      }
+    } else {
+      nodes = [this._contextNode];
+    }
+    if (nodes.length) {
+      for (const n of nodes) {
+        if (n && typeof n === 'object' && 'cloneNode' in n) {
+          let deep;
+          try {
+            deep = /** @type {Node} */ (n.cloneNode(true));
+          } catch { /* c8 ignore start */
+            deep = /** @type {Node} */ (n.cloneNode(false));
+          } /* c8 ignore stop */
+          this._getJoiningTransformer().append(/** @type {any} */ (deep));
+        } else { /* c8 ignore start */
+          this._getJoiningTransformer().append(/** @type {any} */ (n));
+        } /* c8 ignore stop */
+      }
+    } else if (select) { // Scalar path
+      const scalar = this._evalXPath(select, false);
+      // If scalar evaluation unexpectedly returns a Node/Document, use its
+      // textContent instead of attempting to append the Node itself (which
+      // can cause HierarchyRequestError for Document nodes).
+      if (
+        scalar &&
+        typeof scalar === 'object' &&
+        'nodeType' in /** @type {any} */ (scalar)
+      ) {
+        const node = /** @type {Node} */ (scalar);
+        let txt = /** @type {any} */ (node.textContent);
+        if (/* c8 ignore start */
+          (txt === null || typeof txt === 'undefined') &&
+          /** @type {any} */ (node).nodeType === 9 // Document
+        ) {
+          // Fallback to documentElement textContent if available
+          const docEl = /** @type {any} */ (
+            /** @type {any} */ (node)
+          ).documentElement;
+          txt = /** @type {any} */ (docEl && docEl.textContent) || '';
+        } /* c8 ignore stop */
+        this._getJoiningTransformer().append(
+          /** @type {any} */ (txt || /* c8 ignore next */ '')
+        );
+      } else {
+        this._getJoiningTransformer().append(/** @type {any} */ (scalar));
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Shallow copy current context node (cloneNode(false)); scalars copied
+   * directly. Provided for parity with JSONPath copy().
+   * @param {string[]} [_propertySets] Ignored in XPath variant (parity only)
+   * @returns {XPathTransformerContext}
+   */
+  copy (_propertySets) {
+    const target = this._contextNode;
+    let clone;
+    if (target && typeof target === 'object' && 'nodeType' in target) {
+      try {
+        clone = /** @type {Node} */ (target.cloneNode(false));
+      } catch { /* c8 ignore start */
+        clone = target;
+      } /* c8 ignore stop */
+    } else { /* c8 ignore start */
+      clone = target;
+    } /* c8 ignore stop */
+    this._getJoiningTransformer().append(/** @type {any} */ (clone));
     return this;
   }
 
@@ -301,32 +521,330 @@ class XPathTransformerContext {
   }
   /**
    * Log a message (for debugging).
-   * @param {*} json Any value
+   * @param {unknown} json Any value
    * @returns {void}
    */
-  static message (json) {
+  // eslint-disable-next-line class-methods-use-this -- Convenient
+  message (json) {
     /* eslint-disable-next-line no-console -- Debug output */
     console.log(json);
   }
   /**
    * Append string.
    * @param {string} str String to append
-   * @param {Function} [cb] Callback
+   * @param {(this: XPathTransformerContext) => void} [cb] Callback
    * @returns {XPathTransformerContext}
    */
   string (str, cb) {
-    this._getJoiningTransformer().string(str, cb);
+    // We don't pass the callback because it has incompatible 'this' type
+    // The callback is mainly used for context-building in string transformers
+    this._getJoiningTransformer().string(str);
     return this;
   }
   /**
-   * Append number.
-   * @param {number} num Number
+   * Append number with xsl:number-like formatting.
+   * @param {number|string|{
+   *   value?: number|string,
+   *   count?: string,
+   *   level?: 'single'|'multiple'|'any',
+   *   from?: string,
+   *   format?: string,
+   *   groupingSeparator?: string,
+   *   groupingSize?: number
+   * }} num - Number value, "position()" string, or options object
    * @returns {XPathTransformerContext}
    */
   number (num) {
-    this._getJoiningTransformer().number(num);
+    // Handle xsl:number-like functionality
+    if (typeof num === 'object' && num !== null) {
+      const opts = num;
+      let {value} = opts;
+
+      // Handle position() calculation
+      if (value === 'position()' || value === undefined) {
+        const {count} = opts;
+        const level = opts.level || 'single';
+        const {from} = opts;
+
+        switch (level) {
+        case 'single': {
+          value = this._calculatePosition(count, from);
+
+          break;
+        }
+        case 'multiple': {
+          // Hierarchical numbering: get position for each ancestor up to root
+          const positions = [];
+          let node = /** @type {any} */ (this._config).currentNode;
+          while (node) {
+            positions.unshift(this._calculatePosition(count, undefined));
+            node = node.parentNode;
+            if (from) {
+              const fromResult = /** @type {any} */ (
+                this._evalXPath(from, node)
+              );
+              if (fromResult && fromResult.length > 0) {
+                break;
+              }
+            }
+          }
+          value = positions.join('.');
+
+          break;
+        }
+        case 'any': {
+          value = this._calculatePositionAny(count, from);
+
+          break;
+        }
+        // No default
+        }
+      }
+
+      // Determine format string and locale
+      let format = opts.format || '1';
+      // @ts-expect-error: dynamic property access
+      const locale = opts.lang || 'en';
+      // @ts-expect-error: dynamic property access
+      const {letterValue} = opts;
+
+      // If letterValue is 'alphabetic', force alphabetic format
+      if (letterValue === 'alphabetic') {
+        format = (opts.format && (/^[aA]$/v).test(opts.format)) ? opts.format : 'a';
+      }
+
+      const numValue = typeof value === 'string' ? Number(value) : (value || 1);
+      const formatted = this._formatNumber(
+        numValue,
+        format,
+        opts.groupingSeparator,
+        opts.groupingSize,
+        locale
+      );
+      this._getJoiningTransformer().plainText(formatted);
+    } else if (num === 'position()') {
+      // Simple position() call
+      const pos = this._calculatePosition();
+      this._getJoiningTransformer().number(pos);
+    } else {
+      // Simple number
+      this._getJoiningTransformer().number(
+        typeof num === 'string' ? Number(num) : num
+      );
+    }
     return this;
   }
+
+  /**
+   * Calculate position of current node.
+   * @param {string} [count] - XPath pattern to match
+   * @param {string} [from] - XPath pattern for ancestor
+   * @returns {number}
+   * @private
+   */
+  _calculatePosition (count, from) {
+    // eslint-disable-next-line prefer-destructuring -- TS
+    const currentNode = /** @type {any} */ (this._config).currentNode;
+    if (!currentNode) {
+      return 1;
+    }
+
+    // Get parent node
+    const parent = currentNode.parentNode;
+    if (!parent) {
+      return 1;
+    }
+
+    // If from pattern specified, find that ancestor
+    let startNode = parent;
+    if (from) {
+      const fromResult = /** @type {any} */ (
+        this._evalXPath(from, currentNode)
+      );
+      if (fromResult && fromResult.length > 0) {
+        startNode = fromResult[0];
+      }
+    }
+
+    // Count preceding siblings
+    let position = 1;
+    let sibling = currentNode.previousSibling;
+
+    while (sibling) {
+      if (count) {
+        // Check if sibling matches count pattern
+        const matches = /** @type {any} */ (this._evalXPath(count, sibling));
+        if (matches && matches.length > 0) {
+          position++;
+        }
+      } else if (sibling.nodeType === currentNode.nodeType &&
+        (!currentNode.nodeName || sibling.nodeName === currentNode.nodeName)) {
+        position++;
+      }
+      sibling = sibling.previousSibling;
+    }
+
+    return position;
+  }
+
+  /**
+   * Calculate position counting all ancestors (level=any).
+   * @param {string} [count] - XPath pattern to match
+   * @param {string} [from] - XPath pattern for ancestor
+   * @returns {number}
+   * @private
+   */
+  _calculatePositionAny (count, from) {
+    // eslint-disable-next-line prefer-destructuring -- TS
+    const currentNode = /** @type {any} */ (this._config).currentNode;
+    if (!currentNode) {
+      return 1;
+    }
+
+    // Find root or 'from' node
+    let root = currentNode.ownerDocument || currentNode;
+    if (from) {
+      const fromResult = /** @type {any} */ (
+        this._evalXPath(from, currentNode)
+      );
+      if (fromResult && fromResult.length > 0) {
+        root = fromResult[0];
+      }
+    }
+
+    // Count all matching nodes in document order up to current
+    const pattern = count || 'node()';
+    const allNodes = /** @type {any[]} */ (
+      this._evalXPath('//' + pattern, root)
+    );
+
+    for (const [i, allNode] of allNodes.entries()) {
+      if (allNode === currentNode) {
+        return i + 1;
+      }
+    }
+
+    return 1;
+  }
+
+  /**
+   * Format a number according to format string.
+   * @param {number} num - Number to format
+   * @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} [locale]
+   * @returns {string}
+   * @private
+   */
+  _formatNumber (num, format, groupingSeparator, groupingSize, locale = 'en') {
+    if (Number.isNaN(num)) {
+      return String(num);
+    }
+
+    let result;
+    const formatChar = format.charAt(0);
+
+    switch (formatChar) {
+    case 'i': {
+      result = this._toRoman(num).toLowerCase();
+
+      break;
+    }
+    case 'I': {
+      result = this._toRoman(num);
+
+      break;
+    }
+    case 'a': {
+      result = this._toAlphabetic(num, false);
+
+      break;
+    }
+    case 'A': {
+      result = this._toAlphabetic(num, true);
+
+      break;
+    }
+    case '0': {
+      const width = format.length;
+      result = String(num).padStart(width, '0');
+
+      break;
+    }
+    default: {
+      // Use Intl.NumberFormat for decimal formatting if grouping/locale
+      //   options are provided
+      let options = {};
+      if (groupingSeparator || groupingSize) {
+        options = {
+          useGrouping: true
+        };
+      }
+      try {
+        result = new Intl.NumberFormat(locale, options).format(num);
+        if (groupingSeparator) {
+          result = result.replaceAll(',', groupingSeparator);
+        }
+      } catch (e) {
+        result = String(num);
+      }
+    }
+    }
+    return result;
+  }
+
+  /**
+   * Convert number to Roman numerals.
+   * @param {number} num - Number to convert (1-3999)
+   * @returns {string}
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this -- Avoid for now
+  _toRoman (num) {
+    if (num < 1 || num > 3999) {
+      return String(num);
+    }
+
+    const vals = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1];
+    const syms = [
+      'M', 'CM', 'D', 'CD', 'C', 'XC', 'L', 'XL', 'X', 'IX', 'V', 'IV', 'I'
+    ];
+
+    let result = '';
+    for (const [i, val] of vals.entries()) {
+      while (num >= val) {
+        result += syms[i];
+        num -= val;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Convert number to alphabetic sequence.
+   * @param {number} num - Number to convert
+   * @param {boolean} uppercase - Use uppercase letters
+   * @returns {string}
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this -- Avoid for now
+  _toAlphabetic (num, uppercase) {
+    if (num < 1) {
+      return String(num);
+    }
+
+    let result = '';
+    const base = uppercase ? 65 : 97; // 'A' or 'a'
+
+    while (num > 0) {
+      num--; // Make 0-indexed
+      result = String.fromCodePoint(base + (num % 26)) + result;
+      num = Math.floor(num / 26);
+    }
+
+    return result;
+  }
   /**
    * Append plain text (no escaping changes).
    * @param {string} str Text
@@ -339,7 +857,7 @@ class XPathTransformerContext {
   /**
    * Append property/value pair.
    * @param {string} prop Property name
-   * @param {*} val Value
+   * @param {any} val Value
    * @returns {XPathTransformerContext}
    */
   propValue (prop, val) {
@@ -348,43 +866,82 @@ class XPathTransformerContext {
   }
   /**
    * Append object.
-   * @param {...any} args Object args
+   * @param {Record<string, unknown>|
+   *   ((this: XPathTransformerContext) => void)} objOrCb Object or callback
+   * @param {((this: XPathTransformerContext) => void)|
+   *   any[]} [cbOrUsePropertySets] Callback or property sets
+   * @param {any[]|
+   *   Record<string, unknown>} [usePropertySetsOrPropSets]
+   *   Property sets or props
+   * @param {Record<string, unknown>} [propSets] Additional property sets
    * @returns {XPathTransformerContext}
    */
-  object (...args) {
-    this._getJoiningTransformer().object(...args);
+  object (objOrCb, cbOrUsePropertySets, usePropertySetsOrPropSets, propSets) {
+    const jt = this._getJoiningTransformer();
+    // Union of transformers creates intersection types
+    // @ts-expect-error
+    jt.object(objOrCb, cbOrUsePropertySets, usePropertySetsOrPropSets,
+      propSets);
     return this;
   }
   /**
    * Append array.
-   * @param {...any} args Array args
+   * @param {any[]|
+   *   ((this: XPathTransformerContext) => void)} [arrOrCb]
+   *   Array or callback
+   * @param {(this: XPathTransformerContext) => void} [cb] Callback
    * @returns {XPathTransformerContext}
    */
-  array (...args) {
-    this._getJoiningTransformer().array(...args);
+  array (arrOrCb, cb) {
+    const jt = this._getJoiningTransformer();
+    // Union of transformers creates intersection types
+    // @ts-expect-error
+    jt.array(arrOrCb, cb);
     return this;
   }
+
+  /**
+   * Append text node content.
+   * @param {import('./StringJoiningTransformer.js').OutputConfig} cfg Text
+   * @returns {XPathTransformerContext}
+   */
+  output (cfg) {
+    this._getJoiningTransformer().output(cfg);
+    return this;
+  }
+
   /**
    * Append element.
    * @param {string} name Tag name
-   * @param {object} [atts] Attributes
-   * @param {any[]} [children] Children
-   * @param {Function} [cb] Callback
+   * @param {Record<string, string>|any[]|
+   *   ((this: XPathTransformerContext)=>void)} [atts] Attributes
+   * @param {any[]|((this: XPathTransformerContext)=>void)} [children]
+   *   Children
+   * @param {(this: XPathTransformerContext)=>void} [cb] Callback
    * @returns {XPathTransformerContext}
    */
   element (name, atts, children, cb) {
+    // @ts-expect-error - Union of transformers creates intersection types
     this._getJoiningTransformer().element(name, atts, children, cb);
     return this;
   }
   /**
    * Append attribute.
    * @param {string} name Attribute name
-   * @param {string|object} val Value
+   * @param {string|Record<string, unknown>} val Value
    * @param {boolean} [avoid] Avoid duplicates
    * @returns {XPathTransformerContext}
    */
   attribute (name, val, avoid) {
-    this._getJoiningTransformer().attribute(name, val, avoid);
+    const jt = this._getJoiningTransformer();
+    // Only StringJoiningTransformer supports the third parameter
+    if (typeof avoid !== 'undefined') {
+      // Union of transformers creates intersection types
+      // @ts-expect-error
+      jt.attribute(name, /** @type {string} */ (val), avoid);
+    } else {
+      jt.attribute(name, /** @type {string} */ (val));
+    }
     return this;
   }
   /**
@@ -396,27 +953,59 @@ class XPathTransformerContext {
     this._getJoiningTransformer().text(txt);
     return this;
   }
+
+  /**
+   * Append a comment.
+   * @param {string} text - Comment text
+   * @returns {XPathTransformerContext}
+   */
+  comment (text) {
+    const jt = this._getJoiningTransformer();
+    if (jt.comment) {
+      jt.comment(text);
+    }
+    return this;
+  }
+
+  /**
+   * Append a processing instruction.
+   * @param {string} target - Processing instruction target
+   * @param {string} data - Processing instruction data
+   * @returns {XPathTransformerContext}
+   */
+  processingInstruction (target, data) {
+    const jt = this._getJoiningTransformer();
+    if (jt.processingInstruction) {
+      jt.processingInstruction(target, data);
+    }
+    return this;
+  }
+
   /**
    * Define a property set (optionally composed from other sets).
    * @param {string} name Property set name
-   * @param {object} obj Base properties
+   * @param {Record<string, unknown>} obj Base properties
    * @param {string[]} [use] Property set names to merge
    * @returns {XPathTransformerContext}
    */
   propertySet (name, obj, use) {
-    this.propertySets[name] = use
-      ? ({
-        ...obj,
-        ...use.reduce((acc, psName) => this._usePropertySets(acc, psName), {})
-      })
-      : obj;
+    this.propertySets[name] = /** @type {Record<string, unknown>} */ (
+      use
+        ? ({
+          ...obj,
+          ...use.reduce(
+            (acc, psName) => this._usePropertySets(acc, psName), {}
+          )
+        })
+        : obj
+    );
     return this;
   }
   /**
    * Merge properties from a named property set into obj.
-   * @param {object} obj Target object
+   * @param {Record<string, unknown>} obj Target object
    * @param {string} name Property set name
-   * @returns {object}
+   * @returns {Record<string, unknown>}
    */
   _usePropertySets (obj, name) {
     return Object.assign(obj, this.propertySets[name]);
@@ -424,16 +1013,20 @@ class XPathTransformerContext {
   /**
    * Retrieve a key-mapped node matching a value or return context.
    * @param {string} name Key name
-   * @param {*} value Value to match
-   * @returns {*}
+   * @param {any} value Value to match
+   * @returns {any}
    */
   getKey (name, value) {
     const key = this.keys[name];
     const matches = this.get(key.match, true);
-    for (const m of matches) {
+    // When asNodes=true, get() returns Node[]
+    /** @type {Node[]} */
+    const nodesArray = /** @type {Node[]} */ (matches);
+    for (const m of nodesArray) {
       if (m && m.nodeType === 1) { // Element
-        if (m.getAttribute && m.getAttribute(key.use) === value) {
-          return m;
+        const elem = /** @type {Element} */ (m);
+        if (elem.getAttribute(key.use) === value) {
+          return elem;
         }
       }
     }
@@ -451,27 +1044,260 @@ class XPathTransformerContext {
     return this;
   }
 
+  /**
+   * Conditionally execute a callback when an XPath evaluates to a truthy
+   * scalar or a non-empty node set (akin to xsl:if semantics).
+   *
+   * Truthiness rules:
+   * - Node set: length > 0 passes.
+   * - Scalar: Boolean(value) must be true.
+   *
+   * @param {string} select XPath expression
+   * @param {(this: XPathTransformerContext)
+   *   => void} cb Callback invoked if condition passes
+   * @returns {XPathTransformerContext}
+   */
+  if (select, cb) {
+    const passes = this._passesIf(select);
+    if (passes && typeof cb === 'function') {
+      cb.call(this);
+    }
+    return this;
+  }
+
+  /**
+   * Internal helper: evaluate XPath truthiness like if().
+   * @param {string} select
+   * @returns {boolean}
+   */
+  _passesIf (select) {
+    let passes = false;
+    // Try scalar evaluation first (handles boolean/comparison expressions)
+    try {
+      const scalar = this.get(select, false);
+      let normalized;
+      // Unwrap single-item array if it contains a primitive
+      /* c8 ignore next 6 -- Defensive code for edge case where _evalXPath
+       * returns single-item array with asNodes=false; both native XPath v1
+       * and xpath2.js v2 return scalars directly in standard usage. */
+      if (
+        Array.isArray(scalar) &&
+        scalar.length === 1 &&
+        ['boolean', 'number', 'string'].includes(typeof scalar[0])
+      ) {
+        normalized = scalar[0];
+      } else if (['boolean', 'number', 'string'].includes(typeof scalar)) {
+        normalized = scalar;
+      }
+      if (typeof normalized !== 'undefined') {
+        passes = Boolean(normalized);
+      }
+    } catch {
+      // Scalar eval failed; will try node selection
+    }
+    // If not yet truthy, attempt node selection (location paths)
+    if (!passes && (/[\/@*]/v).test(select)) {
+      try {
+        const nodes = this.get(select, true);
+        // eslint-disable-next-line unicorn/prefer-ternary -- for coverage
+        if (Array.isArray(nodes)) {
+          passes = nodes.length > 0;
+        // Defensive for non-array nodes, but _evalXPath with asNodes=true
+        // always returns arrays in both v1 and v2.
+        /* c8 ignore start */
+        } else {
+          passes = Boolean(nodes);
+        }
+        /* c8 ignore stop */
+      } catch {
+        passes = false;
+      }
+    }
+    return passes;
+  }
+
+  /**
+   * Conditional with optional fallback (like choose/otherwise).
+   * Truthiness same as `if()`.
+   * @param {string} select XPath expression
+   * @param {(this: XPathTransformerContext)
+   *   => void} whenCb Callback when condition passes
+   * @param {(this: XPathTransformerContext)
+   *   => void} [otherwiseCb] Callback when condition fails
+   * @returns {XPathTransformerContext}
+   */
+  choose (select, whenCb, otherwiseCb) {
+    const passes = this._passesIf(select);
+    if (passes) {
+      if (typeof whenCb === 'function') {
+        whenCb.call(this);
+      }
+    } else if (typeof otherwiseCb === 'function') {
+      otherwiseCb.call(this);
+    }
+    return this;
+  }
+
+  /**
+   * Analyze a string with a regular expression, equivalent to
+   * xsl:analyze-string. Processes matching and non-matching substrings
+   * with separate callbacks.
+   * @param {string} str - The string to analyze
+   * @param {string|RegExp} regex - Regular expression to match against
+   * @param {{
+   *   matchingSubstring?: (
+   *     this: XPathTransformerContext,
+   *     substring: string,
+   *     groups: string[],
+   *     regexGroup: (n: number) => string
+   *   ) => void,
+   *   nonMatchingSubstring?: (
+   *     this: XPathTransformerContext,
+   *     substring: string
+   *   ) => void,
+   *   flags?: string
+   * }} options - Options object
+   * @returns {XPathTransformerContext}
+   */
+  analyzeString (str, regex, options = {}) {
+    // Ensure we have a string
+    const inputString = String(str || '');
+
+    // If empty string, do nothing
+    if (inputString.length === 0) {
+      return this;
+    }
+
+    const {
+      matchingSubstring,
+      nonMatchingSubstring,
+      flags = ''
+    } = options;
+
+    // Convert regex to RegExp if it's a string
+    let regexObj;
+    if (typeof regex === 'string') {
+      // Ensure 'g' flag is present for global matching
+      const actualFlags = flags.includes('g') ? flags : flags + 'g';
+      regexObj = new RegExp(regex, actualFlags);
+    } else {
+      regexObj = regex;
+      // Ensure global flag is set
+      if (!regexObj.global) {
+        regexObj = new RegExp(
+          regexObj.source,
+          regexObj.flags + 'g'
+        );
+      }
+    }
+
+    // Check for zero-length matches (error condition in XSLT)
+    if (regexObj.test('')) {
+      throw new Error(
+        'Regular expression matches zero-length string'
+      );
+    }
+
+    // Store captured groups for access during callback
+    /** @type {string[] | undefined} */
+    let currentCapturedGroups;
+
+    /**
+     * Get captured group by index.
+     * @param {number} groupNumber - Group index
+     * @returns {string} - Captured group or empty string
+     */
+    const getRegexGroup = (groupNumber) => {
+      if (!currentCapturedGroups ||
+          groupNumber < 0 ||
+          groupNumber >= currentCapturedGroups.length) {
+        return '';
+      }
+      return currentCapturedGroups[groupNumber] || '';
+    };
+
+    // Save previous context to restore later
+    const prevContext = this._contextNode;
+
+    let lastIndex = 0;
+    let match;
+
+    // Bind callbacks to this context
+    const boundMatchingSubstring = matchingSubstring
+      ? matchingSubstring.bind(this)
+      : undefined;
+    const boundNonMatchingSubstring = nonMatchingSubstring
+      ? nonMatchingSubstring.bind(this)
+      : undefined;
+
+    // Find all matches
+    while ((match = regexObj.exec(inputString)) !== null) {
+      // Process non-matching substring before this match
+      if (match.index > lastIndex) {
+        const nonMatchingStr = inputString.slice(lastIndex, match.index);
+        if (boundNonMatchingSubstring) {
+          boundNonMatchingSubstring(nonMatchingStr);
+        }
+      }
+
+      // Process matching substring
+      if (boundMatchingSubstring) {
+        const matchingStr = match[0];
+        // Store captured groups: [full match, group1, group2, ...]
+        currentCapturedGroups = [...match];
+        boundMatchingSubstring(
+          matchingStr, currentCapturedGroups, getRegexGroup
+        );
+        currentCapturedGroups = undefined;
+      }
+
+      const {lastIndex: newLastIndex} = regexObj;
+      lastIndex = newLastIndex;
+
+      // Prevent infinite loop on zero-length matches (shouldn't happen
+      // due to earlier check, but defensive)
+      if (match.index === regexObj.lastIndex) {
+        regexObj.lastIndex++;
+      }
+    }
+
+    // Process final non-matching substring
+    if (lastIndex < inputString.length) {
+      const nonMatchingStr = inputString.slice(lastIndex);
+      if (boundNonMatchingSubstring) {
+        boundNonMatchingSubstring(nonMatchingStr);
+      }
+    }
+
+    // Restore previous context
+    this._contextNode = prevContext;
+
+    return this;
+  }
+
   /* c8 ignore start -- static default rules object has spotty function
    * attribution under coverage; behavior is exercised via applyTemplates */
   static DefaultTemplateRules = {
     transformRoot: {
       /**
-       * @param {*} node Root node
+       * @this {XPathTransformerContext}
+       * @param {unknown} node Root node
        * @param {{mode:string}} cfg Config
        * @returns {void}
        */
       template (node, cfg) {
-        /** @type {any} */ (this).applyTemplates('.', cfg.mode);
+        this.applyTemplates('.', cfg.mode);
       }
     },
     transformElements: {
       /**
-       * @param {*} node Element node
-       * @param {{mode:string}} cfg Config
+       * @this {XPathTransformerContext}
+       * @param {unknown} node Element node
+       * @param {{mode?:string}} cfg Config
        * @returns {void}
        */
       template (node, cfg) {
-        /** @type {any} */ (this).applyTemplates('*', cfg.mode);
+        this.applyTemplates('*', cfg.mode);
       }
     },
     transformTextNodes: {
@@ -484,9 +1310,12 @@ class XPathTransformerContext {
       }
     },
     transformScalars: {
-      /** @returns {*} */
+      /**
+       * @this {XPathTransformerContext}
+       * @returns {XPathTransformerContext}
+       */
       template () {
-        return /** @type {any} */ (this).valueOf({select: '.'});
+        return this.valueOf({select: '.'});
       }
     }
   };