@sdxc/xml 2026.9.15 → 2026.9.23

package/README.md

@@ -40,8 +40,8 @@ let xml = result.data;
 xml.query("channel/title"); // { name: "title", children: ["Feed"] }
 ```
 
-Whitespace-only text nodes are indentation rather than content, so the parser drops them and
-a traversal never has to step over them.
+Whitespace-only text nodes are indentation rather than content, so by default the parser
+drops them and a traversal never has to step over them.
 
 ### Traverse A Document
 
@@ -107,11 +107,27 @@ let source = copy.toString();
 XML.stringify(json); // the same text, as a Result
 ```
 
+### Keep The Source's Whitespace
+
+By default a run of character data holding nothing but whitespace is indentation, and stays
+out of the tree, so traversal sees elements and the text that carries meaning. A caller that
+hashes a document needs the opposite, because a byte of indentation changes the digest:
+
+```typescript
+let xml = XML.parse("<r>\n\t<t>x</t>\n</r>", { whitespace: "preserve" });
+
+// children: ["\n\t", { name: "t", children: ["x"] }, "\n"]
+```
+
+Both modes resolve references first, so `&#32;` counts as the space it decodes to, and both
+allow whitespace around the root element.
+
 ## API
 
-### `XML.parse(source: string): Result<XML, XMLParseError>`
+### `XML.parse(source: string, options?: XML.ParseOptions): Result<XML, XMLParseError>`
 
-Parses XML text into an `XML` instance.
+Parses XML text into an `XML` instance. `options.whitespace` is `"collapse"` by default and
+`"preserve"` to keep whitespace-only text and CDATA in the tree.
 
 ### `XML.stringify(input: XML | XML.Input): Result<string, XMLStringifyError>`
 
@@ -174,8 +190,9 @@ prefix with no namespace declared in scope.
 ### Types
 
 Every public type lives in the `XML` namespace: `XML.Declaration`, `XML.Element`,
-`XML.Node`, `XML.Document`, `XML.Input`, and `XML.Predicate`. `XML.Input` is what
-`stringify` accepts: a whole `XML.Document` or the root `XML.Element` alone.
+`XML.Node`, `XML.Document`, `XML.Input`, `XML.Predicate`, `XML.Whitespace`, and
+`XML.ParseOptions`. `XML.Input` is what `stringify` accepts: a whole `XML.Document` or the
+root `XML.Element` alone.
 
 ```typescript
 import type { XML } from "@sdxc/xml";

package/dist/index.d.ts

@@ -57,6 +57,23 @@ export declare namespace XML {
      * Checks one element while traversing an XML tree.
      */
     type Predicate = (element: Element) => boolean;
+    /**
+     * How whitespace-only character data is treated while parsing. `collapse`
+     * leaves indentation out of the tree; `preserve` keeps every run, which is
+     * what a caller digesting the document needs, since spacing changes the hash.
+     */
+    type Whitespace = "collapse" | "preserve";
+    /**
+     * How one `parse` call reads its source.
+     */
+    interface ParseOptions {
+        /**
+         * Whether whitespace-only text and CDATA reach the tree.
+         *
+         * @default "collapse"
+         */
+        whitespace?: Whitespace;
+    }
 }
 /**
  * Wraps one parsed XML document and provides traversal and serialization helpers.
@@ -73,9 +90,10 @@ export declare class XML {
      * Parses XML into an `XML` instance.
      *
      * @param source - Raw XML text to parse
+     * @param options - Reading choices; the default drops indentation
      * @returns A Result containing an `XML` instance or a parse error
      */
-    static parse(source: string): Result<XML, XMLParseError>;
+    static parse(source: string, options?: XML.ParseOptions): Result<XML, XMLParseError>;
     /**
      * Serializes an XML instance, plain document data, or a root element into XML text.
      *

package/dist/index.js

@@ -42,10 +42,11 @@ export class XML {
      * Parses XML into an `XML` instance.
      *
      * @param source - Raw XML text to parse
+     * @param options - Reading choices; the default drops indentation
      * @returns A Result containing an `XML` instance or a parse error
      */
-    static parse(source) {
-        let result = parseDocument(source);
+    static parse(source, options = {}) {
+        let result = parseDocument(source, options.whitespace ?? "collapse");
         if (result.status === "failure")
             return failure(new XMLParseError(result.error.message));
         return success(new XML(result.data));

package/dist/lib/parse-document.d.ts

@@ -12,6 +12,7 @@ import type { XML } from "../index.js";
  * Parses XML into plain document data.
  *
  * @param source - Raw XML text to parse
+ * @param whitespace - Whether whitespace-only character data reaches the tree
  * @returns A Result containing XML document data or an error
  */
-export declare function parseDocument(source: string): Result<XML.Document, Error>;
+export declare function parseDocument(source: string, whitespace?: XML.Whitespace): Result<XML.Document, Error>;

package/dist/lib/parse-document.js

@@ -21,33 +21,35 @@ const WHITESPACE_PATTERN = /\s/;
  * Parses XML into plain document data.
  *
  * @param source - Raw XML text to parse
+ * @param whitespace - Whether whitespace-only character data reaches the tree
  * @returns A Result containing XML document data or an error
  */
-export function parseDocument(source) {
-    let root = parseRoot(source);
+export function parseDocument(source, whitespace = "collapse") {
+    let root = parseRoot(source, whitespace);
     if (root.status === "failure")
         return root;
     return success({ declaration: parseDeclaration(source), root: root.data });
 }
 /**
  * Walks the source once, building the element tree on a stack of open elements.
- * Text and CDATA that hold only whitespace are dropped, which keeps indentation
- * out of the tree and leaves feed traversal working on elements alone.
+ * Under `collapse` the tree holds elements and meaningful text alone, which is
+ * what feed traversal wants; under `preserve` it holds the source's own spacing.
  */
-function parseRoot(source) {
+function parseRoot(source, whitespace) {
     let stack = [];
     let root;
     let index = 0;
     while (index < source.length) {
         if (source[index] !== "<") {
-            let text = readText(source, index);
+            let text = readText(source, index, whitespace);
             if (text.status === "failure")
                 return text;
             let parent = stack.at(-1);
             if (parent)
                 parent.children?.push(...text.data.value);
-            else if (text.data.value[0])
-                return failure(strayContent(root, text.data.value[0]));
+            else if (outsideRoot(text.data.value)) {
+                return failure(strayContent(root, text.data.value[0] ?? ""));
+            }
             index = text.data.next;
             continue;
         }
@@ -59,7 +61,7 @@ function parseRoot(source) {
             continue;
         }
         if (source.startsWith("<![CDATA[", index)) {
-            let section = readCDATA(source, index);
+            let section = readCDATA(source, index, whitespace);
             if (section.status === "failure")
                 return section;
             stack.at(-1)?.children?.push(...section.data.value);
@@ -121,30 +123,46 @@ function parseRoot(source) {
     return success(root);
 }
 /**
- * Reads the character data up to the next `<`, resolving references first so a
- * run that decodes to nothing but whitespace is dropped along with plain indentation.
+ * Reads the character data up to the next `<`, resolving references before the
+ * run is weighed, so `&#32;` counts as the space it decodes to either way.
  */
-function readText(source, index) {
+function readText(source, index, whitespace) {
     let end = source.indexOf("<", index);
     let stop = end === -1 ? source.length : end;
     let decoded = decodeEntities(source.slice(index, stop));
     if (decoded.status === "failure")
         return decoded;
-    let kept = decoded.data.trim().length > 0 ? [decoded.data] : [];
-    return success({ value: kept, next: stop });
+    return success({ value: keep(decoded.data, whitespace), next: stop });
 }
 /**
  * Reads a CDATA section, whose content reaches the tree verbatim because CDATA
  * exists precisely to carry markup as literal text.
  */
-function readCDATA(source, index) {
+function readCDATA(source, index, whitespace) {
     let start = index + "<![CDATA[".length;
     let end = source.indexOf("]]>", start);
     if (end === -1)
         return failure(new Error("Unterminated CDATA section"));
     let content = source.slice(start, end);
-    let kept = content.trim().length > 0 ? [content] : [];
-    return success({ value: kept, next: end + "]]>".length });
+    return success({ value: keep(content, whitespace), next: end + "]]>".length });
+}
+/**
+ * Reports character data that sits beside the root rather than inside it. The
+ * prolog and the epilog may hold whitespace, so only a run carrying something
+ * else is content XML puts nowhere.
+ */
+function outsideRoot(text) {
+    return text.some((run) => run.trim().length > 0);
+}
+/**
+ * Decides whether one run of character data reaches the tree. A run of nothing
+ * but whitespace is indentation under `collapse` and part of what a digest
+ * covers under `preserve`, so only the caller's mode can tell them apart.
+ */
+function keep(text, whitespace) {
+    if (whitespace === "preserve")
+        return text.length > 0 ? [text] : [];
+    return text.trim().length > 0 ? [text] : [];
 }
 /**
  * Skips past a construct the tree leaves out, such as a comment or a processing

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/xml",
-	"version": "2026.9.15",
+	"version": "2026.9.23",
 	"description": "XML parser and serializer for RSS-style feeds",
 	"license": "MIT",
 	"type": "module",
@@ -10,7 +10,7 @@
 	"dependencies": {
 		"@sdxc/result": "2026.9.15"
 	},
-	"gitHead": "d56f75a79171aab3be101d8fa624d51972cd6028",
+	"gitHead": "00c5691b2e444a348956d1879ab676b07d3f9c8f",
 	"publishConfig": {
 		"access": "public"
 	},