xslt-processor 4.3.0 → 4.4.0

package/README.md

@@ -62,7 +62,7 @@ const xslt = new Xslt();
 const xPath = xslt.xPath;
 ```
 
-Or ou can import it like this:
+Or you can import it like this:
 
 ```js
 import { XPath } from 'xslt-processor'
@@ -70,6 +70,8 @@ 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). 
+
 If you write pre-2015 JS code, make adjustments as needed.
 
 ### `Xslt` class options
@@ -145,76 +147,11 @@ console.log(parsed.root.users.user); // ["Alice", "Bob"]
 You can simply add a tag like this:
 
 ```html
-<script type="application/javascript" src="https://www.unpkg.com/xslt-processor@3.0.0/umd/xslt-processor.js"></script>
+<script type="application/javascript" src="https://www.unpkg.com/xslt-processor@latest/umd/xslt-processor.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). 
 
-### Breaking Changes
-
-#### Version 2
-
-Until version 2.3.1, use like the example below:
-
-```js
-import { Xslt, XmlParser } from 'xslt-processor'
-
-// xmlString: string of xml file contents
-// xsltString: string of xslt file contents
-// outXmlString: output xml string.
-const xslt = new Xslt();
-const xmlParser = new XmlParser();
-const outXmlString = xslt.xsltProcess( // Not async.
-	xmlParser.xmlParse(xmlString),
-	xmlParser.xmlParse(xsltString)
-);
-```
-
-Version 3 received `<xsl:include>` which relies on Fetch API, which is asynchronous. Version 2 doesn't support `<xsl:include>`.
-
-If using Node.js older than version v17.5.0, please use version 3.2.3, that uses `node-fetch` package. Versions 3.3.0 onward require at least Node.js version v17.5.0, since they use native `fetch()` function.
-
-#### Version 1
-
-Until version 1.2.8, use like the example below:
-
-```js
-import { Xslt, xmlParse } from 'xslt-processor'
-
-// xmlString: string of xml file contents
-// xsltString: string of xslt file contents
-// outXmlString: output xml string.
-const xslt = new Xslt();
-const outXmlString = xslt.xsltProcess(
-	xmlParse(xmlString),
-	xmlParse(xsltString)
-);
-```
-
-#### Version 0
-
-Until version 0.11.7, use like the example below:
-
-```js
-import { xsltProcess, xmlParse } from 'xslt-processor'
-
-// xmlString: string of xml file contents
-// xsltString: string of xslt file contents
-// outXmlString: output xml string.
-const outXmlString = xsltProcess(
-	xmlParse(xmlString),
-	xmlParse(xsltString)
-);
-```
-
-and to access the XPath parser:
-
-```js
-import { xpathParse } from 'xslt-processor'
-```
-
-These functions are part of `Xslt` and `XPath` classes, respectively, at version 1.x onward.
-
 ## Introduction
 
 XSLT-processor contains an implementation of XSLT in JavaScript. Because XSLT uses XPath, it also contains an implementation of XPath that can be used
@@ -312,6 +249,71 @@ Use `<xsl:preserve-space>` to preserve whitespace in specific elements, overridi
 3. `xsl:strip-space` applies to remaining matches
 4. By default (no declarations), whitespace is preserved
 
+### Breaking Changes
+
+#### Version 2
+
+Until version 2.3.1, use like the example below:
+
+```js
+import { Xslt, XmlParser } from 'xslt-processor'
+
+// xmlString: string of xml file contents
+// xsltString: string of xslt file contents
+// outXmlString: output xml string.
+const xslt = new Xslt();
+const xmlParser = new XmlParser();
+const outXmlString = xslt.xsltProcess( // Not async.
+	xmlParser.xmlParse(xmlString),
+	xmlParser.xmlParse(xsltString)
+);
+```
+
+Version 3 received `<xsl:include>` which relies on Fetch API, which is asynchronous. Version 2 doesn't support `<xsl:include>`.
+
+If using Node.js older than version v17.5.0, please use version 3.2.3, that uses `node-fetch` package. Versions 3.3.0 onward require at least Node.js version v17.5.0, since they use native `fetch()` function.
+
+#### Version 1
+
+Until version 1.2.8, use like the example below:
+
+```js
+import { Xslt, xmlParse } from 'xslt-processor'
+
+// xmlString: string of xml file contents
+// xsltString: string of xslt file contents
+// outXmlString: output xml string.
+const xslt = new Xslt();
+const outXmlString = xslt.xsltProcess(
+	xmlParse(xmlString),
+	xmlParse(xsltString)
+);
+```
+
+#### Version 0
+
+Until version 0.11.7, use like the example below:
+
+```js
+import { xsltProcess, xmlParse } from 'xslt-processor'
+
+// xmlString: string of xml file contents
+// xsltString: string of xslt file contents
+// outXmlString: output xml string.
+const outXmlString = xsltProcess(
+	xmlParse(xmlString),
+	xmlParse(xsltString)
+);
+```
+
+and to access the XPath parser:
+
+```js
+import { xpathParse } from 'xslt-processor'
+```
+
+These functions are part of `Xslt` and `XPath` classes, respectively, at version 1.x onward.
+
 ## References
 
 - XPath Specification: http://www.w3.org/TR/1999/REC-xpath-19991116

package/index.d.mts

@@ -22,6 +22,7 @@ declare class XNode {
     parentNode: XNode;
     visited: boolean;
     escape: boolean;
+    fromXslText: boolean;
     static _unusedXNodes: any[];
     constructor(type: number, name: string, opt_value: any, opt_owner: any, opt_namespace?: any);
     /**
@@ -138,7 +139,7 @@ interface XPathNode {
     nodeType: number;
     nodeName: string;
     localName?: string;
-    namespaceURI?: string | null;
+    namespaceUri?: string | null;
     textContent?: string | null;
     parentNode?: XPathNode | null;
     childNodes?: ArrayLike<XPathNode>;
@@ -213,6 +214,11 @@ interface XPathContext {
      * Example: { "atom": "http://www.w3.org/2005/Atom" }
      */
     namespaces?: XPathNamespaces;
+    /**
+     * XSLT version ('1.0', '2.0', '3.0') for version-specific behavior.
+     * Used by functions like json-to-xml() which are only available in XSLT 3.0+
+     */
+    xsltVersion?: string;
 }
 /**
  * Result types that can be returned from XPath evaluation.
@@ -412,6 +418,11 @@ declare class NodeConverter {
      * Create custom functions for XPath context (like key(), document(), etc.).
      */
     private createCustomFunctions;
+    /**
+     * Convert an XPathNode interface tree to actual XNode objects.
+     * This is needed to convert json-to-xml() output to XSLT-compatible nodes.
+     */
+    private convertXPathNodeToXNode;
     /**
      * Convert an XML node to a JSON string representation.
      * This is a simplified implementation of XSLT 3.0's xml-to-json().
@@ -532,7 +543,7 @@ type XsltOptions = {
     cData: boolean;
     escape: boolean;
     selfClosingTags: boolean;
-    outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json';
+    outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json' | 'adaptive';
     parameters?: XsltParameter[];
 };
 
@@ -567,7 +578,7 @@ declare class Xslt {
     options: XsltOptions;
     decimalFormatSettings: XsltDecimalFormatSettings;
     outputDocument: XDocument;
-    outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json';
+    outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json' | 'adaptive';
     outputOmitXmlDeclaration: string;
     version: string;
     firstTemplateRan: boolean;
@@ -592,7 +603,7 @@ declare class Xslt {
      * The exported entry point of the XSL-T processor.
      * @param xmlDoc The input document root, as DOM node.
      * @param stylesheet The stylesheet document root, as DOM node.
-     * @returns the processed document, as XML text in a string, or JSON string if outputMethod is 'json'.
+     * @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>;
     /**
@@ -843,6 +854,17 @@ declare class Xslt {
      */
     protected xsltTemplate(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     protected xsltText(context: ExprContext, template: XNode, output?: XNode): void;
+    /**
+     * Validates XSLT stylesheet/transform attributes.
+     * According to XSLT specification, validates:
+     * - Required version attribute
+     * - Valid version values (1.0, 2.0, 3.0)
+     * - Valid namespace declarations
+     * - Valid values for optional attributes (extension-element-prefixes, exclude-result-prefixes)
+     * @param stylesheetElement The `<xsl:stylesheet>` or `<xsl:transform>` element to validate.
+     * @param context The Expression Context for namespace access.
+     */
+    protected validateStylesheetAttributes(stylesheetElement: XNode, context: ExprContext): void;
     /**
      * Implements `<xsl:stylesheet>` and `<xsl:transform>`, and its corresponding
      * validations.

package/index.d.ts

@@ -22,6 +22,7 @@ declare class XNode {
     parentNode: XNode;
     visited: boolean;
     escape: boolean;
+    fromXslText: boolean;
     static _unusedXNodes: any[];
     constructor(type: number, name: string, opt_value: any, opt_owner: any, opt_namespace?: any);
     /**
@@ -138,7 +139,7 @@ interface XPathNode {
     nodeType: number;
     nodeName: string;
     localName?: string;
-    namespaceURI?: string | null;
+    namespaceUri?: string | null;
     textContent?: string | null;
     parentNode?: XPathNode | null;
     childNodes?: ArrayLike<XPathNode>;
@@ -213,6 +214,11 @@ interface XPathContext {
      * Example: { "atom": "http://www.w3.org/2005/Atom" }
      */
     namespaces?: XPathNamespaces;
+    /**
+     * XSLT version ('1.0', '2.0', '3.0') for version-specific behavior.
+     * Used by functions like json-to-xml() which are only available in XSLT 3.0+
+     */
+    xsltVersion?: string;
 }
 /**
  * Result types that can be returned from XPath evaluation.
@@ -412,6 +418,11 @@ declare class NodeConverter {
      * Create custom functions for XPath context (like key(), document(), etc.).
      */
     private createCustomFunctions;
+    /**
+     * Convert an XPathNode interface tree to actual XNode objects.
+     * This is needed to convert json-to-xml() output to XSLT-compatible nodes.
+     */
+    private convertXPathNodeToXNode;
     /**
      * Convert an XML node to a JSON string representation.
      * This is a simplified implementation of XSLT 3.0's xml-to-json().
@@ -532,7 +543,7 @@ type XsltOptions = {
     cData: boolean;
     escape: boolean;
     selfClosingTags: boolean;
-    outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json';
+    outputMethod?: 'xml' | 'html' | 'text' | 'xhtml' | 'json' | 'adaptive';
     parameters?: XsltParameter[];
 };
 
@@ -567,7 +578,7 @@ declare class Xslt {
     options: XsltOptions;
     decimalFormatSettings: XsltDecimalFormatSettings;
     outputDocument: XDocument;
-    outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json';
+    outputMethod: 'xml' | 'html' | 'text' | 'name' | 'xhtml' | 'json' | 'adaptive';
     outputOmitXmlDeclaration: string;
     version: string;
     firstTemplateRan: boolean;
@@ -592,7 +603,7 @@ declare class Xslt {
      * The exported entry point of the XSL-T processor.
      * @param xmlDoc The input document root, as DOM node.
      * @param stylesheet The stylesheet document root, as DOM node.
-     * @returns the processed document, as XML text in a string, or JSON string if outputMethod is 'json'.
+     * @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>;
     /**
@@ -843,6 +854,17 @@ declare class Xslt {
      */
     protected xsltTemplate(context: ExprContext, template: XNode, output?: XNode): Promise<void>;
     protected xsltText(context: ExprContext, template: XNode, output?: XNode): void;
+    /**
+     * Validates XSLT stylesheet/transform attributes.
+     * According to XSLT specification, validates:
+     * - Required version attribute
+     * - Valid version values (1.0, 2.0, 3.0)
+     * - Valid namespace declarations
+     * - Valid values for optional attributes (extension-element-prefixes, exclude-result-prefixes)
+     * @param stylesheetElement The `<xsl:stylesheet>` or `<xsl:transform>` element to validate.
+     * @param context The Expression Context for namespace access.
+     */
+    protected validateStylesheetAttributes(stylesheetElement: XNode, context: ExprContext): void;
     /**
      * Implements `<xsl:stylesheet>` and `<xsl:transform>`, and its corresponding
      * validations.