xml.mjs

Functions

Imports

It imports no other module of this repo. Imported by feeds.mjs, index.mjs, sitemap.mjs.

Source

1/**
2 * The XML and feed-text helpers that were written again in about eight repositories, once, in the form of the best of them
3 * (dustinedwards-info's rss-feed.mjs). Pure, no dependencies, Web-standard only: it runs unchanged in a Worker and in Node.
4 */
5
6/**
7 * All five entities. Attribute values and element text both take this one, since it is safe in either.
8 *
9 * @param {unknown} value
10 * @returns {string}
11 */
12export function escapeXml(value) {
13  return String(value)
14    .replace(/&/g, "&")
15    .replace(/</g, "&lt;")
16    .replace(/>/g, "&gt;")
17    .replace(/"/g, "&quot;")
18    .replace(/'/g, "&apos;");
19}
20
21/**
22 * Element text only: `&`, `<` and `>`. What a site that never puts a quote into a value (a URL, a category) wrote for
23 * itself; `escapeXml` is safe wherever this is, and the two differ only on `"` and `'`.
24 *
25 * @param {unknown} value
26 * @returns {string}
27 */
28export function escapeXmlText(value) {
29  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
30}
31
32/**
33 * A CDATA section ends at the first `]]>`, so it is closed and reopened around one; the two sections concatenate
34 * transparently. A hand-written `<![CDATA[${text}]]>` loses the rest of the text, and the document, at that point.
35 *
36 * @param {unknown} content
37 * @returns {string}
38 */
39export function cdata(content) {
40  return `<![CDATA[${String(content).replace(/\]\]>/g, "]]]]><![CDATA[>")}]]>`;
41}
42
43/**
44 * An RFC 822 date, which RSS `<pubDate>` requires, from a Date, an epoch in milliseconds, or the two string forms the sites
45 * store: ISO 8601 (`2026-06-21T09:30:00Z`) and SQLite's `2026-06-21 09:30:00`, read as UTC. A value that is not a date reads
46 * as the epoch, as germomics always has, so an item is never undated by accident.
47 *
48 * @param {Date | number | string | null | undefined} value
49 * @returns {string}
50 */
51export function rfc822(value) {
52  return toDate(value).toUTCString();
53}
54
55/**
56 * The calendar day of a date as `YYYY-MM-DD` (a sitemap `<lastmod>`), or null when there is none.
57 *
58 * @param {Date | number | string | null | undefined} value
59 * @returns {string | null}
60 */
61export function isoDay(value) {
62  if (value === null || value === undefined || value === "") return null;
63  const date = toDate(value, null);
64  return date && !Number.isNaN(date.getTime()) ? date.toISOString().slice(0, 10) : null;
65}
66
67/**
68 * A Date from the same forms `rfc822` reads, SQLite's `2026-06-21 09:30:00` as UTC. Every feed and sitemap date goes through it,
69 * so a build on a machine that is not on UTC writes the same instant as the Worker does.
70 *
71 * @param {Date | number | string | null | undefined} value
72 * @param {Date | null} [fallback] what an unreadable value becomes; the epoch by default, an invalid Date when null
73 * @returns {Date}
74 */
75export function toDate(value, fallback = new Date(0)) {
76  if (value instanceof Date) return Number.isNaN(value.getTime()) ? (fallback ?? new Date(NaN)) : value;
77  if (typeof value === "number") return new Date(value);
78  if (typeof value === "string" && value !== "") {
79    const date = new Date(value.includes("T") ? value : `${value.replace(" ", "T")}Z`);
80    if (!Number.isNaN(date.getTime())) return date;
81  }
82  return fallback ?? new Date(NaN);
83}
84
85/**
86 * Not an HTML parser: only `href`, `src` and `srcset` values beginning with a single `/` are rewritten. A `//` value is
87 * protocol-relative and already absolute. A feed item is read on someone else's origin, where a root-relative path resolves
88 * against THEIR host.
89 *
90 * @param {string} html
91 * @param {string} origin no trailing slash
92 */
93export function absolutiseUrls(html, origin) {
94  return String(html)
95    .replace(/\b(href|src)="\/(?!\/)/g, `$1="${origin}/`)
96    .replace(
97      /\bsrcset="([^"]*)"/g,
98      (_whole, list) =>
99        `srcset="${String(list)
100          .split(",")
101          .map((candidate) => candidate.replace(/^(\s*)\/(?!\/)/, `$1${origin}/`))
102          .join(",")}"`,
103    );
104}
105
106/**
107 * For a site whose markdown renders math with KaTeX. A feed reader has no `katex.css`, so KaTeX's two trees (clipped MathML
108 * and positioned HTML) would both show, garbled. The TeX comes from KaTeX's own annotation, taken still XML-escaped, because
109 * unescaping would put a stray `<` into the reader's document.
110 *
111 * Counting spans is sound because nothing KaTeX nests inside an expression can close a span it did not open. An expression
112 * with no closing tag or no annotation is left alone.
113 *
114 * @param {string} html
115 */
116export function mathToTex(html) {
117  const source = String(html);
118  let out = "";
119  let cursor = 0;
120
121  for (;;) {
122    // `katex-display` WRAPS the `katex` span, so matching the inner one first would leave the outer wrapper behind, empty,
123    // around a `$$`.
124    const display = source.indexOf('<span class="katex-display">', cursor);
125    const inline = source.indexOf('<span class="katex">', cursor);
126    if (display === -1 && inline === -1) break;
127    const start = display === -1 ? inline : inline === -1 ? display : Math.min(display, inline);
128    const isDisplay = start === display;
129
130    const end = spanEnd(source, start);
131    if (end === -1) break;
132
133    const region = source.slice(start, end);
134    const annotation = region.match(/<annotation encoding="application\/x-tex">([\s\S]*?)<\/annotation>/);
135    // An empty annotation is left alone too, rather than emitting a bare pair of dollar signs.
136    if (!annotation || !annotation[1]) {
137      out += source.slice(cursor, end);
138      cursor = end;
139      continue;
140    }
141
142    const tex = annotation[1].trim();
143    const delimiter = isDisplay ? "$$" : "$";
144    out += source.slice(cursor, start) + delimiter + tex + delimiter;
145    cursor = end;
146  }
147
148  return out + source.slice(cursor);
149}
150
151/**
152 * -1 when the depth never returns to zero.
153 *
154 * @param {string} source @param {number} start index of the opening `<span`
155 */
156function spanEnd(source, start) {
157  const OPEN = "<span";
158  const CLOSE = "</span>";
159  let depth = 0;
160  let i = start;
161  while (i < source.length) {
162    const open = source.indexOf(OPEN, i);
163    const close = source.indexOf(CLOSE, i);
164    if (close === -1) return -1;
165    if (open !== -1 && open < close) {
166      depth += 1;
167      i = open + OPEN.length;
168      continue;
169    }
170    depth -= 1;
171    i = close + CLOSE.length;
172    if (depth === 0) return i;
173  }
174  return -1;
175}