@jxsuite/feed 0.1.0

package/src/Feed.class.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://jxsuite.com/schema/class/v1",
+  "$prototype": "Class",
+  "title": "Feed",
+  "description": "Atom (RFC 4287) and JSON Feed generation from content collections, with RFC 5005 archives",
+  "$implementation": "./feed.ts",
+  "project": {
+    "key": "feed",
+    "title": "Feeds",
+    "description": "Syndication feeds generated from content collections"
+  },
+  "$studio": {
+    "settings": {
+      "label": "Feeds",
+      "description": "One entry per feed. Each names a content collection and the URL prefix its entries are served under."
+    }
+  },
+  "$defs": {
+    "returnTypes": {
+      "NormalizedFeedConfig": {
+        "type": "object",
+        "description": "The feed section with defaults applied, keyed by feed name"
+      },
+      "HeadEntries": {
+        "type": "array",
+        "description": "<head> entries — the feed auto-discovery links",
+        "items": { "type": "object" }
+      },
+      "EmitFiles": {
+        "type": "array",
+        "description": "Files to write under outDir",
+        "items": {
+          "type": "object",
+          "properties": { "path": { "type": "string" }, "content": { "type": "string" } },
+          "required": ["path", "content"]
+        }
+      }
+    },
+    "methods": {
+      "projectData": {
+        "role": "projectData",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "projectData",
+        "timing": ["compiler", "server"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `feed` section value"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/NormalizedFeedConfig" },
+        "description": "Normalize the feed section (defaults applied) into _project.feed"
+      },
+      "head": {
+        "role": "head",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "head",
+        "timing": ["compiler"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `feed` section value"
+          },
+          {
+            "identifier": "ctx",
+            "type": {
+              "type": "object",
+              "properties": { "projectConfig": { "type": "object" }, "root": { "type": "string" } }
+            },
+            "description": "Host context: { projectConfig, root } (extensions.md §8.6)"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/HeadEntries" },
+        "description": "The <link rel=\"alternate\"> auto-discovery tags, derived from configuration alone"
+      },
+      "emit": {
+        "role": "emit",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "emit",
+        "timing": ["compiler"],
+        "parameters": [
+          {
+            "identifier": "sectionValue",
+            "type": { "type": "object" },
+            "description": "The project.json `feed` section value"
+          },
+          {
+            "identifier": "ctx",
+            "type": {
+              "type": "object",
+              "properties": {
+                "projectConfig": { "type": "object" },
+                "root": { "type": "string" },
+                "sections": { "type": "object" },
+                "routes": { "type": "array" }
+              }
+            },
+            "description": "Host context: { projectConfig, root, sections, routes } (extensions.md §8.4)"
+          }
+        ],
+        "returnType": { "$ref": "#/$defs/returnTypes/EmitFiles" },
+        "description": "Serialize every configured feed and its RFC 5005 archives"
+      }
+    }
+  }
+}

package/src/atom.ts

@@ -0,0 +1,113 @@
+/**
+ * Atom 1.0 (RFC 4287), with RFC 5005 archived-feed links.
+ *
+ * Atom rather than RSS 2.0. RSS has no standards body, its date format is RFC 822, and its `<guid>`
+ * semantics were never pinned down; Atom is an IETF standard with required identity and timestamps,
+ * and every reader handles it. The omission is a decision, not an oversight.
+ */
+
+import { escapeXml, feedPath } from "./shared.ts";
+import type { FeedItem, NormalizedFeed } from "./shared.ts";
+
+const ATOM_NS = "http://www.w3.org/2005/Atom";
+/** RFC 5005 §4 — the namespace for `<fh:complete/>`. */
+const HISTORY_NS = "http://purl.org/syndication/history/1.0";
+
+export interface AtomPage {
+  /** Absolute site URL, used to build `<id>` values. */
+  siteUrl: string;
+  feed: NormalizedFeed;
+  items: readonly FeedItem[];
+  /** Absolute URL of THIS document. */
+  selfUrl: string;
+  /** The page the site's readers subscribe to. Absent on the subscription document itself. */
+  currentUrl?: string;
+  prevArchiveUrl?: string;
+  nextArchiveUrl?: string;
+  /** RFC 5005 §4: this document holds the feed's entire history. */
+  complete?: boolean;
+  /** Feed-level timestamp — the newest item, never the build time. */
+  updated: string | null;
+}
+
+function tag(name: string, value: string | null | undefined, indent = "  "): string {
+  return value === null || value === undefined || value === ""
+    ? ""
+    : `${indent}<${name}>${escapeXml(value)}</${name}>\n`;
+}
+
+function link(rel: string, href: string, type?: string): string {
+  const t = type === undefined ? "" : ` type="${type}"`;
+  return `  <link rel="${rel}" href="${escapeXml(href)}"${t}/>\n`;
+}
+
+function renderEntry(item: FeedItem): string {
+  const inner = "    ";
+  const author =
+    item.authorName === null
+      ? ""
+      : `${inner}<author>\n${inner}  <name>${escapeXml(item.authorName)}</name>\n${inner}</author>\n`;
+  return [
+    "  <entry>\n",
+    tag("id", item.id, inner),
+    tag("title", item.title, inner),
+    `${inner}<link rel="alternate" href="${escapeXml(item.url)}"/>\n`,
+    tag("updated", item.updated ?? item.published, inner),
+    tag("published", item.published, inner),
+    author,
+    tag("summary", item.summary, inner),
+    item.contentHtml === null
+      ? ""
+      : `${inner}<content type="html">${escapeXml(item.contentHtml)}</content>\n`,
+    "  </entry>\n",
+  ].join("");
+}
+
+export function renderAtom(page: AtomPage): string {
+  const { feed, items, siteUrl } = page;
+  const ns = page.complete ? ` xmlns:fh="${HISTORY_NS}"` : "";
+  /*
+   * `xml:lang` on the feed element, which RFC 4287 §2 says every child inherits — the Atom way of
+   * saying what language this document carries. JSON Feed says it with a `language` member; the two
+   * are the same fact, and a multilingual site publishes one feed per language rather than one feed
+   * that cannot answer the question.
+   */
+  const lang = feed.language === null ? "" : ` xml:lang="${escapeXml(feed.language)}"`;
+  const head = [
+    '<?xml version="1.0" encoding="utf-8"?>\n',
+    `<feed xmlns="${ATOM_NS}"${ns}${lang}>\n`,
+    tag("id", page.selfUrl),
+    tag("title", feed.title === "" ? "Feed" : feed.title),
+    tag("subtitle", feed.description),
+    /*
+     * RFC 4287 requires `<updated>`. It is the newest ITEM, not the build time: a feed whose
+     * timestamp moves on every deploy re-notifies every subscriber for no reason.
+     */
+    tag("updated", page.updated ?? "1970-01-01T00:00:00Z"),
+    link("self", page.selfUrl, "application/atom+xml"),
+    link("alternate", new URL(feed.basePath, siteUrl).href, "text/html"),
+    page.currentUrl === undefined ? "" : link("current", page.currentUrl, "application/atom+xml"),
+    page.prevArchiveUrl === undefined
+      ? ""
+      : link("prev-archive", page.prevArchiveUrl, "application/atom+xml"),
+    page.nextArchiveUrl === undefined
+      ? ""
+      : link("next-archive", page.nextArchiveUrl, "application/atom+xml"),
+    page.complete === true ? "  <fh:complete/>\n" : "",
+    feed.author?.name === undefined
+      ? ""
+      : `  <author>\n    <name>${escapeXml(feed.author.name)}</name>\n${
+          feed.author.uri === undefined ? "" : `    <uri>${escapeXml(feed.author.uri)}</uri>\n`
+        }${
+          feed.author.email === undefined
+            ? ""
+            : `    <email>${escapeXml(feed.author.email)}</email>\n`
+        }  </author>\n`,
+  ];
+  return `${head.join("")}${items.map((i) => renderEntry(i)).join("")}</feed>\n`;
+}
+
+/** Absolute URL of an Atom document within this feed. */
+export function atomUrl(siteUrl: string, output: string, archiveIndex?: number): string {
+  return new URL(feedPath(output, "xml", archiveIndex), siteUrl).href;
+}

package/src/feed.ts

@@ -0,0 +1,247 @@
+/**
+ * The `Feed` section-owner class.
+ *
+ * Three capabilities, and the split between two of them is the interesting part. `emit` derives
+ * files from loaded content and runs after every page has been written; `head` derives the `<link
+ * rel="alternate">` discovery tag from **configuration** and must run before the first page is
+ * built. A feed needs both, which is why `head` exists (specs/extensions.md §8.6).
+ *
+ * @docs framework/site/feeds
+ */
+
+import { canonicalizeLocale, localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
+import type { ResolvedI18n } from "@jxsuite/schema/locale";
+import type { ContentLoaderEntry, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+import { atomUrl, renderAtom } from "./atom.ts";
+import { jsonFeedUrl, renderJsonFeed } from "./json-feed.ts";
+import {
+  entryToItem,
+  feedPath,
+  feedUpdated,
+  normalizeFeedConfig,
+  paginate,
+  sortItems,
+} from "./shared.ts";
+import type { NormalizedFeed, NormalizedFeedConfig } from "./shared.ts";
+
+interface EmitContext {
+  projectConfig?: ProjectConfig;
+  root?: string;
+  sections?: Record<string, unknown>;
+  routes?: unknown[];
+}
+
+interface HeadContext {
+  projectConfig?: ProjectConfig;
+  root?: string;
+}
+
+const MEDIA_TYPES = { atom: "application/atom+xml", json: "application/feed+json" } as const;
+
+function siteUrlOf(projectConfig: ProjectConfig | undefined): string | null {
+  const url = projectConfig?.url;
+  return typeof url === "string" && url !== "" ? url : null;
+}
+
+/**
+ * The locales a feed is published in, or `[]` when it is published once.
+ *
+ * A feed says what language it carries, and a collection spread over one directory per locale
+ * (site-architecture.md §13.3) carries several — so it is several feeds. One feed mixing three
+ * languages is worse than it sounds: a reader subscribes to it in theirs and receives every post
+ * three times, twice in a language they do not read.
+ *
+ * Read from the collection's `source`, because `head` has to answer this before any content is
+ * loaded and configuration is all it has. That the `content` section belongs to another extension
+ * is not a coupling this introduces — a feed already names a collection out of it.
+ *
+ * @param {ProjectConfig | undefined} projectConfig
+ * @param {string} collection
+ * @returns {{ i18n: ResolvedI18n | null; locales: string[] }}
+ */
+function feedLocales(
+  projectConfig: ProjectConfig | undefined,
+  collection: string,
+): { i18n: ResolvedI18n | null; locales: string[] } {
+  const { i18n } = resolveI18n(projectConfig ?? {});
+  const content = (projectConfig as { content?: Record<string, { source?: unknown }> } | undefined)
+    ?.content;
+  const source = content?.[collection]?.source;
+  const localized = typeof source === "string" && source.includes("{locale}");
+  return { i18n, locales: i18n !== null && localized ? i18n.locales : [] };
+}
+
+/** One locale's view of a feed: its own URL space, its own language. */
+function localeVariant(feed: NormalizedFeed, locale: string, i18n: ResolvedI18n | null) {
+  const prefix = localeUrlPrefix(locale, i18n);
+  return {
+    ...feed,
+    basePath: `${prefix}${feed.basePath}`,
+    language: locale,
+    output: `${prefix}${feed.output}`,
+  };
+}
+
+export const Feed = {
+  /** Normalize the `feed` section into `_project.feed`. */
+  projectData(sectionValue: unknown, ctx?: HeadContext): NormalizedFeedConfig {
+    return normalizeFeedConfig(sectionValue, ctx?.projectConfig?.defaults?.lang);
+  },
+
+  /**
+   * The auto-discovery links.
+   *
+   * Pure configuration, which is exactly why this can run before content loads — a feed's URL comes
+   * from its `output`, not from its entries.
+   */
+  head(sectionValue: unknown, ctx: HeadContext): JxHeadEntry[] {
+    const siteUrl = siteUrlOf(ctx.projectConfig);
+    if (siteUrl === null) {
+      return [];
+    }
+    const config = normalizeFeedConfig(sectionValue, ctx.projectConfig?.defaults?.lang);
+    const entries: JxHeadEntry[] = [];
+    for (const feed of Object.values(config)) {
+      const { i18n, locales } = feedLocales(ctx.projectConfig, feed.collection);
+      /*
+       * One link per language, each carrying `hreflang`. `head` runs before routing and cannot know
+       * which locale the page it lands on is in, so it advertises all of them and lets the client
+       * choose — which is what `hreflang` on an `alternate` link is for.
+       */
+      const published =
+        locales.length > 0 ? locales.map((l) => localeVariant(feed, l, i18n)) : [feed];
+      for (const variant of published) {
+        for (const format of variant.formats) {
+          const href =
+            format === "atom"
+              ? atomUrl(siteUrl, variant.output)
+              : jsonFeedUrl(siteUrl, variant.output);
+          entries.push({
+            attributes: {
+              href,
+              ...(variant.language !== null && locales.length > 0
+                ? { hreflang: variant.language }
+                : {}),
+              rel: "alternate",
+              title: variant.title === "" ? "Feed" : variant.title,
+              type: MEDIA_TYPES[format],
+            },
+            tagName: "link",
+          });
+        }
+      }
+    }
+    return entries;
+  },
+
+  /** Serialize every configured feed, plus its RFC 5005 archives when enabled. */
+  emit(sectionValue: unknown, ctx: EmitContext): { path: string; content: string }[] {
+    const siteUrl = siteUrlOf(ctx.projectConfig);
+    if (siteUrl === null) {
+      console.warn("@jxsuite/feed: `url` is not set in project.json — feeds need absolute links.");
+      return [];
+    }
+    const config = normalizeFeedConfig(sectionValue, ctx.projectConfig?.defaults?.lang);
+    const content = ctx.sections?.content as Map<string, ContentLoaderEntry[]> | undefined;
+    const trailingSlash = String(ctx.projectConfig?.build?.trailingSlash ?? "always");
+    const files: { path: string; content: string }[] = [];
+
+    for (const [key, feed] of Object.entries(config)) {
+      const entries = content?.get(feed.collection);
+      if (!entries) {
+        console.warn(
+          `@jxsuite/feed: feed "${key}" names collection "${feed.collection}", which is not a ` +
+            "loaded content collection — skipped",
+        );
+        continue;
+      }
+      const { i18n, locales } = feedLocales(ctx.projectConfig, feed.collection);
+      if (locales.length === 0) {
+        files.push(...renderFeed(feed, entries, siteUrl, trailingSlash));
+        continue;
+      }
+      /*
+       * One feed per language, each holding only that language's entries. An entry with no locale
+       * belongs to none of them — it cannot happen for a `{locale}` source, and inventing a home
+       * for it would publish it in every language at once.
+       */
+      for (const locale of locales) {
+        const own = entries.filter((e) => canonicalizeLocale(e._meta?.locale) === locale);
+        if (own.length > 0) {
+          files.push(...renderFeed(localeVariant(feed, locale, i18n), own, siteUrl, trailingSlash));
+        }
+      }
+    }
+    return files;
+  },
+};
+
+function renderFeed(
+  feed: NormalizedFeed,
+  entries: readonly ContentLoaderEntry[],
+  siteUrl: string,
+  trailingSlash: string,
+): { path: string; content: string }[] {
+  const items = sortItems(entries.map((e) => entryToItem(e, feed, siteUrl, trailingSlash)));
+  const files: { path: string; content: string }[] = [];
+  const { archives, current } = feed.archive
+    ? paginate(items, feed.pageSize)
+    : { archives: [], current: items.slice(0, feed.pageSize) };
+
+  /*
+   * `fh:complete` is only true when the document really holds everything — no archives AND nothing
+   * trimmed by pageSize. Claiming completeness while entries are missing is worse than saying
+   * nothing, because a reader believes it.
+   */
+  const complete = archives.length === 0 && current.length === items.length;
+
+  for (const format of feed.formats) {
+    const url = format === "atom" ? atomUrl : jsonFeedUrl;
+    if (format === "atom") {
+      files.push({
+        content: renderAtom({
+          complete,
+          feed,
+          items: current,
+          selfUrl: url(siteUrl, feed.output),
+          siteUrl,
+          updated: feedUpdated(items),
+          ...(archives.length > 0
+            ? { prevArchiveUrl: url(siteUrl, feed.output, archives.length - 1) }
+            : {}),
+        }),
+        path: feedPath(feed.output, "xml"),
+      });
+      // Archives run oldest-first, so `prev-archive` walks backwards through time.
+      for (const [i, page] of archives.entries()) {
+        files.push({
+          content: renderAtom({
+            currentUrl: url(siteUrl, feed.output),
+            feed,
+            items: page,
+            selfUrl: url(siteUrl, feed.output, i),
+            siteUrl,
+            updated: feedUpdated(page),
+            ...(i > 0 ? { prevArchiveUrl: url(siteUrl, feed.output, i - 1) } : {}),
+            nextArchiveUrl:
+              i < archives.length - 1
+                ? url(siteUrl, feed.output, i + 1)
+                : url(siteUrl, feed.output),
+          }),
+          path: feedPath(feed.output, "xml", i),
+        });
+      }
+    } else {
+      files.push({
+        content: renderJsonFeed({
+          feed,
+          items: current,
+          selfUrl: url(siteUrl, feed.output),
+          siteUrl,
+        }),
+        path: feedPath(feed.output, "json"),
+      });
+    }
+  }
+  return files;
+}

package/src/json-feed.ts

@@ -0,0 +1,78 @@
+/**
+ * JSON Feed 1.1.
+ *
+ * The same model as the Atom serializer, in the format a reader that would rather not parse XML
+ * asks for. It carries no RFC 5005 links: JSON Feed has its own `next_url` pagination and mixing
+ * the two conventions in one document would be worse than offering the archives in Atom alone.
+ */
+
+import { feedPath } from "./shared.ts";
+import type { FeedItem, NormalizedFeed } from "./shared.ts";
+
+const VERSION = "https://jsonfeed.org/version/1.1";
+
+export interface JsonFeedPage {
+  siteUrl: string;
+  feed: NormalizedFeed;
+  items: readonly FeedItem[];
+  selfUrl: string;
+  /** JSON Feed's own pagination: the next, older page. */
+  nextUrl?: string;
+}
+
+interface JsonFeedItem {
+  id: string;
+  url: string;
+  title: string;
+  content_html?: string;
+  content_text?: string;
+  summary?: string;
+  date_published?: string;
+  date_modified?: string;
+  authors?: { name: string }[];
+}
+
+export function renderJsonFeed(page: JsonFeedPage): string {
+  const { feed, items, siteUrl } = page;
+  const doc: Record<string, unknown> = {
+    description: feed.description === "" ? undefined : feed.description,
+    feed_url: page.selfUrl,
+    home_page_url: new URL(feed.basePath, siteUrl).href,
+    // BCP 47, and the one place a feed states the language of what it carries.
+    language: feed.language ?? undefined,
+    next_url: page.nextUrl,
+    title: feed.title === "" ? "Feed" : feed.title,
+    version: VERSION,
+    // Authors is the 1.1 spelling; `author` was 1.0 and is deprecated.
+    ...(feed.author?.name === undefined ? {} : { authors: [{ name: feed.author.name }] }),
+    items: items.map((item): JsonFeedItem => {
+      const out: JsonFeedItem = { id: item.id, title: item.title, url: item.url };
+      if (item.contentHtml !== null) {
+        out.content_html = item.contentHtml;
+      } else {
+        // 1.1 requires at least one of content_html / content_text.
+        out.content_text = item.summary;
+      }
+      if (item.summary !== "") {
+        out.summary = item.summary;
+      }
+      if (item.published !== null) {
+        out.date_published = item.published;
+      }
+      if (item.updated !== null && item.updated !== item.published) {
+        out.date_modified = item.updated;
+      }
+      if (item.authorName !== null) {
+        out.authors = [{ name: item.authorName }];
+      }
+      return out;
+    }),
+  };
+  // `undefined` values are dropped by JSON.stringify, which is what keeps optional keys absent
+  // Rather than null — a null `language` would claim the feed has no language.
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+export function jsonFeedUrl(siteUrl: string, output: string, archiveIndex?: number): string {
+  return new URL(feedPath(output, "json", archiveIndex), siteUrl).href;
+}