@tradik/xslt-processor 1.0.3 → 1.1.1

package/package.json

@@ -1,27 +1,37 @@
 {
   "name": "@tradik/xslt-processor",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "JavaScript implementation of XSLTProcessor for browser environments and CLI",
   "type": "module",
   "main": "dist/xslt-processor.cjs",
   "module": "dist/xslt-processor.js",
-  "browser": "dist/xslt-processor.browser.js",
+  "browser": "dist/xslt-processor.js",
   "types": "dist/xslt-processor.d.ts",
   "bin": {
-    "xslt": "./bin/xslt.js"
+    "xslt": "bin/xslt.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/xslt-processor.d.ts",
-      "browser": "./dist/xslt-processor.browser.js",
-      "import": "./dist/xslt-processor.js",
-      "require": "./dist/xslt-processor.cjs"
+      "browser": {
+        "types": "./dist/xslt-processor.d.ts",
+        "default": "./dist/xslt-processor.js"
+      },
+      "import": {
+        "types": "./dist/xslt-processor.d.ts",
+        "default": "./dist/xslt-processor.js"
+      },
+      "require": {
+        "types": "./dist/xslt-processor.d.cts",
+        "default": "./dist/xslt-processor.cjs"
+      }
     }
   },
   "files": [
     "dist",
     "src",
-    "bin"
+    "bin",
+    "!src/**/*.test.js",
+    "!bin/**/*.test.js"
   ],
   "publishConfig": {
     "access": "public"
@@ -32,8 +42,8 @@
     "test:watch": "node --test --watch src/**/*.test.js",
     "test:browser": "node tests/browser-test-runner.js",
     "lint": "eslint src/",
-    "format": "prettier --write \"src/**/*.js\"",
-    "format:check": "prettier --check \"src/**/*.js\"",
+    "format": "prettier --write \"src/**/*.js\" \"bin/**/*.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"bin/**/*.js\"",
     "prepublishOnly": "npm run build && npm run test"
   },
   "keywords": [
@@ -57,12 +67,13 @@
   },
   "homepage": "https://github.com/spagu/XSLT-Processor#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "devDependencies": {
-    "eslint": "^9.0.0",
-    "prettier": "^3.4.0",
-    "esbuild": "^0.24.0",
-    "jsdom": "^25.0.0"
+    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.10.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.9.6"
   }
 }

package/src/XSLTProcessor.js

@@ -30,6 +30,113 @@ export class XSLTProcessor {
     this._engine = null;
     this._stylesheet = null;
     this._parameters = new Map();
+    this._stylesheetLoader = null;
+    this._documentLoader = null;
+  }
+
+  /**
+   * The underlying XSLT engine (advanced usage).
+   *
+   * The engine is created lazily by {@link XSLTProcessor#importStylesheet},
+   * so this getter returns `null` until a stylesheet has been imported.
+   * Prefer the public {@link XSLTProcessor#setStylesheetLoader} over reaching
+   * into the engine directly.
+   *
+   * @returns {import('./xslt/engine.js').XsltEngine|null} The engine, or null before import
+   *
+   * @example
+   * processor.importStylesheet(xslDoc, '/styles/main.xsl');
+   * console.log(processor.engine.outputSettings.method);
+   */
+  get engine() {
+    return this._engine;
+  }
+
+  /**
+   * Sets the loader used to resolve `xsl:import` and `xsl:include` references.
+   *
+   * The loader is synchronous: it MUST return the external stylesheet as a
+   * `Document` or as an XML string (which is parsed automatically). Promises
+   * are not awaited by the engine, so pre-load remote stylesheets before
+   * calling `importStylesheet`.
+   *
+   * The loader may be set before or after `importStylesheet`. When set before,
+   * it is passed to the engine on creation, which is required for the loader to
+   * be used while the stylesheet is being compiled. When set after, the live
+   * engine is updated as well.
+   *
+   * @param {((href: string, baseUri?: string) => (Document|string))|null} loader
+   *   The loader function, or null to remove a previously configured loader
+   * @returns {XSLTProcessor} This processor, to allow chaining
+   * @throws {TypeError} If the loader is neither a function nor null
+   *
+   * @example
+   * processor.setStylesheetLoader((href) => readFileSync(href, 'utf8'));
+   * processor.importStylesheet(mainStylesheet, '/styles/main.xsl');
+   */
+  setStylesheetLoader(loader) {
+    if (
+      loader !== null &&
+      loader !== undefined &&
+      typeof loader !== "function"
+    ) {
+      throw new TypeError(
+        "Failed to execute 'setStylesheetLoader' on 'XSLTProcessor': The loader argument must be a function or null.",
+      );
+    }
+
+    this._stylesheetLoader = loader ?? null;
+
+    // Keep an already created engine in sync
+    if (this._engine) {
+      this._engine.setStylesheetLoader(this._stylesheetLoader);
+    }
+
+    return this;
+  }
+
+  /**
+   * Sets the loader used to resolve the XSLT `document()` function.
+   *
+   * The loader is synchronous: it MUST return the referenced document as a
+   * `Document`, as an XML string (which is parsed automatically) or as `null`
+   * when the document cannot be provided. Returning `null`, like configuring no
+   * loader at all, makes `document()` evaluate to an empty node-set rather than
+   * failing the transformation.
+   *
+   * The loader may be set before or after `importStylesheet`; a live engine is
+   * kept in sync.
+   *
+   * @param {((uri: string, baseUri?: string) => (Document|string|null))|null} loader
+   *   The loader function, or null to remove a previously configured loader
+   * @returns {XSLTProcessor} This processor, to allow chaining
+   * @throws {TypeError} If the loader is neither a function nor null
+   *
+   * @example
+   * // Node.js: resolve document() against the file system
+   * import { readFileSync } from 'node:fs';
+   * processor.setDocumentLoader((uri) => readFileSync(uri, 'utf8'));
+   * processor.importStylesheet(xslDoc, '/styles/main.xsl');
+   */
+  setDocumentLoader(loader) {
+    if (
+      loader !== null &&
+      loader !== undefined &&
+      typeof loader !== "function"
+    ) {
+      throw new TypeError(
+        "Failed to execute 'setDocumentLoader' on 'XSLTProcessor': The loader argument must be a function or null.",
+      );
+    }
+
+    this._documentLoader = loader ?? null;
+
+    // Keep an already created engine in sync
+    if (this._engine) {
+      this._engine.setDocumentLoader(this._documentLoader);
+    }
+
+    return this;
   }
 
   /**
@@ -40,14 +147,17 @@ export class XSLTProcessor {
    * <xsl:stylesheet> or <xsl:transform> element.
    *
    * @param {Node} style - The XSLT stylesheet to import (Document or Element)
+   * @param {string} [stylesheetUri] - Optional URI of the stylesheet, used as the
+   *   base URI when resolving relative `xsl:import`/`xsl:include` hrefs. When
+   *   omitted, hrefs are passed to the loader unresolved.
    * @returns {void}
    *
    * @example
    * const parser = new DOMParser();
    * const xslDoc = parser.parseFromString(xslText, 'application/xml');
-   * processor.importStylesheet(xslDoc);
+   * processor.importStylesheet(xslDoc, '/styles/main.xsl');
    */
-  importStylesheet(style) {
+  importStylesheet(style, stylesheetUri) {
     if (!style) {
       throw new TypeError(
         "Failed to execute 'importStylesheet' on 'XSLTProcessor': 1 argument required, but only 0 present.",
@@ -70,14 +180,17 @@ export class XSLTProcessor {
     }
 
     this._stylesheet = style;
-    this._engine = new XsltEngine();
+    this._engine = new XsltEngine({
+      stylesheetLoader: this._stylesheetLoader,
+      documentLoader: this._documentLoader,
+    });
 
     // Apply any previously set parameters
     for (const [key, value] of this._parameters) {
-      this._engine.globalParameters[key] = { value };
+      this._engine.setParameterValue(key, value);
     }
 
-    this._engine.importStylesheet(style);
+    this._engine.importStylesheet(style, stylesheetUri);
   }
 
   /**
@@ -182,6 +295,55 @@ export class XSLTProcessor {
     }
   }
 
+  /**
+   * Transforms the node source by applying the XSLT stylesheet and serializes
+   * the result to a string honoring the stylesheet `xsl:output` settings.
+   *
+   * Non-W3C convenience method: the native XSLTProcessor has no equivalent.
+   * Output method, indentation, XML declaration, document type declaration,
+   * CDATA sections and `disable-output-escaping` are all honored
+   * (XSLT 1.0 section 16).
+   *
+   * @param {Node} source - The XML document to transform
+   * @returns {string|null} The serialized result, or null on a transformation error
+   *
+   * @example
+   * const xml = processor.transformToString(xmlDoc);
+   * // '<?xml version="1.0" encoding="UTF-8"?>\n<BAR>\n  <QUX/>\n</BAR>'
+   */
+  transformToString(source) {
+    if (!source) {
+      throw new TypeError(
+        "Failed to execute 'transformToString' on 'XSLTProcessor': 1 argument required, but only 0 present.",
+      );
+    }
+
+    if (!this._engine || !this._stylesheet) {
+      throw new Error(
+        "Failed to execute 'transformToString' on 'XSLTProcessor': No stylesheet has been imported.",
+      );
+    }
+
+    // Validate source node
+    if (
+      source.nodeType !== 1 &&
+      source.nodeType !== 9 &&
+      source.nodeType !== 11
+    ) {
+      throw new TypeError(
+        "Failed to execute 'transformToString' on 'XSLTProcessor': The source is not a valid node type.",
+      );
+    }
+
+    try {
+      return this._engine.transformToString(source);
+    } catch (error) {
+      // Match transformToDocument behavior - return null on error
+      console.error("XSLT transformation error:", error);
+      return null;
+    }
+  }
+
   /**
    * Sets a parameter in the XSLT stylesheet.
    *
@@ -212,7 +374,7 @@ export class XSLTProcessor {
 
     // If engine is already initialized, update it
     if (this._engine) {
-      this._engine.globalParameters[key] = { value };
+      this._engine.setParameterValue(key, value);
     }
   }
 
@@ -279,7 +441,7 @@ export class XSLTProcessor {
     this._parameters.delete(key);
 
     if (this._engine) {
-      delete this._engine.globalParameters[key];
+      this._engine.clearParameterValue(key);
     }
   }
 
@@ -297,13 +459,20 @@ export class XSLTProcessor {
     this._parameters.clear();
 
     if (this._engine) {
-      this._engine.globalParameters = {};
+      this._engine.clearParameterValues();
     }
   }
 
   /**
    * Removes all parameters and stylesheets from the XSLTProcessor.
    *
+   * Per the W3C `XSLTProcessor` semantics, `reset()` clears stylesheet state and
+   * parameters only. The stylesheet and document loaders are processor
+   * configuration rather than stylesheet state, so they are deliberately
+   * preserved and stay effective for the next `importStylesheet()` call. Pass
+   * `null` to {@link XSLTProcessor#setStylesheetLoader} or
+   * {@link XSLTProcessor#setDocumentLoader} to remove them explicitly.
+   *
    * @returns {void}
    *
    * @example

package/src/index.js

@@ -29,7 +29,7 @@ export {
   XSLTProcessor,
   isNativeXSLTSupported,
   installGlobal,
-  default as default,
+  default,
 } from "./XSLTProcessor.js";
 
 // XPath module (for advanced users)
@@ -46,10 +46,18 @@ export {
 // XSLT engine (for advanced users)
 export { XsltEngine, XsltContext } from "./xslt/index.js";
 
+// Output serializer (xsl:output, XSLT 1.0 section 16)
+export {
+  serializeResult,
+  markRawText,
+  isRawText,
+  resolveOutputSettings,
+} from "./xslt/serializer.js";
+
 /**
  * Version information
  */
-export const VERSION = "1.0.0";
+export const VERSION = "1.1.1";
 
 /**
  * Check if we're running in a browser environment
@@ -61,6 +69,4 @@ export const isBrowser =
  * Check if we're running in Node.js
  */
 export const isNode =
-  typeof process !== "undefined" &&
-  process.versions != null &&
-  process.versions.node != null;
+  typeof process !== "undefined" && process.versions?.node != null;

package/src/xpath/evaluator.js

@@ -51,12 +51,29 @@ const FORBIDDEN_VARIABLE_NAMES = Object.freeze([
  * XPath evaluation context
  */
 export class XPathContext {
-  constructor(node, position = 1, size = 1, variables = {}, namespaces = {}) {
+  /**
+   * @param {Node} node - The context node
+   * @param {number} [position] - The context position (1-based)
+   * @param {number} [size] - The context size
+   * @param {Object} [variables] - Variable bindings by name
+   * @param {Object} [namespaces] - Namespace bindings by prefix
+   * @param {*} [hostContext] - Opaque context of the host language (XSLT),
+   *   carried through unchanged so host defined functions can reach it
+   */
+  constructor(
+    node,
+    position = 1,
+    size = 1,
+    variables = {},
+    namespaces = {},
+    hostContext = null,
+  ) {
     this.node = node;
     this.position = position;
     this.size = size;
     this.variables = variables;
     this.namespaces = namespaces;
+    this.hostContext = hostContext;
   }
 
   clone(overrides = {}) {
@@ -66,6 +83,7 @@ export class XPathContext {
       overrides.size ?? this.size,
       overrides.variables ?? this.variables,
       overrides.namespaces ?? this.namespaces,
+      overrides.hostContext ?? this.hostContext,
     );
   }
 }
@@ -75,7 +93,10 @@ export class XPathContext {
  */
 export class XPathEvaluator {
   constructor(options = {}) {
-    this.functions = this.initCoreFunctions();
+    this.functions = Object.assign(
+      Object.create(null),
+      this.initCoreFunctions(),
+    );
     this.maxRecursionDepth =
       options.maxRecursionDepth ?? XPathLimits.MAX_RECURSION_DEPTH;
     this.maxResultSize = options.maxResultSize ?? XPathLimits.MAX_RESULT_SIZE;
@@ -535,7 +556,8 @@ export class XPathEvaluator {
       case "node":
         return true;
       case "text":
-        return node.nodeType === 3;
+        // The XPath data model has no CDATA sections: they are text nodes
+        return node.nodeType === 3 || node.nodeType === 4;
       case "comment":
         return node.nodeType === 8;
       case "processing-instruction":
@@ -590,15 +612,34 @@ export class XPathEvaluator {
     return context.variables[name];
   }
 
+  /**
+   * Register additional functions, for example the XSLT function library.
+   *
+   * Existing names are overwritten, so a host language can also specialise a
+   * core function. Each function is called as `fn(args, context)` with the
+   * evaluator as `this`.
+   *
+   * @param {Object<string, Function>} functions - Functions by name
+   * @returns {XPathEvaluator} This evaluator, to allow chaining
+   *
+   * @example
+   * evaluator.registerFunctions({ 'my:double': (args, ctx) => 2 });
+   */
+  registerFunctions(functions) {
+    for (const [name, fn] of Object.entries(functions)) {
+      this.functions[name] = fn;
+    }
+    return this;
+  }
+
   evalFunctionCall(ast, context) {
     const name = ast.prefix ? `${ast.prefix}:${ast.name}` : ast.name;
-    const fn = this.functions[name];
 
-    if (!fn) {
+    if (!Object.hasOwn(this.functions, name)) {
       throw new Error(`Unknown function: ${name}`);
     }
 
-    return fn.call(this, ast.args, context);
+    return this.functions[name].call(this, ast.args, context);
   }
 
   // Type conversion functions
@@ -659,7 +700,7 @@ export class XPathEvaluator {
         // Document Fragment
         let text = "";
         const walker = (n) => {
-          if (n.nodeType === 3) {
+          if (n.nodeType === 3 || n.nodeType === 4) {
             text += n.nodeValue || "";
           } else if (n.childNodes) {
             for (const child of n.childNodes) {

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#processXsltElement} handles.
+ */
+
+"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);
+}