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

XSLTProcessor

Constructor

const processor = new XSLTProcessor();

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

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 }).

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.