jtlt 0.2.0 → 0.3.0

package/src/XPathTransformerContext.js

@@ -1,6 +1,16 @@
 import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
 // xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js
 
+/**
+ * @typedef {object} XPathTransformerContextConfig
+ * @property {unknown} [data] - XML/DOM root to transform
+ * @property {number} [xpathVersion] - 1 or 2 (default 1)
+ * @property {import('./index.js').
+ *   JoiningTransformer} joiningTransformer Joiner
+ * @property {boolean} [errorOnEqualPriority]
+ * @property {(path: string) => number} [specificityPriorityResolver]
+ */
+
 /**
  * Execution context for XPath-driven template application.
  *
@@ -16,36 +26,35 @@ import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
  */
 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,8 +62,8 @@ 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) {
@@ -66,11 +75,13 @@ class XPathTransformerContext {
       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 +97,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 +131,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:
@@ -140,15 +153,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 +173,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 +192,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 +205,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 +253,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 +266,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 +283,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 +365,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,21 +502,24 @@ 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;
   }
   /**
@@ -339,7 +543,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 +552,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 +639,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 +699,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 +730,123 @@ 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;
+  }
+
   /* 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 +859,12 @@ class XPathTransformerContext {
       }
     },
     transformScalars: {
-      /** @returns {*} */
+      /**
+       * @this {XPathTransformerContext}
+       * @returns {XPathTransformerContext}
+       */
       template () {
-        return /** @type {any} */ (this).valueOf({select: '.'});
+        return this.valueOf({select: '.'});
       }
     }
   };