@eksml/xml 0.1.0

package/dist/xmlParseStream.mjs

@@ -0,0 +1,313 @@
+import { n as HTML_VOID_ELEMENTS, t as HTML_RAW_CONTENT_TAGS } from "./htmlConstants-D6fsKbZ-.mjs";
+import { t as saxEngine } from "./saxEngine-BDnD7ruG.mjs";
+import { convertItemToLossy } from "./converters/lossy.mjs";
+import { convertItemToLossless } from "./converters/lossless.mjs";
+//#region src/xmlParseStream.ts
+const EQ = 61;
+const SQUOTE = 39;
+const DQUOTE = 34;
+const TAB = 9;
+const LF = 10;
+const CR = 13;
+const SPACE = 32;
+/**
+* Convert a SAX `Attributes` object into the format used by `parse()`:
+* - Returns `null` when there are no attributes.
+* - Returns an `Object.create(null)` prototype-free record otherwise.
+*/
+function toNodeAttributes(attributes) {
+	const keys = Object.keys(attributes);
+	if (keys.length === 0) return null;
+	const out = Object.create(null);
+	for (let i = 0; i < keys.length; i++) out[keys[i]] = attributes[keys[i]];
+	return out;
+}
+/**
+* Parse a processing instruction body string into an attributes record.
+* e.g. `version="1.0" encoding="UTF-8"` -> `{ version: "1.0", encoding: "UTF-8" }`
+*
+* This replicates the attribute-parsing behavior of `parse()` so that PIs
+* emitted by `XmlParseStream` match the `{ tagName: "?xml", attributes: {...} }`
+* format that consumers expect.
+*
+* Returns `null` when the body contains no attributes, matching `parse()`.
+* Uses `Object.create(null)` for prototype-free attribute records.
+*/
+function parsePIAttributes(body) {
+	let attributes = null;
+	const bodyLength = body.length;
+	let i = 0;
+	while (i < bodyLength) {
+		let charCode = body.charCodeAt(i);
+		if (charCode === SPACE || charCode === TAB || charCode === LF || charCode === CR) {
+			i++;
+			continue;
+		}
+		const nameStart = i;
+		while (i < bodyLength) {
+			charCode = body.charCodeAt(i);
+			if (charCode === EQ || charCode === SPACE || charCode === TAB || charCode === LF || charCode === CR) break;
+			i++;
+		}
+		if (i === nameStart) {
+			i++;
+			continue;
+		}
+		const name = body.substring(nameStart, i);
+		if (attributes === null) attributes = Object.create(null);
+		while (i < bodyLength) {
+			charCode = body.charCodeAt(i);
+			if (charCode !== SPACE && charCode !== TAB && charCode !== LF && charCode !== CR) break;
+			i++;
+		}
+		if (i < bodyLength && body.charCodeAt(i) === EQ) {
+			i++;
+			while (i < bodyLength) {
+				charCode = body.charCodeAt(i);
+				if (charCode !== SPACE && charCode !== TAB && charCode !== LF && charCode !== CR) break;
+				i++;
+			}
+			if (i < bodyLength) {
+				const quoteCharCode = body.charCodeAt(i);
+				if (quoteCharCode === DQUOTE || quoteCharCode === SQUOTE) {
+					const quoteCharacter = body[i];
+					i++;
+					const valueStartIndex = i;
+					const end = body.indexOf(quoteCharacter, i);
+					if (end === -1) {
+						attributes[name] = body.substring(valueStartIndex);
+						i = bodyLength;
+					} else {
+						attributes[name] = body.substring(valueStartIndex, end);
+						i = end + 1;
+					}
+				} else {
+					const valueStartIndex = i;
+					while (i < bodyLength) {
+						charCode = body.charCodeAt(i);
+						if (charCode === SPACE || charCode === TAB || charCode === LF || charCode === CR) break;
+						i++;
+					}
+					attributes[name] = body.substring(valueStartIndex, i);
+				}
+			} else attributes[name] = null;
+		} else attributes[name] = null;
+	}
+	return attributes;
+}
+/**
+* A Web Streams `TransformStream` that incrementally parses XML chunks into
+* `TNode` subtrees (or lossy/lossless objects). Works in browsers, Node.js
+* 18+, Deno, and Bun.
+*
+* Follows the platform stream class convention (like `TextDecoderStream`,
+* `DecompressionStream`, etc.) — instantiate with `new` and use with
+* `.pipeThrough()`.
+*
+* Internally powered by the SAX engine with a tree-construction layer
+* that assembles `TNode` subtrees and emits them as they complete.
+*
+* By default, nodes are emitted when a top-level element closes (depth 0).
+* Use the `select` option to emit specific elements as they close at any depth,
+* without waiting for the entire document root to finish.
+*
+* Use the `output` option to choose the emitted format:
+* - `'dom'` (default) — raw `TNode | string`
+* - `'lossy'` — compact lossy objects (`LossyValue`)
+* - `'lossless'` — order-preserving objects (`LosslessEntry`)
+*
+* @example
+* ```ts
+* import { XmlParseStream } from '@eksml/xml/stream';
+*
+* const response = await fetch('/feed.xml');
+* const reader = response.body
+*   .pipeThrough(new TextDecoderStream())
+*   .pipeThrough(new XmlParseStream())
+*   .getReader();
+*
+* while (true) {
+*   const { done, value } = await reader.read();
+*   if (done) break;
+*   console.log(value); // TNode or string
+* }
+* ```
+*/
+var XmlParseStream = class extends TransformStream {
+	constructor(options) {
+		const resolvedOptions = options ?? {};
+		let skipBytes = typeof resolvedOptions.offset === "string" ? resolvedOptions.offset.length : resolvedOptions.offset || 0;
+		const isHtml = resolvedOptions.html === true;
+		const selfClosingTags = resolvedOptions.selfClosingTags ?? (isHtml ? HTML_VOID_ELEMENTS : []);
+		const rawContentTags = resolvedOptions.rawContentTags ?? (isHtml ? HTML_RAW_CONTENT_TAGS : []);
+		const keepComments = resolvedOptions.keepComments === true;
+		const selectSet = resolvedOptions.select == null ? null : typeof resolvedOptions.select === "string" ? new Set([resolvedOptions.select]) : resolvedOptions.select.length > 0 ? new Set(resolvedOptions.select) : null;
+		const outputMode = resolvedOptions.output ?? "dom";
+		const convert = outputMode === "lossy" ? convertItemToLossy : outputMode === "lossless" ? convertItemToLossless : ((item) => item);
+		let streamController = null;
+		const stack = [];
+		let depth = 0;
+		const selectDepths = [];
+		function currentParent() {
+			return stack.length > 0 ? stack[stack.length - 1] : null;
+		}
+		function emitOrAttach(item) {
+			const parent = currentParent();
+			if (parent) parent.children.push(item);
+			else if (streamController) streamController.enqueue(convert(item));
+		}
+		/** Whether we are currently inside a selected subtree. */
+		function insideSelection() {
+			return selectDepths.length > 0;
+		}
+		/** The TNode at the top of the stack, or null. */
+		function selectParent() {
+			return stack.length > 0 ? stack[stack.length - 1] : null;
+		}
+		function defaultOnOpenTag(tagName, attributes) {
+			const node = {
+				tagName,
+				attributes: toNodeAttributes(attributes),
+				children: []
+			};
+			const parent = currentParent();
+			if (parent) parent.children.push(node);
+			stack.push(node);
+		}
+		function defaultOnCloseTag(_tagName) {
+			const node = stack.pop();
+			if (!node) return;
+			if (stack.length === 0 && streamController) streamController.enqueue(convert(node));
+		}
+		function defaultOnText(text) {
+			const parent = currentParent();
+			if (parent) parent.children.push(text);
+		}
+		function defaultOnCdata(data) {
+			const parent = currentParent();
+			if (parent) parent.children.push(data);
+		}
+		function defaultOnComment(comment) {
+			if (!keepComments) return;
+			const parent = currentParent();
+			if (parent) parent.children.push(comment);
+			else if (streamController) streamController.enqueue(convert(comment));
+		}
+		function defaultOnProcessingInstruction(name, body) {
+			emitOrAttach({
+				tagName: "?" + name,
+				attributes: parsePIAttributes(body),
+				children: []
+			});
+		}
+		function defaultOnDoctype(tagName, attributes) {
+			emitOrAttach({
+				tagName,
+				attributes: toNodeAttributes(attributes),
+				children: []
+			});
+		}
+		function selectOnOpenTag(tagName, attributes) {
+			depth++;
+			if (insideSelection()) {
+				const node = {
+					tagName,
+					attributes: toNodeAttributes(attributes),
+					children: []
+				};
+				const parent = selectParent();
+				if (parent) parent.children.push(node);
+				stack.push(node);
+				if (selectSet.has(tagName)) selectDepths.push(depth);
+			} else if (selectSet.has(tagName)) {
+				selectDepths.push(depth);
+				const node = {
+					tagName,
+					attributes: toNodeAttributes(attributes),
+					children: []
+				};
+				stack.push(node);
+			}
+		}
+		function selectOnCloseTag(_tagName) {
+			if (insideSelection()) {
+				const topSelectDepth = selectDepths[selectDepths.length - 1];
+				if (depth === topSelectDepth) {
+					const node = stack.pop();
+					if (node && streamController) streamController.enqueue(convert(node));
+					selectDepths.pop();
+				} else stack.pop();
+			}
+			depth--;
+		}
+		function selectOnText(text) {
+			if (!insideSelection()) return;
+			const parent = selectParent();
+			if (parent) parent.children.push(text);
+		}
+		function selectOnCdata(data) {
+			if (!insideSelection()) return;
+			const parent = selectParent();
+			if (parent) parent.children.push(data);
+		}
+		function selectOnComment(comment) {
+			if (!keepComments) return;
+			if (!insideSelection()) return;
+			const parent = selectParent();
+			if (parent) parent.children.push(comment);
+		}
+		function selectOnProcessingInstruction(name, body) {
+			if (!insideSelection()) return;
+			const node = {
+				tagName: "?" + name,
+				attributes: parsePIAttributes(body),
+				children: []
+			};
+			const parent = selectParent();
+			if (parent) parent.children.push(node);
+		}
+		function selectOnDoctype(tagName, attributes) {
+			if (!insideSelection()) return;
+			const node = {
+				tagName,
+				attributes: toNodeAttributes(attributes),
+				children: []
+			};
+			const parent = selectParent();
+			if (parent) parent.children.push(node);
+		}
+		const parser = saxEngine({
+			selfClosingTags,
+			rawContentTags,
+			onOpenTag: selectSet ? selectOnOpenTag : defaultOnOpenTag,
+			onCloseTag: selectSet ? selectOnCloseTag : defaultOnCloseTag,
+			onText: selectSet ? selectOnText : defaultOnText,
+			onCdata: selectSet ? selectOnCdata : defaultOnCdata,
+			onComment: selectSet ? selectOnComment : defaultOnComment,
+			onProcessingInstruction: selectSet ? selectOnProcessingInstruction : defaultOnProcessingInstruction,
+			onDoctype: selectSet ? selectOnDoctype : defaultOnDoctype
+		});
+		super({
+			transform(chunk, controller) {
+				streamController = controller;
+				if (skipBytes > 0) {
+					if (chunk.length <= skipBytes) {
+						skipBytes -= chunk.length;
+						return;
+					}
+					chunk = chunk.substring(skipBytes);
+					skipBytes = 0;
+				}
+				parser.write(chunk);
+			},
+			flush(controller) {
+				streamController = controller;
+				parser.close();
+			}
+		});
+	}
+};
+//#endregion
+export { XmlParseStream };
+
+//# sourceMappingURL=xmlParseStream.mjs.map

package/dist/xmlParseStream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"xmlParseStream.mjs","names":[],"sources":["../src/xmlParseStream.ts"],"sourcesContent":["import type { TNode } from '#src/parser.ts';\nimport { saxEngine } from '#src/saxEngine.ts';\nimport type { Attributes } from '#src/saxEngine.ts';\nimport {\n  HTML_VOID_ELEMENTS,\n  HTML_RAW_CONTENT_TAGS,\n} from '#src/utilities/htmlConstants.ts';\nimport { convertItemToLossy } from '#src/converters/lossy.ts';\nimport type { LossyValue } from '#src/converters/lossy.ts';\nimport { convertItemToLossless } from '#src/converters/lossless.ts';\nimport type { LosslessEntry } from '#src/converters/lossless.ts';\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Options for `XmlParseStream`.\n *\n * Only the fields that the transform layer actually consumes are exposed here.\n * This keeps the API honest — options like `trimWhitespace`, `entities`, and\n * `strict` belong to the synchronous `parse()` function, not the streaming\n * tree-builder.\n */\nexport interface XmlParseStreamOptions {\n  /**\n   * Starting byte offset — skip this many leading characters from the input.\n   * When a string is passed, its `.length` is used as the offset.\n   */\n  offset?: number | string;\n  /** Enable HTML parsing mode (sets default selfClosingTags/rawContentTags). */\n  html?: boolean;\n  /**\n   * Tag names that are self-closing (void elements).\n   * Defaults to standard HTML void elements when `html` is `true`, else `[]`.\n   */\n  selfClosingTags?: string[];\n  /**\n   * Tag names whose content is raw text (not parsed as XML/HTML).\n   * Defaults to `[\"script\", \"style\"]` when `html` is `true`, else `[]`.\n   */\n  rawContentTags?: string[];\n  /** Keep XML comments in the output. Defaults to `false`. */\n  keepComments?: boolean;\n  /**\n   * Emit only elements matching these tag names instead of waiting for the\n   * entire top-level tree to close.\n   *\n   * When set, each matching element is emitted as a standalone `TNode` subtree\n   * the moment its close tag is encountered, regardless of nesting depth.\n   * Non-matching ancestor elements are **not** built or emitted — the stream\n   * only produces the selected subtrees.\n   *\n   * When multiple selected tags are nested (e.g. selecting both `item` and\n   * `sub` where `<sub>` appears inside `<item>`), each matching element\n   * is emitted independently as it closes. The inner element appears both as a\n   * separate emission **and** as a child within its ancestor's subtree.\n   *\n   * Accepts a single tag name or an array of tag names.\n   *\n   * @example\n   * ```ts\n   * // Given:\n   * // <root>\n   * //   <item>\n   * //     <sub>1</sub><box>a</box>\n   * //   </item>\n   * //   <item>\n   * //     <sub>2</sub><box>b</box>\n   * //   </item>\n   * // </root>\n   * //\n   * // Without select: emits one big <root> TNode after </root>\n   * // With select: \"item\": emits two <item> TNodes as each closes\n   * const stream = new XmlParseStream({ select: 'item' });\n   *\n   * // Nested selection: emits each <sub> as it closes, then the\n   * // containing <item> (which still includes the <sub> as a child).\n   * const stream2 = new XmlParseStream({ select: ['item', 'sub'] });\n   * ```\n   */\n  select?: string | string[];\n  /**\n   * Output format for emitted chunks.\n   *\n   * - `'dom'` (default) — emit raw `TNode | string` values.\n   * - `'lossy'` — convert each item to the compact lossy format (`LossyValue`).\n   * - `'lossless'` — convert each item to the order-preserving lossless format\n   *   (`LosslessEntry`).\n   */\n  output?: 'dom' | 'lossy' | 'lossless';\n}\n\n// Re-export converter output types so consumers can import them from the\n// same entry point when using `output: 'lossy'` or `output: 'lossless'`.\nexport type { LossyValue, LosslessEntry };\n// @generated:char-codes:begin\nconst EQ = 61; // =\nconst SQUOTE = 39; // '\nconst DQUOTE = 34; // \"\nconst TAB = 9; // \\t\nconst LF = 10; // \\n\nconst CR = 13; // \\r\nconst SPACE = 32; // (space)\n// @generated:char-codes:end\n\n/**\n * Convert a SAX `Attributes` object into the format used by `parse()`:\n * - Returns `null` when there are no attributes.\n * - Returns an `Object.create(null)` prototype-free record otherwise.\n */\nfunction toNodeAttributes(\n  attributes: Attributes,\n): Record<string, string | null> | null {\n  const keys = Object.keys(attributes);\n  if (keys.length === 0) return null;\n  const out: Record<string, string | null> = Object.create(null);\n  for (let i = 0; i < keys.length; i++) {\n    out[keys[i]!] = attributes[keys[i]!]!;\n  }\n  return out;\n}\n\n/**\n * Parse a processing instruction body string into an attributes record.\n * e.g. `version=\"1.0\" encoding=\"UTF-8\"` -> `{ version: \"1.0\", encoding: \"UTF-8\" }`\n *\n * This replicates the attribute-parsing behavior of `parse()` so that PIs\n * emitted by `XmlParseStream` match the `{ tagName: \"?xml\", attributes: {...} }`\n * format that consumers expect.\n *\n * Returns `null` when the body contains no attributes, matching `parse()`.\n * Uses `Object.create(null)` for prototype-free attribute records.\n */\nfunction parsePIAttributes(body: string): Record<string, string | null> | null {\n  let attributes: Record<string, string | null> | null = null;\n  const bodyLength = body.length;\n  let i = 0;\n\n  while (i < bodyLength) {\n    // Skip whitespace\n    let charCode = body.charCodeAt(i);\n    if (\n      charCode === SPACE ||\n      charCode === TAB ||\n      charCode === LF ||\n      charCode === CR\n    ) {\n      i++;\n      continue;\n    }\n\n    // Read attribute name\n    const nameStart = i;\n    while (i < bodyLength) {\n      charCode = body.charCodeAt(i);\n      if (\n        charCode === EQ ||\n        charCode === SPACE ||\n        charCode === TAB ||\n        charCode === LF ||\n        charCode === CR\n      )\n        break;\n      i++;\n    }\n    if (i === nameStart) {\n      i++;\n      continue;\n    }\n    const name = body.substring(nameStart, i);\n\n    // Allocate attributes object lazily on first attribute\n    if (attributes === null) attributes = Object.create(null);\n\n    // Skip whitespace\n    while (i < bodyLength) {\n      charCode = body.charCodeAt(i);\n      if (\n        charCode !== SPACE &&\n        charCode !== TAB &&\n        charCode !== LF &&\n        charCode !== CR\n      )\n        break;\n      i++;\n    }\n\n    // Check for =\n    if (i < bodyLength && body.charCodeAt(i) === EQ) {\n      i++; // skip =\n      // Skip whitespace\n      while (i < bodyLength) {\n        charCode = body.charCodeAt(i);\n        if (\n          charCode !== SPACE &&\n          charCode !== TAB &&\n          charCode !== LF &&\n          charCode !== CR\n        )\n          break;\n        i++;\n      }\n      // Read value\n      if (i < bodyLength) {\n        const quoteCharCode = body.charCodeAt(i);\n        if (quoteCharCode === DQUOTE || quoteCharCode === SQUOTE) {\n          const quoteCharacter = body[i]!;\n          i++; // skip opening quote\n          const valueStartIndex = i;\n          const end = body.indexOf(quoteCharacter, i);\n          if (end === -1) {\n            attributes![name] = body.substring(valueStartIndex);\n            i = bodyLength;\n          } else {\n            attributes![name] = body.substring(valueStartIndex, end);\n            i = end + 1;\n          }\n        } else {\n          // Unquoted value — read until whitespace\n          const valueStartIndex = i;\n          while (i < bodyLength) {\n            charCode = body.charCodeAt(i);\n            if (\n              charCode === SPACE ||\n              charCode === TAB ||\n              charCode === LF ||\n              charCode === CR\n            )\n              break;\n            i++;\n          }\n          attributes![name] = body.substring(valueStartIndex, i);\n        }\n      } else {\n        attributes![name] = null;\n      }\n    } else {\n      // Boolean attribute (no value)\n      attributes![name] = null;\n    }\n  }\n\n  return attributes;\n}\n\n/**\n * A Web Streams `TransformStream` that incrementally parses XML chunks into\n * `TNode` subtrees (or lossy/lossless objects). Works in browsers, Node.js\n * 18+, Deno, and Bun.\n *\n * Follows the platform stream class convention (like `TextDecoderStream`,\n * `DecompressionStream`, etc.) — instantiate with `new` and use with\n * `.pipeThrough()`.\n *\n * Internally powered by the SAX engine with a tree-construction layer\n * that assembles `TNode` subtrees and emits them as they complete.\n *\n * By default, nodes are emitted when a top-level element closes (depth 0).\n * Use the `select` option to emit specific elements as they close at any depth,\n * without waiting for the entire document root to finish.\n *\n * Use the `output` option to choose the emitted format:\n * - `'dom'` (default) — raw `TNode | string`\n * - `'lossy'` — compact lossy objects (`LossyValue`)\n * - `'lossless'` — order-preserving objects (`LosslessEntry`)\n *\n * @example\n * ```ts\n * import { XmlParseStream } from '@eksml/xml/stream';\n *\n * const response = await fetch('/feed.xml');\n * const reader = response.body\n *   .pipeThrough(new TextDecoderStream())\n *   .pipeThrough(new XmlParseStream())\n *   .getReader();\n *\n * while (true) {\n *   const { done, value } = await reader.read();\n *   if (done) break;\n *   console.log(value); // TNode or string\n * }\n * ```\n */\nexport class XmlParseStream<TOutput = TNode | string> extends TransformStream<\n  string,\n  TOutput\n> {\n  /** Default DOM output (`TNode | string`). */\n  constructor(options?: XmlParseStreamOptions & { output?: 'dom' });\n  /** Lossy output — each item is converted to `LossyValue`. */\n  constructor(options: XmlParseStreamOptions & { output: 'lossy' });\n  /** Lossless output — each item is converted to `LosslessEntry`. */\n  constructor(options: XmlParseStreamOptions & { output: 'lossless' });\n  /** Dynamic output — when the `output` option is not a literal, returns the widest type. */\n  constructor(options: XmlParseStreamOptions);\n  constructor(options?: XmlParseStreamOptions) {\n    const resolvedOptions = options ?? {};\n    let skipBytes: number =\n      typeof resolvedOptions.offset === 'string'\n        ? resolvedOptions.offset.length\n        : resolvedOptions.offset || 0;\n\n    // Resolve HTML-mode defaults (same logic as parse())\n    const isHtml = resolvedOptions.html === true;\n    const selfClosingTags =\n      resolvedOptions.selfClosingTags ?? (isHtml ? HTML_VOID_ELEMENTS : []);\n    const rawContentTags =\n      resolvedOptions.rawContentTags ?? (isHtml ? HTML_RAW_CONTENT_TAGS : []);\n    const keepComments = resolvedOptions.keepComments === true;\n\n    // Resolve select into a Set for O(1) lookup (null = emit at depth 0)\n    const selectSet: Set<string> | null =\n      resolvedOptions.select == null\n        ? null\n        : typeof resolvedOptions.select === 'string'\n          ? new Set([resolvedOptions.select])\n          : resolvedOptions.select.length > 0\n            ? new Set(resolvedOptions.select)\n            : null;\n\n    // Resolve the output converter — identity for 'dom', otherwise a mapping fn.\n    const outputMode = resolvedOptions.output ?? 'dom';\n    const convert: (item: TNode | string) => TOutput =\n      outputMode === 'lossy'\n        ? (convertItemToLossy as (item: TNode | string) => TOutput)\n        : outputMode === 'lossless'\n          ? (convertItemToLossless as (item: TNode | string) => TOutput)\n          : (((item: TNode | string) => item) as (\n              item: TNode | string,\n            ) => TOutput);\n\n    // --- Tree-construction state ---\n    let streamController: TransformStreamDefaultController<TOutput> | null =\n      null;\n\n    // When `select` is null (default mode): stack holds all open TNodes.\n    // Emission happens when stack.length returns to 0.\n    //\n    // When `select` is set: `depth` tracks total nesting depth (for all\n    // elements, including non-selected ancestors). `stack` only holds nodes\n    // within a selected subtree. `selectDepths` is a stack of depths at which\n    // selected elements were opened — this allows nested selections (e.g.\n    // selecting both `item` and `sub` where `sub` is a child of `item`).\n    // Each entry records the depth at which a matching element was opened.\n    const stack: TNode[] = [];\n    let depth = 0;\n    const selectDepths: number[] = [];\n\n    // -----------------------------------------------------------------------\n    // Default mode helpers (no select — original behavior)\n    // -----------------------------------------------------------------------\n\n    function currentParent(): TNode | null {\n      return stack.length > 0 ? stack[stack.length - 1]! : null;\n    }\n\n    function emitOrAttach(item: TNode | string): void {\n      const parent = currentParent();\n      if (parent) {\n        parent.children.push(item);\n      } else if (streamController) {\n        streamController.enqueue(convert(item));\n      }\n    }\n\n    // -----------------------------------------------------------------------\n    // Select-mode helpers\n    // -----------------------------------------------------------------------\n\n    /** Whether we are currently inside a selected subtree. */\n    function insideSelection(): boolean {\n      return selectDepths.length > 0;\n    }\n\n    /** The TNode at the top of the stack, or null. */\n    function selectParent(): TNode | null {\n      return stack.length > 0 ? stack[stack.length - 1]! : null;\n    }\n\n    // -----------------------------------------------------------------------\n    // SAX handler: default mode (no select)\n    // -----------------------------------------------------------------------\n\n    function defaultOnOpenTag(tagName: string, attributes: Attributes): void {\n      const node: TNode = {\n        tagName,\n        attributes: toNodeAttributes(attributes),\n        children: [],\n      };\n      const parent = currentParent();\n      if (parent) {\n        parent.children.push(node);\n      }\n      stack.push(node);\n    }\n\n    function defaultOnCloseTag(_tagName: string): void {\n      const node = stack.pop();\n      if (!node) return;\n      if (stack.length === 0 && streamController) {\n        streamController.enqueue(convert(node));\n      }\n    }\n\n    function defaultOnText(text: string): void {\n      const parent = currentParent();\n      if (parent) {\n        parent.children.push(text);\n      }\n    }\n\n    function defaultOnCdata(data: string): void {\n      const parent = currentParent();\n      if (parent) {\n        parent.children.push(data);\n      }\n    }\n\n    function defaultOnComment(comment: string): void {\n      if (!keepComments) return;\n      const parent = currentParent();\n      if (parent) {\n        parent.children.push(comment);\n      } else if (streamController) {\n        streamController.enqueue(convert(comment));\n      }\n    }\n\n    function defaultOnProcessingInstruction(name: string, body: string): void {\n      const node: TNode = {\n        tagName: '?' + name,\n        attributes: parsePIAttributes(body),\n        children: [],\n      };\n      emitOrAttach(node);\n    }\n\n    function defaultOnDoctype(tagName: string, attributes: Attributes): void {\n      const node: TNode = {\n        tagName,\n        attributes: toNodeAttributes(attributes),\n        children: [],\n      };\n      emitOrAttach(node);\n    }\n\n    // -----------------------------------------------------------------------\n    // SAX handler: select mode\n    // -----------------------------------------------------------------------\n\n    function selectOnOpenTag(tagName: string, attributes: Attributes): void {\n      depth++;\n      if (insideSelection()) {\n        // Inside a selected subtree — build the TNode and attach to parent.\n        const node: TNode = {\n          tagName,\n          attributes: toNodeAttributes(attributes),\n          children: [],\n        };\n        const parent = selectParent();\n        if (parent) {\n          parent.children.push(node);\n        }\n        stack.push(node);\n        // If this tag also matches the selector, record it so it will be\n        // emitted independently when it closes (in addition to being part\n        // of its ancestor's subtree).\n        if (selectSet!.has(tagName)) {\n          selectDepths.push(depth);\n        }\n      } else if (selectSet!.has(tagName)) {\n        // This element matches the selector — start a new selected subtree.\n        selectDepths.push(depth);\n        const node: TNode = {\n          tagName,\n          attributes: toNodeAttributes(attributes),\n          children: [],\n        };\n        stack.push(node);\n      }\n      // Otherwise: non-selected ancestor — no allocation, just depth tracking.\n    }\n\n    function selectOnCloseTag(_tagName: string): void {\n      if (insideSelection()) {\n        const topSelectDepth = selectDepths[selectDepths.length - 1]!;\n        if (depth === topSelectDepth) {\n          // A selected element is closing — emit it independently.\n          const node = stack.pop();\n          if (node && streamController) {\n            streamController.enqueue(convert(node));\n          }\n          selectDepths.pop();\n        } else {\n          // A descendant of the selected element is closing — already\n          // attached to its parent via onOpenTag, just pop from stack.\n          stack.pop();\n        }\n      }\n      depth--;\n    }\n\n    function selectOnText(text: string): void {\n      if (!insideSelection()) return;\n      const parent = selectParent();\n      if (parent) {\n        parent.children.push(text);\n      }\n    }\n\n    function selectOnCdata(data: string): void {\n      if (!insideSelection()) return;\n      const parent = selectParent();\n      if (parent) {\n        parent.children.push(data);\n      }\n    }\n\n    function selectOnComment(comment: string): void {\n      if (!keepComments) return;\n      if (!insideSelection()) return;\n      const parent = selectParent();\n      if (parent) {\n        parent.children.push(comment);\n      }\n    }\n\n    function selectOnProcessingInstruction(name: string, body: string): void {\n      if (!insideSelection()) return;\n      const node: TNode = {\n        tagName: '?' + name,\n        attributes: parsePIAttributes(body),\n        children: [],\n      };\n      const parent = selectParent();\n      if (parent) {\n        parent.children.push(node);\n      }\n    }\n\n    function selectOnDoctype(tagName: string, attributes: Attributes): void {\n      if (!insideSelection()) return;\n      const node: TNode = {\n        tagName,\n        attributes: toNodeAttributes(attributes),\n        children: [],\n      };\n      const parent = selectParent();\n      if (parent) {\n        parent.children.push(node);\n      }\n    }\n\n    // -----------------------------------------------------------------------\n    // Wire up the appropriate handler set\n    // -----------------------------------------------------------------------\n\n    const parser = saxEngine({\n      selfClosingTags,\n      rawContentTags,\n      onOpenTag: selectSet ? selectOnOpenTag : defaultOnOpenTag,\n      onCloseTag: selectSet ? selectOnCloseTag : defaultOnCloseTag,\n      onText: selectSet ? selectOnText : defaultOnText,\n      onCdata: selectSet ? selectOnCdata : defaultOnCdata,\n      onComment: selectSet ? selectOnComment : defaultOnComment,\n      onProcessingInstruction: selectSet\n        ? selectOnProcessingInstruction\n        : defaultOnProcessingInstruction,\n      onDoctype: selectSet ? selectOnDoctype : defaultOnDoctype,\n    });\n\n    super({\n      transform(\n        chunk: string,\n        controller: TransformStreamDefaultController<TOutput>,\n      ): void {\n        streamController = controller;\n        // Handle offset: skip leading bytes from the first chunk(s)\n        if (skipBytes > 0) {\n          if (chunk.length <= skipBytes) {\n            skipBytes -= chunk.length;\n            return;\n          }\n          chunk = chunk.substring(skipBytes);\n          skipBytes = 0;\n        }\n        parser.write(chunk);\n      },\n\n      flush(controller: TransformStreamDefaultController<TOutput>): void {\n        streamController = controller;\n        parser.close();\n      },\n    });\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@eksml/xml",
+  "version": "0.1.0",
+  "description": "Fast, lightweight XML/HTML parser, serializer, and streaming toolkit",
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    "./parser": {
+      "types": "./dist/parser.d.mts",
+      "import": "./dist/parser.mjs"
+    },
+    "./writer": {
+      "types": "./dist/writer.d.mts",
+      "import": "./dist/writer.mjs"
+    },
+    "./sax": {
+      "types": "./dist/sax.d.mts",
+      "import": "./dist/sax.mjs"
+    },
+    "./stream": {
+      "types": "./dist/xmlParseStream.d.mts",
+      "import": "./dist/xmlParseStream.mjs"
+    },
+    "./lossy": {
+      "types": "./dist/converters/lossy.d.mts",
+      "import": "./dist/converters/lossy.mjs"
+    },
+    "./lossless": {
+      "types": "./dist/converters/lossless.d.mts",
+      "import": "./dist/converters/lossless.mjs"
+    },
+    "./from-lossy": {
+      "types": "./dist/converters/fromLossy.d.mts",
+      "import": "./dist/converters/fromLossy.mjs"
+    },
+    "./from-lossless": {
+      "types": "./dist/converters/fromLossless.d.mts",
+      "import": "./dist/converters/fromLossless.mjs"
+    },
+    "./utilities": {
+      "types": "./dist/utilities/index.d.mts",
+      "import": "./dist/utilities/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "xml",
+    "html",
+    "parser",
+    "serializer",
+    "sax",
+    "streaming",
+    "transform-stream",
+    "dom",
+    "fast",
+    "lightweight"
+  ],
+  "author": "Liam Potter <liam@liampotter.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evoactivity/eksml",
+    "directory": "eksml"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/sax": "^1.2.7",
+    "@types/xml2js": "^0.4.14",
+    "@xmldom/xmldom": "^0.9.9",
+    "fast-xml-parser": "^5.5.9",
+    "htmlparser2": "^12.0.0",
+    "modern-monaco": "^0.4.0",
+    "sax": "^1.6.0",
+    "saxes": "^6.0.0",
+    "tsdown": "^0.21.7",
+    "txml": "^5.2.1",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2",
+    "xml2js": "^0.6.2"
+  },
+  "dependencies": {
+    "entities": "^8.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench",
+    "typecheck": "tsc --noEmit",
+    "examples": "vite",
+    "examples:build": "vite build"
+  }
+}

package/src/converters/fromLossless.ts

@@ -0,0 +1,80 @@
+/**
+ * fromLossless — convert a lossless JSON structure back to a TNode DOM tree.
+ *
+ * This is the inverse of `lossless()`. Because the lossless format preserves
+ * element order, mixed content, attributes, and comments, the round-trip is
+ * exact: `fromLossless(lossless(dom))` produces a tree identical to `dom`.
+ *
+ * Entry types:
+ * - `{ tagName: LosslessEntry[] }` → TNode element
+ * - `{ $text: "..." }` → string child
+ * - `{ $attr: { ... } }` → attributes on the enclosing element (first child)
+ * - `{ $comment: "..." }` → comment string child (`"<!-- ... -->"`)
+ *
+ * @example
+ * ```ts
+ * import { fromLossless } from "@eksml/xml/from-lossless";
+ * import { lossless } from "@eksml/xml/lossless";
+ * import { write } from "@eksml/xml/writer";
+ *
+ * const entries = lossless('<root attr="1"><item>hello</item></root>');
+ * const dom = fromLossless(entries);
+ * const xml = write(dom); // '<root attr="1"><item>hello</item></root>'
+ * ```
+ */
+
+import type { TNode } from '#src/parser.ts';
+import type { LosslessEntry } from '#src/converters/lossless.ts';
+
+/**
+ * Convert a lossless JSON entry array back to a `(TNode | string)[]` DOM tree.
+ *
+ * @param entries - The lossless entry array (as returned by `lossless()`).
+ * @returns A DOM array suitable for `write()` or further processing.
+ */
+export function fromLossless(entries: LosslessEntry[]): (TNode | string)[] {
+  const result: (TNode | string)[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    result.push(convertEntry(entries[i]!));
+  }
+  return result;
+}
+
+function convertEntry(entry: LosslessEntry): TNode | string {
+  // $text → plain string
+  if ('$text' in entry) {
+    return (entry as { $text: string }).$text;
+  }
+
+  // $comment → reconstruct comment string as the parser emits it
+  if ('$comment' in entry) {
+    return '<!--' + (entry as { $comment: string }).$comment + '-->';
+  }
+
+  // $attr should not appear at top level — it's consumed by the element
+  // handler below. If we encounter it here, skip it (defensive).
+  if ('$attr' in entry) {
+    return '';
+  }
+
+  // Element: single key is the tag name, value is children array
+  const keys = Object.keys(entry);
+  const tagName = keys[0]!;
+  const entryChildren = (entry as { [tagName: string]: LosslessEntry[] })[
+    tagName
+  ]!;
+
+  let attributes: Record<string, string | null> | null = null;
+  const children: (TNode | string)[] = [];
+
+  for (let i = 0; i < entryChildren.length; i++) {
+    const child = entryChildren[i]!;
+    if ('$attr' in child) {
+      attributes = (child as { $attr: Record<string, string | null> }).$attr;
+    } else {
+      children.push(convertEntry(child));
+    }
+  }
+
+  return { tagName, attributes, children };
+}