@sdxc/xml 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# @sdxc/xml
+
+XML parser and serializer for RSS-style feeds.
+
+It reads XML text into an `XML` document instance and writes that instance back out. The
+target is the subset of XML feeds actually use: one root element, attributes, nested
+elements, text nodes, CDATA sections, namespace-prefixed names, and an XML declaration.
+
+Real feeds are written by tools that emit ` ` and `—` without declaring a DTD,
+so the parser resolves the five entities XML predefines, numeric character references such
+as `’`, and the 248 named entities the three XHTML 1.0 entity sets declare. A name
+outside those sets is reported as a parse error. Serialization escapes only the five
+predefines, so a document that arrives with ` ` round-trips as the character itself.
+
+## Installation
+
+```bash
+npm add @sdxc/xml
+```
+
+Parsing and serialization report failures as a `Result` from
+[`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), which installs alongside this
+package and supplies `isFailure`, `isSuccess`, and `unwrap`.
+
+## Usage
+
+### Parse A Document
+
+```typescript
+import { isFailure } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+
+let result = XML.parse(
+	`<?xml version="1.0"?><rss version="2.0"><channel><title>Feed</title></channel></rss>`,
+);
+
+if (isFailure(result)) throw result.error;
+
+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.
+
+### Traverse A Document
+
+`query` and `queryAll` take a `/`-delimited path rooted at the document's root element;
+`find` and `findAll` take a predicate and walk depth-first.
+
+```typescript
+let channel = xml.query("channel");
+let items = xml.queryAll("channel/item");
+
+let firstLink = xml.find((element) => element.name === "link");
+let allLinks = xml.findAll((element) => element.name === "link");
+```
+
+### Write A Document
+
+`XML.stringify` takes a root element and returns the text for it:
+
+```typescript
+import { isFailure } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+
+let result = XML.stringify({
+	name: "rss",
+	attributes: { version: "2.0" },
+	children: [
+		{
+			name: "channel",
+			children: [{ name: "title", children: ["Feed"] }],
+		},
+	],
+});
+
+if (isFailure(result)) throw result.error;
+
+let source = result.data; // <rss version="2.0"><channel><title>Feed</title></channel></rss>
+```
+
+A declaration belongs to a document rather than to an element, so pass the whole document to
+write one:
+
+```typescript
+let result = XML.stringify({
+	declaration: { version: "1.0", encoding: "UTF-8" },
+	root: { name: "rss", attributes: { version: "2.0" } },
+});
+
+// <?xml version="1.0" encoding="UTF-8"?>
+// <rss version="2.0"/>
+```
+
+### Round-Trip A Document
+
+`toJSON` hands back plain data that both the `XML` constructor and `XML.stringify` accept,
+and `toString` serializes the instance in place.
+
+```typescript
+let json = xml.toJSON();
+
+let copy = new XML(json);
+let source = copy.toString();
+
+XML.stringify(json); // the same text, as a Result
+```
+
+## API
+
+### `XML.parse(source: string): Result<XML, XMLParseError>`
+
+Parses XML text into an `XML` instance.
+
+### `XML.stringify(input: XML | XML.Input): Result<string, XMLStringifyError>`
+
+Serializes an instance, whole document data, or a bare root element into XML text. An element
+carries no declaration; pass a document or an instance to write one.
+
+```typescript
+XML.stringify({ name: "rss", attributes: { version: "2.0" } });
+// success('<rss version="2.0"/>')
+```
+
+### `new XML(document: XML.Document)`
+
+Wraps a document that is already plain data, such as one from `toJSON`.
+
+### `xml.declaration: XML.Declaration | undefined`
+
+The parsed XML declaration, when the document carried one.
+
+### `xml.root: XML.Element`
+
+The root element.
+
+### `xml.find(predicate: XML.Predicate): XML.Element | undefined`
+
+The first element the predicate accepts, in depth-first order.
+
+### `xml.findAll(predicate: XML.Predicate): XML.Element[]`
+
+Every element the predicate accepts, in depth-first order.
+
+### `xml.query(path: string): XML.Element | undefined`
+
+The first element at a `/`-delimited path such as `channel/item/title`.
+
+### `xml.queryAll(path: string): XML.Element[]`
+
+Every element at a `/`-delimited path such as `channel/item`.
+
+### `xml.toJSON(): XML.Document`
+
+The document as plain serializable data.
+
+### `xml.toString(): string`
+
+The document as XML text. This is the one entry point that throws an `XMLStringifyError`
+rather than returning it, because `toString` has no room for a `Result`; reach for
+`XML.stringify` where a failure is a value you want to handle.
+
+### `XMLParseError`
+
+The source is malformed, carries no root element, or names an entity outside the resolved
+sets.
+
+### `XMLStringifyError`
+
+The tree cannot be expressed as valid XML: a name that fails the XML `Name` production, or a
+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.
+
+```typescript
+import type { XML } from "@sdxc/xml";
+
+function titleOf(element: XML.Element): string | undefined {
+	let [text] = element.children ?? [];
+	return typeof text === "string" ? text : undefined;
+}
+```
+
+An `XML.Node` is either an `XML.Element` or a string, and a string is always a text node.
+Markup belongs in child elements: a string holding `<p>Hi</p>` serializes as escaped text,
+which is what makes the output parse back into the tree it was given.
+
+## Pattern: Reading A Feed's Channel
+
+```typescript
+import { isFailure } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+
+let result = XML.parse(source);
+if (isFailure(result)) throw result.error;
+
+let xml = result.data;
+
+for (let item of xml.queryAll("channel/item")) {
+	let title = item.children?.find((child) => typeof child !== "string" && child.name === "title");
+}
+```
+
+## Pattern: Preserving Namespaces
+
+A prefix is resolved against the `xmlns:*` attributes in scope, so declare one on the same
+element tree that uses it. Serialization fails on a prefix with no declaration rather than
+writing XML that will not parse.
+
+```typescript
+XML.stringify({
+	name: "rss",
+	attributes: {
+		version: "2.0",
+		"xmlns:content": "http://purl.org/rss/1.0/modules/content/",
+	},
+	children: [{ name: "content:encoded", children: ["<p>HTML</p>"] }],
+});
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/xml": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Provides the XML class and error types for parsing, traversing, and
+ * serializing XML documents.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+/**
+ * Signals that XML source could not be converted into the package tree format.
+ */
+export declare class XMLParseError extends Error {
+    name: string;
+}
+/**
+ * Signals that an XML tree could not be serialized into a valid XML string.
+ */
+export declare class XMLStringifyError extends Error {
+    name: string;
+}
+/**
+ * Groups the public XML types under a single import surface.
+ */
+export declare namespace XML {
+    /**
+     * Stores XML declaration attributes that should appear before the root element.
+     */
+    interface Declaration {
+        version?: string;
+        encoding?: string;
+        standalone?: "yes" | "no";
+    }
+    /**
+     * Stores one XML element with its raw tag name, attributes, and ordered children.
+     */
+    interface Element {
+        name: string;
+        attributes?: Record<string, string>;
+        children?: Node[];
+    }
+    /**
+     * Represents either a text node or a nested XML element.
+     */
+    type Node = string | Element;
+    /**
+     * Stores a parsed XML document with the declaration and single root element.
+     */
+    interface Document {
+        declaration?: Declaration;
+        root: Element;
+    }
+    /**
+     * Accepts either a full XML document or a single root element for serialization.
+     */
+    type Input = Document | Element;
+    /**
+     * Checks one element while traversing an XML tree.
+     */
+    type Predicate = (element: Element) => boolean;
+}
+/**
+ * Wraps one parsed XML document and provides traversal and serialization helpers.
+ */
+export declare class XML {
+    #private;
+    /**
+     * Stores one XML document instance around a declaration and root element.
+     *
+     * @param document - The plain XML document data to wrap
+     */
+    constructor(document: XML.Document);
+    /**
+     * Parses XML into an `XML` instance.
+     *
+     * @param source - Raw XML text to parse
+     * @returns A Result containing an `XML` instance or a parse error
+     */
+    static parse(source: string): Result<XML, XMLParseError>;
+    /**
+     * Serializes an XML instance, plain document data, or a root element into XML text.
+     *
+     * @param input - The XML instance, document data, or root element to serialize
+     * @returns A Result containing the XML string or a serialization error
+     */
+    static stringify(input: XML | XML.Input): Result<string, XMLStringifyError>;
+    /**
+     * Exposes the XML declaration as cloned data so callers cannot mutate internals.
+     */
+    get declaration(): XML.Declaration | undefined;
+    /**
+     * Exposes the root element as cloned data so callers cannot mutate internals.
+     */
+    get root(): XML.Element;
+    /**
+     * Returns the wrapped XML document as plain serializable data.
+     */
+    toJSON(): XML.Document;
+    /**
+     * Serializes the current XML instance into a string.
+     */
+    toString(): string;
+    /**
+     * Returns the first element in the document tree that matches the predicate.
+     *
+     * @param predicate - Receives each visited element in depth-first order
+     * @returns The first matching element, if one exists
+     */
+    find(predicate: XML.Predicate): XML.Element | undefined;
+    /**
+     * Returns every element in the document tree that matches the predicate.
+     *
+     * @param predicate - Receives each visited element in depth-first order
+     * @returns All matching elements in traversal order
+     */
+    findAll(predicate: XML.Predicate): XML.Element[];
+    /**
+     * Resolves the first element that matches a simple `/`-delimited path.
+     *
+     * @param path - Path such as `channel/item/title` or `rss/channel`
+     * @returns The first matching element, if one exists
+     */
+    query(path: string): XML.Element | undefined;
+    /**
+     * Resolves all elements that match a simple `/`-delimited path.
+     *
+     * @param path - Path such as `channel/item/title` or `rss/channel`
+     * @returns All matching elements in document order
+     */
+    queryAll(path: string): XML.Element[];
+}

package/dist/index.js

@@ -0,0 +1,167 @@
+/**
+ * Provides the XML class and error types for parsing, traversing, and
+ * serializing XML documents.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { cloneDeclaration } from "./lib/clone-declaration.js";
+import { cloneElement } from "./lib/clone-element.js";
+import { parseDocument } from "./lib/parse-document.js";
+import { stringifyDocument } from "./lib/stringify-document.js";
+import { collectInElement, findInElement, normalizePath, queryFromElements, startsWithRoot, } from "./lib/traversal.js";
+/**
+ * Signals that XML source could not be converted into the package tree format.
+ */
+export class XMLParseError extends Error {
+    name = "XMLParseError";
+}
+/**
+ * Signals that an XML tree could not be serialized into a valid XML string.
+ */
+export class XMLStringifyError extends Error {
+    name = "XMLStringifyError";
+}
+/**
+ * Wraps one parsed XML document and provides traversal and serialization helpers.
+ */
+export class XML {
+    #declaration;
+    #root;
+    /**
+     * Stores one XML document instance around a declaration and root element.
+     *
+     * @param document - The plain XML document data to wrap
+     */
+    constructor(document) {
+        this.#declaration = cloneDeclaration(document.declaration);
+        this.#root = cloneElement(document.root);
+    }
+    /**
+     * Parses XML into an `XML` instance.
+     *
+     * @param source - Raw XML text to parse
+     * @returns A Result containing an `XML` instance or a parse error
+     */
+    static parse(source) {
+        let result = parseDocument(source);
+        if (result.status === "failure")
+            return failure(new XMLParseError(result.error.message));
+        return success(new XML(result.data));
+    }
+    /**
+     * Serializes an XML instance, plain document data, or a root element into XML text.
+     *
+     * @param input - The XML instance, document data, or root element to serialize
+     * @returns A Result containing the XML string or a serialization error
+     */
+    static stringify(input) {
+        let document = toDocument(input);
+        if (document.status === "failure")
+            return document;
+        let result = stringifyDocument(document.data);
+        if (result.status === "failure") {
+            return failure(new XMLStringifyError(result.error.message));
+        }
+        return result;
+    }
+    /**
+     * Exposes the XML declaration as cloned data so callers cannot mutate internals.
+     */
+    get declaration() {
+        return cloneDeclaration(this.#declaration);
+    }
+    /**
+     * Exposes the root element as cloned data so callers cannot mutate internals.
+     */
+    get root() {
+        return cloneElement(this.#root);
+    }
+    /**
+     * Returns the wrapped XML document as plain serializable data.
+     */
+    toJSON() {
+        return {
+            declaration: cloneDeclaration(this.#declaration),
+            root: cloneElement(this.#root),
+        };
+    }
+    /**
+     * Serializes the current XML instance into a string.
+     */
+    toString() {
+        let result = stringifyDocument(this.toJSON());
+        if (result.status === "failure")
+            throw new XMLStringifyError(result.error.message);
+        return result.data;
+    }
+    /**
+     * Returns the first element in the document tree that matches the predicate.
+     *
+     * @param predicate - Receives each visited element in depth-first order
+     * @returns The first matching element, if one exists
+     */
+    find(predicate) {
+        return findInElement(this.#root, predicate);
+    }
+    /**
+     * Returns every element in the document tree that matches the predicate.
+     *
+     * @param predicate - Receives each visited element in depth-first order
+     * @returns All matching elements in traversal order
+     */
+    findAll(predicate) {
+        let matches = [];
+        collectInElement(this.#root, predicate, matches);
+        return matches;
+    }
+    /**
+     * Resolves the first element that matches a simple `/`-delimited path.
+     *
+     * @param path - Path such as `channel/item/title` or `rss/channel`
+     * @returns The first matching element, if one exists
+     */
+    query(path) {
+        return this.queryAll(path).at(0);
+    }
+    /**
+     * Resolves all elements that match a simple `/`-delimited path.
+     *
+     * @param path - Path such as `channel/item/title` or `rss/channel`
+     * @returns All matching elements in document order
+     */
+    queryAll(path) {
+        let segments = normalizePath(path);
+        if (segments.length === 0)
+            return [];
+        let roots = startsWithRoot(segments, this.#root.name)
+            ? queryFromElements([this.#root], segments.slice(1))
+            : queryFromElements([this.#root], segments);
+        return roots.map(cloneElement);
+    }
+}
+/**
+ * Recognizes the element shape, which is what tells a bare root element apart from
+ * the document that holds one, and what a value arriving from JavaScript is checked
+ * against before anything reads a name off it.
+ */
+function isElement(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return typeof value.name === "string";
+}
+/**
+ * Reads the document out of everything `stringify` accepts, wrapping a bare root
+ * element in the document that holds it. An input carrying no root element is the
+ * failure the Result promises, rather than a throw from deeper in serialization.
+ */
+function toDocument(input) {
+    if (input instanceof XML)
+        return success(input.toJSON());
+    if (isElement(input))
+        return success({ root: input });
+    if (isElement(input.root))
+        return success(input);
+    return failure(new XMLStringifyError("Expected a document carrying a root element, or the element itself."));
+}

package/dist/lib/clone-declaration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Provides a helper for cloning XML declaration data.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "../index.js";
+/**
+ * Clones declaration data so external code cannot mutate the stored value.
+ *
+ * @param declaration - The declaration data to clone
+ * @returns A shallow clone of the declaration or `undefined`
+ */
+export declare function cloneDeclaration(declaration?: XML.Declaration): XML.Declaration | undefined;

package/dist/lib/clone-declaration.js

@@ -0,0 +1,17 @@
+/**
+ * Provides a helper for cloning XML declaration data.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Clones declaration data so external code cannot mutate the stored value.
+ *
+ * @param declaration - The declaration data to clone
+ * @returns A shallow clone of the declaration or `undefined`
+ */
+export function cloneDeclaration(declaration) {
+    if (!declaration)
+        return undefined;
+    return structuredClone(declaration);
+}

package/dist/lib/clone-element.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Recursively clones XML element trees.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "../index.js";
+/**
+ * Clones one XML element tree recursively.
+ *
+ * @param element - The element tree to clone
+ * @returns A deep clone of the provided element
+ */
+export declare function cloneElement(element: XML.Element): XML.Element;

package/dist/lib/clone-element.js

@@ -0,0 +1,21 @@
+/**
+ * Recursively clones XML element trees.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Clones one XML element tree recursively.
+ *
+ * @param element - The element tree to clone
+ * @returns A deep clone of the provided element
+ */
+export function cloneElement(element) {
+    let attributes = element.attributes ? { ...element.attributes } : undefined;
+    let children = element.children?.map((child) => {
+        if (typeof child === "string")
+            return child;
+        return cloneElement(child);
+    });
+    return { name: element.name, attributes, children };
+}

package/dist/lib/decode-entities.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves the character references and named entities that appear inside text nodes
+ * and attribute values, covering XML's predefines, numeric forms and the XHTML entity
+ * sets, so a caller always receives text that is fully decoded.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+/**
+ * Replaces every reference in one run of parsed character data.
+ *
+ * @param value - Raw text taken straight from the source, still encoded
+ * @returns A Result with the decoded text, or the first reference that failed
+ */
+export declare function decodeEntities(value: string): Result<string, Error>;