xslt-processor 4.9.0 → 5.0.1

package/README.md

@@ -63,6 +63,41 @@ xslt.xsltProcess(
 
 If you write pre-2015 JS code, make adjustments as needed.
 
+### Working with browser DOM and XDocument output
+
+Feature available in v5 (next major) of this library. 
+
+If you already have a browser DOM `Document` or `Node`, convert it to an `XDocument` without re-parsing XML strings:
+
+```js
+import { domDocumentToXDocument } from 'xslt-processor'
+
+const parser = new DOMParser();
+const nativeDoc = parser.parseFromString('<root>hello</root>', 'text/xml');
+const xDoc = domDocumentToXDocument(nativeDoc);
+```
+
+You can also run XSLT and get the output as an `XDocument` tree instead of a serialized string:
+
+```js
+import { Xslt, XmlParser } from 'xslt-processor'
+
+const xmlParser = new XmlParser();
+const xslt = new Xslt();
+
+const xmlDoc = xmlParser.xmlParse('<root><item>hello</item></root>');
+const styleDoc = xmlParser.xmlParse(
+  '<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">' +
+  '  <xsl:template match="/">' +
+  '    <output><xsl:value-of select="/root/item"/></output>' +
+  '  </xsl:template>' +
+  '</xsl:stylesheet>'
+);
+
+const outDoc = await xslt.xsltProcessToDocument(xmlDoc, styleDoc);
+// outDoc is an XDocument you can traverse or serialize with xmlTransformedText.
+```
+
 ### `Xslt` class options
 
 You can pass an `options` object to `Xslt` class:
@@ -84,7 +119,47 @@ const xslt = new Xslt(options);
 - `parameters` (`array`, default `[]`): external parameters that you want to use.
     - `name`: the parameter name;
     - `namespaceUri` (optional): the namespace;
-    - `value`: the value.
+    - `value`: the value. The type is preserved automatically:
+        - **string** values become `StringValue`;
+        - **number** values become `NumberValue` (usable in XPath arithmetic);
+        - **boolean** values become `BooleanValue` (usable in `xsl:if`/`xsl:when` tests);
+        - Note: in XPath/XSLT, any non-empty string is truthy, so the string "false" still behaves as true in tests;
+        - **`NodeSetValue`** instances are kept as-is (useful for passing additional documents);
+        - DOM nodes (objects with `nodeType`) are wrapped in a `NodeSetValue`;
+        - arrays of nodes are wrapped in a `NodeSetValue`.
+
+**`parameters` examples:**
+
+```js
+import { Xslt, XmlParser } from 'xslt-processor'
+
+// String parameter (default behavior)
+const xslt = new Xslt({ parameters: [
+  { name: 'title', value: 'Hello' }
+] });
+
+// Number parameter — works in XPath arithmetic ($count + 1 = 43)
+const xslt = new Xslt({ parameters: [
+  { name: 'count', value: 42 }
+] });
+
+// Boolean parameter — works in xsl:if / xsl:when tests
+const xslt = new Xslt({ parameters: [
+  { name: 'debug', value: true }
+] });
+
+// Node-set parameter — pass an additional document for cross-document lookups
+import { NodeSetValue } from 'xslt-processor/xpath/values'
+
+const xmlParser = new XmlParser();
+const lookupDoc = xmlParser.xmlParse('<lookup><entry key="a">Alpha</entry></lookup>');
+
+const xslt = new Xslt({ parameters: [
+  { name: 'lookup', value: new NodeSetValue([lookupDoc]) }
+] });
+// In XSLT: <xsl:value-of select="$lookup/lookup/entry[@key='a']"/>
+```
+
 - `fetchFunction` (`(uri: string) => Promise<string>`, optional): a custom function for loading external resources referenced by `<xsl:import>` and `<xsl:include>`. Receives the URI and must return the fetched content as a string. Defaults to the global `fetch` API. This is useful for:
     - Denying external loading entirely;
     - Loading from the local filesystem or other non-HTTP sources;

package/index.d.mts

@@ -76,6 +76,16 @@ declare class XDocument extends XNode {
     createProcessingInstruction(target: string, data: any): XNode;
 }
 
+/**
+ * Converts a native browser DOM Document or Node into an XDocument/XNode tree
+ * compatible with the XSLT processor. This allows browser users who already
+ * have a parsed DOM to skip the string-based xmlParse() step.
+ *
+ * @param nativeNode A browser DOM Document, Element, or other Node.
+ * @returns An XDocument representing the same tree structure.
+ */
+declare function domDocumentToXDocument(nativeNode: Document | Node): XDocument;
+
 /**
  * Escape XML special markup characters: tag delimiter <, >, and entity
  * reference start delimiter &. The escaped string can be used in XML
@@ -878,6 +888,18 @@ declare class Xslt {
      * @returns the processed document, as XML text in a string, JSON string if outputMethod is 'json', or text if outputMethod is 'text' or 'adaptive' (with text content).
      */
     xsltProcess(xmlDoc: XDocument, stylesheet: XDocument): Promise<string>;
+    /**
+     * Processes the XSLT transformation and returns the output as an XDocument
+     * instead of a serialized string. This is useful for:
+     * - Working with the result tree programmatically
+     * - Converting to a different DOM representation (e.g., React elements)
+     * - Using browser-native serialization (XMLSerializer) if desired
+     *
+     * @param xmlDoc The input document root, as DOM node.
+     * @param stylesheet The stylesheet document root, as DOM node.
+     * @returns The processed document as an XDocument tree.
+     */
+    xsltProcessToDocument(xmlDoc: XDocument, stylesheet: XDocument): Promise<XDocument>;
     /**
      * The main entry point of the XSL-T processor, as explained on the top of the file.
      * @param context The input document root, as XPath `ExprContext`.
@@ -1471,6 +1493,15 @@ declare class Xslt {
      * @returns The coerced value.
      */
     protected coerceToType(value: NodeValue, type: string): NodeValue;
+    /**
+     * Converts a raw JavaScript value to the appropriate NodeValue type.
+     * Detects NodeValue instances, DOM nodes, arrays, numbers, booleans,
+     * and falls back to StringValue.
+     *
+     * @param value The raw value to convert.
+     * @returns The wrapped NodeValue.
+     */
+    protected toNodeValue(value: any): NodeValue;
     /**
      * Execute a user-defined xsl:function.
      * Called when a function from userDefinedFunctions is invoked from XPath.
@@ -1733,4 +1764,4 @@ declare class Xslt {
     protected isXsltElement(element: XNode, opt_wantedName?: string): boolean;
 }
 
-export { ExprContext, XPath, XmlParser, Xslt, type XsltOptions, xmlEscapeText };
+export { ExprContext, XDocument, XNode, XPath, XmlParser, Xslt, type XsltOptions, domDocumentToXDocument, xmlEscapeText };

package/index.d.ts

@@ -76,6 +76,16 @@ declare class XDocument extends XNode {
     createProcessingInstruction(target: string, data: any): XNode;
 }
 
+/**
+ * Converts a native browser DOM Document or Node into an XDocument/XNode tree
+ * compatible with the XSLT processor. This allows browser users who already
+ * have a parsed DOM to skip the string-based xmlParse() step.
+ *
+ * @param nativeNode A browser DOM Document, Element, or other Node.
+ * @returns An XDocument representing the same tree structure.
+ */
+declare function domDocumentToXDocument(nativeNode: Document | Node): XDocument;
+
 /**
  * Escape XML special markup characters: tag delimiter <, >, and entity
  * reference start delimiter &. The escaped string can be used in XML
@@ -878,6 +888,18 @@ declare class Xslt {
      * @returns the processed document, as XML text in a string, JSON string if outputMethod is 'json', or text if outputMethod is 'text' or 'adaptive' (with text content).
      */
     xsltProcess(xmlDoc: XDocument, stylesheet: XDocument): Promise<string>;
+    /**
+     * Processes the XSLT transformation and returns the output as an XDocument
+     * instead of a serialized string. This is useful for:
+     * - Working with the result tree programmatically
+     * - Converting to a different DOM representation (e.g., React elements)
+     * - Using browser-native serialization (XMLSerializer) if desired
+     *
+     * @param xmlDoc The input document root, as DOM node.
+     * @param stylesheet The stylesheet document root, as DOM node.
+     * @returns The processed document as an XDocument tree.
+     */
+    xsltProcessToDocument(xmlDoc: XDocument, stylesheet: XDocument): Promise<XDocument>;
     /**
      * The main entry point of the XSL-T processor, as explained on the top of the file.
      * @param context The input document root, as XPath `ExprContext`.
@@ -1471,6 +1493,15 @@ declare class Xslt {
      * @returns The coerced value.
      */
     protected coerceToType(value: NodeValue, type: string): NodeValue;
+    /**
+     * Converts a raw JavaScript value to the appropriate NodeValue type.
+     * Detects NodeValue instances, DOM nodes, arrays, numbers, booleans,
+     * and falls back to StringValue.
+     *
+     * @param value The raw value to convert.
+     * @returns The wrapped NodeValue.
+     */
+    protected toNodeValue(value: any): NodeValue;
     /**
      * Execute a user-defined xsl:function.
      * Called when a function from userDefinedFunctions is invoked from XPath.
@@ -1733,4 +1764,4 @@ declare class Xslt {
     protected isXsltElement(element: XNode, opt_wantedName?: string): boolean;
 }
 
-export { ExprContext, XPath, XmlParser, Xslt, type XsltOptions, xmlEscapeText };
+export { ExprContext, XDocument, XNode, XPath, XmlParser, Xslt, type XsltOptions, domDocumentToXDocument, xmlEscapeText };

package/index.js

@@ -7800,9 +7800,12 @@ var init_expressions = __esm({
 var index_exports = {};
 __export(index_exports, {
   ExprContext: () => ExprContext,
+  XDocument: () => XDocument,
+  XNode: () => XNode,
   XPath: () => XPath,
   XmlParser: () => XmlParser,
   Xslt: () => Xslt,
+  domDocumentToXDocument: () => domDocumentToXDocument,
   xmlEscapeText: () => xmlEscapeText
 });
 module.exports = __toCommonJS(index_exports);
@@ -10279,38 +10282,6 @@ function createXPathParser(version = DEFAULT_XPATH_VERSION, options) {
 // src/xpath/xpath.ts
 init_expressions();
 
-// src/dom/functions.ts
-function domGetAttributeValue(node, name) {
-  return node.getAttributeValue(name);
-}
-function domSetAttribute(node, name, value) {
-  return node.setAttribute(name, value);
-}
-function domAppendChild(node, child) {
-  return node.appendChild(child);
-}
-function domCreateTextNode(node, text) {
-  return node.createTextNode(text);
-}
-function domCreateElement(doc, name) {
-  return doc.createElement(name);
-}
-function domCreateCDATASection(doc, data2) {
-  return doc.createCDATASection(data2);
-}
-function domCreateComment(doc, text) {
-  return doc.createComment(text);
-}
-function domCreateDocumentFragment(doc) {
-  return doc.createDocumentFragment();
-}
-function domCreateDTDSection(doc, data2) {
-  return doc.createDTDSection(data2);
-}
-function domCreateProcessingInstruction(doc, target, data2) {
-  return doc.createProcessingInstruction(target, data2);
-}
-
 // src/constants.ts
 var DOM_ELEMENT_NODE = 1;
 var DOM_ATTRIBUTE_NODE = 2;
@@ -10735,7 +10706,9 @@ var XDocument = class extends XNode {
   }
   appendChild(node) {
     super.appendChild(node);
-    this.documentElement = this.childNodes[0];
+    if (node.nodeType === DOM_ELEMENT_NODE && !this.documentElement) {
+      this.documentElement = node;
+    }
   }
   createElement(name) {
     return XNode.create(DOM_ELEMENT_NODE, name, null, this);
@@ -10769,6 +10742,130 @@ var XDocument = class extends XNode {
   }
 };
 
+// src/dom/dom-to-xdocument.ts
+function domDocumentToXDocument(nativeNode) {
+  if (nativeNode.nodeType === DOM_DOCUMENT_NODE) {
+    const xDoc2 = new XDocument();
+    const childNodes = nativeNode.childNodes;
+    for (let i = 0; i < childNodes.length; i++) {
+      const converted2 = convertNode(childNodes[i], xDoc2);
+      if (converted2) {
+        converted2.siblingPosition = xDoc2.childNodes.length;
+        xDoc2.appendChild(converted2);
+      }
+    }
+    return xDoc2;
+  }
+  const xDoc = new XDocument();
+  const converted = convertNode(nativeNode, xDoc);
+  if (converted) {
+    converted.siblingPosition = 0;
+    xDoc.appendChild(converted);
+  }
+  return xDoc;
+}
+function convertNode(nativeNode, ownerDoc) {
+  switch (nativeNode.nodeType) {
+    case DOM_ELEMENT_NODE: {
+      const element = nativeNode;
+      const xNode = XNode.create(
+        DOM_ELEMENT_NODE,
+        element.nodeName,
+        null,
+        ownerDoc,
+        element.namespaceURI
+      );
+      xNode.prefix = element.prefix || null;
+      xNode.localName = element.localName || element.nodeName;
+      const attrs = element.attributes;
+      for (let i = 0; i < attrs.length; i++) {
+        const attr = attrs[i];
+        const attrNode = XNode.create(
+          DOM_ATTRIBUTE_NODE,
+          attr.name,
+          attr.value,
+          xNode,
+          attr.namespaceURI
+        );
+        attrNode.prefix = attr.prefix || null;
+        attrNode.localName = attr.localName || attr.name;
+        attrNode.parentNode = xNode;
+        attrNode.siblingPosition = xNode.childNodes.length;
+        xNode.appendChild(attrNode);
+      }
+      const childNodes = nativeNode.childNodes;
+      for (let i = 0; i < childNodes.length; i++) {
+        const converted = convertNode(childNodes[i], ownerDoc);
+        if (converted) {
+          converted.siblingPosition = xNode.childNodes.length;
+          xNode.appendChild(converted);
+        }
+      }
+      return xNode;
+    }
+    case DOM_TEXT_NODE:
+      return XNode.create(DOM_TEXT_NODE, "#text", nativeNode.nodeValue || "", ownerDoc);
+    case DOM_CDATA_SECTION_NODE:
+      return XNode.create(DOM_CDATA_SECTION_NODE, "#cdata-section", nativeNode.nodeValue || "", ownerDoc);
+    case DOM_COMMENT_NODE:
+      return XNode.create(DOM_COMMENT_NODE, "#comment", nativeNode.nodeValue || "", ownerDoc);
+    case DOM_PROCESSING_INSTRUCTION_NODE: {
+      const pi2 = nativeNode;
+      return XNode.create(DOM_PROCESSING_INSTRUCTION_NODE, pi2.target, pi2.data, ownerDoc);
+    }
+    case DOM_DOCUMENT_TYPE_NODE: {
+      const dt = nativeNode;
+      return XNode.create(DOM_DOCUMENT_TYPE_NODE, "#dtd-section", dt.name, ownerDoc);
+    }
+    case DOM_DOCUMENT_FRAGMENT_NODE: {
+      const fragment = XNode.create(DOM_DOCUMENT_FRAGMENT_NODE, "#document-fragment", null, ownerDoc);
+      const childNodes = nativeNode.childNodes;
+      for (let i = 0; i < childNodes.length; i++) {
+        const converted = convertNode(childNodes[i], ownerDoc);
+        if (converted) {
+          converted.siblingPosition = fragment.childNodes.length;
+          fragment.appendChild(converted);
+        }
+      }
+      return fragment;
+    }
+    default:
+      return null;
+  }
+}
+
+// src/dom/functions.ts
+function domGetAttributeValue(node, name) {
+  return node.getAttributeValue(name);
+}
+function domSetAttribute(node, name, value) {
+  return node.setAttribute(name, value);
+}
+function domAppendChild(node, child) {
+  return node.appendChild(child);
+}
+function domCreateTextNode(node, text) {
+  return node.createTextNode(text);
+}
+function domCreateElement(doc, name) {
+  return doc.createElement(name);
+}
+function domCreateCDATASection(doc, data2) {
+  return doc.createCDATASection(data2);
+}
+function domCreateComment(doc, text) {
+  return doc.createComment(text);
+}
+function domCreateDocumentFragment(doc) {
+  return doc.createDocumentFragment();
+}
+function domCreateDTDSection(doc, data2) {
+  return doc.createDTDSection(data2);
+}
+function domCreateProcessingInstruction(doc, target, data2) {
+  return doc.createProcessingInstruction(target, data2);
+}
+
 // src/dom/html-entity-decoder.ts
 var NAMED_ENTITIES = {
   "amp": "&",
@@ -11770,28 +11867,37 @@ var NodeConverter = class {
    */
   convertVariables(exprContext) {
     const variables = {};
-    for (const [name, value] of Object.entries(exprContext.variables || {})) {
-      if (value && typeof value === "object" && "stringValue" in value) {
-        const nodeValue = value;
-        if (nodeValue.type === "node-set") {
-          variables[name] = value.nodeSetValue().map((n) => this.adaptXNode(n));
-        } else if (nodeValue.type === "string") {
-          variables[name] = value.stringValue();
-        } else if (nodeValue.type === "number") {
-          variables[name] = value.numberValue();
-        } else if (nodeValue.type === "boolean") {
-          variables[name] = value.booleanValue();
-        } else if (nodeValue.type === "map") {
-          variables[name] = nodeValue.value;
-        } else if (nodeValue.type === "array") {
-          variables[name] = nodeValue.value;
-        } else if (nodeValue.type === "function") {
-          variables[name] = nodeValue.value;
+    const contexts = [];
+    let ctx = exprContext;
+    while (ctx) {
+      contexts.push(ctx);
+      ctx = ctx.parent;
+    }
+    for (let i = contexts.length - 1; i >= 0; i--) {
+      const current = contexts[i];
+      for (const [name, value] of Object.entries(current.variables || {})) {
+        if (value && typeof value === "object" && "stringValue" in value) {
+          const nodeValue = value;
+          if (nodeValue.type === "node-set") {
+            variables[name] = value.nodeSetValue().map((n) => this.adaptXNode(n));
+          } else if (nodeValue.type === "string") {
+            variables[name] = value.stringValue();
+          } else if (nodeValue.type === "number") {
+            variables[name] = value.numberValue();
+          } else if (nodeValue.type === "boolean") {
+            variables[name] = value.booleanValue();
+          } else if (nodeValue.type === "map") {
+            variables[name] = nodeValue.value;
+          } else if (nodeValue.type === "array") {
+            variables[name] = nodeValue.value;
+          } else if (nodeValue.type === "function") {
+            variables[name] = nodeValue.value;
+          } else {
+            variables[name] = value.stringValue();
+          }
         } else {
-          variables[name] = value.stringValue();
+          variables[name] = value;
         }
-      } else {
-        variables[name] = value;
       }
     }
     return variables;
@@ -12384,7 +12490,7 @@ var ExprContext = class _ExprContext {
       this.xsltVersion,
       typeof opt_position !== "undefined" ? opt_position : this.position,
       this.decimalFormatSettings,
-      this.variables,
+      Object.create(this.variables || {}),
       this.knownNamespaces,
       this,
       this.caseInsensitive,
@@ -13931,16 +14037,7 @@ var Xslt = class {
    */
   xsltProcess(xmlDoc, stylesheet) {
     return __async(this, null, function* () {
-      const outputDocument = new XDocument();
-      this.outputDocument = outputDocument;
-      const expressionContext = new ExprContext([xmlDoc]);
-      expressionContext.warningsCallback = this.warningsCallback;
-      if (this.options.parameters.length > 0) {
-        for (const parameter of this.options.parameters) {
-          expressionContext.setVariable(parameter.name, new StringValue(parameter.value));
-        }
-      }
-      yield this.xsltProcessContext(expressionContext, stylesheet, this.outputDocument);
+      const outputDocument = yield this.xsltProcessToDocument(xmlDoc, stylesheet);
       if (this.outputMethod === "json") {
         return xmlToJson(outputDocument);
       }
@@ -13963,6 +14060,32 @@ var Xslt = class {
       return transformedOutputXml;
     });
   }
+  /**
+   * Processes the XSLT transformation and returns the output as an XDocument
+   * instead of a serialized string. This is useful for:
+   * - Working with the result tree programmatically
+   * - Converting to a different DOM representation (e.g., React elements)
+   * - Using browser-native serialization (XMLSerializer) if desired
+   *
+   * @param xmlDoc The input document root, as DOM node.
+   * @param stylesheet The stylesheet document root, as DOM node.
+   * @returns The processed document as an XDocument tree.
+   */
+  xsltProcessToDocument(xmlDoc, stylesheet) {
+    return __async(this, null, function* () {
+      const outputDocument = new XDocument();
+      this.outputDocument = outputDocument;
+      const expressionContext = new ExprContext([xmlDoc]);
+      expressionContext.warningsCallback = this.warningsCallback;
+      if (this.options.parameters.length > 0) {
+        for (const parameter of this.options.parameters) {
+          expressionContext.setVariable(parameter.name, this.toNodeValue(parameter.value));
+        }
+      }
+      yield this.xsltProcessContext(expressionContext, stylesheet, this.outputDocument);
+      return outputDocument;
+    });
+  }
   /**
    * The main entry point of the XSL-T processor, as explained on the top of the file.
    * @param context The input document root, as XPath `ExprContext`.
@@ -17189,6 +17312,29 @@ var Xslt = class {
         return value;
     }
   }
+  /**
+   * Converts a raw JavaScript value to the appropriate NodeValue type.
+   * Detects NodeValue instances, DOM nodes, arrays, numbers, booleans,
+   * and falls back to StringValue.
+   *
+   * @param value The raw value to convert.
+   * @returns The wrapped NodeValue.
+   */
+  toNodeValue(value) {
+    if (value && typeof value === "object" && "stringValue" in value) {
+      return value;
+    } else if (value && typeof value === "object" && "nodeType" in value) {
+      return new NodeSetValue([value]);
+    } else if (Array.isArray(value)) {
+      return new NodeSetValue(value);
+    } else if (typeof value === "number") {
+      return new NumberValue(value);
+    } else if (typeof value === "boolean") {
+      return new BooleanValue(value);
+    } else {
+      return new StringValue(String(value != null ? value : ""));
+    }
+  }
   /**
    * Execute a user-defined xsl:function.
    * Called when a function from userDefinedFunctions is invoked from XPath.
@@ -17226,30 +17372,10 @@ var Xslt = class {
       const paramName = xmlGetAttribute(params[i], "name");
       if (paramName) {
         if (i < args.length) {
-          let argValue = args[i];
           const paramType = xmlGetAttribute(params[i], "as");
-          let paramValue;
-          if (argValue && typeof argValue === "object" && "stringValue" in argValue) {
-            paramValue = argValue;
-            if (paramType) {
-              paramValue = this.coerceToType(paramValue, paramType);
-            }
-          } else if (argValue && typeof argValue === "object" && "nodeType" in argValue) {
-            paramValue = new NodeSetValue([argValue]);
-            if (paramType) {
-              paramValue = this.coerceToType(paramValue, paramType);
-            }
-          } else if (Array.isArray(argValue)) {
-            paramValue = new NodeSetValue(argValue);
-            if (paramType) {
-              paramValue = this.coerceToType(paramValue, paramType);
-            }
-          } else if (typeof argValue === "number") {
-            paramValue = new NumberValue(argValue);
-          } else if (typeof argValue === "boolean") {
-            paramValue = new BooleanValue(argValue);
-          } else {
-            paramValue = new StringValue(String(argValue != null ? argValue : ""));
+          let paramValue = this.toNodeValue(args[i]);
+          if (paramType) {
+            paramValue = this.coerceToType(paramValue, paramType);
           }
           functionContext.setVariable(paramName, paramValue);
         } else {
@@ -17456,12 +17582,12 @@ var Xslt = class {
       } else if (select) {
         value = this.xPath.xPathEval(select, context);
       } else {
-        let parameterValue = "";
         const filteredParameter = this.options.parameters.filter((p) => p.name === name);
         if (filteredParameter.length > 0) {
-          parameterValue = filteredParameter[0].value;
+          value = this.toNodeValue(filteredParameter[0].value);
+        } else {
+          value = new StringValue("");
         }
-        value = new StringValue(parameterValue);
       }
       if (override || !context.getVariable(name)) {
         context.setVariable(name, value);
@@ -18036,9 +18162,12 @@ var Xslt = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ExprContext,
+  XDocument,
+  XNode,
   XPath,
   XmlParser,
   Xslt,
+  domDocumentToXDocument,
   xmlEscapeText
 });
 //# sourceMappingURL=index.js.map