@sdxc/atom 0.0.0-pre.1

package/dist/lib/build-document.js

@@ -0,0 +1,195 @@
+/**
+ * Builds the XML document for a feed, declaring the Atom namespace on the root and
+ * writing every construct back in the form the format expects.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { ATOM_NAMESPACE } from "./constants.js";
+import { buildContentElement } from "./content.js";
+import { toXMLElement } from "./extensions.js";
+import { buildTextElement } from "./text-construct.js";
+import { normalizeArray } from "./utils.js";
+/**
+ * Builds the whole document.
+ *
+ * @param feed - The feed-level metadata
+ * @param entries - The entries to write, in order
+ * @returns The document, ready to serialize
+ */
+export function buildDocument(feed, entries) {
+    return {
+        declaration: { version: "1.0", encoding: "UTF-8" },
+        root: {
+            name: "feed",
+            attributes: buildRootAttributes(feed),
+            children: [...buildFeedChildren(feed), ...entries.map(buildEntryElement)],
+        },
+    };
+}
+/**
+ * Builds the root's attributes, declaring the Atom namespace as the default so
+ * every element beneath it is unprefixed, alongside any the feed carried.
+ */
+function buildRootAttributes(feed) {
+    let attributes = {
+        xmlns: ATOM_NAMESPACE,
+        ...feed.attributes,
+    };
+    for (let [prefix, uri] of Object.entries(feed.namespaces ?? {})) {
+        if (prefix === "")
+            continue;
+        attributes[`xmlns:${prefix}`] = uri;
+    }
+    if (feed.base !== undefined)
+        attributes["xml:base"] = feed.base;
+    if (feed.lang !== undefined)
+        attributes["xml:lang"] = feed.lang;
+    return attributes;
+}
+/** Builds the feed element's own children, in the order RFC 4287 presents them. */
+function buildFeedChildren(feed) {
+    let children = [
+        textElement("id", feed.id),
+        buildTextElement("title", feed.title),
+        textElement("updated", feed.updated),
+    ];
+    if (feed.subtitle !== undefined)
+        children.push(buildTextElement("subtitle", feed.subtitle));
+    if (feed.rights !== undefined)
+        children.push(buildTextElement("rights", feed.rights));
+    for (let author of normalizeArray(feed.author))
+        children.push(buildPersonElement("author", author));
+    for (let contributor of normalizeArray(feed.contributor)) {
+        children.push(buildPersonElement("contributor", contributor));
+    }
+    for (let link of normalizeArray(feed.link))
+        children.push(buildLinkElement(link));
+    for (let category of normalizeArray(feed.category))
+        children.push(buildCategoryElement(category));
+    if (feed.generator)
+        children.push(buildGeneratorElement(feed.generator));
+    if (feed.icon !== undefined)
+        children.push(textElement("icon", feed.icon));
+    if (feed.logo !== undefined)
+        children.push(textElement("logo", feed.logo));
+    for (let extension of feed.extensions ?? [])
+        children.push(toXMLElement(extension));
+    return children;
+}
+/** Builds one entry element. */
+function buildEntryElement(entry) {
+    let attributes = { ...entry.attributes };
+    if (entry.base !== undefined)
+        attributes["xml:base"] = entry.base;
+    if (entry.lang !== undefined)
+        attributes["xml:lang"] = entry.lang;
+    let children = [
+        textElement("id", entry.id),
+        buildTextElement("title", entry.title),
+        textElement("updated", entry.updated),
+    ];
+    if (entry.published !== undefined)
+        children.push(textElement("published", entry.published));
+    if (entry.summary !== undefined)
+        children.push(buildTextElement("summary", entry.summary));
+    if (entry.content)
+        children.push(buildContentElement(entry.content));
+    if (entry.rights !== undefined)
+        children.push(buildTextElement("rights", entry.rights));
+    for (let author of normalizeArray(entry.author))
+        children.push(buildPersonElement("author", author));
+    for (let contributor of normalizeArray(entry.contributor)) {
+        children.push(buildPersonElement("contributor", contributor));
+    }
+    for (let link of normalizeArray(entry.link))
+        children.push(buildLinkElement(link));
+    for (let category of normalizeArray(entry.category))
+        children.push(buildCategoryElement(category));
+    if (entry.source)
+        children.push(buildSourceElement(entry.source));
+    for (let extension of entry.extensions ?? [])
+        children.push(toXMLElement(extension));
+    return { name: "entry", attributes, children };
+}
+/** Builds a person construct. */
+function buildPersonElement(name, person) {
+    let children = [textElement("name", person.name)];
+    if (person.uri !== undefined)
+        children.push(textElement("uri", person.uri));
+    if (person.email !== undefined)
+        children.push(textElement("email", person.email));
+    for (let extension of person.extensions ?? [])
+        children.push(toXMLElement(extension));
+    return { name, attributes: {}, children };
+}
+/** Builds a link, which is empty and carries everything in its attributes. */
+function buildLinkElement(link) {
+    let attributes = { href: link.href, ...link.attributes };
+    if (link.rel !== undefined)
+        attributes["rel"] = link.rel;
+    if (link.type !== undefined)
+        attributes["type"] = link.type;
+    if (link.hreflang !== undefined)
+        attributes["hreflang"] = link.hreflang;
+    if (link.title !== undefined)
+        attributes["title"] = link.title;
+    if (link.length !== undefined && Number.isFinite(link.length)) {
+        attributes["length"] = String(link.length);
+    }
+    return {
+        name: "link",
+        attributes,
+        children: (link.extensions ?? []).map(toXMLElement),
+    };
+}
+/** Builds a category from either the bare-term or the structured form. */
+function buildCategoryElement(category) {
+    if (typeof category === "string") {
+        return { name: "category", attributes: { term: category }, children: [] };
+    }
+    let attributes = { term: category.term, ...category.attributes };
+    if (category.scheme !== undefined)
+        attributes["scheme"] = category.scheme;
+    if (category.label !== undefined)
+        attributes["label"] = category.label;
+    return {
+        name: "category",
+        attributes,
+        children: (category.extensions ?? []).map(toXMLElement),
+    };
+}
+/** Builds the generator element. */
+function buildGeneratorElement(generator) {
+    let attributes = {};
+    if (generator.uri !== undefined)
+        attributes["uri"] = generator.uri;
+    if (generator.version !== undefined)
+        attributes["version"] = generator.version;
+    return { name: "generator", attributes, children: [generator.value] };
+}
+/** Builds the source element an entry copied from another feed carries. */
+function buildSourceElement(source) {
+    let children = [];
+    if (source.id !== undefined)
+        children.push(textElement("id", source.id));
+    if (source.title !== undefined)
+        children.push(buildTextElement("title", source.title));
+    if (source.subtitle !== undefined)
+        children.push(buildTextElement("subtitle", source.subtitle));
+    if (source.updated !== undefined)
+        children.push(textElement("updated", source.updated));
+    if (source.rights !== undefined)
+        children.push(buildTextElement("rights", source.rights));
+    for (let author of normalizeArray(source.author))
+        children.push(buildPersonElement("author", author));
+    for (let link of normalizeArray(source.link))
+        children.push(buildLinkElement(link));
+    for (let extension of source.extensions ?? [])
+        children.push(toXMLElement(extension));
+    return { name: "source", attributes: { ...source.attributes }, children };
+}
+/** Builds an element holding one run of text and no attributes. */
+function textElement(name, value) {
+    return { name, attributes: {}, children: [value] };
+}

package/dist/lib/clone.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Deep-clone helpers for feed, entry, and extension element data, so the class
+ * hands out copies and a caller cannot reach its internals through a return value.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Atom } from "../index.js";
+/**
+ * Clones an attribute record, reporting an absent or empty one as `undefined` so
+ * a document that declared nothing does not grow an empty object.
+ *
+ * @param attributes - The attributes to clone
+ * @returns The cloned attributes, or `undefined`
+ */
+export declare function cloneAttributes(attributes?: Record<string, string>): Record<string, string> | undefined;
+/** Clones a list of extension elements, or reports `undefined` for none. */
+export declare function cloneExtensionElements(elements?: Atom.Element[]): Atom.Element[] | undefined;
+/** Clones a text construct, which is immutable in its string form. */
+export declare function cloneTextInput(text?: Atom.TextInput): Atom.TextInput | undefined;
+/** Clones one person or a list of them, preserving which form was used. */
+export declare function clonePersonInput(person?: Atom.PersonInput): Atom.PersonInput | undefined;
+/** Clones one link or a list of them, preserving which form was used. */
+export declare function cloneLinkInput(link?: Atom.LinkInput): Atom.LinkInput | undefined;
+/** Clones one category or a list of them, preserving which form was used. */
+export declare function cloneCategoryInput(category?: Atom.CategoryInput | Atom.CategoryInput[]): Atom.CategoryInput | Atom.CategoryInput[] | undefined;
+/**
+ * Clones feed-level metadata deeply enough that nothing reachable from the copy
+ * is shared with the original.
+ *
+ * @param feed - The feed to clone
+ * @returns The cloned feed
+ */
+export declare function cloneFeed(feed: Atom.Feed): Atom.Feed;
+/**
+ * Clones one entry deeply enough that nothing reachable from the copy is shared
+ * with the original.
+ *
+ * @param entry - The entry to clone
+ * @returns The cloned entry
+ */
+export declare function cloneEntry(entry: Atom.Entry): Atom.Entry;

package/dist/lib/clone.js

@@ -0,0 +1,147 @@
+/**
+ * Deep-clone helpers for feed, entry, and extension element data, so the class
+ * hands out copies and a caller cannot reach its internals through a return value.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Clones an attribute record, reporting an absent or empty one as `undefined` so
+ * a document that declared nothing does not grow an empty object.
+ *
+ * @param attributes - The attributes to clone
+ * @returns The cloned attributes, or `undefined`
+ */
+export function cloneAttributes(attributes) {
+    if (!attributes)
+        return undefined;
+    if (Object.keys(attributes).length === 0)
+        return undefined;
+    return { ...attributes };
+}
+/** Clones a list of extension elements, or reports `undefined` for none. */
+export function cloneExtensionElements(elements) {
+    if (!elements)
+        return undefined;
+    return elements.map(cloneExtensionElement);
+}
+/** Clones one extension element and everything beneath it. */
+function cloneExtensionElement(element) {
+    let children = element.children?.map((child) => typeof child === "string" ? child : cloneExtensionElement(child));
+    return { name: element.name, attributes: cloneAttributes(element.attributes), children };
+}
+/** Clones a text construct, which is immutable in its string form. */
+export function cloneTextInput(text) {
+    if (text === undefined)
+        return undefined;
+    if (typeof text === "string")
+        return text;
+    return { ...text };
+}
+/** Clones one person construct. */
+function clonePerson(person) {
+    return { ...person, extensions: cloneExtensionElements(person.extensions) };
+}
+/** Clones one person or a list of them, preserving which form was used. */
+export function clonePersonInput(person) {
+    if (person === undefined)
+        return undefined;
+    if (Array.isArray(person))
+        return person.map(clonePerson);
+    return clonePerson(person);
+}
+/** Clones one link. */
+function cloneLink(link) {
+    return {
+        ...link,
+        attributes: cloneAttributes(link.attributes),
+        extensions: cloneExtensionElements(link.extensions),
+    };
+}
+/** Clones one link or a list of them, preserving which form was used. */
+export function cloneLinkInput(link) {
+    if (link === undefined)
+        return undefined;
+    if (Array.isArray(link))
+        return link.map(cloneLink);
+    return cloneLink(link);
+}
+/** Clones one category, which stays a bare string when it carried nothing else. */
+function cloneCategory(category) {
+    if (typeof category === "string")
+        return category;
+    return {
+        ...category,
+        attributes: cloneAttributes(category.attributes),
+        extensions: cloneExtensionElements(category.extensions),
+    };
+}
+/** Clones one category or a list of them, preserving which form was used. */
+export function cloneCategoryInput(category) {
+    if (category === undefined)
+        return undefined;
+    if (Array.isArray(category))
+        return category.map(cloneCategory);
+    return cloneCategory(category);
+}
+/** Clones the source feed metadata an entry was copied with. */
+function cloneSource(source) {
+    return {
+        ...source,
+        title: cloneTextInput(source.title),
+        subtitle: cloneTextInput(source.subtitle),
+        rights: cloneTextInput(source.rights),
+        author: clonePersonInput(source.author),
+        link: cloneLinkInput(source.link),
+        attributes: cloneAttributes(source.attributes),
+        extensions: cloneExtensionElements(source.extensions),
+    };
+}
+/**
+ * Clones feed-level metadata deeply enough that nothing reachable from the copy
+ * is shared with the original.
+ *
+ * @param feed - The feed to clone
+ * @returns The cloned feed
+ */
+export function cloneFeed(feed) {
+    return {
+        ...feed,
+        title: cloneTextInput(feed.title),
+        subtitle: cloneTextInput(feed.subtitle),
+        rights: cloneTextInput(feed.rights),
+        author: clonePersonInput(feed.author),
+        contributor: clonePersonInput(feed.contributor),
+        link: cloneLinkInput(feed.link),
+        category: cloneCategoryInput(feed.category),
+        generator: feed.generator ? { ...feed.generator } : undefined,
+        namespaces: cloneAttributes(feed.namespaces),
+        attributes: cloneAttributes(feed.attributes),
+        extensions: cloneExtensionElements(feed.extensions),
+    };
+}
+/**
+ * Clones one entry deeply enough that nothing reachable from the copy is shared
+ * with the original.
+ *
+ * @param entry - The entry to clone
+ * @returns The cloned entry
+ */
+export function cloneEntry(entry) {
+    return {
+        ...entry,
+        title: cloneTextInput(entry.title),
+        summary: cloneTextInput(entry.summary),
+        rights: cloneTextInput(entry.rights),
+        content: entry.content
+            ? { ...entry.content, attributes: cloneAttributes(entry.content.attributes) }
+            : undefined,
+        author: clonePersonInput(entry.author),
+        contributor: clonePersonInput(entry.contributor),
+        link: cloneLinkInput(entry.link),
+        category: cloneCategoryInput(entry.category),
+        source: entry.source ? cloneSource(entry.source) : undefined,
+        attributes: cloneAttributes(entry.attributes),
+        extensions: cloneExtensionElements(entry.extensions),
+    };
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The namespace that identifies Atom and the default a text construct assumes,
+ * shared across the package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Stores the Atom 1.0 namespace URI, which identifies the format rather than any
+ * prefix a document happens to bind it to.
+ */
+export declare const ATOM_NAMESPACE = "http://www.w3.org/2005/Atom";
+/**
+ * Stores the text type assumed when a construct omits its `type` attribute,
+ * which RFC 4287 §3.1.1 defines as `text`.
+ */
+export declare const DEFAULT_TEXT_TYPE = "text";

package/dist/lib/constants.js

@@ -0,0 +1,17 @@
+/**
+ * The namespace that identifies Atom and the default a text construct assumes,
+ * shared across the package.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Stores the Atom 1.0 namespace URI, which identifies the format rather than any
+ * prefix a document happens to bind it to.
+ */
+export const ATOM_NAMESPACE = "http://www.w3.org/2005/Atom";
+/**
+ * Stores the text type assumed when a construct omits its `type` attribute,
+ * which RFC 4287 §3.1.1 defines as `text`.
+ */
+export const DEFAULT_TEXT_TYPE = "text";

package/dist/lib/content.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reads and writes an entry's `content` element, which extends a text construct
+ * with any media type and with `src` for a body held out of line (RFC 4287 §4.1.3).
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { XML } from "@sdxc/xml";
+import type { Atom } from "../index.js";
+import type { Scope } from "./xml-base.js";
+/**
+ * Reads the content element.
+ *
+ * A `src` body is reported without a value, because the element is empty by
+ * definition and inventing one would hide that the body lives elsewhere. Text,
+ * HTML and XHTML share the text construct's reading; any other media type is
+ * handed back as the raw string it was written as, undecoded.
+ *
+ * @param element - The content element
+ * @param scope - The base and language in effect
+ * @returns The parsed content
+ */
+export declare function parseContent(element: XML.Element, scope: Scope): Atom.Content;
+/**
+ * Builds the content element.
+ *
+ * An `xhtml` body is written back as `html` for the reason the text constructs
+ * are: by this point the markup is a string, and re-parsing it to rebuild a
+ * wrapper would fail on any fragment the XML parser rejects.
+ *
+ * @param content - The content to serialize
+ * @returns The element, ready to place in an entry
+ */
+export declare function buildContentElement(content: Atom.Content): XML.Element;

package/dist/lib/content.js

@@ -0,0 +1,75 @@
+/**
+ * Reads and writes an entry's `content` element, which extends a text construct
+ * with any media type and with `src` for a body held out of line (RFC 4287 §4.1.3).
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { XML } from "@sdxc/xml";
+import { cloneAttributes } from "./clone.js";
+import { parseText } from "./text-construct.js";
+import { getElementText } from "./utils.js";
+import { resolveUri } from "./xml-base.js";
+/**
+ * Reads the content element.
+ *
+ * A `src` body is reported without a value, because the element is empty by
+ * definition and inventing one would hide that the body lives elsewhere. Text,
+ * HTML and XHTML share the text construct's reading; any other media type is
+ * handed back as the raw string it was written as, undecoded.
+ *
+ * @param element - The content element
+ * @param scope - The base and language in effect
+ * @returns The parsed content
+ */
+export function parseContent(element, scope) {
+    let attributes = { ...element.attributes };
+    let type = attributes["type"];
+    let src = attributes["src"];
+    delete attributes["type"];
+    delete attributes["src"];
+    let content = {};
+    if (type !== undefined)
+        content.type = type;
+    if (src !== undefined)
+        content.src = resolveUri(scope, src);
+    if (src === undefined)
+        content.value = readValue(element, type);
+    let remaining = cloneAttributes(attributes);
+    if (remaining)
+        content.attributes = remaining;
+    return content;
+}
+/**
+ * Reads an inline body, routing the three text types through the text construct
+ * and leaving every other media type as the source text.
+ */
+function readValue(element, type) {
+    if (type === undefined || type === "text" || type === "html" || type === "xhtml") {
+        let text = parseText(element);
+        return typeof text === "string" ? text : text.value;
+    }
+    return getElementText(element);
+}
+/**
+ * Builds the content element.
+ *
+ * An `xhtml` body is written back as `html` for the reason the text constructs
+ * are: by this point the markup is a string, and re-parsing it to rebuild a
+ * wrapper would fail on any fragment the XML parser rejects.
+ *
+ * @param content - The content to serialize
+ * @returns The element, ready to place in an entry
+ */
+export function buildContentElement(content) {
+    let attributes = { ...content.attributes };
+    if (content.type !== undefined)
+        attributes["type"] = content.type === "xhtml" ? "html" : content.type;
+    if (content.src !== undefined)
+        attributes["src"] = content.src;
+    return {
+        name: "content",
+        attributes,
+        children: content.src === undefined && content.value !== undefined ? [content.value] : [],
+    };
+}

package/dist/lib/extensions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Converts between XML elements and the package's extension element shape, so a
+ * foreign module the parser does not model survives a read and a write unchanged.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "@sdxc/xml";
+import type { Atom } from "../index.js";
+/**
+ * Converts one XML element into the package extension element shape.
+ *
+ * @param element - The XML element to convert
+ * @returns The package extension element
+ */
+export declare function toExtensionElement(element: XML.Element): Atom.Element;
+/**
+ * Converts one package extension element into the XML element shape.
+ *
+ * @param element - The extension element to convert
+ * @returns The XML element representation
+ */
+export declare function toXMLElement(element: Atom.Element): XML.Element;

package/dist/lib/extensions.js

@@ -0,0 +1,42 @@
+/**
+ * Converts between XML elements and the package's extension element shape, so a
+ * foreign module the parser does not model survives a read and a write unchanged.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { cloneAttributes } from "./clone.js";
+/**
+ * Converts one XML element into the package extension element shape.
+ *
+ * @param element - The XML element to convert
+ * @returns The package extension element
+ */
+export function toExtensionElement(element) {
+    let children = [];
+    for (let child of element.children ?? []) {
+        if (typeof child === "string") {
+            children.push(child);
+            continue;
+        }
+        children.push(toExtensionElement(child));
+    }
+    return { name: element.name, attributes: cloneAttributes(element.attributes), children };
+}
+/**
+ * Converts one package extension element into the XML element shape.
+ *
+ * @param element - The extension element to convert
+ * @returns The XML element representation
+ */
+export function toXMLElement(element) {
+    let children = [];
+    for (let child of element.children ?? []) {
+        if (typeof child === "string") {
+            children.push(child);
+            continue;
+        }
+        children.push(toXMLElement(child));
+    }
+    return { name: element.name, attributes: cloneAttributes(element.attributes) ?? {}, children };
+}

package/dist/lib/namespaces.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { XML } from "@sdxc/xml";
+/** The namespace declarations in scope, keyed by prefix with `""` for the default. */
+export type NamespaceScope = Record<string, string>;
+/**
+ * Reads every `xmlns` declaration off an element.
+ *
+ * @param element - The element whose declarations should be read
+ * @returns The declared namespaces, keyed by prefix
+ */
+export declare function readNamespaceDeclarations(element: XML.Element): NamespaceScope;
+/**
+ * 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 declare function extendNamespaceScope(scope: NamespaceScope, element: XML.Element): NamespaceScope;
+/**
+ * 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 declare function namespaceOf(name: string, scope: NamespaceScope): string | undefined;
+/**
+ * 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 declare function isAtomName(name: string, scope: NamespaceScope): boolean;