jtlt 0.1.0

package/src/JSONPathTransformerContext.js

@@ -0,0 +1,807 @@
+import {JSONPath as jsonpath} from 'jsonpath-plus';
+import JSONPathTransformer from './JSONPathTransformer.js';
+
+/**
+ * Execution context for JSONPath-driven template application.
+ *
+ * Holds the current node, parent, path, variables, and property sets while
+ * 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.
+ */
+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
+   */
+  constructor (config, templates) {
+    this._config = config;
+    this._templates = templates;
+    this._contextObj = this._origObj = config.data;
+    this._parent = config.parent || this._config;
+    this._parentProperty = config.parentProperty || 'data';
+    /** @type {Record<string, any>} */
+    this.vars = {};
+    /** @type {Record<string, any>} */
+    this.propertySets = {};
+    /** @type {Record<string, any>} */
+    this.keys = {};
+    /** @type {boolean | undefined} */
+    this._initialized = undefined;
+    /** @type {string | undefined} */
+    this._currPath = undefined;
+  }
+
+  /**
+   * Triggers an error if equal priority templates are found.
+   * @returns {void}
+   */
+  _triggerEqualPriorityError () {
+    if (this._config.errorOnEqualPriority) {
+      throw new Error(
+        'You have configured JSONPathTransformer to throw errors on ' +
+        'finding templates of equal priority and these have been found.'
+      );
+    }
+  }
+
+  /**
+   * Gets the joining transformer from config.
+   * @returns {any} The joining transformer
+   */
+  _getJoiningTransformer () {
+    return this._config.joiningTransformer;
+  }
+
+  /**
+   * @param {*} item - Item to append to output
+   * @returns {JSONPathTransformerContext}
+   */
+  appendOutput (item) {
+    /** @type {any} */ (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
+   */
+  getOutput () {
+    return /** @type {any} */ (this._getJoiningTransformer()).get();
+  }
+
+  /**
+   * Get() and set() are provided as a convenience method for templates, but
+   *   it should typically not be used (use valueOf or the copy methods to add
+   *   to the result tree instead).
+   * @param {string} select - JSONPath selector
+   * @param {boolean} wrap - Whether to wrap results
+   * @returns {*} The selected value(s)
+   */
+  get (select, wrap) {
+    if (select) {
+      return /** @type {any} */ (jsonpath)({
+        path: select, json: this._contextObj,
+        preventEval: this._config.preventEval,
+        wrap: wrap || false, returnType: 'value'
+      });
+    }
+    return this._contextObj;
+  }
+
+  /**
+   * @param {*} v - Value to set
+   * @returns {JSONPathTransformerContext}
+   */
+  set (v) {
+    (/** @type {Record<string, any>} */ (this._parent))[
+      this._parentProperty
+    ] = v;
+    return this;
+  }
+
+  /**
+   * Apply matching templates to nodes selected by JSONPath, optionally sorted.
+   *
+   * Sort parameter forms:
+   * - string: JSONPath relative to each match (e.g., '$.name' or '@')
+   * - function: comparator (aValue, bValue, ctx) => number
+   * - object: { select, order='ascending'|'descending', type='text'|'number',
+   *            locale, localeOptions }
+   * - array: multiple key objects/strings in priority order.
+   *
+   * @param {string|object} select - JSONPath selector or options object
+   * @param {string} [mode] - Mode to apply
+   * @param {string|Function|object|Array<string|object>} [sort] - Sort spec
+   * @returns {JSONPathTransformerContext}
+   */
+  applyTemplates (select, mode, sort) {
+    // Matches templates by (path, mode), resolves priority, and invokes each
+    //   template in document order (or sorted order) for all nodes selected by
+    //   `select`.
+    // 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;
+    }
+    if (!this._initialized) {
+      select = select || '$';
+      this._currPath = '$';
+      this._initialized = true;
+    } else {
+      select = select || '*';
+    }
+    // Preserve original selector to support special suffixes (e.g., "$~")
+    const originalSelect = /** @type {string} */ (select);
+    select = JSONPathTransformer.makeJSONPathAbsolute(originalSelect);
+    const propertyNamesMode = select.endsWith('~');
+    const jsonPathExpr = propertyNamesMode ? select.slice(0, -1) : select;
+    // Todo: Use results here?
+    /* const results = */ this._getJoiningTransformer();
+    const modeMatchedTemplates = this._templates.filter(function (templateObj) {
+      return ((mode && mode === templateObj.mode) ||
+        (!mode && !templateObj.mode));
+    });
+
+    // Collect matches first (to allow sorting), then process
+    /**
+     * @type {{
+     *   value:any, parent:any, parentProperty?:string, path:string
+     * }[]}
+     */
+    const matches = /** @type {any} */ (jsonpath)({
+      path: jsonPathExpr,
+      resultType: 'all',
+      wrap: true,
+      json: this._contextObj,
+      preventEval: this._config.preventEval
+    });
+
+    // Sorting utilities
+    /**
+     * @param {string} expr
+     * @param {any} ctxVal
+     * @returns {any}
+     */
+    function evalInContext (expr, ctxVal) {
+      if (!expr) {
+        return undefined;
+      }
+      if (expr === '.' || expr === '@') {
+        return ctxVal;
+      }
+      return /** @type {any} */ (jsonpath)({
+        path: expr,
+        json: ctxVal,
+        preventEval: that._config.preventEval,
+        wrap: false, returnType: 'value'
+      });
+    }
+    /**
+     * @param {any} aVal
+     * @param {any} bVal
+     * @param {{
+     *   order?: 'ascending'|'descending', type?: 'text'|'number',
+     *   locale?: string, localeOptions?: any
+     * }|undefined} spec
+     * @returns {number}
+     */
+    function compareBySpec (aVal, bVal, spec) {
+      const order = (spec && spec.order === 'descending') ? -1 : 1;
+      const type = (spec && spec.type) || 'text';
+      if (type === 'number') {
+        const an = Number(aVal);
+        const bn = Number(bVal);
+        if (Number.isNaN(an) && Number.isNaN(bn)) {
+          return 0;
+        }
+        if (Number.isNaN(an)) {
+          return Number(order);
+        }
+        if (Number.isNaN(bn)) {
+          return -1 * order;
+        }
+        return (an - bn) * order;
+      }
+      // text
+      const aStr = aVal === null || aVal === undefined ? '' : String(aVal);
+      const bStr = bVal === null || bVal === undefined ? '' : String(bVal);
+      if (spec && spec.locale) {
+        return aStr.localeCompare(
+          bStr, spec.locale, spec.localeOptions
+        ) * order;
+      }
+      return (aStr < bStr ? -1 : (aStr > bStr ? 1 : 0)) * order;
+    }
+    /**
+     * @param {any} sortSpec
+     * @returns {((a:{value:any}, b:{value:any})=>number)|null}
+     */
+    function buildComparator (sortSpec) {
+      if (!sortSpec) {
+        return null;
+      }
+      if (typeof sortSpec === 'function') {
+        return function (a, b) {
+          return sortSpec(a.value, b.value, that);
+        };
+      }
+      const specs = Array.isArray(sortSpec) ? sortSpec : [sortSpec];
+      return function (a, b) {
+        for (const s of specs) {
+          if (typeof s === 'string') {
+            const av = evalInContext(s, a.value);
+            const bv = evalInContext(s, b.value);
+            const c = compareBySpec(av, bv, {type: 'text', order: 'ascending'});
+            if (c !== 0) {
+              return c;
+            }
+          } else if (s && typeof s === 'object') {
+            const av = evalInContext(s.select, a.value);
+            const bv = evalInContext(s.select, b.value);
+            const c = compareBySpec(av, bv, s);
+            if (c !== 0) {
+              return c;
+            }
+          }
+        }
+        return 0;
+      };
+    }
+
+    const comparator = buildComparator(sort);
+    if (comparator) {
+      matches.sort(comparator);
+    }
+
+    // Preserve outer context across processing
+    const prevContext = that._contextObj;
+    const prevParent = that._parent;
+    const prevParentProp = that._parentProperty;
+    const prevCurrPath = that._currPath;
+
+    // Process in (sorted) order
+    for (const o of matches) {
+      const {value, parent, parentProperty, path} = o;
+      const _oldPath = that._currPath;
+      that._currPath += path.replace(/^\$/v, '');
+      const pathMatchedTemplates = modeMatchedTemplates.filter(
+        function (templateObj) {
+          const queryResult = /** @type {any[]} */ (
+            (/** @type {any} */ (jsonpath))({
+              path: JSONPathTransformer.makeJSONPathAbsolute(
+                templateObj.path
+              ),
+              json: that._origObj,
+              resultType: 'path',
+              preventEval: that._config.preventEval,
+              wrap: true
+            })
+          );
+          return (
+            /** @type {any[]} */ (queryResult)
+          ).includes(that._currPath);
+        }
+      );
+
+      let templateObj;
+      if (!pathMatchedTemplates.length) {
+        const dtr = JSONPathTransformer.DefaultTemplateRules;
+        if (propertyNamesMode) {
+          templateObj = dtr.transformPropertyNames;
+        } else if (Array.isArray(value)) {
+          templateObj = dtr.transformArrays;
+        } else if (value && typeof value === 'object') {
+          templateObj = dtr.transformObjects;
+        } else if (value && typeof value === 'function') {
+          templateObj = dtr.transformFunctions;
+        } else {
+          templateObj = dtr.transformScalars;
+        }
+      } else {
+        pathMatchedTemplates.sort(function (a, b) {
+          /* c8 ignore start -- Fallback to priority 0 when no numeric priority
+           * and no specificityPriorityResolver is extremely rare in practice.
+           * Requires: template without priority property AND no resolver AND
+           * multiple templates matching same path. Equal priorities then
+           * trigger error, making the `: 0` branch nearly unreachable. */
+          const aPriority = typeof a.priority === 'number'
+            ? a.priority
+            : (that._config.specificityPriorityResolver
+              ? that._config.specificityPriorityResolver(a.path)
+              : 0);
+          const bPriority = typeof b.priority === 'number'
+            ? b.priority
+            : (that._config.specificityPriorityResolver
+              ? that._config.specificityPriorityResolver(b.path)
+              : 0);
+          /* c8 ignore stop */
+
+          if (aPriority === bPriority) {
+            that._triggerEqualPriorityError();
+          }
+
+          return (aPriority > bPriority) ? -1 : 1;
+        });
+
+        templateObj = pathMatchedTemplates.shift();
+      }
+
+      that._contextObj = value;
+      that._parent = parent;
+      that._parentProperty = (parentProperty ?? that._parentProperty);
+
+      const ret = templateObj.template.call(
+        that, value, {mode, parent, parentProperty}
+      );
+      if (typeof ret !== 'undefined') {
+        that._getJoiningTransformer().append(ret);
+      }
+
+      that._contextObj = value;
+      that._parent = parent;
+      that._parentProperty = (parentProperty ?? that._parentProperty);
+      that._currPath = _oldPath;
+    }
+    // Restore outer context
+    that._contextObj = prevContext;
+    that._parent = prevParent;
+    that._parentProperty = prevParentProp;
+    that._currPath = prevCurrPath;
+    return this;
+  }
+
+  /**
+   * @param {string|object} name - Template name or options object
+   * @param {any[]} [withParams] - Parameters to pass to template
+   * @returns {JSONPathTransformerContext}
+   */
+  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 = withParams || [];
+    const paramValues = withParams.map(function (withParam) {
+      return withParam.value || that.get(withParam.select, false);
+    });
+    const results = this._getJoiningTransformer();
+    const templateObj = this._templates.find(function (template) {
+      return template.name === name;
+    });
+    if (!templateObj) {
+      throw new Error(
+        'Template, ' + name + ', cannot be called as it was not found.'
+      );
+    }
+
+    const result = templateObj.template.apply(this, paramValues);
+    /** @type {any} */ (results).append(result);
+    return this;
+  }
+
+  /**
+   * Iterate over values selected by JSONPath, optionally sorted.
+   *
+   * 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}
+   */
+  forEach (select, cb, sort) {
+    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
+    const that = this;
+    /** @type {{value:any}[]} */
+    const matches = /** @type {any} */ (jsonpath)({
+      path: select,
+      json: this._contextObj,
+      preventEval: this._config.preventEval,
+      wrap: true,
+      resultType: 'all'
+    });
+
+    /**
+     * @param {string} expr
+     * @param {any} ctxVal
+     * @returns {any}
+     */
+    function feEvalInContext (expr, ctxVal) {
+      if (!expr) {
+        return undefined;
+      }
+      if (expr === '.' || expr === '@') {
+        return ctxVal;
+      }
+      return /** @type {any} */ (jsonpath)({
+        path: expr,
+        json: ctxVal,
+        preventEval: that._config.preventEval,
+        wrap: false, returnType: 'value'
+      });
+    }
+    /**
+     * @param {any} aVal
+     * @param {any} bVal
+     * @param {{
+     *   order?: 'ascending'|'descending', type?: 'text'|'number',
+     *   locale?: string, localeOptions?: any
+     * }|undefined} spec
+     * @returns {number}
+     */
+    function feCompareBySpec (aVal, bVal, spec) {
+      const order = (spec && spec.order === 'descending') ? -1 : 1;
+      const type = (spec && spec.type) || 'text';
+      if (type === 'number') {
+        const an = Number(aVal);
+        const bn = Number(bVal);
+        if (Number.isNaN(an) && Number.isNaN(bn)) {
+          return 0;
+        }
+        if (Number.isNaN(an)) {
+          return Number(order);
+        }
+        if (Number.isNaN(bn)) {
+          return -1 * order;
+        }
+        return (an - bn) * order;
+      }
+      const aStr = aVal === null || aVal === undefined ? '' : String(aVal);
+      const bStr = bVal === null || bVal === undefined ? '' : String(bVal);
+      if (spec && spec.locale) {
+        return aStr.localeCompare(
+          bStr, spec.locale, spec.localeOptions
+        ) * order;
+      }
+      return (aStr < bStr ? -1 : (aStr > bStr ? 1 : 0)) * order;
+    }
+    /**
+     * @param {any} sortSpec
+     * @returns {((a:{value:any}, b:{value:any})=>number)|null}
+     */
+    function feBuildComparator (sortSpec) {
+      if (!sortSpec) {
+        return null;
+      }
+      if (typeof sortSpec === 'function') {
+        return function (a, b) {
+          return sortSpec(a.value, b.value, that);
+        };
+      }
+      const specs = Array.isArray(sortSpec) ? sortSpec : [sortSpec];
+      return function (a, b) {
+        for (const s of specs) {
+          if (typeof s === 'string') {
+            const av = feEvalInContext(s, a.value);
+            const bv = feEvalInContext(s, b.value);
+            const c = feCompareBySpec(
+              av, bv, {type: 'text', order: 'ascending'}
+            );
+            if (c !== 0) {
+              return c;
+            }
+          } else if (s && typeof s === 'object') {
+            const av = feEvalInContext(s.select, a.value);
+            const bv = feEvalInContext(s.select, b.value);
+            const c = feCompareBySpec(av, bv, s);
+            if (c !== 0) {
+              return c;
+            }
+          }
+        }
+        return 0;
+      };
+    }
+
+    const comparator = feBuildComparator(sort);
+    const list = comparator ? [...matches].toSorted(comparator) : matches;
+    for (const m of list) {
+      cb.call(that, m.value);
+    }
+    return this;
+  }
+
+  /**
+   * @param {string|object} [select] - JSONPath selector
+   * @returns {JSONPathTransformerContext}
+   */
+  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);
+    /** @type {any} */ (results).append(result);
+    return this;
+  }
+
+  /**
+   * Deep copy selection or current context when omitted.
+   * @param {string} [select] - JSONPath selector
+   * @returns {JSONPathTransformerContext}
+   */
+  copyOf (select) { // Deep
+    // Deeply clones the value at `select` (or current context if omitted)
+    // and appends the clone to output. Cycles supported if structuredClone
+    // available; otherwise falls back to JSON serialization (dropping
+    // functions/undefined).
+    const val = select ? this.get(select, false) : this._contextObj;
+    // If JSONPath returned array of matches (wrap true not used here), we
+    // just copy the raw value which should be scalar/object/array/function.
+    // For functions or non-serializable values, structuredClone may throw.
+    /** @type {any} */ let clone;
+    if (val && typeof val === 'object') {
+      /* c8 ignore try -- structuredClone existence depends on runtime */
+      try {
+        // Prefer native structuredClone when available.
+        clone = typeof structuredClone === 'function'
+          ? structuredClone(val)
+          // Fall back to a (potentially shallow) spread clone when deep
+          // cloning utility unavailable; better than lossy JSON stringify.
+          : (Array.isArray(val) ? [...val] : {...val});
+      } catch {
+        /* c8 ignore start -- structuredClone error fallback attribution can
+         * 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;
+          }
+        }
+        // For non-functions, attempting structuredClone again would rethrow;
+        // use shallow clone to retain non-serializable props like Symbols.
+        clone = Array.isArray(val) ? [...val] : {...val};
+        /* c8 ignore stop */
+      }
+    } else {
+      // Primitives/functions copied by value/reference semantics naturally.
+      clone = val;
+    }
+    /** @type {any} */ (this._getJoiningTransformer()).append(clone);
+    return this;
+  }
+
+  /**
+   * Shallow copy current context; optionally merge property set names.
+   * @param {string[]} [propertySets] - Property sets to merge
+   * @returns {JSONPathTransformerContext}
+   */
+  copy (propertySets) { // Shallow
+    // Creates a shallow clone of current context object/array (or primitive)
+    // and appends it. If `propertySets` is an array of names, merges those
+    // named property sets (if found) into the top-level shallow copy.
+    const src = this._contextObj;
+    /** @type {any} */ let clone;
+    if (src && typeof src === 'object') {
+      clone = Array.isArray(src) ? [...src] : {...src};
+      if (Array.isArray(propertySets)) {
+        for (const ps of propertySets) {
+          if (this.propertySets[ps]) {
+            Object.assign(clone, this.propertySets[ps]);
+          }
+        }
+      }
+    } 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);
+    return this;
+  }
+
+  /**
+   * @param {string} name - Variable name
+   * @param {string} select - JSONPath selector
+   * @returns {JSONPathTransformerContext}
+   */
+  variable (name, select) {
+    this.vars[name] = this.get(select, false);
+    return this;
+  }
+
+  /**
+   * @param {*} json - JSON data to log
+   * @returns {void}
+   */
+  // eslint-disable-next-line class-methods-use-this -- Convenient
+  message (json) {
+    // eslint-disable-next-line no-console -- Ok
+    console.log(json);
+  }
+
+  /**
+   * @param {string} str - String value
+   * @param {Function} cb - Callback function
+   * @returns {JSONPathTransformerContext}
+   */
+  // 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}
+   */
+  number (num) {
+    /** @type {any} */ (this._getJoiningTransformer()).number(num);
+    return this;
+  }
+
+  /**
+   * 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}
+   */
+  plainText (str) {
+    /** @type {any} */ (this._getJoiningTransformer()).plainText(str);
+    return this;
+  }
+
+  /**
+   * 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}
+   */
+  propValue (prop, val) {
+    /** @type {any} */ (this._getJoiningTransformer()).propValue(prop, val);
+    return this;
+  }
+
+  /**
+   * Build an object. Mirrors the joining transformer API. All joiners now
+   * 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}
+   */
+  object (...args) {
+    /** @type {any} */ (this._getJoiningTransformer()).object(...args);
+    return this;
+  }
+
+  /**
+   * 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}
+   */
+  array (...args) {
+    /** @type {any} */ (this._getJoiningTransformer()).array(...args);
+    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 {any[]} [children] - Child nodes
+   * @param {Function} [cb] - Callback function
+   * @returns {JSONPathTransformerContext}
+   */
+  element (name, atts, children, cb) {
+    /** @type {any} */ (this._getJoiningTransformer()).element(
+      name, atts, children, cb
+    );
+    return this;
+  }
+
+  /**
+   * 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}
+   */
+  attribute (name, val, avoidAttEscape) {
+    /** @type {any} */ (this._getJoiningTransformer()).attribute(
+      name, val, avoidAttEscape
+    );
+    return this;
+  }
+
+  /**
+   * Append text content. Mirrors the joining transformer API so templates can
+   * call `this.text()`.
+   * @param {string} txt - Text content
+   * @returns {JSONPathTransformerContext}
+   */
+  text (txt) {
+    /** @type {any} */ (this._getJoiningTransformer()).text(txt);
+    return this;
+  }
+
+  /**
+   * @param {string} name - Property set name
+   * @param {object} propertySetObj - Property set object
+   * @param {any[]} [usePropertySets] - Property sets to use
+   * @returns {JSONPathTransformerContext}
+   */
+  propertySet (name, propertySetObj, usePropertySets) {
+    // eslint-disable-next-line unicorn/no-this-assignment -- Temporary
+    const that = this;
+    this.propertySets[name] = usePropertySets
+      ? ({
+        ...propertySetObj,
+        ...usePropertySets.reduce((obj, psName) => {
+          return that._usePropertySets(obj, psName);
+        }, {})
+      })
+      : propertySetObj;
+    return this;
+  }
+
+  /**
+   * @param {object} obj - Object to assign properties to
+   * @param {string} name - Property set name
+   * @returns {object}
+   */
+  _usePropertySets (obj, name) {
+    return Object.assign(obj, this.propertySets[name]);
+  }
+
+  /**
+   * @param {string} name - Key name
+   * @param {*} value - Value to match
+   * @returns {*}
+   */
+  getKey (name, value) {
+    const key = this.keys[name];
+    const matches = this.get(key.match, true);
+    for (const match of matches) { // For objects or arrays
+      if (match && typeof match === 'object' &&
+        match[key.use] === value) {
+        return match;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * @param {string} name - Key name
+   * @param {string} match - Match expression
+   * @param {string} use - Use expression
+   * @returns {JSONPathTransformerContext}
+   */
+  key (name, match, use) {
+    this.keys[name] = {match, use};
+    return this;
+  }
+}
+
+export default JSONPathTransformerContext;