@sdxc/atom 0.0.0-pre.1

package/dist/lib/namespaces.js

@@ -0,0 +1,63 @@
+/**
+ * Resolves which prefixes a document binds to which namespaces, so an element can
+ * be tested for membership in the Atom namespace rather than for a spelling. The
+ * XML layer performs no namespace resolution, so this package does its own.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ATOM_NAMESPACE } from "./constants.js";
+import { prefixOf } from "./utils.js";
+/**
+ * Reads every `xmlns` declaration off an element.
+ *
+ * @param element - The element whose declarations should be read
+ * @returns The declared namespaces, keyed by prefix
+ */
+export function readNamespaceDeclarations(element) {
+    let declarations = {};
+    for (let [name, value] of Object.entries(element.attributes ?? {})) {
+        if (name === "xmlns") {
+            declarations[""] = value;
+            continue;
+        }
+        if (name.startsWith("xmlns:"))
+            declarations[name.slice("xmlns:".length)] = value;
+    }
+    return declarations;
+}
+/**
+ * Extends an inherited scope with the declarations an element adds, so a nested
+ * element that rebinds a prefix is read against its own binding.
+ *
+ * @param scope - The namespaces inherited from ancestors
+ * @param element - The element whose declarations should be layered on top
+ * @returns The scope in effect inside the element
+ */
+export function extendNamespaceScope(scope, element) {
+    let declarations = readNamespaceDeclarations(element);
+    if (Object.keys(declarations).length === 0)
+        return scope;
+    return { ...scope, ...declarations };
+}
+/**
+ * Resolves the namespace a qualified name belongs to under a scope.
+ *
+ * @param name - The qualified element name
+ * @param scope - The namespaces in effect
+ * @returns The namespace URI, or `undefined` when the prefix is unbound
+ */
+export function namespaceOf(name, scope) {
+    return scope[prefixOf(name)];
+}
+/**
+ * Reports whether an element belongs to the Atom namespace, which is what
+ * separates an Atom element from a foreign one carrying the same local name.
+ *
+ * @param name - The qualified element name
+ * @param scope - The namespaces in effect
+ * @returns `true` when the name resolves to the Atom namespace
+ */
+export function isAtomName(name, scope) {
+    return namespaceOf(name, scope) === ATOM_NAMESPACE;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Parses an XML tree into Atom feed and entry data, threading the namespace and
+ * base-URI scopes down the document so an element is judged by the namespace it
+ * resolves to and every relative reference is read against the bases above it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { XML } from "@sdxc/xml";
+import type { Atom } from "../index.js";
+import { AtomParseError } from "../index.js";
+/**
+ * Parses a document into feed metadata and entries.
+ *
+ * @param xml - The parsed XML document
+ * @param base - Document URI, seeding the base against which relative references resolve
+ * @returns The feed and its entries, or the reason the document is not Atom
+ */
+export declare function parseDocument(xml: XML, base?: string): Result<Atom.Document, AtomParseError>;

package/dist/lib/parse-feed.js

@@ -0,0 +1,431 @@
+/**
+ * Parses an XML tree into Atom feed and entry data, threading the namespace and
+ * base-URI scopes down the document so an element is judged by the namespace it
+ * resolves to and every relative reference is read against the bases above it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, success } from "@sdxc/result";
+import { AtomParseError } from "../index.js";
+import { cloneAttributes } from "./clone.js";
+import { parseContent } from "./content.js";
+import { toExtensionElement } from "./extensions.js";
+import { extendNamespaceScope, isAtomName, readNamespaceDeclarations } from "./namespaces.js";
+import { parseText } from "./text-construct.js";
+import { collapseArray, getChildElements, getElementText, localName, parseOptionalNumber, } from "./utils.js";
+import { extendScope, resolveUri } from "./xml-base.js";
+/**
+ * Parses a document into feed metadata and entries.
+ *
+ * @param xml - The parsed XML document
+ * @param base - Document URI, seeding the base against which relative references resolve
+ * @returns The feed and its entries, or the reason the document is not Atom
+ */
+export function parseDocument(xml, base) {
+    let root = xml.root;
+    let namespaces = readNamespaceDeclarations(root);
+    if (localName(root.name) !== "feed") {
+        return failure(new AtomParseError(`Expected the root element to be "feed".`));
+    }
+    if (!isAtomName(root.name, namespaces)) {
+        return failure(new AtomParseError("Expected the root element in the Atom namespace."));
+    }
+    let scope = extendScope({ base }, root);
+    let feedResult = parseFeed(root, scope, namespaces);
+    if (feedResult.status === "failure")
+        return feedResult;
+    let entries = [];
+    for (let child of getChildElements(root)) {
+        if (!isAtomName(child.name, namespaces) || localName(child.name) !== "entry")
+            continue;
+        let entryResult = parseEntry(child, scope, namespaces);
+        if (entryResult.status === "failure")
+            return entryResult;
+        entries.push(entryResult.data);
+    }
+    return success({ feed: feedResult.data, entries });
+}
+/**
+ * Parses the feed element's own children, skipping the entries, which the caller
+ * collects separately so one pass does not have to build both shapes at once.
+ */
+function parseFeed(element, scope, namespaces) {
+    let authors = [];
+    let contributors = [];
+    let links = [];
+    let categories = [];
+    let extensions = [];
+    let feed = {
+        namespaces: cloneAttributes(namespaces),
+        attributes: readOwnAttributes(element),
+        lang: scope.lang,
+        base: scope.base,
+    };
+    for (let child of getChildElements(element)) {
+        if (!isAtomName(child.name, extendNamespaceScope(namespaces, child))) {
+            extensions.push(toExtensionElement(child));
+            continue;
+        }
+        let childScope = extendScope(scope, child);
+        switch (localName(child.name)) {
+            case "id": {
+                feed.id = getElementText(child);
+                break;
+            }
+            case "title": {
+                feed.title = parseText(child);
+                break;
+            }
+            case "updated": {
+                feed.updated = getElementText(child);
+                break;
+            }
+            case "subtitle": {
+                feed.subtitle = parseText(child);
+                break;
+            }
+            case "rights": {
+                feed.rights = parseText(child);
+                break;
+            }
+            case "author": {
+                authors.push(parsePerson(child, childScope, namespaces));
+                break;
+            }
+            case "contributor": {
+                contributors.push(parsePerson(child, childScope, namespaces));
+                break;
+            }
+            case "link": {
+                links.push(parseLink(child, childScope, namespaces));
+                break;
+            }
+            case "category": {
+                categories.push(parseCategory(child, namespaces));
+                break;
+            }
+            case "generator": {
+                feed.generator = parseGenerator(child, childScope);
+                break;
+            }
+            case "icon": {
+                feed.icon = resolveUri(childScope, getElementText(child));
+                break;
+            }
+            case "logo": {
+                feed.logo = resolveUri(childScope, getElementText(child));
+                break;
+            }
+            /** Collected by the caller, which builds the entry list in its own pass. */
+            case "entry": {
+                break;
+            }
+            default: {
+                extensions.push(toExtensionElement(child));
+            }
+        }
+    }
+    if (!feed.id)
+        return failure(new AtomParseError("Feed must include an id."));
+    if (feed.title === undefined)
+        return failure(new AtomParseError("Feed must include a title."));
+    if (!feed.updated) {
+        return failure(new AtomParseError("Feed must include an updated timestamp."));
+    }
+    if (authors.length > 0)
+        feed.author = collapseArray(authors);
+    if (contributors.length > 0)
+        feed.contributor = collapseArray(contributors);
+    if (links.length > 0)
+        feed.link = collapseArray(links);
+    if (categories.length > 0)
+        feed.category = collapseArray(categories);
+    if (extensions.length > 0)
+        feed.extensions = extensions;
+    return success(feed);
+}
+/** Parses one entry element. */
+function parseEntry(element, parentScope, namespaces) {
+    let scope = extendScope(parentScope, element);
+    let authors = [];
+    let contributors = [];
+    let links = [];
+    let categories = [];
+    let extensions = [];
+    let entry = {
+        attributes: readOwnAttributes(element),
+        lang: scope.lang === parentScope.lang ? undefined : scope.lang,
+        base: scope.base === parentScope.base ? undefined : scope.base,
+    };
+    for (let child of getChildElements(element)) {
+        if (!isAtomName(child.name, extendNamespaceScope(namespaces, child))) {
+            extensions.push(toExtensionElement(child));
+            continue;
+        }
+        let childScope = extendScope(scope, child);
+        switch (localName(child.name)) {
+            case "id": {
+                entry.id = getElementText(child);
+                break;
+            }
+            case "title": {
+                entry.title = parseText(child);
+                break;
+            }
+            case "updated": {
+                entry.updated = getElementText(child);
+                break;
+            }
+            case "published": {
+                entry.published = getElementText(child);
+                break;
+            }
+            case "summary": {
+                entry.summary = parseText(child);
+                break;
+            }
+            case "content": {
+                entry.content = parseContent(child, childScope);
+                break;
+            }
+            case "rights": {
+                entry.rights = parseText(child);
+                break;
+            }
+            case "author": {
+                authors.push(parsePerson(child, childScope, namespaces));
+                break;
+            }
+            case "contributor": {
+                contributors.push(parsePerson(child, childScope, namespaces));
+                break;
+            }
+            case "link": {
+                links.push(parseLink(child, childScope, namespaces));
+                break;
+            }
+            case "category": {
+                categories.push(parseCategory(child, namespaces));
+                break;
+            }
+            case "source": {
+                entry.source = parseSource(child, childScope, namespaces);
+                break;
+            }
+            default: {
+                extensions.push(toExtensionElement(child));
+            }
+        }
+    }
+    if (!entry.id)
+        return failure(new AtomParseError("Entry must include an id."));
+    if (entry.title === undefined)
+        return failure(new AtomParseError("Entry must include a title."));
+    if (!entry.updated) {
+        return failure(new AtomParseError("Entry must include an updated timestamp."));
+    }
+    if (authors.length > 0)
+        entry.author = collapseArray(authors);
+    if (contributors.length > 0)
+        entry.contributor = collapseArray(contributors);
+    if (links.length > 0)
+        entry.link = collapseArray(links);
+    if (categories.length > 0)
+        entry.category = collapseArray(categories);
+    if (extensions.length > 0)
+        entry.extensions = extensions;
+    return success(entry);
+}
+/** Parses a person construct: an author or a contributor. */
+function parsePerson(element, scope, namespaces) {
+    let person = { name: "" };
+    let extensions = [];
+    for (let child of getChildElements(element)) {
+        if (!isAtomName(child.name, extendNamespaceScope(namespaces, child))) {
+            extensions.push(toExtensionElement(child));
+            continue;
+        }
+        switch (localName(child.name)) {
+            case "name": {
+                person.name = getElementText(child);
+                break;
+            }
+            case "uri": {
+                person.uri = resolveUri(extendScope(scope, child), getElementText(child));
+                break;
+            }
+            case "email": {
+                person.email = getElementText(child);
+                break;
+            }
+            default: {
+                extensions.push(toExtensionElement(child));
+            }
+        }
+    }
+    if (extensions.length > 0)
+        person.extensions = extensions;
+    return person;
+}
+/**
+ * Parses a link, resolving `href` against the base in scope. `rel` is left as the
+ * document spelled it, absent included, because RFC 4287's `alternate` default is
+ * a reader's concern rather than something to bake into stored data.
+ */
+function parseLink(element, scope, namespaces) {
+    let attributes = { ...element.attributes };
+    let link = { href: resolveUri(scope, attributes["href"] ?? "") };
+    if (attributes["rel"] !== undefined)
+        link.rel = attributes["rel"];
+    if (attributes["type"] !== undefined)
+        link.type = attributes["type"];
+    if (attributes["hreflang"] !== undefined)
+        link.hreflang = attributes["hreflang"];
+    if (attributes["title"] !== undefined)
+        link.title = attributes["title"];
+    if (attributes["length"] !== undefined) {
+        link.length = parseOptionalNumber(attributes["length"]);
+    }
+    for (let name of ["href", "rel", "type", "hreflang", "title", "length"])
+        delete attributes[name];
+    let remaining = cloneAttributes(stripScopeAttributes(attributes));
+    if (remaining)
+        link.attributes = remaining;
+    let extensions = collectForeignChildren(element, namespaces);
+    if (extensions.length > 0)
+        link.extensions = extensions;
+    return link;
+}
+/** Parses a category, collapsing to the bare term when nothing else is present. */
+function parseCategory(element, namespaces) {
+    let attributes = { ...element.attributes };
+    let term = attributes["term"] ?? "";
+    let scheme = attributes["scheme"];
+    let label = attributes["label"];
+    for (let name of ["term", "scheme", "label"])
+        delete attributes[name];
+    let remaining = cloneAttributes(stripScopeAttributes(attributes));
+    let extensions = collectForeignChildren(element, namespaces);
+    if (scheme === undefined && label === undefined && !remaining && extensions.length === 0) {
+        return term;
+    }
+    let category = { term };
+    if (scheme !== undefined)
+        category.scheme = scheme;
+    if (label !== undefined)
+        category.label = label;
+    if (remaining)
+        category.attributes = remaining;
+    if (extensions.length > 0)
+        category.extensions = extensions;
+    return category;
+}
+/** Parses the generator element, whose `uri` resolves against the base in scope. */
+function parseGenerator(element, scope) {
+    let attributes = element.attributes ?? {};
+    let generator = { value: getElementText(element) };
+    if (attributes["uri"] !== undefined)
+        generator.uri = resolveUri(scope, attributes["uri"]);
+    if (attributes["version"] !== undefined)
+        generator.version = attributes["version"];
+    return generator;
+}
+/**
+ * Parses the source element, which carries a subset of feed metadata describing
+ * where a copied entry came from.
+ */
+function parseSource(element, scope, namespaces) {
+    let source = {};
+    let authors = [];
+    let links = [];
+    let extensions = [];
+    for (let child of getChildElements(element)) {
+        if (!isAtomName(child.name, extendNamespaceScope(namespaces, child))) {
+            extensions.push(toExtensionElement(child));
+            continue;
+        }
+        let childScope = extendScope(scope, child);
+        switch (localName(child.name)) {
+            case "id": {
+                source.id = getElementText(child);
+                break;
+            }
+            case "title": {
+                source.title = parseText(child);
+                break;
+            }
+            case "subtitle": {
+                source.subtitle = parseText(child);
+                break;
+            }
+            case "updated": {
+                source.updated = getElementText(child);
+                break;
+            }
+            case "rights": {
+                source.rights = parseText(child);
+                break;
+            }
+            case "author": {
+                authors.push(parsePerson(child, childScope, namespaces));
+                break;
+            }
+            case "link": {
+                links.push(parseLink(child, childScope, namespaces));
+                break;
+            }
+            default: {
+                extensions.push(toExtensionElement(child));
+            }
+        }
+    }
+    let attributes = readOwnAttributes(element);
+    if (attributes)
+        source.attributes = attributes;
+    if (authors.length > 0)
+        source.author = collapseArray(authors);
+    if (links.length > 0)
+        source.link = collapseArray(links);
+    if (extensions.length > 0)
+        source.extensions = extensions;
+    return source;
+}
+/** Collects the children of an element that fall outside the Atom namespace. */
+function collectForeignChildren(element, namespaces) {
+    let extensions = [];
+    for (let child of getChildElements(element)) {
+        if (isAtomName(child.name, extendNamespaceScope(namespaces, child)))
+            continue;
+        extensions.push(toExtensionElement(child));
+    }
+    return extensions;
+}
+/**
+ * Reads the attributes an element carries in its own right, dropping the ones
+ * already modelled elsewhere: namespace declarations become `namespaces`, and
+ * `xml:base`/`xml:lang` become the scope every reference was resolved against.
+ */
+function readOwnAttributes(element) {
+    let attributes = {};
+    for (let [name, value] of Object.entries(element.attributes ?? {})) {
+        if (name === "xmlns" || name.startsWith("xmlns:"))
+            continue;
+        if (name === "xml:base" || name === "xml:lang")
+            continue;
+        attributes[name] = value;
+    }
+    return cloneAttributes(attributes);
+}
+/** Drops the scope-carrying attributes from a record already stripped of its own keys. */
+function stripScopeAttributes(attributes) {
+    let remaining = {};
+    for (let [name, value] of Object.entries(attributes)) {
+        if (name === "xmlns" || name.startsWith("xmlns:"))
+            continue;
+        if (name === "xml:base" || name === "xml:lang")
+            continue;
+        remaining[name] = value;
+    }
+    return remaining;
+}

package/dist/lib/text-construct.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reads and writes Atom text constructs, whose `type` decides whether the payload
+ * is plain text, a run of HTML, or an XHTML subtree that has to be serialized back
+ * into markup before a consumer can use it (RFC 4287 §3.1).
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { XML } from "@sdxc/xml";
+import type { Atom } from "../index.js";
+/**
+ * Reads one text construct.
+ *
+ * An `xhtml` construct collapses to the serialized markup its single `div`
+ * wrapper contained — the wrapper itself is structural and is dropped — so every
+ * construct hands back a string regardless of how it was written.
+ *
+ * @param element - The element holding the construct
+ * @returns The construct, collapsed to a bare string when it carries no type
+ */
+export declare function parseText(element: XML.Element): Atom.TextInput;
+/**
+ * Builds the element for one text construct.
+ *
+ * An `xhtml` construct is written back as `html`: the value is markup in a string
+ * by then, and re-parsing it to rebuild a wrapper would fail on any fragment the
+ * XML parser rejects. The payload survives; the typing narrows.
+ *
+ * @param name - The element name to write
+ * @param text - The construct to serialize
+ * @returns The element, ready to place in a document
+ */
+export declare function buildTextElement(name: string, text: Atom.TextInput): XML.Element;

package/dist/lib/text-construct.js

@@ -0,0 +1,97 @@
+/**
+ * Reads and writes Atom text constructs, whose `type` decides whether the payload
+ * is plain text, a run of HTML, or an XHTML subtree that has to be serialized back
+ * into markup before a consumer can use it (RFC 4287 §3.1).
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+import { DEFAULT_TEXT_TYPE } from "./constants.js";
+import { getChildElements, getElementText, localName } from "./utils.js";
+/** The characters that carry markup meaning when XHTML text is re-serialized. */
+const TEXT_ESCAPES = {
+    "<": "&lt;",
+    ">": "&gt;",
+    "&": "&amp;",
+};
+const TEXT_PATTERN = /[<>&]/g;
+/**
+ * Reads one text construct.
+ *
+ * An `xhtml` construct collapses to the serialized markup its single `div`
+ * wrapper contained — the wrapper itself is structural and is dropped — so every
+ * construct hands back a string regardless of how it was written.
+ *
+ * @param element - The element holding the construct
+ * @returns The construct, collapsed to a bare string when it carries no type
+ */
+export function parseText(element) {
+    let type = element.attributes?.type ?? DEFAULT_TEXT_TYPE;
+    if (type === "xhtml")
+        return { value: readXhtml(element), type: "xhtml" };
+    if (type === "html")
+        return { value: getElementText(element), type: "html" };
+    /**
+     * A `text` construct is the default, so the bare string says everything the
+     * structured form would and reads better at a call site.
+     */
+    return getElementText(element);
+}
+/**
+ * Serializes the children of an `xhtml` construct's wrapper.
+ *
+ * The wrapper is the `div` RFC 4287 §3.1.1.3 requires; when a document omits it
+ * the element's own children are serialized instead, so malformed input still
+ * yields the markup it meant rather than nothing.
+ */
+function readXhtml(element) {
+    let wrapper = getChildElements(element).find((child) => localName(child.name) === "div");
+    let host = wrapper ?? element;
+    let markup = "";
+    for (let child of host.children ?? []) {
+        if (typeof child === "string") {
+            markup += escapeText(child);
+            continue;
+        }
+        markup += stringifyElement(child);
+    }
+    return markup;
+}
+/**
+ * Serializes one element of an XHTML construct back into markup.
+ *
+ * A failure yields the element's text alone, because losing the tags around a
+ * paragraph is a better outcome for a reader than losing the paragraph.
+ */
+function stringifyElement(element) {
+    let result = XML.stringify(element);
+    if (isFailure(result))
+        return escapeText(getElementText(element));
+    return result.data;
+}
+/** Escapes the three characters that would otherwise read as markup. */
+function escapeText(value) {
+    return value.replace(TEXT_PATTERN, (character) => TEXT_ESCAPES[character] ?? character);
+}
+/**
+ * Builds the element for one text construct.
+ *
+ * An `xhtml` construct is written back as `html`: the value is markup in a string
+ * by then, and re-parsing it to rebuild a wrapper would fail on any fragment the
+ * XML parser rejects. The payload survives; the typing narrows.
+ *
+ * @param name - The element name to write
+ * @param text - The construct to serialize
+ * @returns The element, ready to place in a document
+ */
+export function buildTextElement(name, text) {
+    if (typeof text === "string")
+        return { name, attributes: {}, children: [text] };
+    let type = text.type === "xhtml" ? "html" : text.type;
+    let attributes = {};
+    if (type && type !== DEFAULT_TEXT_TYPE)
+        attributes["type"] = type;
+    return { name, attributes, children: [text.value] };
+}