xslt-processor 4.8.5 → 5.0.0

package/README.md

@@ -4,7 +4,7 @@ _A JavaScript XSLT processor without native library dependencies._
 
   <p align="center">
     <a href="https://github.com/DesignLiquido/xslt-processor/issues" target="_blank">
-      <img src="https://img.shields.io/github/issues/Designliquido/xslt-processor" />
+      <img src="https://img.shields.io/github/issues/DesignLiquido/xslt-processor" />
     </a>
     <img src="https://img.shields.io/github/stars/Designliquido/xslt-processor" />
     <img src="https://img.shields.io/github/forks/Designliquido/xslt-processor" />
@@ -37,7 +37,7 @@ ohpm install xslt-processor
 yarn add xslt-processor
 ```
 
-Within your ES2015+ code, import the `Xslt` class, the `XmlParser` class and use this way:
+Within your ES2015+ code, import the `Xslt` class, the `XmlParser` class and use it this way:
 
 ```js
 import { Xslt, XmlParser } from 'xslt-processor'
@@ -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:
@@ -80,11 +115,44 @@ const xslt = new Xslt(options);
 - `cData` (`boolean`, default `true`): resolves CDATA elements in the output. Content under CDATA is resolved as text. This overrides `escape` for CDATA content.
 - `escape` (`boolean`, default `true`): replaces symbols like `<`, `>`, `&` and `"` by the corresponding [HTML/XML entities](https://www.tutorialspoint.com/xml/xml_character_entities.htm). Can be overridden by `disable-output-escaping`, that also does the opposite, unescaping `&gt;` and `&lt;` by `<` and `>`, respectively.
 - `selfClosingTags` (`boolean`, default `true`): Self-closes tags that don't have inner elements, if `true`. For instance, `<test></test>` becomes `<test />`.
-- `outputMethod` (`string`, default `xml`): Specifies the default output method. if `<xsl:output>` is declared in your XSLT file, this will be overridden. Valid values: `xml`, `html`, `text`, `name`, `xhtml`, `json`, `adaptive`.
+- `outputMethod` (`string`, default `xml`): Specifies the default output method. If `<xsl:output>` is declared in your XSLT file, this will be overridden. Valid values: `xml`, `html`, `text`, `xhtml`, `json`, `adaptive`.
 - `parameters` (`array`, default `[]`): external parameters that you want to use.
     - `name`: the parameter name;
     - `namespaceUri` (optional): the namespace;
     - `value`: the value.
+- `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;
+    - Transforming or remapping URIs before fetching.
+
+**`fetchFunction` examples:**
+
+```js
+import { readFileSync } from 'fs';
+
+// Deny all external loading
+const xslt = new Xslt({
+  fetchFunction: async (uri) => {
+    throw new Error(`External loading is not allowed: ${uri}`);
+  }
+});
+
+// Load from local filesystem
+const xslt = new Xslt({
+  fetchFunction: async (uri) => {
+    return readFileSync(uri, 'utf-8');
+  }
+});
+
+// Remap URIs before fetching
+const xslt = new Xslt({
+  fetchFunction: async (uri) => {
+    const remapped = uri.replace('https://example.com/', '/local/stylesheets/');
+    const response = await fetch(remapped);
+    return response.text();
+  }
+});
+```
 
 #### JSON Output Format
 
@@ -182,10 +250,10 @@ console.log(result2); // "<users><user>John</user></users>" (XML)
 You can simply add a tag like this:
 
 ```html
-<script type="application/javascript" src="https://www.unpkg.com/xslt-processor@latest/umd/xslt-processor.global.js"></script>
+<script type="application/javascript" src="https://unpkg.com/xslt-processor@latest/umd/xslt-processor.global.js"></script>
 ```
 
-All the exports will live under `globalThis.XsltProcessor` and `window.XsltProcessor`. [See a usage example here](https://github.com/DesignLiquido/xslt-processor/blob/main/interactive-tests/xslt.html). 
+All the exports will live under `globalThis.XsltProcessor` and `window.XsltProcessor`. [See a usage example here](https://github.com/DesignLiquido/xslt-processor/blob/main/interactive-tests/xslt.html).
 
 ## XPath Parser
 
@@ -204,7 +272,7 @@ import { XPath } from 'xslt-processor'
 const xPath = new XPath();
 ```
 
-`XPath` class is an external dependency, [living in its own repository](https://github.com/DesignLiquido/xpath). 
+`XPath` class is an external dependency, [living in its own repository](https://github.com/DesignLiquido/xpath).
 
 ## Introduction
 
@@ -215,13 +283,40 @@ XSLT-processor builds on Google's [AJAXSLT](https://github.com/4031651/ajaxslt)
 
 This implementation of XSLT operates at the DOM level on its input documents. It internally uses a DOM implementation to create the output document, but usually returns the output document as text stream. The DOM to construct the output document can be supplied by the application, or else an internal minimal DOM implementation is used. This DOM comes with a minimal XML parser that can be used to generate a suitable DOM representation of the input documents if they are present as text.
 
+## Building from source
+
+The XPath engine lives in a Git submodule at `src/xpath/lib`. A regular `git clone` does **not** fetch it automatically, so the build will fail unless the submodule is initialised.
+
+### Fresh clone
+
+```sh
+git clone --recurse-submodules https://github.com/DesignLiquido/xslt-processor.git
+cd xslt-processor
+yarn install
+yarn build
+```
+
+### Already cloned without submodules
+
+```sh
+git submodule update --init --recursive
+yarn install
+yarn build
+```
+
+### Updating the submodule to the latest commit
+
+```sh
+git submodule update --remote src/xpath/lib
+```
+
 ## Tests and usage examples
 
-New tests are written in Jest an can be run by calling: `yarn test`.
+New tests are written in Jest and can be run by calling: `yarn test`.
 
 The files `xslt.html` and `xpath.html` in the directory `interactive-tests` are interactive tests. They can be run directly from the file system; no HTTP server is needed.
 
-Both interactive tests and automatic tests demonstrate the use of the library functions. 
+Both interactive tests and automatic tests demonstrate the use of the library functions.
 
 ## Conformance
 
@@ -233,9 +328,9 @@ So far, we have implemented XQuery functions for versions 1.0 and 2.0, but this
 
 The DOM implementation is minimal so as to support the XSLT processing, and not intended to be complete.
 
-The implementation is all agnostic about namespaces. It just expects XSLT elements to have tags that carry the `xsl:` prefix, but we disregard all namespace declaration for them.
+The implementation is all agnostic about namespaces. It just expects XSLT elements to have tags that carry the `xsl:` prefix, but we disregard all namespace declarations for them.
 
-[There are a few nonstandard XPath functions](https://github.com/search?q=repo%3ADesignLiquido%2Fxslt-processor%20ext-&type=code). 
+[There are a few nonstandard XPath functions](https://github.com/search?q=repo%3ADesignLiquido%2Fxslt-processor%20ext-&type=code).
 
 ### HTML Conformance
 

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
@@ -172,6 +182,7 @@ type XsltOptions = {
     selfClosingTags: boolean;
     outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json' | 'adaptive';
     parameters?: XsltParameter[];
+    fetchFunction?: (uri: string) => Promise<string>;
 };
 
 interface NodeValue {
@@ -760,6 +771,12 @@ declare class Xslt {
     options: XsltOptions;
     decimalFormatSettings: XsltDecimalFormatSettings;
     warningsCallback: (...args: any[]) => void;
+    /**
+     * Custom fetch function for loading external resources (e.g. xsl:import, xsl:include).
+     * Takes a URI and returns the fetched content as a string.
+     * Defaults to using the global `fetch` API.
+     */
+    fetchFunction: (uri: string) => Promise<string>;
     outputDocument: XDocument;
     outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json' | 'adaptive';
     outputOmitXmlDeclaration: string;
@@ -871,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`.
@@ -1464,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.
@@ -1726,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
@@ -172,6 +182,7 @@ type XsltOptions = {
     selfClosingTags: boolean;
     outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json' | 'adaptive';
     parameters?: XsltParameter[];
+    fetchFunction?: (uri: string) => Promise<string>;
 };
 
 interface NodeValue {
@@ -760,6 +771,12 @@ declare class Xslt {
     options: XsltOptions;
     decimalFormatSettings: XsltDecimalFormatSettings;
     warningsCallback: (...args: any[]) => void;
+    /**
+     * Custom fetch function for loading external resources (e.g. xsl:import, xsl:include).
+     * Takes a URI and returns the fetched content as a string.
+     * Defaults to using the global `fetch` API.
+     */
+    fetchFunction: (uri: string) => Promise<string>;
     outputDocument: XDocument;
     outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json' | 'adaptive';
     outputOmitXmlDeclaration: string;
@@ -871,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`.
@@ -1464,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.
@@ -1726,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 };