@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/domParsing.js

@@ -0,0 +1,95 @@
+/**
+ * XML parsing through whatever DOM implementation is available.
+ *
+ * Stylesheets pulled in by xsl:import/xsl:include and documents returned by a
+ * `document()` loader may be XML strings. They are parsed with, in order: a
+ * DOMParser given to the engine (`domParser` option), the global
+ * `DOMParser` (browsers, or a jsdom/xmldom global installed by the host), or
+ * the DOMParser of the window owning the stylesheet document. Parse errors are
+ * detected through `getElementsByTagName`, which every DOM implementation
+ * has (xmldom, for one, has no `querySelector`).
+ *
+ * @module xslt/domParsing
+ */
+
+"use strict";
+
+/**
+ * Namespace Gecko puts its `parsererror` element in. A namespace name is an
+ * identifier compared as a string, never fetched, so http is correct here.
+ */
+const GECKO_PARSER_ERROR_NS =
+  "http://www.mozilla.org/newlayout/xml/parsererror.xml"; // NOSONAR
+
+/**
+ * @typedef {{parseFromString: (text: string, type: string) => Document}} DomParserLike
+ */
+
+/**
+ * The first `parsererror` element of a document parsed by a DOMParser, if
+ * any. Browsers and jsdom report malformed XML this way instead of throwing
+ * (xmldom throws, see {@link parseXml}).
+ *
+ * @param {Node|null|undefined} doc - A parsed document (or element)
+ * @returns {Element|null} The error element, or null when parsing succeeded
+ *
+ * @example
+ * findParseError(new DOMParser().parseFromString("<a>", "application/xml"));
+ * // <parsererror>…</parsererror>
+ */
+export function findParseError(doc) {
+  if (!doc?.getElementsByTagName) return null;
+  const plain = doc.getElementsByTagName("parsererror");
+  if (plain.length > 0) return plain[0];
+  const gecko = doc.getElementsByTagNameNS?.(
+    GECKO_PARSER_ERROR_NS,
+    "parsererror",
+  );
+  return gecko?.length > 0 ? gecko[0] : null;
+}
+
+/**
+ * Pick the DOMParser to use.
+ *
+ * @param {DomParserLike|null|undefined} configured - The engine's `domParser` option
+ * @param {Document|null|undefined} referenceDoc - A document whose window may
+ *   provide a DOMParser (usually the stylesheet)
+ * @returns {DomParserLike|null} A parser, or null when none is available
+ */
+export function resolveDomParser(configured, referenceDoc) {
+  if (configured) return configured;
+  const Parser =
+    globalThis.DOMParser ?? referenceDoc?.defaultView?.DOMParser ?? null;
+  return Parser ? new Parser() : null;
+}
+
+/**
+ * Parse an XML string into a document.
+ *
+ * @param {string} xml - The markup
+ * @param {DomParserLike|null} parser - The parser (see {@link resolveDomParser})
+ * @returns {Document} The parsed document
+ * @throws {Error} When no parser is available or the markup is not well formed
+ *
+ * @example
+ * parseXml("<a/>", new DOMParser()).documentElement.nodeName; // "a"
+ */
+export function parseXml(xml, parser) {
+  if (!parser) {
+    throw new Error(
+      "XML parsing not available in this environment: pass a domParser option or install a global DOMParser",
+    );
+  }
+  let doc;
+  try {
+    doc = parser.parseFromString(xml, "application/xml");
+  } catch (thrown) {
+    // xmldom's own DOMParser throws a ParseError instead
+    throw new Error(`XML parse error: ${thrown.message}`, {
+      cause: thrown,
+    });
+  }
+  const error = findParseError(doc);
+  if (error) throw new Error(`XML parse error: ${error.textContent}`);
+  return doc;
+}

package/src/xslt/elements.js

@@ -0,0 +1,57 @@
+/**
+ * XSLT element vocabulary.
+ *
+ * Single source of truth for the XSLT namespace URI and for the element names
+ * the engine can instantiate. `element-available()` reports against this table,
+ * so it stays in step with what {@link XsltEngine#instructionMethod} dispatches.
+ */
+
+"use strict";
+
+/** The XSLT 1.0 namespace URI. */
+export const XSLT_NAMESPACE = "http://www.w3.org/1999/XSL/Transform";
+
+/**
+ * Element names the engine dispatches, i.e. every element that
+ * `element-available()` must report as supported.
+ */
+export const XSLT_ELEMENTS = Object.freeze([
+  "apply-imports",
+  "apply-templates",
+  "attribute",
+  "call-template",
+  "choose",
+  "comment",
+  "copy",
+  "copy-of",
+  "element",
+  "fallback",
+  "for-each",
+  "if",
+  "message",
+  "number",
+  "otherwise",
+  "param",
+  "processing-instruction",
+  "sort",
+  "text",
+  "value-of",
+  "variable",
+  "when",
+  "with-param",
+]);
+
+const ELEMENT_SET = new Set(XSLT_ELEMENTS);
+
+/**
+ * Check whether an XSLT element local name is supported by the engine.
+ *
+ * @param {string} localName - Element local name, e.g. `for-each`
+ * @returns {boolean} True when the engine instantiates the element
+ *
+ * @example
+ * isXsltElementAvailable('for-each'); // true
+ */
+export function isXsltElementAvailable(localName) {
+  return ELEMENT_SET.has(localName);
+}

package/src/xslt/engine/bindings.js

@@ -0,0 +1,195 @@
+/**
+ * Variables and parameters: external parameter values, the global bindings
+ * of a transformation, variable values, xsl:variable and xsl:with-param.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { trimXmlSpace } from "../../xpath/strings.js";
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+import { GlobalBindings } from "../variables.js";
+
+/**
+ * Whether a variable-binding element has content (XSLT 1.0 section 11.2).
+ *
+ * Whitespace-only text is stripped from stylesheets, and comments and
+ * processing instructions are not part of a template, so they do not count.
+ *
+ * @param {Element|undefined} node - xsl:variable, xsl:param or xsl:with-param
+ * @returns {boolean} True when instantiating the element produces a fragment
+ */
+function hasTemplateContent(node) {
+  for (let child = node?.firstChild; child; child = child.nextSibling) {
+    if (child.nodeType === 1) return true;
+    const isText = child.nodeType === 3 || child.nodeType === 4;
+    if (isText && trimXmlSpace(child.nodeValue) !== "") return true;
+  }
+  return false;
+}
+
+export const bindingMethods = {
+  /**
+   * Supply the value of a global parameter from outside the stylesheet.
+   *
+   * The value is merged into the `xsl:param` declaration when there is one, so
+   * removing the value later restores the declared default.
+   *
+   * @param {string} name - The parameter name, `{uri}local` when namespaced
+   * @param {*} value - The value to use
+   * @returns {void}
+   *
+   * @example
+   * engine.setParameterValue('sortOrder', 'ascending');
+   */
+  setParameterValue(name, value) {
+    const definition = this.globalParameters[name];
+
+    if (definition) definition.value = value;
+    else this.globalParameters[name] = { value };
+  },
+
+  /**
+   * Remove an externally supplied parameter value.
+   *
+   * The `xsl:param` declaration of the stylesheet is kept, so the parameter
+   * falls back to its declared default instead of becoming undefined.
+   *
+   * @param {string} name - The parameter name, `{uri}local` when namespaced
+   * @returns {void}
+   *
+   * @example
+   * engine.clearParameterValue('sortOrder');
+   */
+  clearParameterValue(name) {
+    const definition = this.globalParameters[name];
+    if (!definition) return;
+
+    if (definition.node) delete definition.value;
+    else delete this.globalParameters[name];
+  },
+
+  /**
+   * Remove every externally supplied parameter value.
+   *
+   * @returns {void}
+   *
+   * @example
+   * engine.clearParameterValues();
+   */
+  clearParameterValues() {
+    for (const name of Object.keys(this.globalParameters)) {
+      this.clearParameterValue(name);
+    }
+  },
+
+  /**
+   * Declare the global variables and parameters of the stylesheet for one
+   * transformation. They are evaluated lazily with the root node as context
+   * node (XSLT 1.0 section 11.4), so they may refer to each other in any
+   * order. Of a variable and a parameter of the same name, the one with the
+   * higher import precedence wins (section 11.4), the variable when the
+   * precedences are equal.
+   *
+   * @param {XsltContext} rootContext - The initial context
+   * @returns {GlobalBindings} The global bindings
+   */
+  createGlobals(rootContext) {
+    const globals = new GlobalBindings((def) => {
+      const context = rootContext.clone();
+      if (def.node) context.namespaces = inScopeNamespaces(def.node);
+      return this.evaluateVariable(def, context);
+    });
+
+    for (const [name, def] of Object.entries(this.globalParameters)) {
+      globals.define(name, def);
+    }
+    for (const [name, def] of Object.entries(this.globalVariables)) {
+      const param = this.globalParameters[name];
+      if (param?.node && param.importPrecedence > def.importPrecedence) {
+        continue;
+      }
+      globals.define(name, def);
+    }
+    return globals;
+  },
+
+  /**
+   * Compute the value of a variable or parameter definition.
+   *
+   * A value supplied from outside (`setParameter`) wins over the `select`
+   * expression and over the instantiated content of the declaration.
+   *
+   * @param {{value?: *, select?: string, node?: Element}} def - The definition
+   * @param {XsltContext} context - The context used for evaluation
+   * @returns {*} The variable value
+   */
+  evaluateVariable(def, context) {
+    if ("value" in def) {
+      return def.value;
+    }
+
+    if (def.select) {
+      return this.evaluateXPath(def.select, context);
+    }
+
+    // Empty content and no select: the value is an empty string (XSLT 11.2),
+    // which is false in a boolean test, unlike an (always true) fragment.
+    if (!hasTemplateContent(def.node)) {
+      return "";
+    }
+
+    // Otherwise the content is instantiated as a result tree fragment
+    const fragment = context.outputDocument.createDocumentFragment();
+    this.processChildren(def.node, context, fragment);
+    return fragment;
+  },
+
+  /**
+   * Evaluate the xsl:with-param children of an apply-templates or
+   * call-template instruction.
+   *
+   * @param {Element} node - The invoking instruction
+   * @param {XsltContext} context - Its context
+   * @returns {Object<string, *>} Values by parameter name
+   */
+  withParams(node, context) {
+    const params = {};
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      if (this.isXsltElement(child, "with-param")) {
+        params[child.getAttribute("name")] = this.evaluateVariable(
+          { node: child, select: child.getAttribute("select") },
+          context,
+        );
+      }
+    }
+    return params;
+  },
+
+  /**
+   * Instantiate xsl:variable: bind the variable for the following siblings.
+   * Content is instantiated from the work stack (see workStack.js), so
+   * recursion inside a variable keeps the JavaScript stack flat, and the
+   * fragment is bound once it is complete.
+   *
+   * @param {Element} node - The xsl:variable element
+   * @param {XsltContext} context - The current context
+   * @param {Node} _output - Unused: a variable produces no output
+   * @returns {void}
+   */
+  xslVariable(node, context, _output) {
+    const name = node.getAttribute("name");
+    const select = node.getAttribute("select");
+    if (select || !hasTemplateContent(node)) {
+      context.setVariable(
+        name,
+        this.evaluateVariable({ node, select }, context),
+      );
+      return;
+    }
+
+    const fragment = context.outputDocument.createDocumentFragment();
+    this.scheduleChildren(node, context, fragment, () =>
+      context.setVariable(name, fragment),
+    );
+  },
+};

package/src/xslt/engine/context.js

@@ -0,0 +1,105 @@
+/**
+ * XSLT processing context (the state of one instruction's evaluation).
+ */
+
+import { XPathEvaluator } from "../../xpath/evaluator.js";
+import { createVariableView, lookupVariable } from "../variables.js";
+
+/**
+ * XSLT Processing Context
+ *
+ * `variables` and `parameters` hold the local bindings in scope; the global
+ * variables and parameters of the transformation are in `globals`. The engine
+ * starts every template invocation with empty local bindings (and the
+ * template's own parameters), so local variables are lexically scoped.
+ * `namespaces` holds the prefixes in scope on the stylesheet element being
+ * instantiated.
+ */
+export class XsltContext {
+  constructor(options = {}) {
+    this.currentNode = options.currentNode;
+    this.currentNodeList = options.currentNodeList || [];
+    this.position = options.position || 1;
+    this.variables = { ...options.variables };
+    this.parameters = { ...options.parameters };
+    this.globals = options.globals ?? null;
+    this.outputDocument = options.outputDocument;
+    this.stylesheet = options.stylesheet;
+    this.namespaces = options.namespaces ?? {};
+    this.templates = options.templates || [];
+    this.keys = options.keys || {};
+    this.decimalFormats = options.decimalFormats || {};
+    this.outputMethod = options.outputMethod || "xml";
+    this.xpathEvaluator = options.xpathEvaluator || new XPathEvaluator();
+    this.currentTemplate = options.currentTemplate || null;
+    this.currentMode = options.currentMode ?? null;
+    this.variableView = null;
+  }
+
+  /**
+   * Copy the context, changing some of its properties.
+   *
+   * `variables`, `parameters` and `namespaces` overrides are merged into the
+   * current ones; with `fresh: true` the copy starts without local bindings
+   * (a new template invocation).
+   *
+   * @param {object} [overrides] - Properties to change
+   * @returns {XsltContext} The copy
+   */
+  clone(overrides = {}) {
+    const fresh = overrides.fresh === true;
+    const merge = (own, extra) => (extra ? { ...own, ...extra } : own);
+    return new XsltContext({
+      currentNode: overrides.currentNode ?? this.currentNode,
+      currentNodeList: overrides.currentNodeList ?? this.currentNodeList,
+      position: overrides.position ?? this.position,
+      variables: fresh ? null : merge(this.variables, overrides.variables),
+      parameters: fresh ? null : merge(this.parameters, overrides.parameters),
+      globals: this.globals,
+      outputDocument: this.outputDocument,
+      stylesheet: this.stylesheet,
+      namespaces: merge(this.namespaces, overrides.namespaces),
+      templates: this.templates,
+      keys: this.keys,
+      decimalFormats: this.decimalFormats,
+      outputMethod: this.outputMethod,
+      xpathEvaluator: this.xpathEvaluator,
+      currentTemplate: overrides.currentTemplate ?? this.currentTemplate,
+      currentMode: overrides.currentMode ?? this.currentMode,
+    });
+  }
+
+  /**
+   * The variables in scope, as the object view the XPath evaluator reads.
+   *
+   * @returns {object} A live, read-only view (see createVariableView)
+   */
+  get xpathVariables() {
+    this.variableView ??= createVariableView(this);
+    return this.variableView;
+  }
+
+  /**
+   * The value of a variable or parameter in scope.
+   *
+   * @param {string} name - The variable name
+   * @returns {*} The value
+   * @throws {Error} When no such variable is in scope
+   */
+  getVariable(name) {
+    const { found, value } = lookupVariable(this, name);
+    if (!found) throw new Error(`Undefined variable: $${name}`);
+    return value;
+  }
+
+  /**
+   * Bind a local variable in this context.
+   *
+   * @param {string} name - The variable name
+   * @param {*} value - Its value
+   * @returns {void}
+   */
+  setVariable(name, value) {
+    this.variables[name] = value;
+  }
+}

package/src/xslt/engine/controlFlow.js

@@ -0,0 +1,145 @@
+/**
+ * Conditional and repetition instructions: xsl:if, xsl:choose,
+ * xsl:for-each, and the xsl:sort glue shared with xsl:apply-templates.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { sortNodes } from "../sort.js";
+import { LoopFrame } from "./workStack.js";
+
+/**
+ * Evaluate the `select` expression of xsl:for-each or xsl:apply-templates
+ * as a node list.
+ *
+ * @param {object} engine - The engine
+ * @param {string} select - The expression
+ * @param {XsltContext} context - The current context
+ * @returns {Node[]} The selected nodes (a single value becomes a list of
+ *   one, an empty value an empty list)
+ */
+export function selectNodes(engine, select, context) {
+  const nodes = engine.evaluateXPath(select, context);
+  if (Array.isArray(nodes)) return nodes;
+  return nodes ? [nodes] : [];
+}
+
+export const controlFlowMethods = {
+  /**
+   * Instantiate `xsl:if`: the content when the test is true.
+   *
+   * @param {Element} node - The xsl:if instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  xslIf(node, context, output) {
+    const test = node.getAttribute("test");
+    const result = this.evaluateXPath(test, context);
+
+    if (this.xpathEvaluator.toBoolean(result)) {
+      this.scheduleChildren(node, context, output);
+    }
+  },
+
+  /**
+   * Instantiate `xsl:choose`: the first xsl:when whose test is true, else
+   * the xsl:otherwise.
+   *
+   * @param {Element} node - The xsl:choose instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  xslChoose(node, context, output) {
+    for (const child of node.childNodes) {
+      if (child.nodeType !== 1) continue;
+
+      if (this.isXsltElement(child, "when")) {
+        const test = child.getAttribute("test");
+        const result = this.evaluateXPath(test, context);
+
+        if (this.xpathEvaluator.toBoolean(result)) {
+          this.scheduleChildren(child, context, output);
+          return;
+        }
+      } else if (this.isXsltElement(child, "otherwise")) {
+        this.scheduleChildren(child, context, output);
+        return;
+      }
+    }
+  },
+
+  /**
+   * Instantiate `xsl:for-each`: the content once per selected node, in
+   * xsl:sort order, with that node as current node.
+   *
+   * @param {Element} node - The xsl:for-each instruction
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @returns {void}
+   */
+  xslForEach(node, context, output) {
+    const select = node.getAttribute("select");
+    const nodes = this.sortNodes(
+      selectNodes(this, select, context),
+      this.sortElementsOf(node),
+      context,
+    );
+
+    if (nodes.length === 0) return;
+
+    // One node at a time from the work stack (see workStack.js)
+    this.continueWith(
+      new LoopFrame(nodes.length, (i) => {
+        const newContext = context.clone({
+          currentNode: nodes[i],
+          currentNodeList: nodes,
+          position: i + 1,
+        });
+        this.scheduleChildren(node, newContext, output);
+      }),
+    );
+  },
+
+  /**
+   * The xsl:sort children of a sorting instruction, in document order.
+   *
+   * @param {Element} instruction - xsl:for-each or xsl:apply-templates
+   * @returns {Element[]} The xsl:sort elements
+   */
+  sortElementsOf(instruction) {
+    return Array.from(instruction.childNodes).filter((child) =>
+      this.isXsltElement(child, "sort"),
+    );
+  },
+
+  /**
+   * Sort a node list by xsl:sort elements (see sort.js).
+   *
+   * @param {Node[]} nodes - Nodes in document order
+   * @param {Element[]} sortElements - The xsl:sort elements
+   * @param {XsltContext} context - Context of the sorting instruction
+   * @returns {Node[]} The sorted nodes
+   */
+  sortNodes(nodes, sortElements, context) {
+    return sortNodes(nodes, sortElements, context, this.sortHost);
+  },
+
+  /**
+   * Engine callbacks used by the sort module, created once per engine.
+   *
+   * @returns {import('../sort.js').SortHost} The callbacks
+   */
+  get sortHost() {
+    if (!this._sortHost) {
+      this._sortHost = {
+        evaluate: (expr, ctx) => this.evaluateXPath(expr, ctx),
+        avt: (value, ctx) => this.processAttributeValueTemplate(value, ctx),
+        toString: (value) => this.xpathEvaluator.toString(value),
+        toNumber: (value) => this.xpathEvaluator.toNumber(value),
+      };
+    }
+    return this._sortHost;
+  },
+};