jtlt 0.2.0 → 0.4.0

package/src/JSONPathTransformerContext.js

@@ -1,6 +1,53 @@
 import {JSONPath as jsonpath} from 'jsonpath-plus';
 import JSONPathTransformer from './JSONPathTransformer.js';
 
+/**
+ * @typedef {number|string|{
+ *   value?: number|string,
+ *   count?: string,
+ *   format?: string,
+ *   groupingSeparator?: string,
+ *   groupingSize?: number,
+ *   lang?: string,
+ *   letterValue?: string
+ * }} NumberValue
+ */
+
+/**
+ * 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 +55,18 @@ 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
+   * Holds the current iteration state (for position calculations).
+   * @type {{ index?: number } | undefined}
+   */
+  iterationState;
+  /**
+   * @param {JSONPathTransformerContextConfig<T>} config
+   * @param {import('./index.js').JSONPathTemplateObject<T>[]} templates - Array
+   *   of template objects
    */
   constructor (config, templates) {
     this._config = config;
@@ -32,16 +74,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 +103,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 +135,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 +149,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 +169,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 +183,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 +200,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 +212,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 +281,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 +333,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 +380,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 +397,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 +434,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 +477,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 +493,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 +567,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,24 +613,181 @@ 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;
   }
 
+  /**
+   * 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: JSONPathTransformerContext<T>,
+   *     substring: string,
+   *     groups: string[],
+   *     regexGroup: (n: number) => string
+   *   ) => void,
+   *   nonMatchingSubstring?: (
+   *     this: JSONPathTransformerContext<T>,
+   *     substring: string
+   *   ) => void,
+   *   flags?: string
+   * }} options - Options object
+   * @returns {this}
+   */
+  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._contextObj;
+
+    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) {
+          this._contextObj = nonMatchingStr;
+          boundNonMatchingSubstring(nonMatchingStr);
+        }
+      }
+
+      // Process matching substring
+      if (boundMatchingSubstring) {
+        const matchingStr = match[0];
+        // Store captured groups: [full match, group1, group2, ...]
+        currentCapturedGroups = [...match];
+        this._contextObj = matchingStr;
+        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) {
+        this._contextObj = nonMatchingStr;
+        boundNonMatchingSubstring(nonMatchingStr);
+      }
+    }
+
+    // Restore previous context
+    this._contextObj = prevContext;
+
+    return this;
+  }
+
   /**
    * 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 +813,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 +828,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 +855,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 +870,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,35 +881,297 @@ 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;
   }
 
   /**
-   * 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}
+   * Append a number to JSON output with xsl:number-like formatting.
+   * @param {NumberValue} num - Number value, "position()" string, or
+   *   options object
+   * @returns {this}
    */
   number (num) {
-    /** @type {any} */ (this._getJoiningTransformer()).number(num);
+    // Handle xsl:number-like functionality
+    if (typeof num === 'object' && num !== null) {
+      const opts = num;
+      let {value} = opts;
+
+      // Handle position() and hierarchical numbering
+      if (value === 'position()' || value === undefined) {
+        const {count} = opts;
+        // @ts-expect-error: dynamic property access
+        const level = opts.level || 'single';
+
+        switch (level) {
+        case 'single': {
+          value = this.calculatePosition(count);
+          // If count is set, simulate count by returning total items
+          //   in current context
+          if (count) {
+            const arr = Array.isArray(this.get(count, true))
+              ? this.get(count, true)
+              /* c8 ignore next -- defensive: get(wrap) always returns array */
+              : [];
+            value = arr.length;
+          }
+
+          break;
+        }
+        case 'multiple': {
+          // Hierarchical numbering: get position for each ancestor up to root
+          const positions = [];
+          let state = /** @type {any} */ (this._config).iterationState;
+          while (state) {
+            // If count is set, use count for each ancestor if possible
+            if (count) {
+              const arr = Array.isArray(this.get(count, true))
+                ? this.get(count, true)
+                /* c8 ignore next -- defensive: get(wrap) returns array */
+                : [];
+              positions.unshift(arr.length);
+            } else {
+              positions.unshift(
+                state.index !== undefined
+                  ? state.index + 1
+                  /* c8 ignore next -- defensive: state always has index */
+                  : 1
+              );
+            }
+            state = state.parentState;
+          }
+          value = positions.join('.');
+
+          break;
+        }
+        case 'any': {
+          // Count all matching items up to current
+          value = this.calculatePosition(count);
+
+          break;
+        }
+        // No default
+        }
+      }
+
+      // Determine format string and locale
+      let format = opts.format || '1';
+      const locale = opts.lang || 'en';
+      const {letterValue} = opts;
+
+      // If letterValue is 'alphabetic', force alphabetic format
+      if (letterValue === 'alphabetic') {
+        format = (opts.format && (/^[aA]$/v).test(opts.format)) ? opts.format : 'a';
+      }
+
+      // Ensure value is a number or string for formatting
+      let numValue = value;
+      // If value is undefined, fallback to opts.value
+      if (typeof numValue === 'undefined') {
+        numValue = opts.value;
+      }
+      if (typeof numValue === 'string') {
+        numValue = Number(numValue);
+      }
+      if (typeof numValue !== 'number' || Number.isNaN(numValue)) {
+        numValue = 1;
+      }
+      const formatted = this._formatNumber(
+        numValue,
+        format,
+        opts.groupingSeparator,
+        opts.groupingSize,
+        locale
+      );
+
+      // Output as string if formatted, otherwise as number
+      if (format && format !== '1') {
+        this._getJoiningTransformer().plainText(formatted);
+      } else {
+        this._getJoiningTransformer().number(Number(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 in current iteration context.
+   * @param {string} [count] - JSONPath expression to match
+   * @returns {number}
+   */
+  calculatePosition (count) {
+    // If count is provided, return the length of the matched array from
+    //   the root data
+    if (count) {
+      const result = jsonpath({
+        path: count, json: this._origObj, resultType: 'value', wrap: true
+      });
+      if (Array.isArray(result)) {
+        if (result.length === 0) {
+          return 0;
+        }
+        // If the first item is an array, return its length
+        if (Array.isArray(result[0])) {
+          return result[0].length;
+        }
+        // Otherwise, return the number of matches
+        return result.length;
+      }
+      /* c8 ignore next 3 -- defensive:
+        jsonpath-plus with wrap:true always returns arrays */
+      return 0;
+    }
+    // Get current index from iteration state
+    const state = this.iterationState;
+    if (state && typeof state.index === 'number') {
+      return state.index + 1; // 1-indexed
+    }
+    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
+   * @param {number} [groupingSize] - Size of groups
+   * @param {string} [locale]
+   * @returns {string}
+   */
+  _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 directly to the output without escaping or JSON
    *   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 +1179,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 +1192,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 +1203,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 +1241,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 +1255,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 +1311,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 +1321,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 +1340,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;