jtlt 0.1.0

package/src/XPathTransformerContext.js

@@ -0,0 +1,496 @@
+import xpath2 from 'xpath2.js'; // Runtime JS import; ambient types declared
+// xpathVersion: 1 => browser/native XPathEvaluator API; 2 => xpath2.js
+
+/**
+ * Execution context for XPath-driven template application.
+ *
+ * Similar to JSONPathTransformerContext but uses XPath expressions on a
+ * DOM/XML-like tree. Supports XPath 1.0 (default) or 2.0 when
+ * `xpathVersion: 2`.
+ *
+ * Expected config:
+ * - data: A Document, Element, or XML-like root node.
+ * - joiningTransformer: joiner with append(), string(), object(), array(), etc.
+ * - xpathVersion: 1|2 (default 1)
+ * - errorOnEqualPriority, specificityPriorityResolver (same semantics).
+ */
+class XPathTransformerContext {
+  /**
+   * @param {object} config - Configuration object
+   * @param {Document|Element|any} config.data - XML/DOM root to transform
+   * @param {number} [config.xpathVersion] - 1 or 2 (default 1)
+  * @param {object} config.joiningTransformer Joiner
+  * @param {Function} config.joiningTransformer.append Append output
+  * @param {Function} config.joiningTransformer.get Get output
+  * @param {Function} config.joiningTransformer.string Emit string
+  * @param {Function} config.joiningTransformer.object Emit object
+  * @param {Function} config.joiningTransformer.array Emit array
+   * @param {boolean} [config.errorOnEqualPriority]
+   * @param {Function} [config.specificityPriorityResolver]
+   * @param {any[]} templates - Template objects
+   */
+  constructor (config, templates) {
+    this._config = config;
+    this._templates = templates;
+    this._contextNode = this._origNode = config.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; // XPath string of current context
+  }
+
+  /** @returns {any} */
+  _getJoiningTransformer () {
+    return this._config.joiningTransformer;
+  }
+
+  /**
+   * Evaluate an XPath expression against the current context node.
+   * @param {string} expr - XPath expression
+  * @param {boolean} [asNodes] Return nodes (array) instead of scalar
+   * @returns {any}
+   */
+  _evalXPath (expr, asNodes) {
+    if (!expr) {
+      return this._contextNode;
+    }
+    const version = this._config.xpathVersion === 2 ? 2 : 1;
+    if (version === 1) {
+      // Use native XPath (browser-like); rely on DOM doc if available.
+      const doc = this._contextNode && this._contextNode.ownerDocument
+        ? this._contextNode.ownerDocument
+        : (this._contextNode.nodeType === 9 ? this._contextNode : undefined);
+      if (!doc || typeof doc.evaluate !== 'function') {
+        throw new Error(
+          'Native XPath unavailable for xpathVersion=1'
+        );
+      }
+      // Evaluate relative to current node. Namespace support optional.
+      const resolver = null; // Placeholder for future namespaceResolver config
+      /* c8 ignore start -- environment-dependent XPathResult availability */
+      const type = asNodes
+        ? (
+          globalThis.XPathResult
+            ? globalThis.XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
+            : 7
+        )
+        : (
+          globalThis.XPathResult
+            ? globalThis.XPathResult.ANY_TYPE
+            : 0
+        );
+      /* c8 ignore stop */
+      const resultObj = doc.evaluate(
+        expr, this._contextNode, resolver, type, null
+      );
+      if (asNodes) {
+        const arr = [];
+        for (let i = 0; i < resultObj.snapshotLength; i++) {
+          arr.push(resultObj.snapshotItem(i));
+        }
+        return arr;
+      }
+      // Handle primitive types from XPathResult
+      const XR = globalThis.XPathResult || {};
+      /* c8 ignore start -- JSDOM's XPath implementation does not properly
+       * set resultType for STRING_TYPE, NUMBER_TYPE, or BOOLEAN_TYPE. These
+       * branches work in real browsers but cannot be tested in JSDOM. */
+      switch (resultObj.resultType) {
+      case XR.STRING_TYPE: return resultObj.stringValue;
+      case XR.NUMBER_TYPE: return resultObj.numberValue;
+      case XR.BOOLEAN_TYPE: return resultObj.booleanValue;
+        /* c8 ignore stop */
+        /* c8 ignore start -- iterator result branch env-dependent */
+      case XR.UNORDERED_NODE_ITERATOR_TYPE:
+      case XR.ORDERED_NODE_ITERATOR_TYPE: {
+        /* c8 ignore start -- jsdom yields snapshots; iterator traversal
+         * validated logically but not triggered in this environment. */
+        const nodes = [];
+        let n = resultObj.iterateNext();
+        while (n) {
+          nodes.push(n);
+          n = resultObj.iterateNext();
+        }
+        return nodes;
+      }
+      /* c8 ignore stop */
+      /* c8 ignore start -- Default fallback for unsupported XPathResult
+       * types; environment-dependent and not hit under jsdom. */
+      default:
+        // Fallback: return original context for unsupported types
+        return this._contextNode;
+      /* c8 ignore stop */
+      }
+    }
+    // Version 2: xpath2.js
+    const result = xpath2.evaluate(expr, this._contextNode);
+    if (asNodes) {
+      /* c8 ignore next -- array wrap/identity branch counted in other tests */
+      return Array.isArray(result) ? result : [result];
+    }
+    /* c8 ignore next -- scalar return trivial; wrap behavior tested */
+    return result;
+  }
+
+  /**
+   * Append raw item to output.
+   * @param {*} item
+   * @returns {XPathTransformerContext}
+   */
+  appendOutput (item) {
+    this._getJoiningTransformer().append(item);
+    return this;
+  }
+
+  /** @returns {*} */
+  getOutput () {
+    return this._getJoiningTransformer().get();
+  }
+
+  /**
+   * Get value(s) by XPath relative to current context.
+   * @param {string} select - XPath expression
+   * @param {boolean} [asNodes]
+   * @returns {*}
+   */
+  get (select, asNodes) {
+    return this._evalXPath(select, Boolean(asNodes));
+  }
+
+  /**
+   * Set current context's parent property (for parity with JSONPath context).
+   * Mostly placeholder for object-mirroring behavior.
+   * @param {*} v
+   * @returns {XPathTransformerContext}
+   */
+  set (v) {
+    this._contextNode = v;
+    return this;
+  }
+
+  /**
+   * Apply templates to nodes matched by an XPath expression.
+   * @param {string} select - XPath expression (default '.')
+   * @param {string} [mode]
+   * @returns {XPathTransformerContext}
+   */
+  applyTemplates (select, mode) {
+    // Initialization similar to JSONPath context
+    if (!this._initialized) {
+      select = select || '.';
+      this._currPath = '.'; // Root context indicator
+      this._initialized = true;
+    } else {
+      select = select || '*';
+    }
+    const nodes = this._evalXPath(select, true);
+    const modeMatched = this._templates.filter((t) => (
+      mode ? t.mode === mode : !t.mode
+    ));
+    // Process each node
+    for (const node of nodes) {
+    // Path resolution simplified (could track full XPath if needed)
+      const pathMatchedTemplates = modeMatched.filter((t) => {
+        // Basic matching: template.path is XPath tested for existence
+        try {
+          const res = this._evalXPath(t.path, true);
+          return res.includes(node);
+        } catch {
+          return false;
+        }
+      });
+      let templateObj;
+      if (!pathMatchedTemplates.length) { // default template rule branches
+        // Default template rules (simplified compared to JSON version)
+        const DTR = XPathTransformerContext.DefaultTemplateRules;
+        // Treat Document (9) like Element (1) so the default root rule
+        // descends into children when no template matches the Document.
+        /* c8 ignore start -- nodeType default-rule union env-stable */
+        if (node && (node.nodeType === 1 || node.nodeType === 9)) {
+          // Element or Document
+          templateObj = DTR.transformElements;
+        } else if (node && node.nodeType === 3) { // Text
+          templateObj = DTR.transformTextNodes;
+        } else {
+          templateObj = DTR.transformScalars;
+        }
+        /* c8 ignore stop */
+      } else {
+        // Sort by priority (numeric or specificity resolver)
+        pathMatchedTemplates.sort((a, b) => {
+          const aPr = typeof a.priority === 'number'
+            ? a.priority
+            : (this._config.specificityPriorityResolver
+              ? this._config.specificityPriorityResolver(a.path)
+              : 0);
+          const bPr = typeof b.priority === 'number'
+            ? b.priority
+            : (this._config.specificityPriorityResolver
+              ? this._config.specificityPriorityResolver(b.path)
+              : 0);
+          if (aPr === bPr && this._config.errorOnEqualPriority) {
+            throw new Error('Equal priority templates found.');
+          }
+          return aPr > bPr ? -1 : 1;
+        });
+        templateObj = pathMatchedTemplates.shift();
+      }
+      this._contextNode = node;
+      const ret = templateObj.template.call(this, node, {mode});
+      if (typeof ret !== 'undefined') {
+        this._getJoiningTransformer().append(ret);
+      }
+      this._contextNode = node; // Restore (placeholder for more complex state)
+    }
+    return this;
+  }
+
+  /**
+   * Iterate over nodes selected by XPath.
+   * @param {string} select - XPath expression
+   * @param {Function} cb - Callback invoked per node
+   * @returns {XPathTransformerContext}
+   */
+  forEach (select, cb) {
+    const nodes = this._evalXPath(select, true);
+    for (const n of nodes) {
+      cb.call(this, n);
+    }
+    return this;
+  }
+
+  /**
+   * Append the value from an XPath expression or the context node text.
+   * @param {string|object} [select]
+   * @returns {XPathTransformerContext}
+   */
+  valueOf (select) {
+    const jt = this._getJoiningTransformer();
+    let val;
+    if (!select || (
+      typeof select === 'object' && /** @type {any} */ (select).select === '.'
+    )) {
+      val = this._contextNode.nodeType === 3
+        ? this._contextNode.nodeValue
+        : this._contextNode.textContent;
+    } else {
+      const res = this._evalXPath(/** @type {string} */ (select), true);
+      // Simplify: use textContent of first match if node, else raw
+      const first = res[0];
+      val = first && first.nodeType ? first.textContent : first;
+    }
+    jt.append(val);
+    return this;
+  }
+
+  /**
+   * Define a variable by XPath selection (stores node array if nodes).
+   * @param {string} name Variable name
+   * @param {string} select XPath expression
+   * @returns {XPathTransformerContext}
+   */
+  variable (name, select) {
+    this.vars[name] = this.get(select, true);
+    return this;
+  }
+  /**
+   * Log a message (for debugging).
+   * @param {*} json Any value
+   * @returns {void}
+   */
+  static message (json) {
+    /* eslint-disable-next-line no-console -- Debug output */
+    console.log(json);
+  }
+  /**
+   * Append string.
+   * @param {string} str String to append
+   * @param {Function} [cb] Callback
+   * @returns {XPathTransformerContext}
+   */
+  string (str, cb) {
+    this._getJoiningTransformer().string(str, cb);
+    return this;
+  }
+  /**
+   * Append number.
+   * @param {number} num Number
+   * @returns {XPathTransformerContext}
+   */
+  number (num) {
+    this._getJoiningTransformer().number(num);
+    return this;
+  }
+  /**
+   * Append plain text (no escaping changes).
+   * @param {string} str Text
+   * @returns {XPathTransformerContext}
+   */
+  plainText (str) {
+    this._getJoiningTransformer().plainText(str);
+    return this;
+  }
+  /**
+   * Append property/value pair.
+   * @param {string} prop Property name
+   * @param {*} val Value
+   * @returns {XPathTransformerContext}
+   */
+  propValue (prop, val) {
+    this._getJoiningTransformer().propValue(prop, val);
+    return this;
+  }
+  /**
+   * Append object.
+   * @param {...any} args Object args
+   * @returns {XPathTransformerContext}
+   */
+  object (...args) {
+    this._getJoiningTransformer().object(...args);
+    return this;
+  }
+  /**
+   * Append array.
+   * @param {...any} args Array args
+   * @returns {XPathTransformerContext}
+   */
+  array (...args) {
+    this._getJoiningTransformer().array(...args);
+    return this;
+  }
+  /**
+   * Append element.
+   * @param {string} name Tag name
+   * @param {object} [atts] Attributes
+   * @param {any[]} [children] Children
+   * @param {Function} [cb] Callback
+   * @returns {XPathTransformerContext}
+   */
+  element (name, atts, children, cb) {
+    this._getJoiningTransformer().element(name, atts, children, cb);
+    return this;
+  }
+  /**
+   * Append attribute.
+   * @param {string} name Attribute name
+   * @param {string|object} val Value
+   * @param {boolean} [avoid] Avoid duplicates
+   * @returns {XPathTransformerContext}
+   */
+  attribute (name, val, avoid) {
+    this._getJoiningTransformer().attribute(name, val, avoid);
+    return this;
+  }
+  /**
+   * Append text node content.
+   * @param {string} txt Text
+   * @returns {XPathTransformerContext}
+   */
+  text (txt) {
+    this._getJoiningTransformer().text(txt);
+    return this;
+  }
+  /**
+   * Define a property set (optionally composed from other sets).
+   * @param {string} name Property set name
+   * @param {object} obj Base properties
+   * @param {string[]} [use] Property set names to merge
+   * @returns {XPathTransformerContext}
+   */
+  propertySet (name, obj, use) {
+    this.propertySets[name] = use
+      ? ({
+        ...obj,
+        ...use.reduce((acc, psName) => this._usePropertySets(acc, psName), {})
+      })
+      : obj;
+    return this;
+  }
+  /**
+   * Merge properties from a named property set into obj.
+   * @param {object} obj Target object
+   * @param {string} name Property set name
+   * @returns {object}
+   */
+  _usePropertySets (obj, name) {
+    return Object.assign(obj, this.propertySets[name]);
+  }
+  /**
+   * Retrieve a key-mapped node matching a value or return context.
+   * @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 m of matches) {
+      if (m && m.nodeType === 1) { // Element
+        if (m.getAttribute && m.getAttribute(key.use) === value) {
+          return m;
+        }
+      }
+    }
+    return this;
+  }
+  /**
+   * Register a key for later lookup.
+   * @param {string} name Key name
+   * @param {string} match XPath selecting nodes
+   * @param {string} use Attribute (or property) name to compare
+   * @returns {XPathTransformerContext}
+   */
+  key (name, match, use) {
+    this.keys[name] = {match, use};
+    return this;
+  }
+
+  /* c8 ignore start -- static default rules object has spotty function
+   * attribution under coverage; behavior is exercised via applyTemplates */
+  static DefaultTemplateRules = {
+    transformRoot: {
+      /**
+       * @param {*} node Root node
+       * @param {{mode:string}} cfg Config
+       * @returns {void}
+       */
+      template (node, cfg) {
+        /** @type {any} */ (this).applyTemplates('.', cfg.mode);
+      }
+    },
+    transformElements: {
+      /**
+       * @param {*} node Element node
+       * @param {{mode:string}} cfg Config
+       * @returns {void}
+       */
+      template (node, cfg) {
+        /** @type {any} */ (this).applyTemplates('*', cfg.mode);
+      }
+    },
+    transformTextNodes: {
+      /**
+       * @param {{nodeValue:string}} node Text node
+       * @returns {string}
+       */
+      template (node) {
+        return node.nodeValue;
+      }
+    },
+    transformScalars: {
+      /** @returns {*} */
+      template () {
+        return /** @type {any} */ (this).valueOf({select: '.'});
+      }
+    }
+  };
+  /* c8 ignore stop */
+}
+
+export default XPathTransformerContext;

package/src/XSLTStyleJSONPathResolver.js

@@ -0,0 +1,39 @@
+import {JSONPath} from 'jsonpath-plus';
+
+/**
+ * Computes a simple specificity score for JSONPath selectors inspired by XSLT.
+ *
+ * Used by the engine to break ties between templates when multiple JSONPath
+ * expressions match the same node. Lower values indicate broader matches
+ * (e.g., wildcards), while higher values indicate more specific matches.
+ */
+class XSLTStyleJSONPathResolver {
+  /**
+   * @param {string|string[]} path
+   * @returns {-0.5|0.5|0}
+   */
+  // eslint-disable-next-line class-methods-use-this -- Convenient
+  getPriorityBySpecificity (path) {
+    if (typeof path === 'string') {
+      path = JSONPath.toPathArray(path);
+    }
+
+    const terminal = path.at(-1);
+    // *, ~, @string() (comparable to XSLT's *, @*, and node tests,
+    //   respectively)
+    if (terminal && (/^(?:\*|~|@[a-z]*?\(\))$/vi).test(terminal)) {
+      return -0.5;
+    }
+    // ., .., [] or [()] or [(?)] (comparable to XSLT's /, //, or [],
+    //   respectively)
+    if (terminal && (/^(?:\.+|\[.*?\])$/v).test(terminal)) {
+      return 0.5;
+    }
+    // single name (i.e., $..someName or someName if allowing such
+    //   relative paths) (comparable to XSLT's identifying a particular
+    //   element or attribute name)
+    return 0;
+  }
+}
+
+export default XSLTStyleJSONPathResolver;