@sdxc/atom 0.0.0-pre.1

package/dist/lib/utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared helpers for reading XML elements, splitting qualified names, and
+ * normalizing the package's scalar-or-array data shapes.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "@sdxc/xml";
+/**
+ * Returns the direct child elements of an XML element.
+ *
+ * @param element - The element whose child elements should be returned
+ * @returns The direct child elements in source order
+ */
+export declare function getChildElements(element: XML.Element): XML.Element[];
+/**
+ * Reads the concatenated text content of one XML element.
+ *
+ * @param element - The element whose text content should be collected
+ * @returns The concatenated text content
+ */
+export declare function getElementText(element: XML.Element): string;
+/**
+ * Splits the prefix off a qualified name.
+ *
+ * @param name - The qualified element or attribute name
+ * @returns The prefix, or an empty string for an unprefixed name
+ */
+export declare function prefixOf(name: string): string;
+/**
+ * Strips the prefix from a qualified name, which is how this package compares
+ * element names: the XML layer resolves no namespaces, so the prefix a document
+ * binds Atom to carries no meaning on its own.
+ *
+ * @param name - The qualified element or attribute name
+ * @returns The name without its prefix
+ */
+export declare function localName(name: string): string;
+/**
+ * Parses one optional numeric text value.
+ *
+ * @param value - The raw string to parse
+ * @returns The parsed number or `NaN`
+ */
+export declare function parseOptionalNumber(value: string): number;
+/**
+ * Collapses one-item arrays back to the package's scalar-friendly API shape.
+ *
+ * @param values - The values to collapse
+ * @returns One value or the full array
+ */
+export declare function collapseArray<T>(values: T[]): T | T[];
+/**
+ * Normalizes undefined, scalar, and array values into a flat array.
+ *
+ * @param value - The value to normalize
+ * @returns A flat array representation
+ */
+export declare function normalizeArray<T>(value?: T | T[]): T[];

package/dist/lib/utils.js

@@ -0,0 +1,99 @@
+/**
+ * Shared helpers for reading XML elements, splitting qualified names, and
+ * normalizing the package's scalar-or-array data shapes.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Returns the direct child elements of an XML element.
+ *
+ * @param element - The element whose child elements should be returned
+ * @returns The direct child elements in source order
+ */
+export function getChildElements(element) {
+    let children = [];
+    for (let child of element.children ?? []) {
+        if (typeof child === "string")
+            continue;
+        children.push(child);
+    }
+    return children;
+}
+/**
+ * Reads the concatenated text content of one XML element.
+ *
+ * @param element - The element whose text content should be collected
+ * @returns The concatenated text content
+ */
+export function getElementText(element) {
+    let content = "";
+    for (let child of element.children ?? []) {
+        if (typeof child !== "string")
+            continue;
+        content += child;
+    }
+    return content;
+}
+/**
+ * Splits the prefix off a qualified name.
+ *
+ * @param name - The qualified element or attribute name
+ * @returns The prefix, or an empty string for an unprefixed name
+ */
+export function prefixOf(name) {
+    let separator = name.indexOf(":");
+    if (separator === -1)
+        return "";
+    return name.slice(0, separator);
+}
+/**
+ * Strips the prefix from a qualified name, which is how this package compares
+ * element names: the XML layer resolves no namespaces, so the prefix a document
+ * binds Atom to carries no meaning on its own.
+ *
+ * @param name - The qualified element or attribute name
+ * @returns The name without its prefix
+ */
+export function localName(name) {
+    let separator = name.indexOf(":");
+    if (separator === -1)
+        return name;
+    return name.slice(separator + 1);
+}
+/**
+ * Parses one optional numeric text value.
+ *
+ * @param value - The raw string to parse
+ * @returns The parsed number or `NaN`
+ */
+export function parseOptionalNumber(value) {
+    let number = Number(value);
+    if (Number.isFinite(number))
+        return number;
+    return Number.NaN;
+}
+/**
+ * Collapses one-item arrays back to the package's scalar-friendly API shape.
+ *
+ * @param values - The values to collapse
+ * @returns One value or the full array
+ */
+export function collapseArray(values) {
+    if (values.length === 1)
+        return values[0];
+    return values;
+}
+/**
+ * Normalizes undefined, scalar, and array values into a flat array.
+ *
+ * @param value - The value to normalize
+ * @returns A flat array representation
+ */
+export function normalizeArray(value) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}

package/dist/lib/validate-entry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Guards the three elements RFC 4287 §4.1.2 requires of every entry, so an
+ * instance can never hold data that would serialize into an invalid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Atom } from "../index.js";
+/**
+ * Reads the string behind either text construct form, so a caller testing for
+ * presence does not branch on which form the value took.
+ *
+ * @param text - The construct to read
+ * @returns The text, or an empty string when there is none
+ */
+export declare function readTextValue(text?: Atom.TextInput): string;
+/**
+ * Checks that an entry carries an id, a title and an updated timestamp.
+ *
+ * @param entry - The entry to check
+ * @throws AtomParseError Naming the first required element that is missing
+ */
+export declare function validateEntry(entry: Atom.Entry): void;

package/dist/lib/validate-entry.js

@@ -0,0 +1,34 @@
+/**
+ * Guards the three elements RFC 4287 §4.1.2 requires of every entry, so an
+ * instance can never hold data that would serialize into an invalid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { AtomParseError } from "../index.js";
+/**
+ * Reads the string behind either text construct form, so a caller testing for
+ * presence does not branch on which form the value took.
+ *
+ * @param text - The construct to read
+ * @returns The text, or an empty string when there is none
+ */
+export function readTextValue(text) {
+    if (text === undefined)
+        return "";
+    return typeof text === "string" ? text : text.value;
+}
+/**
+ * Checks that an entry carries an id, a title and an updated timestamp.
+ *
+ * @param entry - The entry to check
+ * @throws AtomParseError Naming the first required element that is missing
+ */
+export function validateEntry(entry) {
+    if (!entry.id)
+        throw new AtomParseError("Entry must include an id.");
+    if (!readTextValue(entry.title))
+        throw new AtomParseError("Entry must include a title.");
+    if (!entry.updated)
+        throw new AtomParseError("Entry must include an updated timestamp.");
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Guards the three elements RFC 4287 §4.1.1 requires of every feed, so an
+ * instance can never hold data that would serialize into an invalid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Atom } from "../index.js";
+/**
+ * Checks that a feed carries an id, a title and an updated timestamp.
+ *
+ * @param feed - The feed to check
+ * @throws AtomParseError Naming the first required element that is missing
+ */
+export declare function validateFeed(feed: Atom.Feed): void;

package/dist/lib/validate-feed.js

@@ -0,0 +1,23 @@
+/**
+ * Guards the three elements RFC 4287 §4.1.1 requires of every feed, so an
+ * instance can never hold data that would serialize into an invalid document.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { AtomParseError } from "../index.js";
+import { readTextValue } from "./validate-entry.js";
+/**
+ * Checks that a feed carries an id, a title and an updated timestamp.
+ *
+ * @param feed - The feed to check
+ * @throws AtomParseError Naming the first required element that is missing
+ */
+export function validateFeed(feed) {
+    if (!feed.id)
+        throw new AtomParseError("Feed must include an id.");
+    if (!readTextValue(feed.title))
+        throw new AtomParseError("Feed must include a title.");
+    if (!feed.updated)
+        throw new AtomParseError("Feed must include an updated timestamp.");
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Tracks the `xml:base` and `xml:lang` in effect at a point in the tree, so a
+ * relative reference resolves against the bases that enclose it. RFC 4287 §4.1.1
+ * makes both inherited, and makes a relative base compose with the one above it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { XML } from "@sdxc/xml";
+/** The base URI and language inherited at one point in the document. */
+export interface Scope {
+    base?: string;
+    lang?: string;
+}
+/**
+ * Layers an element's own `xml:base` and `xml:lang` over the inherited scope. A
+ * relative `xml:base` is resolved against the enclosing one, so nested bases
+ * accumulate rather than replace.
+ *
+ * @param scope - The scope inherited from ancestors
+ * @param element - The element whose attributes should be layered on top
+ * @returns The scope in effect inside the element
+ */
+export declare function extendScope(scope: Scope, element: XML.Element): Scope;
+/**
+ * Resolves a reference against the base in scope.
+ *
+ * The reference is returned unchanged when no base applies or when the pair does
+ * not form a URL, because a feed's own text is more useful to a consumer than a
+ * value this package invented or dropped.
+ *
+ * @param scope - The scope supplying the base URI
+ * @param reference - The possibly-relative reference to resolve
+ * @returns The absolute reference, or the original when it cannot be resolved
+ */
+export declare function resolveUri(scope: Scope, reference: string): string;

package/dist/lib/xml-base.js

@@ -0,0 +1,49 @@
+/**
+ * Tracks the `xml:base` and `xml:lang` in effect at a point in the tree, so a
+ * relative reference resolves against the bases that enclose it. RFC 4287 §4.1.1
+ * makes both inherited, and makes a relative base compose with the one above it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Layers an element's own `xml:base` and `xml:lang` over the inherited scope. A
+ * relative `xml:base` is resolved against the enclosing one, so nested bases
+ * accumulate rather than replace.
+ *
+ * @param scope - The scope inherited from ancestors
+ * @param element - The element whose attributes should be layered on top
+ * @returns The scope in effect inside the element
+ */
+export function extendScope(scope, element) {
+    let attributes = element.attributes ?? {};
+    let base = attributes["xml:base"];
+    let lang = attributes["xml:lang"];
+    if (base === undefined && lang === undefined)
+        return scope;
+    return {
+        base: base === undefined ? scope.base : resolveUri(scope, base),
+        lang: lang ?? scope.lang,
+    };
+}
+/**
+ * Resolves a reference against the base in scope.
+ *
+ * The reference is returned unchanged when no base applies or when the pair does
+ * not form a URL, because a feed's own text is more useful to a consumer than a
+ * value this package invented or dropped.
+ *
+ * @param scope - The scope supplying the base URI
+ * @param reference - The possibly-relative reference to resolve
+ * @returns The absolute reference, or the original when it cannot be resolved
+ */
+export function resolveUri(scope, reference) {
+    if (!scope.base)
+        return reference;
+    try {
+        return new URL(reference, scope.base).toString();
+    }
+    catch {
+        return reference;
+    }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@sdxc/atom",
+	"version": "0.0.0-pre.1",
+	"description": "Atom 1.0 feed parser and builder",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.9.5",
+		"@sdxc/xml": "0.0.0-pre.1"
+	},
+	"gitHead": "6b352367c6853be4019c3a3ab761185df8ab5ab8",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/atom"
+	}
+}