@sdxc/atom 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,245 @@
+# @sdxc/atom
+
+Atom 1.0 feed parser and builder.
+
+It reads [RFC 4287](https://www.rfc-editor.org/rfc/rfc4287) documents into an `Atom`
+instance and serializes that instance back into XML. It is a faithful reader rather than a
+helpful one: every link keeps its relation, dates stay the text the source held, and an entry
+that omits an author is reported as omitting one.
+
+That matters because Atom leaves several choices to the consumer. Which link is "the" link,
+whether an entry inherits its author from the feed, and how a date should be interpreted are
+decisions a reader makes differently from an archiver. Both get the same complete picture
+here, and pick from it.
+
+Elements outside the Atom namespace are preserved through `extensions`, so a document
+carrying a foreign module survives a read and a write unchanged.
+
+## Installation
+
+```bash
+npm add @sdxc/atom
+```
+
+The statics report failures as a `Result` from
+[`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), and `Atom.fromXML` takes a
+document from [`@sdxc/xml`](https://www.npmjs.com/package/@sdxc/xml). Both install alongside
+this package.
+
+## Usage
+
+### Parse A Feed
+
+```typescript
+import { Atom } from "@sdxc/atom";
+import { isFailure } from "@sdxc/result";
+
+let result = Atom.parse(xml);
+if (isFailure(result)) throw result.error;
+
+let atom = result.data;
+console.log(atom.feed.title);
+for (let entry of atom.entries) console.log(entry.id, entry.updated);
+```
+
+Pass the document's own URL as the second argument, and the references the feed leaves
+relative resolve against it:
+
+```typescript
+let result = Atom.parse(xml, "https://example.com/feed.xml");
+```
+
+### Fetch A Feed
+
+```typescript
+let result = await Atom.fetch(new URL("https://example.com/feed.xml"));
+```
+
+`Atom.fetch` places no constraint on the response's `Content-Type`, because feeds are
+routinely served as `text/xml`, `application/octet-stream`, and worse. Relative references
+resolve against the URL the response finally came from, so a redirected feed still yields
+absolute links.
+
+### Build A Feed
+
+```typescript
+import { Atom } from "@sdxc/atom";
+
+let atom = new Atom({
+	id: "tag:example.com,2026:feed",
+	title: "My Blog",
+	updated: new Date().toISOString(),
+	link: [
+		{ href: "https://example.com/", rel: "alternate", type: "text/html" },
+		{ href: "https://example.com/feed.xml", rel: "self", type: "application/atom+xml" },
+	],
+	author: { name: "Ada Lovelace" },
+});
+
+atom.addEntry({
+	id: "tag:example.com,2026:post-1",
+	title: "Hello World",
+	updated: "2026-04-14T10:30:00Z",
+	published: "2026-04-14T09:00:00Z",
+	summary: "A short summary",
+	content: { type: "html", value: "<p>Full post content</p>" },
+	link: { href: "https://example.com/posts/hello", rel: "alternate" },
+});
+
+let xml = atom.toString();
+```
+
+## API
+
+### `new Atom(feed: Atom.Feed)`
+
+Creates a feed from its metadata, with no entries. RFC 4287 §4.1.1 requires `id`, `title`,
+and `updated`, and an `AtomParseError` is thrown when one is missing.
+
+### `atom.feed`
+
+The feed-level metadata, as a clone. Assigning a new `Atom.Feed` replaces it and leaves the
+entries in place.
+
+### `atom.entries`
+
+The entries, as clones, in the order they were added.
+
+### `atom.addEntry(entry: Atom.Entry)`
+
+Appends one entry. Each entry requires `id`, `title`, and `updated`, on the same terms as the
+feed.
+
+### `atom.removeEntry(id: string)`
+
+Removes the entry carrying an id. RFC 4287 makes entry ids unique within a feed, so at most
+one entry matches.
+
+### `atom.toJSON()`
+
+Returns `{ feed, entries }` as plain serializable data.
+
+### `atom.toString()`
+
+Serializes the feed to Atom 1.0 XML.
+
+### `Atom.parse(source: string, base?: string): Result<Atom, AtomParseError>`
+
+Parses XML text, resolving relative references against `base`.
+
+### `Atom.fromXML(xml: XML, base?: string): Result<Atom, AtomParseError>`
+
+Reads a feed out of an already-parsed document, for a caller that parsed the text for some
+other purpose first.
+
+### `Atom.fetch(input, init?): Promise<Result<Atom, AtomFetchError | AtomParseError>>`
+
+Retrieves a document and parses it, so a failed request, an error status, and an unparseable
+body are all values rather than exceptions.
+
+### Errors
+
+`AtomParseError` reports a document that is not a feed, or metadata missing a required
+field. `AtomFetchError` reports a request that failed or answered with an error status.
+`AtomStringifyError` reports a feed that cannot be written as XML.
+
+## Reading The Data
+
+### Text Constructs
+
+`title`, `subtitle`, `summary`, and `rights` carry a `type` of `text`, `html`, or `xhtml`. A
+construct with no type collapses to a plain string; the other two arrive as
+`{ value, type }`:
+
+```typescript
+atom.feed.title; // "My Blog"
+entry.summary; // { value: "<em>Recap</em>", type: "html" }
+```
+
+An `xhtml` construct is serialized back into a markup string while parsing, and the `<div>`
+wrapper RFC 4287 requires is dropped, so reading a title never means walking a second tree.
+
+### Links
+
+Every `<link>` is kept with its attributes. RFC 4287 defaults an absent `rel` to
+`alternate`, and that default is left absent rather than filled in, because applying it is a
+reader's concern:
+
+```typescript
+let links = Array.isArray(entry.link) ? entry.link : entry.link ? [entry.link] : [];
+let page = links.find((link) => (link.rel ?? "alternate") === "alternate");
+```
+
+### Dates
+
+`updated` and `published` are the raw RFC 3339 strings the document held, so a malformed date
+is visible to you rather than becoming an `Invalid Date` inside the parser. Convert at the
+point of use:
+
+```typescript
+let publishedAt = new Date(entry.published ?? entry.updated);
+```
+
+### Authors
+
+RFC 4287 §4.1.2 lets an entry omit its author when the feed supplies one, or when `<source>`
+does. All three positions are recorded and no fallback is applied, so a consumer picks the
+precedence it wants:
+
+```typescript
+let author = entry.author ?? entry.source?.author ?? atom.feed.author;
+```
+
+### Relative References
+
+`xml:base` is inherited, and a relative base composes with the one enclosing it. Every
+`href`, `uri`, `src`, `icon`, and `logo` resolves against the base in scope while parsing. A
+reference with no base in scope, or one that cannot form a URL with it, is left as the
+document wrote it.
+
+### Namespaces
+
+The Atom namespace identifies the format; the prefix a document binds it to does not.
+`<feed xmlns="…">` and `<a:feed xmlns:a="…">` both parse, and an element counts as Atom only
+when its prefix resolves to `http://www.w3.org/2005/Atom`. Anything else is preserved:
+
+```typescript
+atom.feed.extensions;
+// [{ name: "media:rating", attributes: { scheme: "urn:simple" }, children: ["adult"] }]
+```
+
+## Notes
+
+1. An `xhtml` text construct re-serializes as `type="html"`. Its value is a markup string by
+   then, and re-parsing it to rebuild a wrapper would fail on any fragment the XML parser
+   rejects, so the payload is kept and the typing narrows.
+2. Text is never sanitized. An `html` or `xhtml` construct holds whatever the publisher
+   wrote, and escaping it is the responsibility of whatever renders it.
+3. `length` on a link parses like the rest of the package's numbers: a non-numeric value
+   reads as `NaN` rather than failing the document.
+
+## 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/atom": "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,231 @@
+/**
+ * Atom 1.0 feed parser and builder. Reads a document into the `Atom` class and
+ * serializes it back, keeping every link, text construct and foreign element the
+ * source carried so a consumer decides what matters rather than the parser.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+/** Raised when a document is not a usable Atom feed. */
+export declare class AtomParseError extends Error {
+    name: string;
+}
+/** Raised when a feed cannot be retrieved or does not arrive as XML. */
+export declare class AtomFetchError extends Error {
+    name: string;
+}
+/** Raised when in-memory feed data cannot be serialized to XML. */
+export declare class AtomStringifyError extends Error {
+    name: string;
+}
+export declare namespace Atom {
+    /** A foreign element, preserved verbatim so unknown modules round-trip. */
+    interface Element {
+        name: string;
+        attributes?: Record<string, string>;
+        children?: Node[];
+    }
+    /** A child of a foreign element: either text or another element. */
+    type Node = string | Element;
+    /** How a text construct's payload should be read (RFC 4287 §3.1). */
+    type TextType = "text" | "html" | "xhtml";
+    /**
+     * A human-readable text construct. `value` is always a string: an `xhtml`
+     * construct arrives as the serialized markup its wrapper contained, so a
+     * consumer never walks a second tree to read a title.
+     */
+    interface Text {
+        value: string;
+        type?: TextType;
+    }
+    /** A text construct, or the bare string form when it carries no type. */
+    type TextInput = string | Text;
+    /** A person construct: an author or a contributor (RFC 4287 §3.2). */
+    interface Person {
+        name: string;
+        uri?: string;
+        email?: string;
+        extensions?: Element[];
+    }
+    /** One person, or several. */
+    type PersonInput = Person | Person[];
+    /**
+     * A reference away from the feed or entry. `rel` is left as the document
+     * spelled it, absent included, because the default is a reader's concern.
+     */
+    interface Link {
+        href: string;
+        rel?: string;
+        type?: string;
+        hreflang?: string;
+        title?: string;
+        length?: number;
+        attributes?: Record<string, string>;
+        extensions?: Element[];
+    }
+    /** One link, or several. */
+    type LinkInput = Link | Link[];
+    /** A category, with the scheme that gives its term meaning. */
+    interface Category {
+        term: string;
+        scheme?: string;
+        label?: string;
+        attributes?: Record<string, string>;
+        extensions?: Element[];
+    }
+    /** A category, or the bare term when it carries nothing else. */
+    type CategoryInput = string | Category;
+    /** The agent that produced the feed. */
+    interface Generator {
+        value: string;
+        uri?: string;
+        version?: string;
+    }
+    /**
+     * An entry's body. A superset of a text construct: `type` may be any media
+     * type, and `src` points at content held out of line, in which case the
+     * element itself is empty and `value` is absent.
+     */
+    interface Content {
+        type?: string;
+        src?: string;
+        value?: string;
+        attributes?: Record<string, string>;
+    }
+    /** Metadata of the feed an entry was copied from (RFC 4287 §4.2.11). */
+    interface Source {
+        id?: string;
+        title?: TextInput;
+        updated?: string;
+        subtitle?: TextInput;
+        author?: PersonInput;
+        link?: LinkInput;
+        rights?: TextInput;
+        attributes?: Record<string, string>;
+        extensions?: Element[];
+    }
+    /** Feed-level metadata. `updated` stays the raw RFC 3339 text the source held. */
+    interface Feed {
+        id: string;
+        title: TextInput;
+        updated: string;
+        subtitle?: TextInput;
+        rights?: TextInput;
+        author?: PersonInput;
+        contributor?: PersonInput;
+        link?: LinkInput;
+        category?: CategoryInput | CategoryInput[];
+        generator?: Generator;
+        icon?: string;
+        logo?: string;
+        /** `xml:lang` on the feed element, inherited by everything inside it. */
+        lang?: string;
+        /** `xml:base` on the feed element, against which its references resolved. */
+        base?: string;
+        namespaces?: Record<string, string>;
+        attributes?: Record<string, string>;
+        extensions?: Element[];
+    }
+    /** One entry. `updated` is required by RFC 4287 §4.1.2; `published` is not. */
+    interface Entry {
+        id: string;
+        title: TextInput;
+        updated: string;
+        published?: string;
+        summary?: TextInput;
+        content?: Content;
+        author?: PersonInput;
+        contributor?: PersonInput;
+        link?: LinkInput;
+        category?: CategoryInput | CategoryInput[];
+        rights?: TextInput;
+        source?: Source;
+        lang?: string;
+        base?: string;
+        attributes?: Record<string, string>;
+        extensions?: Element[];
+    }
+    /** A whole document: the feed's metadata and its entries. */
+    interface Document {
+        feed: Feed;
+        entries: Entry[];
+    }
+}
+/**
+ * An Atom 1.0 feed, holding feed-level metadata and an ordered list of entries.
+ *
+ * Reading accessors hand back clones, so a caller cannot reach into the instance
+ * by mutating what it returned.
+ */
+export declare class Atom {
+    #private;
+    /**
+     * Builds a feed from its metadata, starting with no entries.
+     *
+     * @param feed - The feed-level metadata
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    constructor(feed: Atom.Feed);
+    /** The feed-level metadata. */
+    get feed(): Atom.Feed;
+    /**
+     * Replaces the feed-level metadata, leaving the entries in place.
+     *
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    set feed(feed: Atom.Feed);
+    /** The entries, in the order they were added. */
+    get entries(): Atom.Entry[];
+    /**
+     * Appends one entry.
+     *
+     * @param entry - The entry to append
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    addEntry(entry: Atom.Entry): void;
+    /**
+     * Removes the first entry carrying an id, which RFC 4287 makes unique within
+     * a feed, so at most one entry can match.
+     *
+     * @param id - The entry id to remove
+     */
+    removeEntry(id: string): void;
+    /** The feed and its entries as plain, serializable data. */
+    toJSON(): Atom.Document;
+    /**
+     * Serializes the feed into Atom 1.0 XML.
+     *
+     * @throws AtomStringifyError When the data cannot form a valid document
+     */
+    toString(): string;
+    /**
+     * Reads a feed out of an already-parsed XML document, which is the entry
+     * point for a caller that parsed the text for some other purpose first.
+     *
+     * @param xml - The parsed XML document
+     * @param base - Document URI, used to resolve references the feed leaves relative
+     * @returns The feed, or the reason the document is not one
+     */
+    static fromXML(xml: XML, base?: string): Result<Atom, AtomParseError>;
+    /**
+     * Parses Atom XML text.
+     *
+     * @param source - The raw XML text
+     * @param base - Document URI, used to resolve references the feed leaves relative
+     * @returns The feed, or the reason the text is not one
+     */
+    static parse(source: string, base?: string): Result<Atom, AtomParseError>;
+    /**
+     * Retrieves a feed and parses it.
+     *
+     * References the feed leaves relative resolve against the URL the response
+     * finally came from, so a redirected feed still yields absolute links.
+     *
+     * @param input - The URL or request to retrieve
+     * @param init - Additional request options
+     * @returns The feed, or the reason it could not be read
+     */
+    static fetch(input: URL | RequestInfo, init?: RequestInit): Promise<Result<Atom, AtomFetchError | AtomParseError>>;
+}

package/dist/index.js

@@ -0,0 +1,162 @@
+/**
+ * Atom 1.0 feed parser and builder. Reads a document into the `Atom` class and
+ * serializes it back, keeping every link, text construct and foreign element the
+ * source carried so a consumer decides what matters rather than the parser.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { XML } from "@sdxc/xml";
+import { buildDocument } from "./lib/build-document.js";
+import { cloneEntry, cloneFeed } from "./lib/clone.js";
+import { parseDocument } from "./lib/parse-feed.js";
+import { validateEntry } from "./lib/validate-entry.js";
+import { validateFeed } from "./lib/validate-feed.js";
+/** Raised when a document is not a usable Atom feed. */
+export class AtomParseError extends Error {
+    name = "AtomParseError";
+}
+/** Raised when a feed cannot be retrieved or does not arrive as XML. */
+export class AtomFetchError extends Error {
+    name = "AtomFetchError";
+}
+/** Raised when in-memory feed data cannot be serialized to XML. */
+export class AtomStringifyError extends Error {
+    name = "AtomStringifyError";
+}
+/**
+ * An Atom 1.0 feed, holding feed-level metadata and an ordered list of entries.
+ *
+ * Reading accessors hand back clones, so a caller cannot reach into the instance
+ * by mutating what it returned.
+ */
+export class Atom {
+    #feed;
+    #entries = [];
+    /**
+     * Builds a feed from its metadata, starting with no entries.
+     *
+     * @param feed - The feed-level metadata
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    constructor(feed) {
+        validateFeed(feed);
+        this.#feed = cloneFeed(feed);
+    }
+    /** The feed-level metadata. */
+    get feed() {
+        return cloneFeed(this.#feed);
+    }
+    /**
+     * Replaces the feed-level metadata, leaving the entries in place.
+     *
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    set feed(feed) {
+        validateFeed(feed);
+        this.#feed = cloneFeed(feed);
+    }
+    /** The entries, in the order they were added. */
+    get entries() {
+        return this.#entries.map(cloneEntry);
+    }
+    /**
+     * Appends one entry.
+     *
+     * @param entry - The entry to append
+     * @throws AtomParseError When `id`, `title` or `updated` is missing
+     */
+    addEntry(entry) {
+        validateEntry(entry);
+        this.#entries.push(cloneEntry(entry));
+    }
+    /**
+     * Removes the first entry carrying an id, which RFC 4287 makes unique within
+     * a feed, so at most one entry can match.
+     *
+     * @param id - The entry id to remove
+     */
+    removeEntry(id) {
+        let index = this.#entries.findIndex((entry) => entry.id === id);
+        if (index === -1)
+            return;
+        this.#entries.splice(index, 1);
+    }
+    /** The feed and its entries as plain, serializable data. */
+    toJSON() {
+        return { feed: cloneFeed(this.#feed), entries: this.#entries.map(cloneEntry) };
+    }
+    /**
+     * Serializes the feed into Atom 1.0 XML.
+     *
+     * @throws AtomStringifyError When the data cannot form a valid document
+     */
+    toString() {
+        let result = XML.stringify(new XML(buildDocument(this.#feed, this.#entries)));
+        if (isFailure(result))
+            throw new AtomStringifyError(result.error.message);
+        return result.data;
+    }
+    /**
+     * Reads a feed out of an already-parsed XML document, which is the entry
+     * point for a caller that parsed the text for some other purpose first.
+     *
+     * @param xml - The parsed XML document
+     * @param base - Document URI, used to resolve references the feed leaves relative
+     * @returns The feed, or the reason the document is not one
+     */
+    static fromXML(xml, base) {
+        let document = parseDocument(xml, base);
+        if (isFailure(document))
+            return document;
+        let atom = new Atom(document.data.feed);
+        for (let entry of document.data.entries)
+            atom.addEntry(entry);
+        return success(atom);
+    }
+    /**
+     * Parses Atom XML text.
+     *
+     * @param source - The raw XML text
+     * @param base - Document URI, used to resolve references the feed leaves relative
+     * @returns The feed, or the reason the text is not one
+     */
+    static parse(source, base) {
+        let parsed = XML.parse(source);
+        if (isFailure(parsed))
+            return failure(new AtomParseError(parsed.error.message));
+        return Atom.fromXML(parsed.data, base);
+    }
+    /**
+     * Retrieves a feed and parses it.
+     *
+     * References the feed leaves relative resolve against the URL the response
+     * finally came from, so a redirected feed still yields absolute links.
+     *
+     * @param input - The URL or request to retrieve
+     * @param init - Additional request options
+     * @returns The feed, or the reason it could not be read
+     */
+    static async fetch(input, init) {
+        let response;
+        try {
+            response = await fetch(input, init);
+        }
+        catch (error) {
+            return failure(new AtomFetchError(`Failed to fetch Atom feed: ${message(error)}`));
+        }
+        if (!response.ok) {
+            return failure(new AtomFetchError(`Failed to fetch Atom feed: ${response.status}`));
+        }
+        let text = await response.text();
+        return Atom.parse(text, response.url || undefined);
+    }
+}
+/**
+ * Reads a thrown value's message, so a rejected request reports what went wrong
+ * whether or not it rejected with an `Error`.
+ */
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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 type { XML } from "@sdxc/xml";
+import type { Atom } from "../index.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 declare function buildDocument(feed: Atom.Feed, entries: Atom.Entry[]): XML.Document;