jtlt 0.2.0 → 0.3.0

package/src/JSONPathTransformerContext.js

@@ -1,6 +1,41 @@
 import {JSONPath as jsonpath} from 'jsonpath-plus';
 import JSONPathTransformer from './JSONPathTransformer.js';
 
+/**
+ * Sort spec types used by applyTemplates() and forEach().
+ * @typedef {{
+ *   select?: string,
+ *   order?: 'ascending' | 'descending',
+ *   type?: 'text'|'number',
+ *   locale?: string,
+ *   localeOptions?: unknown
+ * }} SortObject
+ * @typedef {(a: unknown, b: unknown,
+ *   ctx: JSONPathTransformerContext
+ * ) => number} SortComparator
+ * @typedef {string | SortObject | SortComparator |
+ *   Array<string|SortObject>} SortSpec
+ */
+
+/**
+ * @template [T = "json"]
+ * @typedef {object} JSONPathTransformerContextConfig
+ * @property {null|boolean|number|string|object} data - Data to transform
+ * @property {object} [parent] - Parent object
+ * @property {string} [parentProperty] - Parent property name
+ * @property {boolean} [errorOnEqualPriority] - Whether to error on
+ *   equal priority
+ * @property {T extends "json" ? import('./JSONJoiningTransformer.js').
+ *   default : T extends "string" ? import('./StringJoiningTransformer.js').
+ *   default : import('./DOMJoiningTransformer.js').
+ *   default} joiningTransformer - Joining transformer
+ * @property {boolean} [preventEval] - Whether to prevent eval in
+ *   JSONPath
+ * @property {(path: string) => number} [specificityPriorityResolver]
+ *   Priority resolver function
+ * @property {import('./index.js').JSONPathTemplateObject<T>[]} templates
+ */
+
 /**
  * Execution context for JSONPath-driven template application.
  *
@@ -8,23 +43,13 @@ import JSONPathTransformer from './JSONPathTransformer.js';
  * running templates. Exposes helper methods that mirror the underlying
  * joining transformer (e.g., string(), object(), array()) so templates can
  * emit results without referencing the joiner directly.
+ * @template [T = "json"]
  */
 class JSONPathTransformerContext {
   /**
-   * @param {object} config - Configuration object
-   * @param {object} config.data - Data to transform
-   * @param {object} [config.parent] - Parent object
-   * @param {string} [config.parentProperty] - Parent property name
-   * @param {boolean} [config.errorOnEqualPriority] - Whether to error on
-   *   equal priority
-   * @param {{append: Function, get: Function, string: Function,
-   *   object: Function, array: Function}} config.joiningTransformer -
-   *   Joining transformer
-   * @param {boolean} [config.preventEval] - Whether to prevent eval in
-   *   JSONPath
-   * @param {Function} [config.specificityPriorityResolver] - Function to
-   *   resolve priority
-   * @param {any[]} templates - Array of template objects
+   * @param {JSONPathTransformerContextConfig<T>} config
+   * @param {import('./index.js').JSONPathTemplateObject<T>[]} templates - Array
+   *   of template objects
    */
   constructor (config, templates) {
     this._config = config;
@@ -32,16 +57,18 @@ class JSONPathTransformerContext {
     this._contextObj = this._origObj = config.data;
     this._parent = config.parent || this._config;
     this._parentProperty = config.parentProperty || 'data';
-    /** @type {Record<string, any>} */
+    /** @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;
+    /** @type {Record<string, any> | undefined} */
+    this._params = undefined;
   }
 
   /**
@@ -59,28 +86,30 @@ class JSONPathTransformerContext {
 
   /**
    * Gets the joining transformer from config.
-   * @returns {any} The joining transformer
+   * @returns {T extends "json" ? import('./JSONJoiningTransformer.js').
+   *   default : T extends "string" ? import('./StringJoiningTransformer.js').
+   *   default : import('./DOMJoiningTransformer.js').
+   *   default} The joining transformer
    */
   _getJoiningTransformer () {
     return this._config.joiningTransformer;
   }
 
   /**
-   * @param {*} item - Item to append to output
-   * @returns {JSONPathTransformerContext}
+   * @param {string | Node} item - Item to append to output
+   * @returns {this}
    */
   appendOutput (item) {
-    /** @type {any} */ (this._getJoiningTransformer()).append(item);
+    this._getJoiningTransformer().append(item);
     return this;
   }
 
-  /* c8 ignore next 4 -- JSDoc block incorrectly counted as coverable by c8 */
   /**
    * Gets the current output.
-   * @returns {*} The output from the joining transformer
+   * @returns {any} The output from the joining transformer
    */
   getOutput () {
-    return /** @type {any} */ (this._getJoiningTransformer()).get();
+    return this._getJoiningTransformer().get();
   }
 
   /**
@@ -89,7 +118,7 @@ class JSONPathTransformerContext {
    *   to the result tree instead).
    * @param {string} select - JSONPath selector
    * @param {boolean} wrap - Whether to wrap results
-   * @returns {*} The selected value(s)
+   * @returns {any} The selected value(s)
    */
   get (select, wrap) {
     if (select) {
@@ -103,8 +132,8 @@ class JSONPathTransformerContext {
   }
 
   /**
-   * @param {*} v - Value to set
-   * @returns {JSONPathTransformerContext}
+   * @param {any} v - Value to set
+   * @returns {this}
    */
   set (v) {
     (/** @type {Record<string, any>} */ (this._parent))[
@@ -123,10 +152,12 @@ class JSONPathTransformerContext {
    *            locale, localeOptions }
    * - array: multiple key objects/strings in priority order.
    *
-   * @param {string|object} select - JSONPath selector or options object
+   * @param {string|null|
+   *   {mode?: string, select?: string}
+   * } [select] - JSONPath selector or options object
    * @param {string} [mode] - Mode to apply
-   * @param {string|Function|object|Array<string|object>} [sort] - Sort spec
-   * @returns {JSONPathTransformerContext}
+   * @param {SortSpec} [sort] - Sort spec
+   * @returns {this}
    */
   applyTemplates (select, mode, sort) {
     // Matches templates by (path, mode), resolves priority, and invokes each
@@ -135,10 +166,8 @@ class JSONPathTransformerContext {
     // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
     const that = this;
     if (select && typeof select === 'object') {
-      /** @type {{mode?: string, select?: string}} */
-      const selectObj = /** @type {any} */ (select);
-      mode = selectObj.mode ?? mode;
-      select = selectObj.select ?? select;
+      mode = select.mode ?? mode;
+      select = select.select ?? select;
     }
     if (!this._initialized) {
       select = select || '$';
@@ -154,7 +183,11 @@ class JSONPathTransformerContext {
     const jsonPathExpr = propertyNamesMode ? select.slice(0, -1) : select;
     // Todo: Use results here?
     /* const results = */ this._getJoiningTransformer();
-    const modeMatchedTemplates = this._templates.filter(function (templateObj) {
+    const modeMatchedTemplates = this._templates.filter((templateObj) => {
+      // Exclude named-only templates (those with name but no path)
+      if (templateObj.name && !templateObj.path) {
+        return false;
+      }
       return ((mode && mode === templateObj.mode) ||
         (!mode && !templateObj.mode));
     });
@@ -162,7 +195,7 @@ class JSONPathTransformerContext {
     // Collect matches first (to allow sorting), then process
     /**
      * @type {{
-     *   value:any, parent:any, parentProperty?:string, path:string
+     *   value: any, parent: any, parentProperty?: string, path: string
      * }[]}
      */
     const matches = /** @type {any} */ (jsonpath)({
@@ -231,7 +264,7 @@ class JSONPathTransformerContext {
     }
     /**
      * @param {any} sortSpec
-     * @returns {((a:{value:any}, b:{value:any})=>number)|null}
+     * @returns {((a: {value: any}, b: {value: any}) => number) | null}
      */
     function buildComparator (sortSpec) {
       if (!sortSpec) {
@@ -283,6 +316,13 @@ class JSONPathTransformerContext {
       that._currPath += path.replace(/^\$/v, '');
       const pathMatchedTemplates = modeMatchedTemplates.filter(
         function (templateObj) {
+          // At this point, we know templateObj.path exists because we filtered
+          // out named-only templates in modeMatchedTemplates
+          /* c8 ignore start -- defensive check, already filtered at line 188 */
+          if (!templateObj.path) {
+            return false;
+          }
+          /* c8 ignore stop */
           const queryResult = /** @type {any[]} */ (
             (/** @type {any} */ (jsonpath))({
               path: JSONPathTransformer.makeJSONPathAbsolute(
@@ -323,12 +363,12 @@ class JSONPathTransformerContext {
            * trigger error, making the `: 0` branch nearly unreachable. */
           const aPriority = typeof a.priority === 'number'
             ? a.priority
-            : (that._config.specificityPriorityResolver
+            : (that._config.specificityPriorityResolver && a.path
               ? that._config.specificityPriorityResolver(a.path)
               : 0);
           const bPriority = typeof b.priority === 'number'
             ? b.priority
-            : (that._config.specificityPriorityResolver
+            : (that._config.specificityPriorityResolver && b.path
               ? that._config.specificityPriorityResolver(b.path)
               : 0);
           /* c8 ignore stop */
@@ -340,18 +380,27 @@ class JSONPathTransformerContext {
           return (aPriority > bPriority) ? -1 : 1;
         });
 
-        templateObj = pathMatchedTemplates.shift();
+        templateObj =
+          /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
+            pathMatchedTemplates.shift()
+          );
       }
 
       that._contextObj = value;
       that._parent = parent;
       that._parentProperty = (parentProperty ?? that._parentProperty);
 
-      const ret = templateObj.template.call(
-        that, value, {mode, parent, parentProperty}
-      );
+      const ret =
+        /** @type {import('./index.js').JSONPathTemplateObject<T>} */ (
+          templateObj
+        ).template.call(
+          that, value, {mode, parent, parentProperty}
+        );
       if (typeof ret !== 'undefined') {
-        that._getJoiningTransformer().append(ret);
+        // After the undefined check, ret is ResultType<T>
+        that._getJoiningTransformer().append(
+          /** @type {string|Node|*} */ (ret)
+        );
       }
 
       that._contextObj = value;
@@ -368,26 +417,41 @@ class JSONPathTransformerContext {
   }
 
   /**
-   * @param {string|object} name - Template name or options object
+   * @param {string|
+   *   {name: string, withParam?: any[]}} name - Template name or
+   *   options object
    * @param {any[]} [withParams] - Parameters to pass to template
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   callTemplate (name, withParams) {
     // Invokes a named template, optionally passing values via withParam.
-    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
-    const that = this;
     if (name && typeof name === 'object') {
-      /** @type {{name?: string, withParam?: any[]}} */
-      const nameObj = /** @type {any} */ (name);
-      withParams = nameObj.withParam || withParams;
-      name = nameObj.name ?? name;
+      withParams = name.withParam || withParams;
+      ({name} = name);
     }
     withParams = withParams || [];
-    const paramValues = withParams.map(function (withParam) {
-      return withParam.value || that.get(withParam.select, false);
+
+    // 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(function (template) {
+    const templateObj = this._templates.find((template) => {
       return template.name === name;
     });
     if (!templateObj) {
@@ -396,8 +460,14 @@ class JSONPathTransformerContext {
       );
     }
 
-    const result = templateObj.template.apply(this, paramValues);
-    /** @type {any} */ (results).append(result);
+    const result = templateObj.template.call(this, this._contextObj, {});
+    if (typeof result !== 'undefined') {
+      /** @type {any} */ (results).append(result);
+    }
+
+    // Restore previous parameter context
+    this._params = prevParams;
+
     return this;
   }
 
@@ -406,14 +476,16 @@ class JSONPathTransformerContext {
    *
    * Sort parameter forms are the same as applyTemplates().
    * @param {string} select - JSONPath selector
-   * @param {Function} cb - Callback function
-   * @param {string|Function|object|Array<string|object>} [sort] - Sort spec
-   * @returns {JSONPathTransformerContext}
+   * @param {(this: JSONPathTransformerContext<T>,
+   *   value: any
+   * ) => void} cb - Callback function
+   * @param {SortSpec} [sort] - Sort spec
+   * @returns {this}
    */
   forEach (select, cb, sort) {
     // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
     const that = this;
-    /** @type {{value:any}[]} */
+    /** @type {{value: any}[]} */
     const matches = /** @type {any} */ (jsonpath)({
       path: select,
       json: this._contextObj,
@@ -478,7 +550,7 @@ class JSONPathTransformerContext {
     }
     /**
      * @param {any} sortSpec
-     * @returns {((a:{value:any}, b:{value:any})=>number)|null}
+     * @returns {((a: {value: any}, b: {value: any}) => number) | null}
      */
     function feBuildComparator (sortSpec) {
       if (!sortSpec) {
@@ -524,16 +596,33 @@ class JSONPathTransformerContext {
 
   /**
    * @param {string|object} [select] - JSONPath selector
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   valueOf (select) {
     // Appends the value of the given JSONPath (or the current context when
     // `{select: '.'}` is passed) to the output via the joining transformer.
     const results = this._getJoiningTransformer();
-    const result = select && typeof select === 'object' &&
-    /** @type {{select?: string}} */ (select).select === '.'
-      ? this._contextObj
-      : this.get(/** @type {string} */ (select), false);
+    let result;
+
+    if (select && typeof select === 'object' &&
+    /** @type {{select?: string}} */ (select).select === '.') {
+      result = this._contextObj;
+    } else {
+      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);
+        result = (this._params && paramName in this._params)
+          ? this._params[paramName]
+          : this.get(/** @type {string} */ (selectStr), false);
+      } else {
+        result = this.get(/** @type {string} */ (select), false);
+      }
+    }
+
     /** @type {any} */ (results).append(result);
     return this;
   }
@@ -541,7 +630,7 @@ class JSONPathTransformerContext {
   /**
    * Deep copy selection or current context when omitted.
    * @param {string} [select] - JSONPath selector
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   copyOf (select) { // Deep
     // Deeply clones the value at `select` (or current context if omitted)
@@ -567,11 +656,9 @@ class JSONPathTransformerContext {
          * vary across environments; behavior covered by tests. */
         // structuredClone failed (e.g., Symbols); if any functions present
         // on own enumerable string-keyed properties, preserve via shallow.
-        /** @type {boolean} */ let hasFunc = false;
         for (const k of Object.keys(val)) {
           const v = /** @type {any} */ (val)[k];
           if (typeof v === 'function') {
-            hasFunc = true;
             break;
           }
         }
@@ -584,14 +671,14 @@ class JSONPathTransformerContext {
       // Primitives/functions copied by value/reference semantics naturally.
       clone = val;
     }
-    /** @type {any} */ (this._getJoiningTransformer()).append(clone);
+    this._getJoiningTransformer().append(clone);
     return this;
   }
 
   /**
    * Shallow copy current context; optionally merge property set names.
    * @param {string[]} [propertySets] - Property sets to merge
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   copy (propertySets) { // Shallow
     // Creates a shallow clone of current context object/array (or primitive)
@@ -611,14 +698,14 @@ class JSONPathTransformerContext {
     } else { /* c8 ignore start -- primitive branch attribution variance */
       clone = src; // Primitive/function - nothing to shallow clone
     } /* c8 ignore stop */
-    /** @type {any} */ (this._getJoiningTransformer()).append(clone);
+    this._getJoiningTransformer().append(clone);
     return this;
   }
 
   /**
    * @param {string} name - Variable name
    * @param {string} select - JSONPath selector
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   variable (name, select) {
     this.vars[name] = this.get(select, false);
@@ -626,7 +713,7 @@ class JSONPathTransformerContext {
   }
 
   /**
-   * @param {*} json - JSON data to log
+   * @param {unknown} json - JSON data to log
    * @returns {void}
    */
   // eslint-disable-next-line class-methods-use-this -- Convenient
@@ -637,10 +724,11 @@ class JSONPathTransformerContext {
 
   /**
    * @param {string} str - String value
-   * @param {Function} cb - Callback function
-   * @returns {JSONPathTransformerContext}
+   * @param {import('./JSONJoiningTransformer.js').
+   *   SimpleCallback<T>} [cb] - Optional callback to build nested
+   *   string content
+   * @returns {this}
    */
-  // Todo: Add other methods from the joining transformers
   string (str, cb) {
     /** @type {any} */ (this._getJoiningTransformer()).string(str, cb);
     return this;
@@ -650,10 +738,10 @@ class JSONPathTransformerContext {
    * Append a number to JSON output. Mirrors the joining transformer API so
    *   templates can call `this.number()`.
    * @param {number} num - Number value to append
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   number (num) {
-    /** @type {any} */ (this._getJoiningTransformer()).number(num);
+    this._getJoiningTransformer().number(num);
     return this;
   }
 
@@ -662,10 +750,10 @@ class JSONPathTransformerContext {
    *   stringification. Mirrors the joining transformer API so templates can
    *   call `this.plainText()`.
    * @param {string} str - Plain text to append
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   plainText (str) {
-    /** @type {any} */ (this._getJoiningTransformer()).plainText(str);
+    this._getJoiningTransformer().plainText(str);
     return this;
   }
 
@@ -673,11 +761,11 @@ class JSONPathTransformerContext {
    * Set a property value on the current object (JSON joiner). Mirrors the
    *   joining transformer API so templates can call `this.propValue()`.
    * @param {string} prop - Property name
-   * @param {*} val - Property value
-   * @returns {JSONPathTransformerContext}
+   * @param {any} val - Property value
+   * @returns {this}
    */
   propValue (prop, val) {
-    /** @type {any} */ (this._getJoiningTransformer()).propValue(prop, val);
+    this._getJoiningTransformer().propValue(prop, val);
     return this;
   }
 
@@ -686,7 +774,7 @@ class JSONPathTransformerContext {
    * support both signatures: (obj, cb, usePropertySets, propSets) with seed
    * object or (cb, usePropertySets, propSets) without.
    * @param {...any} args - Arguments to pass to joiner
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   object (...args) {
     /** @type {any} */ (this._getJoiningTransformer()).object(...args);
@@ -697,21 +785,32 @@ class JSONPathTransformerContext {
    * Build an array. Mirrors the joining transformer API. All joiners now
    * support both signatures: (arr, cb) with seed array or (cb) without.
    * @param {...any} args - Arguments to pass to joiner
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   array (...args) {
     /** @type {any} */ (this._getJoiningTransformer()).array(...args);
     return this;
   }
 
+  /**
+   * Set document-level configuration.
+   * @param {import('./StringJoiningTransformer.js').OutputConfig} cfg Text
+   * @returns {this}
+   */
+  output (cfg) {
+    this._getJoiningTransformer().output(cfg);
+    return this;
+  }
+
   /**
    * Create an element. Mirrors the joining transformer API so templates can
    * call `this.element()`.
    * @param {string} name - Element name
-   * @param {object} [atts] - Attributes object
+   * @param {Record<string, string>} [atts] - Attributes object
    * @param {any[]} [children] - Child nodes
-   * @param {Function} [cb] - Callback function
-   * @returns {JSONPathTransformerContext}
+   * @param {import('./JSONJoiningTransformer.js').
+   *   SimpleCallback<T>} [cb] - Callback function
+   * @returns {this}
    */
   element (name, atts, children, cb) {
     /** @type {any} */ (this._getJoiningTransformer()).element(
@@ -724,13 +823,12 @@ class JSONPathTransformerContext {
    * Add an attribute to the most recently opened element. Mirrors the joining
    * transformer API so templates can call `this.attribute()`.
    * @param {string} name - Attribute name
-   * @param {string|object} val - Attribute value
-   * @param {boolean} [avoidAttEscape] - Whether to avoid escaping
-   * @returns {JSONPathTransformerContext}
+   * @param {string|Record<string, unknown>} val - Attribute value
+   * @returns {this}
    */
-  attribute (name, val, avoidAttEscape) {
+  attribute (name, val) {
     /** @type {any} */ (this._getJoiningTransformer()).attribute(
-      name, val, avoidAttEscape
+      name, val
     );
     return this;
   }
@@ -739,18 +837,46 @@ class JSONPathTransformerContext {
    * Append text content. Mirrors the joining transformer API so templates can
    * call `this.text()`.
    * @param {string} txt - Text content
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   text (txt) {
-    /** @type {any} */ (this._getJoiningTransformer()).text(txt);
+    this._getJoiningTransformer().text(txt);
+    return this;
+  }
+
+  /**
+   * Add a comment to the most recently opened element. Mirrors the joining
+   * transformer API so templates can call `this.comment()`.
+   * @param {string} text - Comment text
+   * @returns {this}
+   */
+  comment (text) {
+    this._getJoiningTransformer().comment(
+      text
+    );
+    return this;
+  }
+
+  /**
+   * Add a processing instruction to the most recently opened element.
+   *   Mirrors the joining transformer API so templates can call
+   *   `this.processingInstruction()`.
+   * @param {string} target - Processing instruction target
+   * @param {string} data - Processing instruction data
+   * @returns {this}
+   */
+  processingInstruction (target, data) {
+    this._getJoiningTransformer().processingInstruction(
+      target, data
+    );
     return this;
   }
 
   /**
    * @param {string} name - Property set name
-   * @param {object} propertySetObj - Property set object
+   * @param {Record<string, unknown>} propertySetObj - Property set object
    * @param {any[]} [usePropertySets] - Property sets to use
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   propertySet (name, propertySetObj, usePropertySets) {
     // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
@@ -767,9 +893,9 @@ class JSONPathTransformerContext {
   }
 
   /**
-   * @param {object} obj - Object to assign properties to
+   * @param {Record<string, unknown>} obj - Object to assign properties to
    * @param {string} name - Property set name
-   * @returns {object}
+   * @returns {Record<string, unknown>}
    */
   _usePropertySets (obj, name) {
     return Object.assign(obj, this.propertySets[name]);
@@ -777,8 +903,8 @@ class JSONPathTransformerContext {
 
   /**
    * @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];
@@ -796,12 +922,90 @@ class JSONPathTransformerContext {
    * @param {string} name - Key name
    * @param {string} match - Match expression
    * @param {string} use - Use expression
-   * @returns {JSONPathTransformerContext}
+   * @returns {this}
    */
   key (name, match, use) {
     this.keys[name] = {match, use};
     return this;
   }
+
+  /**
+   * Conditionally execute a callback when a JSONPath selector evaluates
+   * to a truthy scalar or a non-empty result set (node set analogue).
+   * Mirrors XSLT's xsl:if semantics where a non-empty node set is truthy.
+   *
+   * Truthiness rules:
+   * - If the selection (with wrap) yields an array with length > 0, the
+   *   condition passes.
+   * - Otherwise the (non-wrapped) scalar value is coerced with Boolean();
+   *   e.g., 0, '', null, undefined => false; others => true.
+   *
+   * @param {string} select - JSONPath selector expression
+   * @param {(this: JSONPathTransformerContext<T>)
+   *   => void} cb - Callback to invoke if condition is met
+   * @returns {this}
+   */
+  if (select, cb) {
+    const passes = this._passesIf(select);
+    if (passes && typeof cb === 'function') {
+      cb.call(this);
+    }
+    return this;
+  }
+
+  /**
+   * Internal helper: determine if `select` passes truthiness test.
+   * Non-empty wrapped results => true; single item: objects truthy,
+   * primitives coerced via Boolean().
+   * @param {string} select
+   * @returns {boolean}
+   */
+  _passesIf (select) {
+    // Evaluate with wrapping to detect non-empty match sets
+    /** @type {any} */ const wrapped = this.get(select, true);
+    if (Array.isArray(wrapped)) {
+      if (wrapped.length === 0) {
+        return false;
+      }
+      if (wrapped.length > 1) {
+        // Multiple matches (node set analogue) => truthy
+        return true;
+      }
+      // Single item; apply scalar truthiness
+      const single = wrapped[0];
+      // Objects (arrays) always truthy; primitives use Boolean()
+      if (single && typeof single === 'object') {
+        return true;
+      }
+      return Boolean(single);
+    }
+    /* c8 ignore next 3 -- unreachable defensive non-array branch:
+     * jsonpath-plus with wrap:true always returns arrays. */
+    // Fallback if library behavior changed in future
+    return Boolean(wrapped);
+  }
+
+  /**
+   * Like `if()`, but also supports an optional fallback callback executed
+   * when the test does not pass (similar to xsl:choose/xsl:otherwise).
+   * @param {string} select JSONPath selector
+   * @param {(this: JSONPathTransformerContext<T>)
+   *   => void} whenCb Callback when condition passes
+   * @param {(this: JSONPathTransformerContext<T>)
+   *   => void} [otherwiseCb] Callback when condition fails
+   * @returns {this}
+   */
+  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;
+  }
 }
 
 export default JSONPathTransformerContext;