@sdxc/xml 0.0.0-pre.1

package/dist/lib/decode-entities.js

@@ -0,0 +1,90 @@
+/**
+ * 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 { failure, success } from "@sdxc/result";
+import { HTML_ENTITIES } from "./html-entities.js";
+/**
+ * Matches a complete reference: an ampersand, a run of reference characters and
+ * a semicolon. Prose containing a loose ampersand therefore reads as text.
+ */
+const REFERENCE_PATTERN = /&([^;&<\s]*);/g;
+const DECIMAL_PATTERN = /^#([0-9]+)$/;
+const HEXADECIMAL_PATTERN = /^#[xX]([0-9a-fA-F]+)$/;
+const MAXIMUM_CODE_POINT = 0x10_ff_ff;
+const FIRST_SURROGATE = 0xd8_00;
+const LAST_SURROGATE = 0xdf_ff;
+/**
+ * The five entities XML predefines, and so the complete set available to a
+ * document that declares its own entities through a DTD.
+ */
+const PREDEFINED_ENTITIES = {
+    lt: "<",
+    gt: ">",
+    amp: "&",
+    quot: '"',
+    apos: "'",
+};
+/**
+ * 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 function decodeEntities(value) {
+    if (!value.includes("&"))
+        return success(value);
+    let output = "";
+    let cursor = 0;
+    REFERENCE_PATTERN.lastIndex = 0;
+    let match = REFERENCE_PATTERN.exec(value);
+    while (match) {
+        let resolved = resolveReference(match[1] ?? "");
+        if (resolved.status === "failure")
+            return resolved;
+        output += value.slice(cursor, match.index) + resolved.data;
+        cursor = match.index + match[0].length;
+        match = REFERENCE_PATTERN.exec(value);
+    }
+    return success(output + value.slice(cursor));
+}
+/**
+ * Resolves the text between `&` and `;` into the character it stands for.
+ *
+ * The XHTML sets are consulted after the predefines and after numeric references, so
+ * a document declaring none of them still decodes the prose feeds are written in.
+ */
+function resolveReference(reference) {
+    let predefined = PREDEFINED_ENTITIES[reference];
+    if (predefined)
+        return success(predefined);
+    let decimal = reference.match(DECIMAL_PATTERN);
+    if (decimal?.[1])
+        return resolveCodePoint(reference, Number.parseInt(decimal[1], 10));
+    let hexadecimal = reference.match(HEXADECIMAL_PATTERN);
+    if (hexadecimal?.[1])
+        return resolveCodePoint(reference, Number.parseInt(hexadecimal[1], 16));
+    if (reference.startsWith("#")) {
+        return failure(new Error(`entity not matching Reference production: &${reference};`));
+    }
+    let named = HTML_ENTITIES[reference];
+    if (named)
+        return success(named);
+    return failure(new Error(`entity not found:&${reference};`));
+}
+/**
+ * Turns a numeric reference into its character, refusing the values that cannot
+ * stand alone in a string: unpaired surrogates and anything past the last plane.
+ */
+function resolveCodePoint(reference, codePoint) {
+    let outOfRange = codePoint === 0 || codePoint > MAXIMUM_CODE_POINT;
+    let surrogate = codePoint >= FIRST_SURROGATE && codePoint <= LAST_SURROGATE;
+    if (outOfRange || surrogate) {
+        return failure(new Error(`entity not matching Reference production: &${reference};`));
+    }
+    return success(String.fromCodePoint(codePoint));
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Escapes the characters that carry meaning as markup when XML text and
+ * attribute values are serialized, so the output re-parses into the tree it came
+ * from.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Escapes a text node. `>` is escaped alongside `<` and `&` so that a literal
+ * `]]>` in the content reaches the reader as text.
+ *
+ * @param value - The text node content
+ * @returns The escaped text
+ */
+export declare function escapeText(value: string): string;
+/**
+ * Escapes an attribute value. Tabs and line breaks become numeric references so
+ * they survive the round trip intact, since a parser reads the literal
+ * characters as spaces.
+ *
+ * @param value - The attribute value
+ * @returns The escaped value, safe to place between double quotes
+ */
+export declare function escapeAttribute(value: string): string;

package/dist/lib/escape-xml.js

@@ -0,0 +1,44 @@
+/**
+ * Escapes the characters that carry meaning as markup when XML text and
+ * attribute values are serialized, so the output re-parses into the tree it came
+ * from.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+const TEXT_PATTERN = /[<>&]/g;
+const ATTRIBUTE_PATTERN = /[<>&"\t\n\r]/g;
+const NAMED_REPLACEMENTS = {
+    "<": "&lt;",
+    ">": "&gt;",
+    "&": "&amp;",
+    '"': "&quot;",
+};
+/**
+ * Escapes a text node. `>` is escaped alongside `<` and `&` so that a literal
+ * `]]>` in the content reaches the reader as text.
+ *
+ * @param value - The text node content
+ * @returns The escaped text
+ */
+export function escapeText(value) {
+    return value.replace(TEXT_PATTERN, replaceCharacter);
+}
+/**
+ * Escapes an attribute value. Tabs and line breaks become numeric references so
+ * they survive the round trip intact, since a parser reads the literal
+ * characters as spaces.
+ *
+ * @param value - The attribute value
+ * @returns The escaped value, safe to place between double quotes
+ */
+export function escapeAttribute(value) {
+    return value.replace(ATTRIBUTE_PATTERN, replaceCharacter);
+}
+/**
+ * Maps one character to its entity, falling back to a decimal numeric reference
+ * for the whitespace that attribute values escape.
+ */
+function replaceCharacter(character) {
+    return NAMED_REPLACEMENTS[character] ?? `&#${character.charCodeAt(0)};`;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The named character entities the three XHTML 1.0 entity sets declare, so text
+ * carrying ` ` or `—` decodes instead of failing the document. Feeds
+ * are authored by publishing tools that emit these without declaring a DTD.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Every entity from `xhtml-lat1`, `xhtml-special` and `xhtml-symbol`, mapped to the
+ * character it stands for. Values are written as escapes throughout because a third
+ * of the set is whitespace or zero-width and would otherwise be invisible in review.
+ *
+ * The five XML predefines its own parser resolves are absent here on purpose: they
+ * are the document's regardless of any DTD, so they resolve before this table is read.
+ */
+export declare const HTML_ENTITIES: Record<string, string>;

package/dist/lib/html-entities.js

@@ -0,0 +1,269 @@
+/**
+ * The named character entities the three XHTML 1.0 entity sets declare, so text
+ * carrying ` ` or `—` decodes instead of failing the document. Feeds
+ * are authored by publishing tools that emit these without declaring a DTD.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Every entity from `xhtml-lat1`, `xhtml-special` and `xhtml-symbol`, mapped to the
+ * character it stands for. Values are written as escapes throughout because a third
+ * of the set is whitespace or zero-width and would otherwise be invisible in review.
+ *
+ * The five XML predefines its own parser resolves are absent here on purpose: they
+ * are the document's regardless of any DTD, so they resolve before this table is read.
+ */
+export const HTML_ENTITIES = {
+    /** xhtml-lat1: the Latin-1 supplement, U+00A0 through U+00FF. */
+    nbsp: " ",
+    iexcl: "¡",
+    cent: "¢",
+    pound: "£",
+    curren: "¤",
+    yen: "¥",
+    brvbar: "¦",
+    sect: "§",
+    uml: "¨",
+    copy: "©",
+    ordf: "ª",
+    laquo: "«",
+    not: "¬",
+    shy: "­",
+    reg: "®",
+    macr: "¯",
+    deg: "°",
+    plusmn: "±",
+    sup2: "²",
+    sup3: "³",
+    acute: "´",
+    micro: "µ",
+    para: "¶",
+    middot: "·",
+    cedil: "¸",
+    sup1: "¹",
+    ordm: "º",
+    raquo: "»",
+    frac14: "¼",
+    frac12: "½",
+    frac34: "¾",
+    iquest: "¿",
+    Agrave: "À",
+    Aacute: "Á",
+    Acirc: "Â",
+    Atilde: "Ã",
+    Auml: "Ä",
+    Aring: "Å",
+    AElig: "Æ",
+    Ccedil: "Ç",
+    Egrave: "È",
+    Eacute: "É",
+    Ecirc: "Ê",
+    Euml: "Ë",
+    Igrave: "Ì",
+    Iacute: "Í",
+    Icirc: "Î",
+    Iuml: "Ï",
+    ETH: "Ð",
+    Ntilde: "Ñ",
+    Ograve: "Ò",
+    Oacute: "Ó",
+    Ocirc: "Ô",
+    Otilde: "Õ",
+    Ouml: "Ö",
+    times: "×",
+    Oslash: "Ø",
+    Ugrave: "Ù",
+    Uacute: "Ú",
+    Ucirc: "Û",
+    Uuml: "Ü",
+    Yacute: "Ý",
+    THORN: "Þ",
+    szlig: "ß",
+    agrave: "à",
+    aacute: "á",
+    acirc: "â",
+    atilde: "ã",
+    auml: "ä",
+    aring: "å",
+    aelig: "æ",
+    ccedil: "ç",
+    egrave: "è",
+    eacute: "é",
+    ecirc: "ê",
+    euml: "ë",
+    igrave: "ì",
+    iacute: "í",
+    icirc: "î",
+    iuml: "ï",
+    eth: "ð",
+    ntilde: "ñ",
+    ograve: "ò",
+    oacute: "ó",
+    ocirc: "ô",
+    otilde: "õ",
+    ouml: "ö",
+    divide: "÷",
+    oslash: "ø",
+    ugrave: "ù",
+    uacute: "ú",
+    ucirc: "û",
+    uuml: "ü",
+    yacute: "ý",
+    thorn: "þ",
+    yuml: "ÿ",
+    /** xhtml-special: Latin Extended-A, spacing modifiers, punctuation and the euro. */
+    OElig: "Œ",
+    oelig: "œ",
+    Scaron: "Š",
+    scaron: "š",
+    Yuml: "Ÿ",
+    circ: "ˆ",
+    tilde: "˜",
+    ensp: " ",
+    emsp: " ",
+    thinsp: " ",
+    zwnj: "‌",
+    zwj: "‍",
+    lrm: "‎",
+    rlm: "‏",
+    ndash: "–",
+    mdash: "—",
+    lsquo: "‘",
+    rsquo: "’",
+    sbquo: "‚",
+    ldquo: "“",
+    rdquo: "”",
+    bdquo: "„",
+    dagger: "†",
+    Dagger: "‡",
+    permil: "‰",
+    lsaquo: "‹",
+    rsaquo: "›",
+    euro: "€",
+    /** xhtml-symbol: Greek, general punctuation, arrows and mathematical operators. */
+    fnof: "ƒ",
+    Alpha: "Α",
+    Beta: "Β",
+    Gamma: "Γ",
+    Delta: "Δ",
+    Epsilon: "Ε",
+    Zeta: "Ζ",
+    Eta: "Η",
+    Theta: "Θ",
+    Iota: "Ι",
+    Kappa: "Κ",
+    Lambda: "Λ",
+    Mu: "Μ",
+    Nu: "Ν",
+    Xi: "Ξ",
+    Omicron: "Ο",
+    Pi: "Π",
+    Rho: "Ρ",
+    Sigma: "Σ",
+    Tau: "Τ",
+    Upsilon: "Υ",
+    Phi: "Φ",
+    Chi: "Χ",
+    Psi: "Ψ",
+    Omega: "Ω",
+    alpha: "α",
+    beta: "β",
+    gamma: "γ",
+    delta: "δ",
+    epsilon: "ε",
+    zeta: "ζ",
+    eta: "η",
+    theta: "θ",
+    iota: "ι",
+    kappa: "κ",
+    lambda: "λ",
+    mu: "μ",
+    nu: "ν",
+    xi: "ξ",
+    omicron: "ο",
+    pi: "π",
+    rho: "ρ",
+    sigmaf: "ς",
+    sigma: "σ",
+    tau: "τ",
+    upsilon: "υ",
+    phi: "φ",
+    chi: "χ",
+    psi: "ψ",
+    omega: "ω",
+    thetasym: "ϑ",
+    upsih: "ϒ",
+    piv: "ϖ",
+    bull: "•",
+    hellip: "…",
+    prime: "′",
+    Prime: "″",
+    oline: "‾",
+    frasl: "⁄",
+    weierp: "℘",
+    image: "ℑ",
+    real: "ℜ",
+    trade: "™",
+    alefsym: "ℵ",
+    larr: "←",
+    uarr: "↑",
+    rarr: "→",
+    darr: "↓",
+    harr: "↔",
+    crarr: "↵",
+    lArr: "⇐",
+    uArr: "⇑",
+    rArr: "⇒",
+    dArr: "⇓",
+    hArr: "⇔",
+    forall: "∀",
+    part: "∂",
+    exist: "∃",
+    empty: "∅",
+    nabla: "∇",
+    isin: "∈",
+    notin: "∉",
+    ni: "∋",
+    prod: "∏",
+    sum: "∑",
+    minus: "−",
+    lowast: "∗",
+    radic: "√",
+    prop: "∝",
+    infin: "∞",
+    ang: "∠",
+    and: "∧",
+    or: "∨",
+    cap: "∩",
+    cup: "∪",
+    int: "∫",
+    there4: "∴",
+    sim: "∼",
+    cong: "≅",
+    asymp: "≈",
+    ne: "≠",
+    equiv: "≡",
+    le: "≤",
+    ge: "≥",
+    sub: "⊂",
+    sup: "⊃",
+    nsub: "⊄",
+    sube: "⊆",
+    supe: "⊇",
+    oplus: "⊕",
+    otimes: "⊗",
+    perp: "⊥",
+    sdot: "⋅",
+    lceil: "⌈",
+    rceil: "⌉",
+    lfloor: "⌊",
+    rfloor: "⌋",
+    lang: "〈",
+    rang: "〉",
+    loz: "◊",
+    spades: "♠",
+    clubs: "♣",
+    hearts: "♥",
+    diams: "♦",
+};

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

@@ -0,0 +1,17 @@
+/**
+ * Parses XML text into plain document data by scanning the source directly, so
+ * the package runs anywhere JavaScript does, workerd included. Covers the subset
+ * RSS and similar feeds use: one root, attributes, text, CDATA, prefixed names.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { XML } from "../index.js";
+/**
+ * Parses XML into plain document data.
+ *
+ * @param source - Raw XML text to parse
+ * @returns A Result containing XML document data or an error
+ */
+export declare function parseDocument(source: string): Result<XML.Document, Error>;