@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/io/decode.js

@@ -0,0 +1,140 @@
+/**
+ * XML Input Decoding
+ *
+ * Turns the raw bytes of an XML document into text following XML 1.0 Appendix F
+ * ("Autodetection of Character Encodings"): a byte order mark wins, then the
+ * `encoding` pseudo-attribute of the XML declaration, then UTF-8. Decoding is
+ * done with TextDecoder, so every WHATWG encoding label is accepted
+ * (ISO-8859-x, windows-125x, Shift_JIS, EUC-KR, ...).
+ *
+ * Shared by the command line tool (bin/lib/decode.js) and the asynchronous
+ * API (byte streams and loader responses); it only needs the global
+ * TextDecoder, so it runs in browsers too.
+ *
+ * @module io/decode
+ */
+
+"use strict";
+
+/** Byte order marks, longest first, with the encoding they announce. */
+const BYTE_ORDER_MARKS = [
+  { bytes: [0xef, 0xbb, 0xbf], encoding: "utf-8" },
+  { bytes: [0xff, 0xfe], encoding: "utf-16le" },
+  { bytes: [0xfe, 0xff], encoding: "utf-16be" },
+];
+
+/** First bytes of `<?` in UTF-16 without a byte order mark. */
+const UTF16_SIGNATURES = [
+  { bytes: [0x3c, 0x00, 0x3f, 0x00], encoding: "utf-16le" },
+  { bytes: [0x00, 0x3c, 0x00, 0x3f], encoding: "utf-16be" },
+];
+
+/** How many leading bytes are scanned for the XML declaration. */
+const DECLARATION_SCAN_LENGTH = 1024;
+
+/** Matches the encoding pseudo-attribute of an XML declaration. */
+const ENCODING_DECLARATION =
+  /^<\?xml\s[^>]*?\bencoding\s*=\s*(["'])([A-Za-z][\w.:-]*)\1/;
+
+/**
+ * Error raised when a file declares an encoding the runtime cannot decode.
+ */
+export class EncodingError extends Error {
+  /**
+   * @param {string} message - Human readable explanation
+   */
+  constructor(message) {
+    super(message);
+    this.name = "EncodingError";
+  }
+}
+
+/**
+ * Check whether a buffer starts with the given bytes.
+ *
+ * @param {Uint8Array} buffer - Raw file content
+ * @param {number[]} bytes - Expected leading bytes
+ * @returns {boolean} True when the buffer starts with bytes
+ */
+function startsWith(buffer, bytes) {
+  return bytes.every((byte, index) => buffer[index] === byte);
+}
+
+/**
+ * Read the encoding pseudo-attribute from an ASCII compatible XML declaration.
+ *
+ * @param {Uint8Array} buffer - Raw file content
+ * @returns {string|null} The declared encoding label, or null when absent
+ */
+function readDeclaredEncoding(buffer) {
+  const prefix = new globalThis.TextDecoder("latin1").decode(
+    buffer.subarray(0, DECLARATION_SCAN_LENGTH),
+  );
+  const match = ENCODING_DECLARATION.exec(prefix);
+  return match ? match[2] : null;
+}
+
+/**
+ * Detect the character encoding of an XML file (XML 1.0 Appendix F).
+ *
+ * A UTF-16 label declared in an ASCII compatible file cannot be right (the
+ * declaration itself was readable as single bytes), so it falls back to
+ * UTF-8, as browsers do.
+ *
+ * @param {Uint8Array} buffer - Raw file content
+ * @returns {{encoding: string, bomLength: number}} Encoding label and the
+ *   number of byte order mark bytes to skip
+ *
+ * @example
+ * detectEncoding(Buffer.from('<?xml version="1.0" encoding="ISO-8859-1"?><a/>'));
+ * // { encoding: 'ISO-8859-1', bomLength: 0 }
+ */
+export function detectEncoding(buffer) {
+  const bom = BYTE_ORDER_MARKS.find(({ bytes }) => startsWith(buffer, bytes));
+  if (bom) {
+    return { encoding: bom.encoding, bomLength: bom.bytes.length };
+  }
+
+  const utf16 = UTF16_SIGNATURES.find(({ bytes }) => startsWith(buffer, bytes));
+  if (utf16) {
+    return { encoding: utf16.encoding, bomLength: 0 };
+  }
+
+  const declared = readDeclaredEncoding(buffer);
+  if (!declared || /^utf-?16/i.test(declared)) {
+    return { encoding: "utf-8", bomLength: 0 };
+  }
+
+  return { encoding: declared, bomLength: 0 };
+}
+
+/**
+ * Decode the raw bytes of an XML file into a string without byte order mark.
+ *
+ * Malformed byte sequences become U+FFFD instead of aborting the run.
+ *
+ * @param {Uint8Array} buffer - Raw file content
+ * @param {string} [label] - Human readable file name used in errors
+ * @returns {string} The decoded document text
+ * @throws {EncodingError} When the declared encoding is not supported
+ *
+ * @example
+ * decodeXml(readFileSync('latin1.xml')); // '<?xml ... encoding="ISO-8859-1"?><a>café</a>'
+ */
+export function decodeXml(buffer, label = "document") {
+  const { encoding, bomLength } = detectEncoding(buffer);
+  let decoder;
+
+  try {
+    decoder = new globalThis.TextDecoder(encoding, {
+      fatal: false,
+      ignoreBOM: true,
+    });
+  } catch {
+    throw new EncodingError(
+      `Unsupported encoding "${encoding}" declared in ${label}`,
+    );
+  }
+
+  return decoder.decode(buffer.subarray(bomLength));
+}

package/src/io/readSource.js

@@ -0,0 +1,167 @@
+/**
+ * Asynchronous XML Input
+ *
+ * Reads the input of the asynchronous API: a DOM node, a string, a WHATWG
+ * `ReadableStream` or an async iterable of strings or bytes (a Node.js
+ * `Readable`, a `Response.body`, a generator...). XSLT 1.0 gives templates
+ * random access to the whole source tree (any axis, `key()`, `id()`), so a
+ * stream is read to its end and parsed once: input streaming bounds nothing,
+ * it only lets callers pass what they have without collecting it first.
+ *
+ * @module io/readSource
+ */
+
+import { decodeXml } from "./decode.js";
+import { parseXml, resolveDomParser } from "../xslt/domParsing.js";
+import { throwIfAborted } from "../async/abort.js";
+
+/**
+ * @typedef {string|Uint8Array|ArrayBuffer} SourceChunk
+ */
+
+/**
+ * Whether a value is a WHATWG ReadableStream (or anything with getReader).
+ *
+ * @param {unknown} value - Candidate
+ * @returns {boolean} True for readable streams
+ */
+function isReadableStream(value) {
+  return typeof value?.getReader === "function";
+}
+
+/**
+ * Iterate a ReadableStream through its reader, which every implementation
+ * has (not every browser makes streams async iterable).
+ *
+ * @param {ReadableStream} stream - The stream
+ * @yields {SourceChunk} Its chunks
+ * @returns {AsyncGenerator<SourceChunk, void, void>} The chunks
+ */
+async function* readerChunks(stream) {
+  const reader = stream.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Bytes of a binary chunk.
+ *
+ * @param {Uint8Array|ArrayBuffer} chunk - The chunk
+ * @returns {Uint8Array|null} Its bytes, or null for a non-binary value
+ */
+function toBytes(chunk) {
+  if (chunk instanceof Uint8Array) return chunk;
+  if (chunk instanceof ArrayBuffer) return new Uint8Array(chunk);
+  return null;
+}
+
+/**
+ * Concatenate byte chunks.
+ *
+ * @param {Uint8Array[]} chunks - The chunks
+ * @returns {Uint8Array} All bytes
+ */
+function concatBytes(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return bytes;
+}
+
+/**
+ * Read a stream of strings or bytes to its end. Strings are joined; bytes are
+ * decoded as a whole (byte order mark, XML declaration encoding, else UTF-8),
+ * so a multi-byte character split between chunks is decoded correctly.
+ *
+ * @param {ReadableStream<SourceChunk>|AsyncIterable<SourceChunk>} stream - Input
+ * @param {AbortSignal} [signal] - Cancels the read between chunks
+ * @returns {Promise<string>} The text
+ * @throws {TypeError} When a chunk is neither a string nor bytes, or strings
+ *   and bytes are mixed
+ * @throws {*} The abort reason when `signal` is aborted
+ *
+ * @example
+ * await readText(Readable.from(["<a>", "</a>"])); // "<a></a>"
+ */
+export async function readText(stream, signal) {
+  const iterable = isReadableStream(stream) ? readerChunks(stream) : stream;
+  const texts = [];
+  const binary = [];
+  for await (const chunk of iterable) {
+    throwIfAborted(signal);
+    const bytes = typeof chunk === "string" ? null : toBytes(chunk);
+    if (bytes === null && typeof chunk !== "string") {
+      throw new TypeError(
+        "XML input streams must yield strings, Uint8Arrays or ArrayBuffers",
+      );
+    }
+    if (bytes) binary.push(bytes);
+    else texts.push(chunk);
+    if (texts.length > 0 && binary.length > 0) {
+      throw new TypeError("XML input streams cannot mix strings and bytes");
+    }
+  }
+  throwIfAborted(signal);
+  return binary.length > 0 ? decodeXml(concatBytes(binary)) : texts.join("");
+}
+
+/**
+ * Whether a value can be read by {@link readText}.
+ *
+ * @param {unknown} value - Candidate
+ * @returns {boolean} True for readable streams and async iterables
+ */
+export function isStreamSource(value) {
+  return (
+    isReadableStream(value) ||
+    typeof value?.[Symbol.asyncIterator] === "function"
+  );
+}
+
+/**
+ * Turn any supported input into a DOM node: a node is returned as is, bytes
+ * are decoded, a stream is read to its end, and text is parsed with the
+ * configured DOMParser (see domParsing.js).
+ *
+ * @param {Node|string|Uint8Array|ArrayBuffer|ReadableStream|AsyncIterable} source - Input
+ * @param {object} [options] - Reading options
+ * @param {AbortSignal} [options.signal] - Cancels the read
+ * @param {import('../xslt/domParsing.js').DomParserLike|null} [options.domParser] -
+ *   Parser to use instead of the global DOMParser
+ * @param {Document|null} [options.referenceDoc] - Document whose window may
+ *   provide a DOMParser
+ * @returns {Promise<Node>} The source node
+ * @throws {TypeError} For unsupported inputs
+ * @throws {Error} When the markup is not well formed
+ *
+ * @example
+ * const doc = await readSource(response.body);
+ */
+export async function readSource(source, options = {}) {
+  const { signal, domParser = null, referenceDoc = null } = options;
+  throwIfAborted(signal);
+  if (typeof source?.nodeType === "number") return source;
+
+  let text;
+  const bytes = toBytes(source);
+  if (typeof source === "string") text = source;
+  else if (bytes) text = decodeXml(bytes);
+  else if (isStreamSource(source)) text = await readText(source, signal);
+  else {
+    throw new TypeError(
+      "The source must be a Node, a string, bytes, a ReadableStream or an async iterable",
+    );
+  }
+  return parseXml(text, resolveDomParser(domParser, referenceDoc));
+}