@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/async/stream.js

@@ -0,0 +1,125 @@
+/**
+ * Streaming Output
+ *
+ * Serializes a transformation result as a WHATWG `ReadableStream<string>`.
+ * XSLT 1.0 builds the result tree in memory (templates can read anything
+ * they wrote into variables, and the whole source tree), so the tree is built
+ * first; what streams is the serialization: chunks are produced on demand
+ * (`pull`), one at a time, so the output is never held as one string and a
+ * consumer that reads slowly holds serialization back (backpressure).
+ *
+ * @module async/stream
+ */
+
+import { serializeChunks } from "../xslt/serializer.js";
+import { throwIfAborted } from "./abort.js";
+
+/**
+ * Serialize the transformation of a source node in chunks, as
+ * `engine.transformToString` does in one piece.
+ *
+ * @param {import('../xslt/engine.js').XsltEngine|import('../bridge/engine.js').Xslt3Engine} engine -
+ *   Engine with an imported stylesheet
+ * @param {Node} sourceNode - Source document or element
+ * @param {{chunkSize?: number}} [options] - Chunk size in UTF-16 code units
+ * @returns {Iterator<string>} The chunks; the result tree is built by this
+ *   call, serialization happens as the iterator is consumed
+ *
+ * @example
+ * for (const chunk of transformToChunks(engine, xmlDoc)) out.write(chunk);
+ */
+export function transformToChunks(engine, sourceNode, options = {}) {
+  // The @tradik/xslt3 engine (xsltVersion "auto") serializes on its own
+  if (engine.transformToChunks) {
+    return engine.transformToChunks(sourceNode, options);
+  }
+  const fragment = engine.buildResultTree(
+    sourceNode,
+    engine.createDocument(sourceNode),
+  );
+  return serializeChunks(fragment, engine.outputSettings, options);
+}
+
+/**
+ * Expose lazily produced chunks as a ReadableStream.
+ *
+ * @param {() => (Iterator<string>|Promise<Iterator<string>>)} start - Called
+ *   once, on the first pull, to produce the chunk iterator (may be async, e.g.
+ *   to read the input first)
+ * @param {{signal?: AbortSignal}} [options] - Aborting errors the stream with
+ *   the abort reason and stops the serialization
+ * @returns {ReadableStream<string>} The stream; errors of `start` or of the
+ *   serialization error the stream
+ * @throws {TypeError} When the runtime has no ReadableStream
+ *
+ * @example
+ * const stream = chunkStream(() => serializeChunks(doc, settings));
+ */
+export function chunkStream(start, options = {}) {
+  const { signal } = options;
+  const Stream = globalThis.ReadableStream;
+  if (typeof Stream !== "function") {
+    throw new TypeError("ReadableStream is not available in this runtime");
+  }
+
+  let chunks = null;
+  const stop = () => chunks?.return?.();
+  let onAbort = null;
+
+  return new Stream(
+    {
+      start(controller) {
+        if (signal?.aborted) {
+          controller.error(signal.reason);
+          return;
+        }
+        onAbort = () => {
+          stop();
+          controller.error(signal.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+      },
+      async pull(controller) {
+        try {
+          chunks ??= await start();
+          throwIfAborted(signal);
+          const { done, value } = chunks.next();
+          if (done) {
+            signal?.removeEventListener("abort", onAbort);
+            controller.close();
+          } else {
+            controller.enqueue(value);
+          }
+        } catch (error) {
+          signal?.removeEventListener("abort", onAbort);
+          throw error;
+        }
+      },
+      cancel() {
+        signal?.removeEventListener("abort", onAbort);
+        stop();
+      },
+    },
+    { highWaterMark: 1 },
+  );
+}
+
+/**
+ * Transform a source node and stream the serialized result.
+ *
+ * @param {import('../xslt/engine.js').XsltEngine} engine - Engine with an imported stylesheet
+ * @param {Node} sourceNode - Source document or element
+ * @param {{signal?: AbortSignal, chunkSize?: number}} [options] - Options
+ * @returns {ReadableStream<string>} The serialized result
+ *
+ * @example
+ * const response = new Response(
+ *   transformToStream(engine, xmlDoc).pipeThrough(new TextEncoderStream()),
+ * );
+ */
+export function transformToStream(engine, sourceNode, options = {}) {
+  return chunkStream(
+    () => transformToChunks(engine, sourceNode, options),
+    options,
+  );
+}

package/src/bridge/engine.js

@@ -0,0 +1,221 @@
+/**
+ * Xslt3Engine: @tradik/xslt3 behind the interface of the XSLT 1.0 engine
+ *
+ * XSLTProcessor drives its engine through a small interface (loaders,
+ * parameters, importStylesheet, transformToFragment/Document/String,
+ * outputSettings). This class implements it with `compileStylesheet` and
+ * `CompiledStylesheet#transform` of @tradik/xslt3, so the W3C API, the
+ * asynchronous API and the command line tool run XSLT 2.0/3.0 stylesheets
+ * unchanged when `xsltVersion` is "auto".
+ *
+ * @module bridge/engine
+ */
+
+import { parseXml, resolveDomParser } from "../xslt/domParsing.js";
+import { transformationMethods } from "../xslt/engine/transformation.js";
+import { loadedXslt3 } from "./loader.js";
+import { camelCaseOutput, documentResult, fragmentResult } from "./results.js";
+import { stylesheetVersion } from "./version.js";
+
+/**
+ * A parameter value for @tradik/xslt3: node lists become arrays (sequences
+ * of nodes); other values are converted by @tradik/xslt3 (strings to
+ * xs:string, numbers to xs:double, booleans, nodes, arrays, Dates, maps).
+ *
+ * @param {*} value - Value given to setParameter
+ * @returns {*} The value to pass
+ */
+function parameterValue(value) {
+  const isNodeList =
+    typeof value?.length === "number" && typeof value.item === "function";
+  return isNodeList ? Array.from(value) : value;
+}
+
+/** Runs XSLT 2.0/3.0 stylesheets with @tradik/xslt3. */
+export class Xslt3Engine {
+  /**
+   * @param {object} xslt3 - The @tradik/xslt3 module
+   * @param {object} [options] - Options of XSLTProcessor
+   * @param {Function|null} [options.stylesheetLoader] - xsl:import/include loader
+   * @param {Function|null} [options.documentLoader] - doc()/document() loader
+   * @param {(() => Date)|null} [options.clock] - current-dateTime() clock
+   */
+  constructor(xslt3, options = {}) {
+    this.xslt3 = xslt3;
+    this.stylesheetLoader = options.stylesheetLoader ?? null;
+    this.documentLoader = options.documentLoader ?? null;
+    this.clock = options.clock ?? null;
+    /** @type {Map<string, *>} Parameters by `{uri}local` or `local` */
+    this.parameters = new Map();
+    this.compiled = null;
+    this.stylesheetDoc = null;
+    /** Output settings (camelCase); changes override the stylesheet's. */
+    this.outputSettings = {};
+    this.declaredOutput = {};
+  }
+
+  /** @param {Function|null} loader - xsl:import/xsl:include loader */
+  setStylesheetLoader(loader) {
+    this.stylesheetLoader = loader;
+  }
+
+  /** @param {Function|null} loader - doc()/document() loader */
+  setDocumentLoader(loader) {
+    this.documentLoader = loader;
+  }
+
+  /**
+   * @param {string} key - `{uri}local` or `local`
+   * @param {*} value - The value
+   */
+  setParameterValue(key, value) {
+    this.parameters.set(key, parameterValue(value));
+  }
+
+  /** @param {string} key - `{uri}local` or `local` */
+  clearParameterValue(key) {
+    this.parameters.delete(key);
+  }
+
+  /** Remove every parameter. */
+  clearParameterValues() {
+    this.parameters.clear();
+  }
+
+  /**
+   * Parse markup returned by a loader.
+   *
+   * @param {string} text - XML markup
+   * @returns {Document} The document
+   */
+  parseXmlString(text) {
+    return parseXml(text, resolveDomParser(null, this.stylesheetDoc));
+  }
+
+  /**
+   * A loader result as a document (markup is parsed).
+   *
+   * @param {Document|string|null} loaded - What a loader returned
+   * @returns {Document|null} The document
+   */
+  toDocument(loaded) {
+    return typeof loaded === "string" ? this.parseXmlString(loaded) : loaded;
+  }
+
+  /**
+   * Compile a stylesheet.
+   *
+   * @param {Node} style - Stylesheet document or root element
+   * @param {string} [stylesheetUri] - Its URI
+   * @returns {void}
+   * @throws {Error} The static errors of @tradik/xslt3 (XTSE...)
+   */
+  importStylesheet(style, stylesheetUri) {
+    this.stylesheetDoc = style.ownerDocument ?? style;
+    this.compiled = this.xslt3.compileStylesheet(style, {
+      baseUri: stylesheetUri,
+      // A module returned as markup is parsed with parseXml
+      loadStylesheet: (uri) => this.stylesheetLoader?.(uri),
+      parseXml: (text) => this.parseXmlString(text),
+    });
+    const declared = this.compiled.output;
+    this.declaredOutput = camelCaseOutput({ encoding: "UTF-8", ...declared });
+    this.outputSettings = { ...this.declaredOutput };
+  }
+
+  /**
+   * Run the stylesheet on a source.
+   *
+   * @param {Node} source - Source document or element
+   * @returns {{principal: Node, params: object}} The principal result and
+   *   its serialization parameters
+   */
+  run(source) {
+    const loader = this.documentLoader;
+    const result = this.compiled.transform({
+      source,
+      params: this.parameters,
+      documentLoader: loader && ((uri) => this.toDocument(loader(uri))),
+      onMessage: (message) => console.log("XSLT Message:", message.textContent),
+      currentDateTime: this.clock?.(),
+    });
+    return { principal: result.principal, params: this.paramsOf(result) };
+  }
+
+  /**
+   * The serialization parameters of a result: those @tradik/xslt3 reports,
+   * with the output settings changed through `outputSettings` on top.
+   *
+   * @param {{output: object}} result - A transformation result
+   * @returns {Record<string, *>} camelCase parameters
+   */
+  paramsOf(result) {
+    const params = camelCaseOutput(result.output);
+    for (const [name, value] of Object.entries(this.outputSettings)) {
+      if (value !== this.declaredOutput[name]) params[name] = value;
+    }
+    return params;
+  }
+
+  /**
+   * @param {Node} source - Source document or element
+   * @param {Document} output - Document that owns the fragment
+   * @returns {DocumentFragment} The result fragment
+   */
+  transformToFragment(source, output) {
+    const { principal, params } = this.run(source);
+    return fragmentResult(principal, params, output, this.xslt3.serialize);
+  }
+
+  /**
+   * @param {Node} source - Source document or element
+   * @returns {Document} The result document
+   */
+  transformToDocument(source) {
+    const { principal, params } = this.run(source);
+    const doc = transformationMethods.createDocument(source);
+    return documentResult(principal, params, doc, this.xslt3.serialize);
+  }
+
+  /**
+   * @param {Node} source - Source document or element
+   * @returns {string} The serialized result
+   */
+  transformToString(source) {
+    const { principal, params } = this.run(source);
+    return this.xslt3.serialize(principal, params);
+  }
+
+  /**
+   * The serialized result in chunks (transformToStream, the CLI).
+   *
+   * @param {Node} source - Source document or element
+   * @param {{chunkSize?: number}} [options] - Chunk size
+   * @returns {Iterator<string>} The chunks
+   */
+  transformToChunks(source, options = {}) {
+    const { principal, params } = this.run(source);
+    return this.xslt3.serializeChunks(principal, params, options);
+  }
+}
+
+/**
+ * Create the engine of an XSLT 2.0/3.0 stylesheet, with the @tradik/xslt3
+ * module loaded before (XSLTProcessor.preload or the asynchronous API).
+ *
+ * @param {Node} style - The stylesheet (for the error message)
+ * @param {object} options - See {@link Xslt3Engine}
+ * @returns {Xslt3Engine} The engine
+ * @throws {Error} When @tradik/xslt3 has not been loaded
+ */
+export function createXslt3Engine(style, options) {
+  const xslt3 = loadedXslt3();
+  if (!xslt3) {
+    throw new Error(
+      `This XSLT ${stylesheetVersion(style).toFixed(1)} stylesheet needs @tradik/xslt3: ` +
+        'call "await XSLTProcessor.preload()" before importStylesheet(), ' +
+        "or use importStylesheetAsync() / transformAsync()",
+    );
+  }
+  return new Xslt3Engine(xslt3, options);
+}

package/src/bridge/loader.js

@@ -0,0 +1,78 @@
+/**
+ * Loading @tradik/xslt3
+ *
+ * @tradik/xslt3 is an optional peer dependency: it is loaded with a dynamic
+ * `import()` the first time an XSLT 2.0/3.0 stylesheet needs it (or when
+ * `XSLTProcessor.preload()` is called), never statically, so the XSLT 1.0
+ * bundles do not contain it. Once loaded it is kept for the synchronous API.
+ *
+ * @module bridge/loader
+ */
+
+/** What to do when @tradik/xslt3 is missing. */
+export const XSLT3_MISSING =
+  "install @tradik/xslt3 to run XSLT 2.0/3.0 stylesheets (npm install @tradik/xslt3)";
+
+/**
+ * The default importer. The specifier is a literal so that bundlers of the
+ * application can resolve it; the build of this package keeps it external.
+ *
+ * @returns {Promise<object>} The @tradik/xslt3 module
+ */
+const importXslt3 = () => import("@tradik/xslt3");
+
+let importer = importXslt3;
+let loaded = null;
+let pending = null;
+
+/**
+ * Load @tradik/xslt3 once; concurrent calls share the import.
+ *
+ * @returns {Promise<object>} The @tradik/xslt3 module
+ * @throws {Error} "Cannot load @tradik/xslt3: install ..." when the import
+ *   fails (the import error is the `cause`); a later call tries again
+ *
+ * @example
+ * const { compileStylesheet } = await loadXslt3();
+ */
+export function loadXslt3() {
+  if (loaded) return Promise.resolve(loaded);
+  pending ??= Promise.resolve()
+    .then(() => importer())
+    .then(
+      (module) => {
+        loaded = module;
+        return module;
+      },
+      (error) => {
+        pending = null;
+        throw new Error(`Cannot load @tradik/xslt3: ${XSLT3_MISSING}`, {
+          cause: error,
+        });
+      },
+    );
+  return pending;
+}
+
+/**
+ * The module loaded by {@link loadXslt3}, for the synchronous API.
+ *
+ * @returns {object|null} The module, null before it has been loaded
+ */
+export function loadedXslt3() {
+  return loaded;
+}
+
+/**
+ * Replace the importer of @tradik/xslt3 and forget the loaded module
+ * (tests: simulate a missing package without uninstalling it).
+ *
+ * @param {(() => Promise<object>)|null} [replacement] - The importer, or
+ *   null for the default `import("@tradik/xslt3")`
+ * @returns {void}
+ */
+export function setXslt3Importer(replacement) {
+  importer = replacement ?? importXslt3;
+  loaded = null;
+  pending = null;
+}

package/src/bridge/results.js

@@ -0,0 +1,75 @@
+/**
+ * Shaping @tradik/xslt3 Results for the W3C API
+ *
+ * The principal result of @tradik/xslt3 is a document (a well-formed tree)
+ * or a document fragment. `transformToFragment` and `transformToDocument`
+ * return it shaped as the XSLT 1.0 engine shapes its own results (as
+ * Chrome does): html output parsed by the HTML parser of an HTML owner
+ * document, text output wrapped in a `pre` page, xml output as a document
+ * with the `doctype-public`/`doctype-system` of xsl:output.
+ *
+ * @module bridge/results
+ */
+
+import {
+  importResultFragment,
+  isHtmlDocument,
+  parseHtmlFragment,
+  wrapTextResult,
+} from "../xslt/resultTree.js";
+import { fillXmlDocument, parseHtmlDocument } from "../xslt/resultDocument.js";
+
+/**
+ * Serialization parameters by camelCase name (`omit-xml-declaration`
+ * becomes `omitXmlDeclaration`), the form the XSLT 1.0 output settings use.
+ *
+ * @param {Record<string, *>} output - Parameters of @tradik/xslt3
+ * @returns {Record<string, *>} The same parameters, camelCase names
+ *
+ * @example
+ * camelCaseOutput({ "omit-xml-declaration": "yes" }); // { omitXmlDeclaration: "yes" }
+ */
+export function camelCaseOutput(output) {
+  return Object.fromEntries(
+    Object.entries(output).map(([name, value]) => [
+      name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
+      value,
+    ]),
+  );
+}
+
+/**
+ * The result as a fragment owned by `output`.
+ *
+ * @param {Node} principal - Principal result (document or fragment)
+ * @param {Record<string, *>} params - Its serialization parameters
+ * @param {Document} output - The owner document
+ * @param {(node: Node, params: object) => string} serialize - Serializer
+ * @returns {DocumentFragment} The fragment
+ */
+export function fragmentResult(principal, params, output, serialize) {
+  if (isHtmlDocument(output) && params.method === "html") {
+    return parseHtmlFragment(serialize(principal, params), output);
+  }
+  return importResultFragment(principal, output, { htmlElements: true });
+}
+
+/**
+ * The result as a document.
+ *
+ * @param {Node} principal - Principal result (document or fragment)
+ * @param {Record<string, *>} params - Its serialization parameters
+ * @param {Document} doc - An empty document to fill
+ * @param {(node: Node, params: object) => string} serialize - Serializer
+ * @returns {Document} The result document
+ */
+export function documentResult(principal, params, doc, serialize) {
+  if (params.method === "text") {
+    return wrapTextResult(doc, serialize(principal, params));
+  }
+  if (params.method === "html") {
+    const html = parseHtmlDocument(serialize(principal, params), doc);
+    if (html) return html;
+  }
+  return fillXmlDocument(doc, importResultFragment(principal, doc), params);
+}

package/src/bridge/version.js

@@ -0,0 +1,63 @@
+/**
+ * XSLT Version Selection
+ *
+ * The `xsltVersion` option of XSLTProcessor: "1.0" (the default) runs every
+ * stylesheet with the XSLT 1.0 engine, a stylesheet declaring a higher
+ * version in forwards-compatible mode (as Chrome does); "auto" hands a
+ * stylesheet whose effective version is 2.0 or more to @tradik/xslt3.
+ *
+ * @module bridge/version
+ */
+
+import { declaredVersion } from "../xslt/forwardsCompatible.js";
+
+/** Values accepted by the `xsltVersion` option. */
+export const XSLT_VERSION_MODES = Object.freeze(["1.0", "auto"]);
+
+/**
+ * Validate the `xsltVersion` option.
+ *
+ * @param {string|undefined|null} mode - The option value
+ * @returns {"1.0"|"auto"} The mode, "1.0" when not given
+ * @throws {RangeError} For any other value
+ *
+ * @example
+ * xsltVersionMode(undefined); // "1.0"
+ */
+export function xsltVersionMode(mode) {
+  const value = mode ?? "1.0";
+  if (!XSLT_VERSION_MODES.includes(value)) {
+    throw new RangeError(
+      `Invalid xsltVersion "${value}": expected "1.0" or "auto"`,
+    );
+  }
+  return value;
+}
+
+/**
+ * The effective version of a stylesheet: the `version` attribute of
+ * `xsl:stylesheet`/`xsl:transform`, or the `xsl:version` attribute of a
+ * simplified stylesheet (literal result element).
+ *
+ * @param {Node} style - Stylesheet document or root element
+ * @returns {number} The version, NaN when missing or not a number
+ *
+ * @example
+ * stylesheetVersion(xslDoc); // 2 for <xsl:stylesheet version="2.0">
+ */
+export function stylesheetVersion(style) {
+  const root = style.nodeType === 9 ? style.documentElement : style;
+  const version = root ? declaredVersion(root) : null;
+  return version ? Number(version.trim()) : NaN;
+}
+
+/**
+ * Whether a stylesheet is run by @tradik/xslt3 in the given mode.
+ *
+ * @param {Node} style - Stylesheet document or root element
+ * @param {"1.0"|"auto"} mode - The `xsltVersion` option
+ * @returns {boolean} True in "auto" mode for version 2.0 and above
+ */
+export function usesXslt3(style, mode) {
+  return mode === "auto" && stylesheetVersion(style) >= 2;
+}

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * xslt-processor
+ * @tradik/xslt-processor
  *
  * JavaScript implementation of XSLTProcessor for browser environments.
  *
@@ -13,7 +13,7 @@
  *
  * @example
  * // ESM import
- * import { XSLTProcessor, installGlobal } from 'xslt-processor';
+ * import { XSLTProcessor, installGlobal } from '@tradik/xslt-processor';
  *
  * // Install as global replacement
  * installGlobal();
@@ -29,7 +29,7 @@ export {
   XSLTProcessor,
   isNativeXSLTSupported,
   installGlobal,
-  default as default,
+  default,
 } from "./XSLTProcessor.js";
 
 // XPath module (for advanced users)
@@ -40,16 +40,36 @@ export {
   XPathEvaluator,
   XPathContext,
   XPathResultType,
+  XPathLimits,
   parse as parseXPath,
 } from "./xpath/index.js";
 
 // XSLT engine (for advanced users)
-export { XsltEngine, XsltContext } from "./xslt/index.js";
+export {
+  XsltEngine,
+  XsltContext,
+  XSLT_MAX_RESULT_SIZE,
+  XSLT_MAX_EXPRESSION_DEPTH,
+  XSLT_MAX_TEMPLATE_DEPTH,
+} from "./xslt/index.js";
+
+// Output serializer (xsl:output, XSLT 1.0 section 16)
+export {
+  serializeResult,
+  serializeChunks,
+  DEFAULT_CHUNK_SIZE,
+  markRawText,
+  isRawText,
+  resolveOutputSettings,
+} from "./xslt/serializer.js";
+
+// Streaming output on the engine side (advanced users)
+export { transformToChunks, transformToStream } from "./async/stream.js";
 
 /**
  * Version information
  */
-export const VERSION = "1.0.0";
+export const VERSION = "1.3.0";
 
 /**
  * Check if we're running in a browser environment
@@ -61,6 +81,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;