@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/async/abort.js

@@ -0,0 +1,63 @@
+/**
+ * AbortSignal Helpers
+ *
+ * Every asynchronous entry point takes an optional `signal`. It is checked
+ * between steps (and between output chunks), passed to loaders, and raced
+ * against loader promises so that a loader ignoring the signal cannot keep an
+ * aborted call pending. The synchronous parts (compiling the stylesheet,
+ * building the result tree) cannot be interrupted once started.
+ *
+ * @module async/abort
+ */
+
+/**
+ * The reason of an aborted signal, with a DOMException fallback for
+ * implementations without `reason`.
+ *
+ * @param {AbortSignal} signal - An aborted signal
+ * @returns {*} The abort reason
+ */
+function abortReason(signal) {
+  return (
+    signal.reason ??
+    new globalThis.DOMException("This operation was aborted", "AbortError")
+  );
+}
+
+/**
+ * Throw the abort reason when a signal is aborted.
+ *
+ * @param {AbortSignal} [signal] - Optional signal
+ * @returns {void}
+ * @throws {*} The abort reason
+ *
+ * @example
+ * throwIfAborted(options.signal);
+ */
+export function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+
+/**
+ * Settle with a promise, or reject with the abort reason as soon as the
+ * signal aborts, whichever comes first.
+ *
+ * @template T
+ * @param {Promise<T>|T} work - The pending work
+ * @param {AbortSignal} [signal] - Optional signal
+ * @returns {Promise<T>} The work's outcome, or the abort rejection
+ *
+ * @example
+ * const text = await abortable(loader(uri), signal);
+ */
+export function abortable(work, signal) {
+  if (!signal) return Promise.resolve(work);
+  if (signal.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(work)
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}

package/src/async/documentUris.js

@@ -0,0 +1,128 @@
+/**
+ * Statically Known document() URIs
+ *
+ * Finds the `document('literal')` calls of a stylesheet module, so that the
+ * asynchronous API can load those documents before the synchronous
+ * transformation runs. Expressions are parsed with the XPath parser and the
+ * syntax tree is searched for `document()` calls whose first argument is a
+ * string literal; URIs computed at run time (`document(@href)`) and calls
+ * with an explicit base (second argument) are left to the synchronous
+ * document loader.
+ *
+ * Expressions are read from the expression attributes of XSLT instructions
+ * (`select`, `test`, `use`, `value`) and from the `{...}` parts of every other
+ * attribute (attribute value templates).
+ *
+ * @module async/documentUris
+ */
+
+import { NodeType, parse } from "../xpath/parser.js";
+import { parseAvt } from "../xslt/avt.js";
+import { XSLT_NAMESPACE } from "../xslt/elements.js";
+import { resolveUri, stripFragment } from "../xslt/uri.js";
+
+/** Attributes of XSLT instructions holding a whole expression. */
+const EXPRESSION_ATTRIBUTES = new Set(["select", "test", "use", "value"]);
+
+/**
+ * The literal arguments of the `document()` calls of an expression.
+ *
+ * @param {string} expression - XPath expression
+ * @returns {string[]} The literal URIs, empty when the expression is invalid
+ *   (the engine reports that when compiling)
+ *
+ * @example
+ * literalDocumentArguments("document('a.xml')/x | document(@b)"); // ["a.xml"]
+ */
+export function literalDocumentArguments(expression) {
+  let tree;
+  try {
+    tree = parse(expression);
+  } catch {
+    return [];
+  }
+  const found = [];
+  const stack = [tree];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    const [first] = node.args ?? [];
+    const isStatic =
+      node.type === NodeType.FUNCTION_CALL &&
+      node.name === "document" &&
+      !node.prefix &&
+      node.args.length === 1 &&
+      first.type === NodeType.LITERAL;
+    if (isStatic) found.push(first.value);
+    for (const value of Object.values(node)) {
+      for (const child of Array.isArray(value) ? value : [value]) {
+        if (typeof child?.type === "string") stack.push(child);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * The expressions held by an attribute.
+ *
+ * @param {Attr} attribute - An attribute of a stylesheet element
+ * @returns {string[]} The expressions
+ */
+function attributeExpressions(attribute) {
+  const element = attribute.ownerElement;
+  const isExpression =
+    element.namespaceURI === XSLT_NAMESPACE &&
+    !attribute.namespaceURI &&
+    EXPRESSION_ATTRIBUTES.has(attribute.localName);
+  if (isExpression) return [attribute.value];
+  try {
+    return parseAvt(attribute.value)
+      .filter((part) => typeof part !== "string")
+      .map((part) => part.expr);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The resolved URIs of the literal `document()` calls of a stylesheet module.
+ * They are resolved against the main stylesheet URI, as the engine resolves
+ * `document()` calls without a base argument; fragment identifiers are
+ * dropped and `document('')` (the stylesheet itself) is skipped.
+ *
+ * @param {Node} module - Stylesheet document or element
+ * @param {string|undefined} stylesheetUri - URI of the main stylesheet
+ * @returns {string[]} Resolved URIs, possibly repeated
+ *
+ * @example
+ * staticDocumentUris(xslDoc, "/xsl/main.xsl"); // ["/xsl/data.xml"]
+ */
+export function staticDocumentUris(module, stylesheetUri) {
+  const root = module.documentElement ?? module;
+  const uris = [];
+  for (const element of [root, ...root.getElementsByTagName("*")]) {
+    if (!hasDocumentCall(element)) continue;
+    for (const attribute of element.attributes) {
+      for (const expression of attributeExpressions(attribute)) {
+        for (const literal of literalDocumentArguments(expression)) {
+          const target = stripFragment(literal);
+          if (target) uris.push(resolveUri(target, stylesheetUri));
+        }
+      }
+    }
+  }
+  return uris;
+}
+
+/**
+ * Cheap pre-filter: whether any attribute of an element mentions `document`.
+ *
+ * @param {Element} element - Stylesheet element
+ * @returns {boolean} True when an attribute may hold a document() call
+ */
+function hasDocumentCall(element) {
+  for (const attribute of element.attributes) {
+    if (attribute.value.includes("document")) return true;
+  }
+  return false;
+}

package/src/async/loaders.js

@@ -0,0 +1,134 @@
+/**
+ * Asynchronous Loaders
+ *
+ * An asynchronous loader fetches a stylesheet module or a `document()`
+ * document before the synchronous transformation runs:
+ *
+ *     (uri, baseUri, { signal }) => Promise<Document | string | Uint8Array |
+ *                                          ArrayBuffer | Response | null>
+ *
+ * `uri` is already resolved against `baseUri` (as for the synchronous
+ * loaders). Strings are parsed; bytes and `Response` bodies are decoded like
+ * files (byte order mark, XML declaration encoding, else UTF-8). Without a
+ * loader, the global `fetch` is used when there is one (browsers, Node.js
+ * for http(s) URIs).
+ *
+ * @module async/loaders
+ */
+
+import { decodeXml } from "../io/decode.js";
+import { parseXml, resolveDomParser } from "../xslt/domParsing.js";
+import { abortable } from "./abort.js";
+
+/**
+ * @typedef {(uri: string, baseUri: string|undefined, init: {signal?: AbortSignal}) =>
+ *   Promise<Document|string|Uint8Array|ArrayBuffer|Response|null>|Document|string|null} AsyncLoader
+ */
+
+/**
+ * Loader reading a URI with the global `fetch`.
+ *
+ * @param {string} uri - The resolved URI
+ * @param {string} [_baseUri] - Unused
+ * @param {{signal?: AbortSignal}} [init] - Fetch options
+ * @returns {Promise<Response>} The response
+ */
+function fetchLoader(uri, _baseUri, init = {}) {
+  return globalThis.fetch(uri, { signal: init.signal });
+}
+
+/**
+ * The loader to use: the given one, else `fetch` when available.
+ *
+ * @param {AsyncLoader|null|undefined} loader - Configured loader
+ * @returns {AsyncLoader} A loader
+ * @throws {TypeError} When `loader` is not a function, or none is given and
+ *   there is no global fetch
+ */
+export function resolveAsyncLoader(loader) {
+  if (loader !== undefined && loader !== null) {
+    if (typeof loader !== "function") {
+      throw new TypeError("The loader must be a function");
+    }
+    return loader;
+  }
+  if (typeof globalThis.fetch !== "function") {
+    throw new TypeError(
+      "No loader given and no global fetch available to load external resources",
+    );
+  }
+  return fetchLoader;
+}
+
+/**
+ * Whether a value is a fetch `Response` (or looks like one).
+ *
+ * @param {unknown} value - Candidate
+ * @returns {boolean} True for response-like objects
+ */
+function isResponse(value) {
+  return typeof value?.arrayBuffer === "function" && "ok" in value;
+}
+
+/**
+ * Turn what a loader returned into a document.
+ *
+ * @param {unknown} loaded - Loader result
+ * @param {string} uri - The URI, for error messages
+ * @param {object|null} parser - DOMParser to parse text with
+ * @returns {Promise<Document|null>} The document, or null for a null result
+ * @throws {Error} For failed responses, malformed markup or unsupported values
+ */
+async function toDocument(loaded, uri, parser) {
+  if (loaded === null || loaded === undefined) return null;
+  if (typeof loaded.nodeType === "number") return loaded;
+  let value = loaded;
+  if (isResponse(value)) {
+    if (!value.ok) {
+      throw new Error(`Failed to load "${uri}": HTTP ${value.status}`);
+    }
+    value = await value.arrayBuffer();
+  }
+  if (value instanceof ArrayBuffer) value = new Uint8Array(value);
+  if (value instanceof Uint8Array) value = decodeXml(value, uri);
+  if (typeof value !== "string") {
+    throw new TypeError(
+      `The loader returned an unsupported value for "${uri}"`,
+    );
+  }
+  return parseXml(value, parser);
+}
+
+/**
+ * Create a function loading documents with an asynchronous loader, each URI
+ * once (concurrent requests for the same URI share one load).
+ *
+ * @param {AsyncLoader} loader - The loader
+ * @param {object} options - Loading options
+ * @param {AbortSignal} [options.signal] - Passed to the loader; aborting
+ *   rejects pending loads
+ * @param {object|null} [options.domParser] - Parser for loaded text
+ * @param {Document|null} [options.referenceDoc] - Document whose window may
+ *   provide a DOMParser
+ * @returns {(uri: string, baseUri?: string) => Promise<Document|null>} The
+ *   de-duplicating load function
+ *
+ * @example
+ * const load = createDocumentFetcher(resolveAsyncLoader(), { signal });
+ * const doc = await load("https://example.com/common.xsl");
+ */
+export function createDocumentFetcher(loader, options = {}) {
+  const { signal, domParser = null, referenceDoc = null } = options;
+  const parser = resolveDomParser(domParser, referenceDoc);
+  const pending = new Map();
+  return (uri, baseUri) => {
+    if (!pending.has(uri)) {
+      const work = abortable(
+        Promise.resolve().then(() => loader(uri, baseUri, { signal })),
+        signal,
+      ).then((loaded) => toDocument(loaded, uri, parser));
+      pending.set(uri, work);
+    }
+    return pending.get(uri);
+  };
+}

package/src/async/preload.js

@@ -0,0 +1,159 @@
+/**
+ * Stylesheet and Document Preloading
+ *
+ * The XSLT engine compiles and transforms synchronously. To use asynchronous
+ * loaders (`fetch`), everything the engine will ask for is loaded first:
+ *
+ * 1. the `xsl:import`/`xsl:include` tree, breadth first, every module in
+ *    parallel and each URI once (diamond imports share one load). A cycle
+ *    cannot make preloading loop, since a URI is never loaded twice; it is
+ *    reported by the engine while compiling ("Circular stylesheet reference
+ *    detected"), exactly as with a synchronous loader;
+ * 2. the documents named by literal `document('...')` calls of every module
+ *    (see documentUris.js).
+ *
+ * The preloaded documents are then served by synchronous loaders, falling
+ * back to the synchronous loaders configured on the processor.
+ *
+ * @module async/preload
+ */
+
+import { resolveUri } from "../xslt/uri.js";
+import { XSLT_NAMESPACE } from "../xslt/elements.js";
+import { staticDocumentUris } from "./documentUris.js";
+
+/**
+ * The resolved hrefs of the `xsl:import` and `xsl:include` elements of a
+ * stylesheet module (top-level children of its root element).
+ *
+ * @param {Node} module - Stylesheet document or root element
+ * @param {string|undefined} moduleUri - URI of the module
+ * @returns {string[]} Resolved URIs, in document order
+ */
+export function moduleReferences(module, moduleUri) {
+  const root = module.documentElement ?? module;
+  const uris = [];
+  for (const child of root.childNodes) {
+    const isReference =
+      child.nodeType === 1 &&
+      child.namespaceURI === XSLT_NAMESPACE &&
+      (child.localName === "import" || child.localName === "include");
+    const href = isReference ? child.getAttribute("href") : null;
+    if (href) uris.push(resolveUri(href, moduleUri));
+  }
+  return uris;
+}
+
+/**
+ * Load the whole import/include tree of a stylesheet.
+ *
+ * @param {Node} style - The main stylesheet (document or root element)
+ * @param {string|undefined} stylesheetUri - Its URI (base of relative hrefs)
+ * @param {(uri: string, baseUri?: string) => Promise<Document|null>} fetchDocument -
+ *   De-duplicating loader (see createDocumentFetcher)
+ * @returns {Promise<Map<string, Document>>} Every module by resolved URI
+ * @throws {Error} When a module cannot be loaded
+ *
+ * @example
+ * const modules = await preloadModules(xslDoc, "/xsl/main.xsl", load);
+ */
+export async function preloadModules(style, stylesheetUri, fetchDocument) {
+  const modules = new Map();
+  const seen = new Set(stylesheetUri ? [stylesheetUri] : []);
+  let level = [{ module: style, uri: stylesheetUri }];
+
+  while (level.length > 0) {
+    const requests = [];
+    for (const { module, uri } of level) {
+      for (const target of moduleReferences(module, uri)) {
+        if (seen.has(target)) continue;
+        seen.add(target);
+        requests.push(loadModule(target, uri, fetchDocument));
+      }
+    }
+    level = await Promise.all(requests);
+    for (const { module, uri } of level) modules.set(uri, module);
+  }
+  return modules;
+}
+
+/**
+ * Load one stylesheet module.
+ *
+ * @param {string} uri - Resolved URI
+ * @param {string|undefined} baseUri - URI of the referencing module
+ * @param {(uri: string, baseUri?: string) => Promise<Document|null>} fetchDocument - Loader
+ * @returns {Promise<{module: Document, uri: string}>} The module
+ * @throws {Error} When the loader fails or returns nothing
+ */
+async function loadModule(uri, baseUri, fetchDocument) {
+  const module = await fetchDocument(uri, baseUri);
+  if (!module) throw new Error(`Cannot load stylesheet "${uri}"`);
+  return { module, uri };
+}
+
+/**
+ * Load the documents named by literal `document()` calls. A failed load is
+ * not reported here: it is kept and reported when the transformation actually
+ * evaluates that call (it may sit in a branch that never runs). Aborting
+ * rejects at once.
+ *
+ * @param {Array<Node>} modules - Stylesheet modules to scan
+ * @param {string|undefined} stylesheetUri - Base URI of `document()` calls
+ * @param {(uri: string, baseUri?: string) => Promise<Document|null>} fetchDocument - Loader
+ * @param {AbortSignal} [signal] - Optional signal
+ * @returns {Promise<Map<string, {document?: Document|null, error?: Error}>>}
+ *   Outcome by resolved URI
+ */
+export async function preloadDocuments(
+  modules,
+  stylesheetUri,
+  fetchDocument,
+  signal,
+) {
+  const uris = new Set(
+    modules.flatMap((module) => staticDocumentUris(module, stylesheetUri)),
+  );
+  const outcomes = await Promise.all(
+    [...uris].map((uri) =>
+      fetchDocument(uri, stylesheetUri).then(
+        (document) => ({ document }),
+        (error) => {
+          if (signal?.aborted) throw error;
+          return { error };
+        },
+      ),
+    ),
+  );
+  return new Map([...uris].map((uri, index) => [uri, outcomes[index]]));
+}
+
+/**
+ * Synchronous stylesheet loader serving the preloaded modules. Every href of
+ * the import tree is literal, so every module the engine asks for while
+ * compiling has been preloaded.
+ *
+ * @param {Map<string, Document>} modules - Preloaded modules by resolved URI
+ * @returns {(href: string) => Document} The loader
+ */
+export function preloadedStylesheetLoader(modules) {
+  return (href) => modules.get(href);
+}
+
+/**
+ * Synchronous `document()` loader serving preloaded documents first; a
+ * preload failure is thrown when the document is actually needed.
+ *
+ * @param {Map<string, {document?: Document|null, error?: Error}>} documents -
+ *   Preloaded outcomes
+ * @param {Function|null} fallback - Loader configured on the processor
+ * @returns {(uri: string, baseUri?: string) => (Document|string|null)} The loader
+ */
+export function preloadedDocumentLoader(documents, fallback) {
+  return (uri, baseUri) => {
+    const outcome = documents.get(uri);
+    if (outcome?.error) throw outcome.error;
+    if (outcome) return outcome.document;
+    return fallback ? fallback(uri, baseUri) : null;
+  };
+}

package/src/async/processor.js

@@ -0,0 +1,206 @@
+/**
+ * Asynchronous XSLTProcessor Methods
+ *
+ * Implementation of `importStylesheetAsync`, `transformAsync` and
+ * `transformToStream` of {@link XSLTProcessor}. The transformation itself
+ * stays synchronous (XPath evaluation cannot await): the asynchronous work is
+ * reading the inputs and preloading what the stylesheet references, before
+ * the synchronous compile and transform.
+ *
+ * @module async/processor
+ */
+
+import { readSource } from "../io/readSource.js";
+import { toChunkSize } from "../xslt/serializer/chunks.js";
+import { throwIfAborted } from "./abort.js";
+import { createDocumentFetcher, resolveAsyncLoader } from "./loaders.js";
+import {
+  preloadDocuments,
+  preloadModules,
+  preloadedStylesheetLoader,
+} from "./preload.js";
+import { chunkStream, transformToChunks } from "./stream.js";
+
+/**
+ * Reject a configured loader that is not a function.
+ *
+ * @param {Function|null|undefined} loader - Configured loader
+ * @returns {void}
+ * @throws {TypeError} When `loader` is set but not a function
+ */
+function checkLoader(loader) {
+  if (loader !== undefined && loader !== null) resolveAsyncLoader(loader);
+}
+
+/**
+ * A loader that is resolved when first used, so that a stylesheet without
+ * external references needs neither a loader nor `fetch`.
+ *
+ * @param {Function|null|undefined} loader - Configured loader
+ * @returns {Function} The lazy loader
+ */
+function lazyLoader(loader) {
+  return (...args) => resolveAsyncLoader(loader)(...args);
+}
+
+/**
+ * The document owning a node (for its window's DOMParser).
+ *
+ * @param {Node} node - A node
+ * @returns {Document} The owner document
+ */
+function ownerOf(node) {
+  return node.ownerDocument ?? node;
+}
+
+/**
+ * Load the documents of the literal `document()` calls of stylesheet modules.
+ *
+ * @param {Node[]} modules - The stylesheet modules
+ * @param {string|undefined} stylesheetUri - URI of the main stylesheet
+ * @param {Function|null|undefined} loader - Asynchronous document loader
+ * @param {AbortSignal} [signal] - Optional signal
+ * @returns {Promise<Map<string, object>>} Preloaded outcomes by URI
+ */
+async function preloadStaticDocuments(modules, stylesheetUri, loader, signal) {
+  const fetchDocument = createDocumentFetcher(lazyLoader(loader), {
+    signal,
+    referenceDoc: ownerOf(modules[0]),
+  });
+  const documents = await preloadDocuments(
+    modules,
+    stylesheetUri,
+    fetchDocument,
+    signal,
+  );
+  throwIfAborted(signal);
+  return documents;
+}
+
+/**
+ * Import a stylesheet whose `xsl:import`/`xsl:include` modules and literal
+ * `document()` documents are loaded asynchronously first.
+ *
+ * @param {import('../XSLTProcessor.js').XSLTProcessor} processor - Processor
+ * @param {Node|string|Uint8Array|ArrayBuffer|ReadableStream|AsyncIterable} style -
+ *   The stylesheet, as a node or as markup (read and parsed first)
+ * @param {string} [stylesheetUri] - Base URI of relative hrefs and document() URIs
+ * @param {object} [options] - Loading options
+ * @param {Function} [options.loader] - Asynchronous stylesheet loader, `fetch` by default
+ * @param {Function} [options.documentLoader] - Asynchronous document() loader,
+ *   `options.loader` by default
+ * @param {AbortSignal} [options.signal] - Cancels loading
+ * @returns {Promise<void>} Resolves once the stylesheet is compiled
+ */
+export async function importStylesheetAsync(
+  processor,
+  style,
+  stylesheetUri,
+  options = {},
+) {
+  const { signal, loader } = options;
+  const documentLoader = options.documentLoader ?? loader;
+  checkLoader(loader);
+  checkLoader(documentLoader);
+
+  const node = await readSource(style, { signal });
+  // XSLT 2.0/3.0 with xsltVersion "auto": load @tradik/xslt3 first
+  await processor._prepareEngine(node);
+  const modules = await preloadModules(
+    node,
+    stylesheetUri,
+    createDocumentFetcher(lazyLoader(loader), {
+      signal,
+      referenceDoc: ownerOf(node),
+    }),
+  );
+  const allModules = [node, ...modules.values()];
+  const documents = await preloadStaticDocuments(
+    allModules,
+    stylesheetUri,
+    documentLoader,
+    signal,
+  );
+
+  processor._compile(node, stylesheetUri, {
+    stylesheetLoader: preloadedStylesheetLoader(modules),
+    modules: allModules,
+    documents,
+  });
+}
+
+/**
+ * Transform asynchronously: read the source (node, markup or stream),
+ * optionally import a stylesheet or preload `document()` documents first,
+ * then transform and serialize.
+ *
+ * @param {import('../XSLTProcessor.js').XSLTProcessor} processor - Processor
+ * @param {Node|string|Uint8Array|ArrayBuffer|ReadableStream|AsyncIterable} source - Input
+ * @param {object} [options] - Options
+ * @param {AbortSignal} [options.signal] - Cancels the call
+ * @param {Node|string|ReadableStream|AsyncIterable} [options.stylesheet] -
+ *   Stylesheet to import first (see importStylesheetAsync)
+ * @param {string} [options.stylesheetUri] - Its URI
+ * @param {Function} [options.fetchStylesheet] - Asynchronous stylesheet loader
+ * @param {Function} [options.fetchDocument] - Asynchronous document() loader
+ * @returns {Promise<string>} The serialized result
+ * @throws {Error} When loading, parsing or the transformation fails
+ */
+export async function transformAsync(processor, source, options = {}) {
+  const { signal, stylesheet, fetchStylesheet, fetchDocument } = options;
+  if (stylesheet !== undefined && stylesheet !== null) {
+    await importStylesheetAsync(processor, stylesheet, options.stylesheetUri, {
+      loader: fetchStylesheet,
+      documentLoader: fetchDocument,
+      signal,
+    });
+  } else {
+    processor._requireStylesheet("transformAsync");
+    if (fetchDocument) {
+      checkLoader(fetchDocument);
+      processor._usePreloadedDocuments(
+        await preloadStaticDocuments(
+          processor._modules,
+          processor._stylesheetUri,
+          fetchDocument,
+          signal,
+        ),
+      );
+    }
+  }
+  const node = await readSource(source, {
+    signal,
+    referenceDoc: ownerOf(processor._stylesheet),
+  });
+  processor._checkSource("transformAsync", node);
+  throwIfAborted(signal);
+  return processor.engine.transformToString(node);
+}
+
+/**
+ * Transform and stream the serialized result (see async/stream.js).
+ *
+ * @param {import('../XSLTProcessor.js').XSLTProcessor} processor - Processor
+ * @param {Node|string|Uint8Array|ArrayBuffer|ReadableStream|AsyncIterable} source - Input
+ * @param {{signal?: AbortSignal, chunkSize?: number}} [options] - Options
+ * @returns {ReadableStream<string>} The serialized result
+ * @throws {TypeError|RangeError} For a missing stylesheet, an invalid source
+ *   node or chunk size (at once; later failures error the stream)
+ */
+export function transformToStream(processor, source, options = {}) {
+  processor._requireStylesheet("transformToStream");
+  if (typeof source?.nodeType === "number") {
+    processor._checkSource("transformToStream", source);
+  }
+  const chunkSize = toChunkSize(options.chunkSize);
+  const engine = processor.engine;
+  const { signal } = options;
+  return chunkStream(async () => {
+    const node = await readSource(source, {
+      signal,
+      referenceDoc: ownerOf(processor._stylesheet),
+    });
+    processor._checkSource("transformToStream", node);
+    return transformToChunks(engine, node, { chunkSize });
+  }, options);
+}