feeds.mjs

Functions

Imports

It imports xml.mjs. Imported by index.mjs.

Source

1import { absolutiseUrls, cdata, escapeXml, mathToTex, toDate } from "./xml.mjs";
2
3/*
4 * RSS 2.0, Atom 1.0 and JSON Feed 1.1 from the same post rows. `<description>` keeps the summary because readers show it in the
5 * LIST view; the post goes in `content:encoded`. URLs are absolutised because a feed item is read on someone else's origin.
6 * `itemPath` is where a post lives under the origin ("/writing" by default), the one thing the sites disagree on.
7 */
8
9const DEFAULT_ITEM_PATH = "/writing";
10
11/**
12 * @param {{
13 *   slug: string,
14 *   title: string,
15 *   html: string | null,
16 *   description: string | null,
17 *   publishAt: unknown,
18 *   tags: string[],
19 *   author?: string,
20 * }} post one row of `listBlogPostsRendered`; `author` is RSS's own form, an email address with the name in brackets
21 * @param {string} origin the site origin, no trailing slash
22 * @param {string} [itemPath]
23 */
24export function rssItem(post, origin, itemPath = DEFAULT_ITEM_PATH) {
25  const url = `${origin}${itemPath}/${post.slug}`;
26  const published = post.publishAt
27    ? toDate(post.publishAt, null).toUTCString()
28    : null;
29
30  return [
31    "    <item>",
32    `      <title>${escapeXml(post.title)}</title>`,
33    `      <link>${escapeXml(url)}</link>`,
34    `      <guid isPermaLink="true">${escapeXml(url)}</guid>`,
35    post.description ? `      <description>${escapeXml(post.description)}</description>` : null,
36    // Omitted rather than empty: an empty `content:encoded` tells a reader the post IS empty.
37    post.html
38      ? `      <content:encoded>${cdata(absolutiseUrls(mathToTex(post.html), origin))}</content:encoded>`
39      : null,
40    published ? `      <pubDate>${published}</pubDate>` : null,
41    post.author ? `      <author>${escapeXml(post.author)}</author>` : null,
42    ...post.tags.map((tag) => `      <category>${escapeXml(tag)}</category>`),
43    "    </item>",
44  ]
45    .filter(Boolean)
46    .join("\n");
47}
48
49/**
50 * @param {{
51 *   title: string,
52 *   link: string,
53 *   description: string,
54 *   selfUrl: string,
55 *   posts: Array<Parameters<typeof rssItem>[0]>,
56 *   origin: string,
57 *   itemPath?: string,
58 *   lastBuildDate?: unknown,
59 *   image?: { url: string, title: string, link: string },
60 * }} feed `lastBuildDate` is when the content last changed (the newest post), never the clock, so a render stays cacheable
61 * @returns {string}
62 */
63export function rssDocument(feed) {
64  const items = feed.posts.map((post) => rssItem(post, feed.origin, feed.itemPath)).join("\n");
65  const lastBuildDate = feed.lastBuildDate
66    ? `\n    <lastBuildDate>${toDate(feed.lastBuildDate, null).toUTCString()}</lastBuildDate>`
67    : "";
68  const image = feed.image
69    ? `\n    <image>
70      <url>${escapeXml(feed.image.url)}</url>
71      <title>${escapeXml(feed.image.title)}</title>
72      <link>${escapeXml(feed.image.link)}</link>
73    </image>`
74    : "";
75  return `<?xml version="1.0" encoding="UTF-8"?>
76<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
77  <channel>
78    <title>${escapeXml(feed.title)}</title>
79    <link>${escapeXml(feed.link)}</link>
80    <description>${escapeXml(feed.description)}</description>
81    <language>en-us</language>${lastBuildDate}
82    <atom:link href="${escapeXml(feed.selfUrl)}" rel="self" type="application/rss+xml" />${image}
83${items}
84  </channel>
85</rss>
86`;
87}
88
89/**
90 * The body is CDATA rather than escaped inline: double-escaping is how a feed
91 * ends up showing tags as text. No rendered HTML means no `<content>` at all,
92 * since an empty one asserts the post is empty.
93 *
94 * @param {{
95 *   slug: string,
96 *   title: string,
97 *   html: string | null,
98 *   description: string | null,
99 *   publishAt: unknown,
100 *   updatedAt: unknown,
101 *   tags: string[],
102 * }} post
103 * @param {string} origin
104 * @param {string} [itemPath]
105 * @returns {string}
106 */
107export function atomEntry(post, origin, itemPath = DEFAULT_ITEM_PATH) {
108  const url = `${origin}${itemPath}/${post.slug}`;
109  const published = post.publishAt ? toDate(post.publishAt, null) : null;
110  const updated = post.updatedAt ? toDate(post.updatedAt, null) : published;
111
112  return [
113    "    <entry>",
114    `      <title>${escapeXml(post.title)}</title>`,
115    `      <link href="${escapeXml(url)}" rel="alternate" type="text/html" />`,
116    `      <id>${escapeXml(url)}</id>`,
117    // An entry with no `updated` is invalid Atom, hence the epoch fallback.
118    `      <updated>${(updated ?? new Date(0)).toISOString()}</updated>`,
119    published ? `      <published>${published.toISOString()}</published>` : null,
120    post.description ? `      <summary>${escapeXml(post.description)}</summary>` : null,
121    post.html
122      ? `      <content type="html">${cdata(absolutiseUrls(mathToTex(post.html), origin))}</content>`
123      : null,
124    ...post.tags.map((tag) => `      <category term="${escapeXml(tag)}" />`),
125    "    </entry>",
126  ]
127    .filter(Boolean)
128    .join("\n");
129}
130
131/**
132 * @param {{
133 *   title: string,
134 *   subtitle: string,
135 *   alternateUrl: string,
136 *   selfUrl: string,
137 *   authorName: string,
138 *   posts: Array<Parameters<typeof atomEntry>[0]>,
139 *   origin: string,
140 *   itemPath?: string,
141 * }} feed
142 * @returns {string}
143 */
144export function atomDocument(feed) {
145  const entries = feed.posts.map((post) => atomEntry(post, feed.origin, feed.itemPath)).join("\n");
146  // Derived from the rows rather than a clock, so two renders of the same corpus
147  // are byte-identical and the edge can cache them. An empty feed gets the epoch,
148  // which validates where an empty `<updated>` does not.
149  const newest = feed.posts
150    .map((post) => post.updatedAt ?? post.publishAt)
151    .filter(Boolean)
152    .map((value) => toDate(value, null).getTime())
153    .reduce((a, b) => Math.max(a, b), 0);
154
155  return `<?xml version="1.0" encoding="UTF-8"?>
156<feed xmlns="http://www.w3.org/2005/Atom">
157  <title>${escapeXml(feed.title)}</title>
158  <subtitle>${escapeXml(feed.subtitle)}</subtitle>
159  <link href="${escapeXml(feed.alternateUrl)}" rel="alternate" type="text/html" />
160  <link href="${escapeXml(feed.selfUrl)}" rel="self" type="application/atom+xml" />
161  <id>${escapeXml(feed.alternateUrl)}</id>
162  <updated>${new Date(newest).toISOString()}</updated>
163  <author><name>${escapeXml(feed.authorName)}</name><uri>${escapeXml(feed.origin)}</uri></author>
164${entries}
165</feed>
166`;
167}
168
169/**
170 * Undefined-valued keys are how an optional field is omitted (JSON.stringify
171 * drops them), so a direct consumer must judge presence by value, not by `in`.
172 *
173 * @param {{
174 *   slug: string,
175 *   title: string,
176 *   body: string,
177 *   description: string | null,
178 *   publishAt: unknown,
179 *   updatedAt: unknown,
180 *   coverImage: string | null,
181 *   tags: string[],
182 * }} post one row of `listBlogPostsFullText`
183 * @param {string} origin the site origin, no trailing slash
184 * @param {string} [itemPath]
185 */
186export function feedItem(post, origin, itemPath = DEFAULT_ITEM_PATH) {
187  return {
188    id: `${origin}${itemPath}/${post.slug}`,
189    url: `${origin}${itemPath}/${post.slug}`,
190    title: post.title,
191    // JSON Feed 1.1 requires content_html or content_text on every item.
192    content_text: post.body,
193    summary: post.description ?? undefined,
194    date_published: post.publishAt
195      ? toDate(post.publishAt, null).toISOString()
196      : undefined,
197    date_modified: post.updatedAt
198      ? toDate(post.updatedAt, null).toISOString()
199      : undefined,
200    tags: post.tags.length > 0 ? post.tags : undefined,
201    image: post.coverImage ? `${origin}${post.coverImage}` : undefined,
202  };
203}
204
205/**
206 * @param {{
207 *   title: string,
208 *   homePageUrl: string,
209 *   feedUrl: string,
210 *   description: string,
211 *   authorName: string,
212 *   posts: Array<Parameters<typeof feedItem>[0]>,
213 *   origin: string,
214 *   itemPath?: string,
215 * }} feed
216 */
217export function jsonFeedDocument(feed) {
218  return {
219    version: "https://jsonfeed.org/version/1.1",
220    title: feed.title,
221    home_page_url: feed.homePageUrl,
222    feed_url: feed.feedUrl,
223    description: feed.description,
224    language: "en-US",
225    authors: [{ name: feed.authorName, url: feed.origin }],
226    items: feed.posts.map((post) => feedItem(post, feed.origin, feed.itemPath)),
227  };
228}