@tradik/xslt-processor 1.1.1 → 1.3.0

package/bin/lib/transform.js

@@ -2,39 +2,44 @@
  * XSLT Processor CLI - Transformation Helpers
  *
  * DOM environment setup, document parsing and the transformation itself.
- * Output is serialized through XSLTProcessor#transformToString so that the
- * xsl:output settings of the stylesheet are honored.
+ * Output is serialized in chunks (src/async/stream.js, the same serializer
+ * as XSLTProcessor#transformToString) so that the xsl:output settings of the
+ * stylesheet are honored and large results are written as they are produced.
  */
 
 "use strict";
 
-import { JSDOM } from "jsdom";
 import { XSLTProcessor } from "../../src/XSLTProcessor.js";
+import { transformToChunks } from "../../src/async/stream.js";
+import { findParseError } from "../../src/xslt/domParsing.js";
+import { XSLT_VERSION_MODES, usesXslt3 } from "../../src/bridge/version.js";
+import {
+  createDocumentLoader,
+  createStylesheetLoader,
+  toBaseUri,
+} from "./loaders.js";
+import { installDomGlobals, loadDomEnvironment } from "./dom.js";
 
 /**
- * Create a JSDOM based DOM environment and expose it globally.
+ * Create the DOM environment of the command line tool and expose it
+ * globally (see dom.js): jsdom, else @xmldom/xmldom; `XSLT_DOM=xmldom` or
+ * `XSLT_DOM=jsdom` picks one.
  *
  * The XSLT engine builds its result documents through the global `document`,
  * so the globals have to be installed before transforming.
  *
- * @returns {JSDOM} The created JSDOM instance
+ * @param {string} [name] - DOM implementation, default `$XSLT_DOM`
+ * @returns {Promise<import("./dom.js").DomEnvironment>} The environment
+ * @throws {Error} When no DOM implementation is installed
  */
-export function createDomEnvironment() {
-  const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
-    contentType: "text/html",
-  });
-
-  globalThis.document = dom.window.document;
-  globalThis.DOMParser = dom.window.DOMParser;
-  globalThis.XMLSerializer = dom.window.XMLSerializer;
-
-  return dom;
+export async function createDomEnvironment(name = process.env.XSLT_DOM) {
+  return installDomGlobals(await loadDomEnvironment(name));
 }
 
 /**
  * Parse an XML string, reporting parser errors as exceptions.
  *
- * @param {JSDOM} dom - DOM environment
+ * @param {import("./dom.js").DomEnvironment} dom - DOM environment
  * @param {string} content - XML source text
  * @param {string} label - Human readable document label used in errors
  * @returns {Document} Parsed document
@@ -45,7 +50,7 @@ export function parseDocument(dom, content, label) {
     "application/xml",
   );
 
-  const error = doc.querySelector("parsererror");
+  const error = findParseError(doc);
   if (error) {
     throw new Error(`Error parsing ${label}: ${error.textContent}`);
   }
@@ -53,20 +58,29 @@ export function parseDocument(dom, content, label) {
   return doc;
 }
 
+/** Output methods accepted by `--method`. */
+export const OUTPUT_METHODS = Object.freeze(["xml", "html", "xhtml", "text"]);
+
 /**
  * Override the stylesheet xsl:output settings from the command line flags.
  *
  * @param {XSLTProcessor} processor - Processor with an imported stylesheet
  * @param {object} values - Parsed command line option values
  * @returns {object} The effective output settings
+ * @throws {Error} When `--method` is not one of {@link OUTPUT_METHODS}
  */
 export function applyOutputOverrides(processor, values) {
-  const settings = processor._engine.outputSettings;
+  const settings = processor.engine.outputSettings;
 
   if (values.format || values.indent) {
     settings.indent = "yes";
   }
   if (values.method) {
+    if (!OUTPUT_METHODS.includes(values.method)) {
+      throw new Error(
+        `Invalid --method "${values.method}": expected xml, html, xhtml or text`,
+      );
+    }
     settings.method = values.method;
   }
   if (values["no-declaration"]) {
@@ -77,28 +91,90 @@ export function applyOutputOverrides(processor, values) {
 }
 
 /**
- * Run a transformation and serialize its result.
+ * The `xsltVersion` option selected by `--xslt-version`.
+ *
+ * @param {object} values - Parsed command line option values
+ * @returns {"1.0"|"auto"} The mode, "1.0" by default
+ * @throws {Error} When the flag is neither 1.0 nor auto
+ */
+export function xsltVersionOf(values) {
+  const mode = values["xslt-version"] ?? "1.0";
+  if (!XSLT_VERSION_MODES.includes(mode)) {
+    throw new Error(`Invalid --xslt-version "${mode}": expected 1.0 or auto`);
+  }
+  return mode;
+}
+
+/**
+ * Load @tradik/xslt3 (dynamic import) when `--xslt-version auto` is given
+ * and the stylesheet declares version 2.0 or more, so that the synchronous
+ * transformation can use it.
+ *
+ * @param {import("./dom.js").DomEnvironment} dom - DOM environment
+ * @param {string} xsltContent - XSLT stylesheet text
+ * @param {object} values - Parsed command line option values
+ * @returns {Promise<void>} Resolves once the engine is available
+ * @throws {Error} For an invalid flag, or when @tradik/xslt3 is missing
+ */
+export async function prepareXsltVersion(dom, xsltContent, values) {
+  const mode = xsltVersionOf(values);
+  if (mode === "auto") {
+    const xsltDoc = parseDocument(dom, xsltContent, "XSLT");
+    if (usesXslt3(xsltDoc, mode)) await XSLTProcessor.preload();
+  }
+}
+
+/**
+ * @typedef {Object} TransformationInputs
+ * @property {import("./dom.js").DomEnvironment} dom - DOM environment
+ * @property {string} xmlContent - XML source text
+ * @property {string} xsltContent - XSLT stylesheet text
+ * @property {Record<string, string>} params - Stylesheet parameters
+ * @property {object} values - Parsed command line option values
+ * @property {string} [xsltFile] - Canonical stylesheet path; enables
+ *   xsl:include, xsl:import and document() relative to it
+ * @property {string} [baseDir] - Canonical base directory every loaded file
+ *   is confined to (required together with xsltFile)
+ * @property {(message: string) => void} [warn] - Warning sink for document()
+ */
+
+/**
+ * @typedef {Object} StreamedTransformation
+ * @property {Iterator<string>} chunks - The serialized result in chunks of
+ *   bounded size (see src/xslt/serializer/chunks.js), with character
+ *   references for the characters the output encoding cannot represent
+ * @property {string} encoding - The effective `xsl:output` encoding, the
+ *   encoding the result has to be written in
+ */
+
+/**
+ * Run a transformation; its result is serialized as the chunks are read,
+ * so the output is written without ever being held as one string.
  *
- * @param {object} options - Transformation inputs
- * @param {JSDOM} options.dom - DOM environment
- * @param {string} options.xmlContent - XML source text
- * @param {string} options.xsltContent - XSLT stylesheet text
- * @param {Record<string, string>} options.params - Stylesheet parameters
- * @param {object} options.values - Parsed command line option values
- * @returns {string} The serialized transformation result
+ * @param {TransformationInputs} inputs - Transformation inputs
+ * @returns {StreamedTransformation} The result chunks and their encoding
+ * @throws {Error} "Transformation failed" when the transformation fails
+ *   (the cause is reported on stderr, as XSLTProcessor does)
  */
-export function runTransformation({
+export function streamTransformation({
   dom,
   xmlContent,
   xsltContent,
   params,
   values,
+  xsltFile,
+  baseDir,
+  warn,
 }) {
   const xmlDoc = parseDocument(dom, xmlContent, "XML");
   const xsltDoc = parseDocument(dom, xsltContent, "XSLT");
 
-  const processor = new XSLTProcessor();
-  processor.importStylesheet(xsltDoc);
+  const processor = new XSLTProcessor({ xsltVersion: xsltVersionOf(values) });
+  if (xsltFile) {
+    processor.setStylesheetLoader(createStylesheetLoader(baseDir));
+    processor.setDocumentLoader(createDocumentLoader(baseDir, warn));
+  }
+  processor.importStylesheet(xsltDoc, xsltFile && toBaseUri(xsltFile));
 
   for (const [name, value] of Object.entries(params)) {
     processor.setParameter(null, name, value);
@@ -106,10 +182,25 @@ export function runTransformation({
 
   applyOutputOverrides(processor, values);
 
-  const output = processor.transformToString(xmlDoc);
-  if (output === null) {
-    throw new Error("Transformation failed");
+  let chunks;
+  try {
+    chunks = transformToChunks(processor.engine, xmlDoc);
+  } catch (error) {
+    console.error("XSLT transformation error:", error);
+    throw new Error("Transformation failed", { cause: error });
   }
+  return { chunks, encoding: processor.engine.outputSettings.encoding };
+}
 
-  return output;
+/**
+ * Run a transformation and serialize its result to one string.
+ *
+ * @param {TransformationInputs} inputs - Transformation inputs
+ * @returns {{output: string, encoding: string}} The serialized result and
+ *   its encoding
+ * @throws {Error} "Transformation failed" when the transformation fails
+ */
+export function runTransformation(inputs) {
+  const { chunks, encoding } = streamTransformation(inputs);
+  return { output: [...chunks].join(""), encoding };
 }

package/bin/xslt.js

@@ -10,7 +10,7 @@
 
 "use strict";
 
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { parseArgs } from "node:util";
 import {
   CLI_OPTIONS,
@@ -18,7 +18,13 @@ import {
   printHelp,
   printVersion,
 } from "./lib/options.js";
-import { createDomEnvironment, runTransformation } from "./lib/transform.js";
+import {
+  createDomEnvironment,
+  prepareXsltVersion,
+  streamTransformation,
+} from "./lib/transform.js";
+import { decodeXml } from "./lib/decode.js";
+import { writeResult } from "./lib/output.js";
 import {
   resolveBaseDir,
   resolveInputPath,
@@ -39,22 +45,6 @@ function readArguments() {
   }
 }
 
-/**
- * Write the transformation result to a file or to stdout.
- *
- * @param {string} output - Serialized transformation result
- * @param {string|undefined} target - Validated absolute output path, if any
- * @returns {Promise<void>} Resolves once the result has been written
- */
-async function writeOutput(output, target) {
-  if (target) {
-    await writeFile(target, output, "utf-8");
-    console.error(`Output written to ${target}`);
-    return;
-  }
-  console.log(output);
-}
-
 /**
  * CLI entry point.
  *
@@ -81,9 +71,8 @@ async function main() {
     process.exit(1);
   }
 
-  const dom = createDomEnvironment();
-
   try {
+    const dom = await createDomEnvironment();
     const baseDir = resolveBaseDir();
     const xmlFile = resolveInputPath(xmlPath, "XML", baseDir);
     const xsltFile = resolveInputPath(xsltPath, "XSLT", baseDir);
@@ -91,24 +80,34 @@ async function main() {
       ? resolveOutputPath(args.values.output, baseDir)
       : undefined;
 
-    const [xmlContent, xsltContent] = await Promise.all([
-      readFile(xmlFile, "utf-8"),
-      readFile(xsltFile, "utf-8"),
+    const [xmlBytes, xsltBytes] = await Promise.all([
+      readFile(xmlFile),
+      readFile(xsltFile),
     ]);
 
-    const output = runTransformation({
+    const xsltContent = decodeXml(xsltBytes, xsltFile);
+    // --xslt-version auto: load @tradik/xslt3 for a 2.0/3.0 stylesheet
+    await prepareXsltVersion(dom, xsltContent, args.values);
+
+    const { chunks, encoding } = streamTransformation({
       dom,
-      xmlContent,
+      xmlContent: decodeXml(xmlBytes, xmlFile),
       xsltContent,
       params: parseParameters(args.values.param),
       values: args.values,
+      xsltFile,
+      baseDir,
     });
 
-    await writeOutput(output, outputFile);
+    await writeResult(chunks, outputFile, { encoding });
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
 }
 
-main();
+main().catch((err) => {
+  // main() reports expected failures itself; this catches anything unexpected.
+  console.error(`Error: ${err?.message ?? err}`);
+  process.exit(1);
+});