API Reference

The XSLTProcessor class implements the W3C/MDN XSLTProcessor API and adds transformToString() plus stylesheet and document loaders. This page covers its methods, parameters, xsl:output serialization, the module exports, the XsltEngine options and the TypeScript declarations. Loaders for xsl:import, xsl:include and document() are described in Loaders.

Contents

• XSLTProcessor: Constructor, Methods, Properties
• Module exports
• TypeScript
• Serializing output (xsl:output)
• Parameters Example
• Utility Functions
• XsltEngine options
• Opt-in XSLT 2.0/3.0

XSLTProcessor

Constructor

const processor = new XSLTProcessor();

The native constructor takes no argument; this one takes optional, non-W3C options:

Methods

Like the native implementation, the transformTo* methods return null when the transformation fails (for example xsl:message terminate="yes") and log the error with console.error. Missing arguments, a source that is not a Document, Element or DocumentFragment, and calling them before importStylesheet() throw instead.

importStylesheet() throws for a stylesheet that is not valid XSLT 1.0, for example an invalid pattern such as match="a/.." (the error names the pattern), as Chrome's native processor rejects such stylesheets. The processor then keeps its previously imported stylesheet. Invalid names computed at run time by xsl:element/xsl:attribute are reported with console.warn and skipped, as libxslt does.

Properties

Module exports

@tradik/xslt-processor/polyfill

A second package entry, imported for its effect only:

import "@tradik/xslt-processor/polyfill";

It runs installGlobal() and autoApplyXmlStylesheet() on the package's own bundle (ESM dist/polyfill.js, CommonJS dist/polyfill.cjs), so importing it next to @tradik/xslt-processor loads the library once. It exports nothing.

TypeScript

Declarations ship as dist/xslt-processor.d.ts (ESM) and dist/xslt-processor.d.cts (CommonJS) and are picked up automatically through the exports map. The StylesheetLoader and OutputSettings types are exported as well.

Serializing output (xsl:output)

transformToString(source) serializes the result tree according to the xsl:output element of the stylesheet (XSLT 1.0 section 16). Unlike the DOM based methods it returns ready to write markup, so the CLI and Node.js users do not need a separate XMLSerializer or a hand rolled re-indenter.

const xslt = parser.parseFromString(`<?xml version="1.0"?>
  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" indent="yes"/>
    <xsl:template match="/"><BAR><QUX/></BAR></xsl:template>
  </xsl:stylesheet>`, 'application/xml');

const processor = new XSLTProcessor();
processor.importStylesheet(xslt);

processor.transformToString(xmlDoc);
// <?xml version="1.0" encoding="UTF-8"?>
// <BAR>
//   <QUX/>
// </BAR>

Supported xsl:output attributes:

disable-output-escaping="yes" on xsl:text and xsl:value-of is honored: the generated text is emitted verbatim, so <b> reaches the output as <b>.

The serializer can also be used on its own, for example on a fragment produced by transformToFragment:

import { serializeResult } from '@tradik/xslt-processor';

serializeResult(fragment, { method: 'html', indent: 'yes' });

When method is absent (or auto), the output method is derived from the result tree: html when the document element is html in no namespace, xml otherwise.

Parameters Example

const processor = new XSLTProcessor();
processor.importStylesheet(xsltDoc);

// Set parameters
processor.setParameter(null, 'sortOrder', 'ascending');
processor.setParameter(null, 'itemsPerPage', 10);

// Get parameter
const sortOrder = processor.getParameter(null, 'sortOrder');

// Clear parameters
processor.clearParameters();

Utility Functions

import {
  isNativeXSLTSupported,
  installGlobal,
  serializeResult,
  markRawText
} from '@tradik/xslt-processor';

// Check if native XSLT is functional
if (!isNativeXSLTSupported()) {
  console.log('Using JS implementation');
}

// Install as global XSLTProcessor
installGlobal(); // Only if native not available
installGlobal(true); // Force install

// Serialize any result tree with xsl:output settings
serializeResult(node, { method: 'xml', indent: 'yes' });

// Mark a text node so that it is emitted without escaping
markRawText(document.createTextNode('<b>raw</b>'));

XsltEngine options

new XsltEngine({ maxResultSize, maxRecursionDepth }) chooses the XPath limits inside a transformation, see DoS Prevention Limits.

Other XsltEngine options: stylesheetLoader, documentLoader (see Loaders) and domParser, a DOMParser-compatible object used to parse XML strings returned by loaders. It defaults to the global DOMParser or the stylesheet document's window, so it only needs to be set for DOM implementations such as @xmldom/xmldom in Node.js. setStylesheetLoader() and setDocumentLoader() return the engine, so calls can be chained.

Asynchronous and streaming API

Non-W3C additions for loading stylesheets over the network and producing large results incrementally. The synchronous W3C methods are unchanged.

// Browser: fetch the stylesheet and everything it imports, then transform
const processor = new XSLTProcessor();
const url = new URL('/xsl/main.xsl', location.href).href;
await processor.importStylesheetAsync((await fetch(url)).body, url);
const html = await processor.transformAsync((await fetch('/data.xml')).body);

// Node.js: pipe a large result without building one big string
import { Readable } from 'node:stream';
Readable.fromWeb(processor.transformToStream(xmlDoc, { signal })).pipe(process.stdout);

Limits: XSLT 1.0 needs random access to the whole source and result trees, so inputs are read fully before parsing and the result tree is built in memory. Streaming bounds the output text and delivers the first bytes before serialization ends. The transformation itself is synchronous and cannot be aborted midway; the signal is honoured while loading and reading, and between output chunks. Only literal document('...') URIs are preloaded; computed ones use setDocumentLoader. Constant-memory input streaming would need XSLT 3.0 streamability.

The building blocks are exported as well: serializeChunks(node, settings?, { chunkSize? }), DEFAULT_CHUNK_SIZE, and the engine-level transformToChunks(engine, node, options) and transformToStream(engine, node, options).

maxTemplateDepth (default 3000, exported as XSLT_MAX_TEMPLATE_DEPTH) limits the nesting of template instantiations, like libxslt's xsltMaxDepth: new XSLTProcessor({ maxTemplateDepth: 10000 }).

Opt-in XSLT 2.0/3.0

new XSLTProcessor({ xsltVersion: "auto" }) runs a stylesheet whose effective version (the version attribute of xsl:stylesheet, or xsl:version of a simplified stylesheet) is 2.0 or more with @tradik/xslt3; stylesheets of version 1.0 keep the XSLT 1.0 engine. The default, xsltVersion: "1.0", is unchanged: a version="2.0" stylesheet runs in XSLT 1.0 forwards-compatible mode, as in Chrome.

@tradik/xslt3 is an optional peer dependency (npm install @tradik/xslt3), loaded with a dynamic import() the first time it is needed. Because import() is asynchronous:

• the asynchronous API (importStylesheetAsync, transformAsync, transformToStream after an asynchronous import) loads it by itself;
• the synchronous W3C API needs await XSLTProcessor.preload() once beforehand. Without it, importStylesheet() of a 2.0/3.0 stylesheet throws This XSLT 2.0 stylesheet needs @tradik/xslt3: call "await XSLTProcessor.preload()" before importStylesheet(), or use importStylesheetAsync() / transformAsync().

When the package is not installed, preload() and the asynchronous API reject with Cannot load @tradik/xslt3: install @tradik/xslt3 to run XSLT 2.0/3.0 stylesheets (the import error is the cause).

await XSLTProcessor.preload("3.0");
const processor = new XSLTProcessor({ xsltVersion: "auto" });
processor.setStylesheetLoader((href) => readFileSync(fileURLToPath(href), "utf8"));
processor.importStylesheet(xsl30Doc, pathToFileURL("grouping.xsl").href);
processor.setParameter(null, "title", "Report");
const xml = processor.transformToString(xmlDoc);

How the API maps onto @tradik/xslt3:

As with XSLT 1.0, the transformTo* methods return null and log the error when the transformation fails. xsl:result-document secondary results are not returned through this API, and maxTemplateDepth and enableDynamicEvaluate apply to the XSLT 1.0 engine only (xsl:evaluate is part of XSLT 3.0). A string parameter declared with another type (as="xs:integer") is a type error (XTTE0590); declare it as xs:string or untyped, or pass a number.

The library bundles keep import("@tradik/xslt3") as an external import: a browser page loading the IIFE bundle needs an import map for @tradik/xslt3; application bundlers resolve it like any dependency.

DOM implementations in Node.js

With xmldom, set globalThis.DOMParser = DOMParser (or pass domParser to XsltEngine) so string results of loaders can be parsed, and create owner documents with new DOMImplementation().createDocument(null, null). linkedom (no XML namespace support) and xmldom 0.8 are not supported.