@sdxc/xml 0.0.0-pre.1

package/dist/lib/parse-document.js

@@ -0,0 +1,296 @@
+/**
+ * Parses XML text into plain document data by scanning the source directly, so
+ * the package runs anywhere JavaScript does, workerd included. Covers the subset
+ * RSS and similar feeds use: one root, attributes, text, CDATA, prefixed names.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { decodeEntities } from "./decode-entities.js";
+import { matchName } from "./xml-names.js";
+const XML_DECLARATION_PATTERN = /^\s*<\?xml\s+([^?]+)\?>/i;
+const XML_DECLARATION_ATTRIBUTE_PATTERN = /([a-zA-Z_:][\w:.-]*)\s*=\s*(["'])(.*?)\2/g;
+/**
+ * Literal tabs and line breaks inside an attribute value are collapsed to spaces
+ * before references are resolved, so `&#10;` still survives as a line break.
+ */
+const ATTRIBUTE_WHITESPACE_PATTERN = /[\t\n\r]/g;
+const WHITESPACE_PATTERN = /\s/;
+/**
+ * Parses XML into plain document data.
+ *
+ * @param source - Raw XML text to parse
+ * @returns A Result containing XML document data or an error
+ */
+export function parseDocument(source) {
+    let root = parseRoot(source);
+    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.
+ */
+function parseRoot(source) {
+    let stack = [];
+    let root;
+    let index = 0;
+    while (index < source.length) {
+        if (source[index] !== "<") {
+            let text = readText(source, index);
+            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]));
+            index = text.data.next;
+            continue;
+        }
+        if (source.startsWith("<!--", index)) {
+            let skipped = skipUntil(source, index, "-->", "comment");
+            if (skipped.status === "failure")
+                return skipped;
+            index = skipped.data;
+            continue;
+        }
+        if (source.startsWith("<![CDATA[", index)) {
+            let section = readCDATA(source, index);
+            if (section.status === "failure")
+                return section;
+            stack.at(-1)?.children?.push(...section.data.value);
+            index = section.data.next;
+            continue;
+        }
+        if (source.startsWith("<?", index)) {
+            let skipped = skipUntil(source, index, "?>", "processing instruction");
+            if (skipped.status === "failure")
+                return skipped;
+            index = skipped.data;
+            continue;
+        }
+        if (source.startsWith("<!", index)) {
+            let skipped = skipDoctype(source, index);
+            if (skipped.status === "failure")
+                return skipped;
+            index = skipped.data;
+            continue;
+        }
+        if (source.startsWith("</", index)) {
+            let closing = readClosingTag(source, index);
+            if (closing.status === "failure")
+                return closing;
+            let open = stack.at(-1);
+            if (!open)
+                return failure(new Error(`Unexpected closing tag "${closing.data.value}".`));
+            if (open.name !== closing.data.value) {
+                return failure(new Error(`Opening and ending tag mismatch: "${open.name}" != "${closing.data.value}"`));
+            }
+            stack.pop();
+            index = closing.data.next;
+            continue;
+        }
+        let opening = readOpeningTag(source, index);
+        if (opening.status === "failure")
+            return opening;
+        let element = {
+            name: opening.data.value.name,
+            attributes: opening.data.value.attributes,
+            children: [],
+        };
+        let parent = stack.at(-1);
+        if (parent)
+            parent.children?.push(element);
+        else if (root)
+            return failure(new Error("Extra content at the end of the document"));
+        else
+            root = element;
+        if (!opening.data.value.selfClosing)
+            stack.push(element);
+        index = opening.data.next;
+    }
+    if (stack.length > 0) {
+        return failure(new Error(`unclosed xml tag(s): ${stack.map((open) => open.name).join(", ")}`));
+    }
+    if (!root)
+        return failure(new Error("missing root element"));
+    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.
+ */
+function readText(source, index) {
+    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 });
+}
+/**
+ * Reads a CDATA section, whose content reaches the tree verbatim because CDATA
+ * exists precisely to carry markup as literal text.
+ */
+function readCDATA(source, index) {
+    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 });
+}
+/**
+ * Skips past a construct the tree leaves out, such as a comment or a processing
+ * instruction, and names it when the source leaves it unterminated.
+ */
+function skipUntil(source, index, terminator, label) {
+    let end = source.indexOf(terminator, index);
+    if (end === -1)
+        return failure(new Error(`Unterminated ${label}`));
+    return success(end + terminator.length);
+}
+/**
+ * Skips a doctype declaration, tracking the internal subset so the declaration
+ * ends at the `>` that closes it.
+ */
+function skipDoctype(source, index) {
+    let depth = 0;
+    for (let cursor = index; cursor < source.length; cursor++) {
+        let character = source[cursor];
+        if (character === "[")
+            depth++;
+        if (character === "]")
+            depth--;
+        if (character === ">" && depth <= 0)
+            return success(cursor + 1);
+    }
+    return failure(new Error("Unterminated doctype declaration"));
+}
+/**
+ * Reads a closing tag and reports the name it closes.
+ */
+function readClosingTag(source, index) {
+    let name = matchName(source, index + "</".length);
+    if (!name)
+        return failure(new Error("Expected an element name after `</`."));
+    let cursor = skipWhitespace(source, index + "</".length + name.length);
+    if (source[cursor] !== ">")
+        return failure(new Error(`Unterminated closing tag "${name}".`));
+    return success({ value: name, next: cursor + 1 });
+}
+/**
+ * Reads a start tag with its attributes, reporting whether it closes itself.
+ */
+function readOpeningTag(source, index) {
+    let name = matchName(source, index + 1);
+    if (!name)
+        return failure(new Error("Expected an element name after `<`."));
+    let attributes = {};
+    let cursor = index + 1 + name.length;
+    while (cursor < source.length) {
+        let afterWhitespace = skipWhitespace(source, cursor);
+        if (source.startsWith("/>", afterWhitespace)) {
+            return success({
+                value: { name, attributes, selfClosing: true },
+                next: afterWhitespace + 2,
+            });
+        }
+        if (source[afterWhitespace] === ">") {
+            return success({
+                value: { name, attributes, selfClosing: false },
+                next: afterWhitespace + 1,
+            });
+        }
+        if (afterWhitespace === cursor) {
+            return failure(new Error(`Expected whitespace between attributes of "${name}".`));
+        }
+        let attribute = readAttribute(source, afterWhitespace, name);
+        if (attribute.status === "failure")
+            return attribute;
+        if (attribute.data.value.name in attributes) {
+            return failure(new Error(`Attribute ${attribute.data.value.name} redefined`));
+        }
+        attributes[attribute.data.value.name] = attribute.data.value.value;
+        cursor = attribute.data.next;
+    }
+    return failure(new Error(`Unterminated opening tag "${name}".`));
+}
+/**
+ * Reads one `name="value"` pair. The value keeps its quote style out of the tree
+ * and arrives with whitespace normalized and references resolved.
+ */
+function readAttribute(source, index, elementName) {
+    let name = matchName(source, index);
+    if (!name)
+        return failure(new Error(`Expected an attribute name in "${elementName}".`));
+    let cursor = skipWhitespace(source, index + name.length);
+    if (source[cursor] !== "=")
+        return failure(new Error(`attribute "${name}" missed value!`));
+    cursor = skipWhitespace(source, cursor + 1);
+    let quote = source[cursor];
+    if (quote !== '"' && quote !== "'") {
+        return failure(new Error(`attribute "${name}" missed quot(")!`));
+    }
+    let end = source.indexOf(quote, cursor + 1);
+    if (end === -1)
+        return failure(new Error(`attribute "${name}" missed quot(")!`));
+    let raw = source.slice(cursor + 1, end).replace(ATTRIBUTE_WHITESPACE_PATTERN, " ");
+    let decoded = decodeEntities(raw);
+    if (decoded.status === "failure")
+        return decoded;
+    return success({ value: { name, value: decoded.data }, next: end + 1 });
+}
+/**
+ * Advances past any run of whitespace and reports where it ended.
+ */
+function skipWhitespace(source, index) {
+    let cursor = index;
+    while (cursor < source.length && WHITESPACE_PATTERN.test(source[cursor] ?? ""))
+        cursor++;
+    return cursor;
+}
+/**
+ * Names the failure for text found outside the root, which reads differently
+ * depending on whether the root has already been opened.
+ */
+function strayContent(root, text) {
+    if (root)
+        return new Error("Extra content at the end of the document");
+    return new Error(`Unexpected content outside root element: '${text}'`);
+}
+/**
+ * Extracts the XML declaration, which sits ahead of the tree and so is read
+ * straight from the source.
+ */
+function parseDeclaration(source) {
+    let match = source.match(XML_DECLARATION_PATTERN);
+    if (!match?.[1])
+        return undefined;
+    let declaration = {};
+    let attributes = match[1];
+    let attributeMatch = XML_DECLARATION_ATTRIBUTE_PATTERN.exec(attributes);
+    while (attributeMatch) {
+        let name = attributeMatch[1];
+        let value = attributeMatch[3];
+        if (name === "version")
+            declaration.version = value;
+        if (name === "encoding")
+            declaration.encoding = value;
+        if (name === "standalone" && (value === "yes" || value === "no")) {
+            declaration.standalone = value;
+        }
+        attributeMatch = XML_DECLARATION_ATTRIBUTE_PATTERN.exec(attributes);
+    }
+    XML_DECLARATION_ATTRIBUTE_PATTERN.lastIndex = 0;
+    if (!declaration.version && !declaration.encoding && !declaration.standalone) {
+        return undefined;
+    }
+    return declaration;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Serializes plain XML document data into text, emitting the markup directly so
+ * the package runs anywhere JavaScript does, workerd included. Namespace prefixes
+ * are checked against the declarations in scope, names against `Name`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { XML } from "../index.js";
+/**
+ * Serializes plain XML document data into a string.
+ *
+ * @param input - The document data to serialize
+ * @returns A Result containing the XML string or an error
+ */
+export declare function stringifyDocument(input: XML.Document): Result<string, Error>;

package/dist/lib/stringify-document.js

@@ -0,0 +1,120 @@
+/**
+ * Serializes plain XML document data into text, emitting the markup directly so
+ * the package runs anywhere JavaScript does, workerd included. Namespace prefixes
+ * are checked against the declarations in scope, names against `Name`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { escapeAttribute, escapeText } from "./escape-xml.js";
+import { isValidName } from "./xml-names.js";
+/**
+ * `xml` and `xmlns` are bound by the specification itself, so every document may
+ * use them directly.
+ */
+const BUILT_IN_PREFIXES = ["xml", "xmlns"];
+/**
+ * Serializes plain XML document data into a string.
+ *
+ * @param input - The document data to serialize
+ * @returns A Result containing the XML string or an error
+ */
+export function stringifyDocument(input) {
+    if (!isValidName(input.root.name)) {
+        return failure(new Error(`Invalid root element name "${input.root.name}".`));
+    }
+    let root = stringifyElement(input.root, new Set(BUILT_IN_PREFIXES));
+    if (root.status === "failure")
+        return root;
+    let declaration = stringifyDeclaration(input.declaration);
+    if (!declaration)
+        return root;
+    return success(`${declaration}\n${root.data}`);
+}
+/**
+ * Writes one element and everything under it, threading the namespace prefixes
+ * declared so far down the tree so a child can use a prefix an ancestor declared.
+ */
+function stringifyElement(element, inheritedPrefixes) {
+    let attributes = element.attributes ?? {};
+    let children = element.children ?? [];
+    let prefixes = extendPrefixes(attributes, inheritedPrefixes);
+    let elementPrefix = prefixOf(element.name);
+    if (elementPrefix && !prefixes.has(elementPrefix)) {
+        return failure(new Error(`Missing namespace declaration for prefix "${elementPrefix}" on element "${element.name}".`));
+    }
+    let serializedAttributes = stringifyAttributes(attributes, prefixes);
+    if (serializedAttributes.status === "failure")
+        return serializedAttributes;
+    let open = `<${element.name}${serializedAttributes.data}`;
+    if (children.length === 0)
+        return success(`${open}/>`);
+    let content = "";
+    for (let child of children) {
+        if (typeof child === "string") {
+            content += escapeText(child);
+            continue;
+        }
+        if (!isValidName(child.name)) {
+            return failure(new Error(`Invalid element name "${child.name}".`));
+        }
+        let serializedChild = stringifyElement(child, prefixes);
+        if (serializedChild.status === "failure")
+            return serializedChild;
+        content += serializedChild.data;
+    }
+    return success(`${open}>${content}</${element.name}>`);
+}
+/**
+ * Writes the attribute list in declaration order, which keeps a serialized feed
+ * byte-for-byte stable between runs.
+ */
+function stringifyAttributes(attributes, prefixes) {
+    let serialized = "";
+    for (let [name, value] of Object.entries(attributes)) {
+        if (!isValidName(name))
+            return failure(new Error(`Invalid attribute name "${name}".`));
+        let prefix = prefixOf(name);
+        if (prefix && !prefixes.has(prefix)) {
+            return failure(new Error(`Missing namespace declaration for prefix "${prefix}" on attribute "${name}".`));
+        }
+        serialized += ` ${name}="${escapeAttribute(value)}"`;
+    }
+    return success(serialized);
+}
+/**
+ * Collects the prefixes an element declares, so they cover the element itself
+ * and everything nested inside it.
+ */
+function extendPrefixes(attributes, inheritedPrefixes) {
+    let prefixes = new Set(inheritedPrefixes);
+    for (let name of Object.keys(attributes)) {
+        if (name.startsWith("xmlns:"))
+            prefixes.add(name.slice("xmlns:".length));
+    }
+    return prefixes;
+}
+/**
+ * Reads the namespace prefix off a qualified name. An unprefixed name belongs to
+ * the default namespace, which every element already has in scope.
+ */
+function prefixOf(name) {
+    let separator = name.indexOf(":");
+    if (separator === -1)
+        return undefined;
+    return name.slice(0, separator);
+}
+/**
+ * Converts the declaration object into a stable XML declaration string.
+ */
+function stringifyDeclaration(declaration) {
+    if (!declaration)
+        return undefined;
+    let attributes = [`version="${declaration.version ?? "1.0"}"`];
+    if (declaration.encoding)
+        attributes.push(`encoding="${declaration.encoding}"`);
+    if (declaration.standalone)
+        attributes.push(`standalone="${declaration.standalone}"`);
+    return `<?xml ${attributes.join(" ")}?>`;
+}

package/dist/lib/traversal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Traverses and queries XML element trees by predicate or by `/`-delimited
+ * child-name path.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "../index.js";
+/**
+ * Returns the first element matching the predicate in depth-first order.
+ *
+ * @param element - The root element to traverse
+ * @param predicate - The predicate to match against
+ * @returns The first matching element, if one exists
+ */
+export declare function findInElement(element: XML.Element, predicate: XML.Predicate): XML.Element | undefined;
+/**
+ * Collects all elements matching the predicate in depth-first order.
+ *
+ * @param element - The root element to traverse
+ * @param predicate - The predicate to match against
+ * @param matches - The array to append matches to
+ */
+export declare function collectInElement(element: XML.Element, predicate: XML.Predicate, matches: XML.Element[]): void;
+/**
+ * Normalizes a `/`-delimited path into non-empty segments.
+ *
+ * @param path - The raw query path
+ * @returns The normalized path segments
+ */
+export declare function normalizePath(path: string): string[];
+/**
+ * Checks whether the path is rooted at the provided root element name.
+ *
+ * @param segments - The normalized path segments
+ * @param rootName - The root element name
+ * @returns `true` when the first segment matches the root name
+ */
+export declare function startsWithRoot(segments: string[], rootName: string): boolean;
+/**
+ * Traverses the tree by exact child-name matches for each path segment.
+ *
+ * @param elements - The current set of elements to match from
+ * @param segments - The remaining path segments
+ * @returns The elements that match the full path
+ */
+export declare function queryFromElements(elements: XML.Element[], segments: string[]): XML.Element[];

package/dist/lib/traversal.js

@@ -0,0 +1,90 @@
+/**
+ * Traverses and queries XML element trees by predicate or by `/`-delimited
+ * child-name path.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { cloneElement } from "./clone-element.js";
+/**
+ * Returns the first element matching the predicate in depth-first order.
+ *
+ * @param element - The root element to traverse
+ * @param predicate - The predicate to match against
+ * @returns The first matching element, if one exists
+ */
+export function findInElement(element, predicate) {
+    if (predicate(element))
+        return cloneElement(element);
+    for (let child of element.children ?? []) {
+        if (typeof child === "string")
+            continue;
+        let match = findInElement(child, predicate);
+        if (match)
+            return match;
+    }
+    return undefined;
+}
+/**
+ * Collects all elements matching the predicate in depth-first order.
+ *
+ * @param element - The root element to traverse
+ * @param predicate - The predicate to match against
+ * @param matches - The array to append matches to
+ */
+export function collectInElement(element, predicate, matches) {
+    if (predicate(element))
+        matches.push(cloneElement(element));
+    for (let child of element.children ?? []) {
+        if (typeof child === "string")
+            continue;
+        collectInElement(child, predicate, matches);
+    }
+}
+/**
+ * Normalizes a `/`-delimited path into non-empty segments.
+ *
+ * @param path - The raw query path
+ * @returns The normalized path segments
+ */
+export function normalizePath(path) {
+    return path
+        .split("/")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+}
+/**
+ * Checks whether the path is rooted at the provided root element name.
+ *
+ * @param segments - The normalized path segments
+ * @param rootName - The root element name
+ * @returns `true` when the first segment matches the root name
+ */
+export function startsWithRoot(segments, rootName) {
+    return segments[0] === rootName;
+}
+/**
+ * Traverses the tree by exact child-name matches for each path segment.
+ *
+ * @param elements - The current set of elements to match from
+ * @param segments - The remaining path segments
+ * @returns The elements that match the full path
+ */
+export function queryFromElements(elements, segments) {
+    if (segments.length === 0)
+        return elements;
+    let [segment, ...rest] = segments;
+    let matches = [];
+    for (let element of elements) {
+        for (let child of element.children ?? []) {
+            if (typeof child === "string")
+                continue;
+            if (child.name !== segment)
+                continue;
+            matches.push(child);
+        }
+    }
+    if (rest.length === 0)
+        return matches;
+    return queryFromElements(matches, rest);
+}

package/dist/lib/xml-names.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Implements the XML `Name` production, which both reading and writing depend on:
+ * the parser uses it to find where a tag or attribute name ends, and the
+ * serializer uses it to confirm a name can be written back out as valid XML.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Reads the name starting at `index`, anchored there so the parser advances
+ * through the source one name at a time.
+ *
+ * @param source - The full XML text being parsed
+ * @param index - Offset the name is expected to start at
+ * @returns The name, or `undefined` when no name starts there
+ */
+export declare function matchName(source: string, index: number): string | undefined;
+/**
+ * Reports whether a name can be written into a tag or attribute as-is, so the
+ * serializer emits output that parses back into the tree it was given.
+ *
+ * @param value - The element or attribute name to check
+ * @returns Whether the whole value is one XML name
+ */
+export declare function isValidName(value: string): boolean;

package/dist/lib/xml-names.js

@@ -0,0 +1,38 @@
+/**
+ * Implements the XML `Name` production, which both reading and writing depend on:
+ * the parser uses it to find where a tag or attribute name ends, and the
+ * serializer uses it to confirm a name can be written back out as valid XML.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * The `:` belongs to the production itself, so a namespace-prefixed name such as
+ * `content:encoded` is one name here and the prefix is resolved separately.
+ */
+const NAME_START = "A-Za-z_:\\u00C0-\\u02FF\\u0370-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD";
+const NAME_REST = `${NAME_START}0-9.\\-\\u00B7\\u0300-\\u036F\\u203F-\\u2040`;
+const SCANNING_PATTERN = new RegExp(`[${NAME_START}][${NAME_REST}]*`, "y");
+const EXACT_PATTERN = new RegExp(`^[${NAME_START}][${NAME_REST}]*$`);
+/**
+ * Reads the name starting at `index`, anchored there so the parser advances
+ * through the source one name at a time.
+ *
+ * @param source - The full XML text being parsed
+ * @param index - Offset the name is expected to start at
+ * @returns The name, or `undefined` when no name starts there
+ */
+export function matchName(source, index) {
+    SCANNING_PATTERN.lastIndex = index;
+    return SCANNING_PATTERN.exec(source)?.[0];
+}
+/**
+ * Reports whether a name can be written into a tag or attribute as-is, so the
+ * serializer emits output that parses back into the tree it was given.
+ *
+ * @param value - The element or attribute name to check
+ * @returns Whether the whole value is one XML name
+ */
+export function isValidName(value) {
+    return EXACT_PATTERN.test(value);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@sdxc/xml",
+	"version": "0.0.0-pre.1",
+	"description": "XML parser and serializer for RSS-style feeds",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.9.5"
+	},
+	"gitHead": "6b352367c6853be4019c3a3ab761185df8ab5ab8",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/xml"
+	}
+}