@jxsuite/feed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Shenk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/feed.js

@@ -0,0 +1,465 @@
+// ../../packages/schema/src/locale.ts
+var RTL_SCRIPTS = new Set([
+  "Adlm",
+  "Arab",
+  "Aran",
+  "Armi",
+  "Avst",
+  "Cprt",
+  "Egyd",
+  "Egyh",
+  "Elym",
+  "Gara",
+  "Hatr",
+  "Hebr",
+  "Hluw",
+  "Hung",
+  "Khar",
+  "Lydi",
+  "Mand",
+  "Mani",
+  "Mend",
+  "Merc",
+  "Mero",
+  "Narb",
+  "Nbat",
+  "Nkoo",
+  "Orkh",
+  "Palm",
+  "Phli",
+  "Phlp",
+  "Phnx",
+  "Prti",
+  "Rohg",
+  "Samr",
+  "Sarb",
+  "Sogd",
+  "Sogo",
+  "Syrc",
+  "Thaa",
+  "Todr",
+  "Yezi"
+]);
+function canonicalizeLocale(tag) {
+  if (typeof tag !== "string" || tag.trim() === "") {
+    return null;
+  }
+  try {
+    return new Intl.Locale(tag.trim()).toString();
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_ROUTING = "prefix-except-default";
+function resolveI18n(projectConfig) {
+  const raw = projectConfig.i18n;
+  const errors = [];
+  if (!raw || typeof raw !== "object") {
+    return { errors, i18n: null };
+  }
+  const declared = Array.isArray(raw.locales) ? raw.locales : [];
+  const locales = [];
+  for (const tag of declared) {
+    const canonical = canonicalizeLocale(tag);
+    if (canonical === null) {
+      errors.push(`i18n.locales: "${String(tag)}" is not a well-formed BCP 47 language tag.`);
+      continue;
+    }
+    if (!locales.includes(canonical)) {
+      locales.push(canonical);
+    }
+  }
+  const defaultLocale = canonicalizeLocale(raw.defaultLocale) ?? locales[0] ?? null;
+  if (raw.defaultLocale !== undefined && canonicalizeLocale(raw.defaultLocale) === null) {
+    errors.push(`i18n.defaultLocale: "${String(raw.defaultLocale)}" is not a well-formed BCP 47 language tag.`);
+  }
+  if (defaultLocale === null) {
+    errors.push("i18n is declared with no usable locale — set `defaultLocale` or `locales`.");
+    return { errors, i18n: null };
+  }
+  if (!locales.includes(defaultLocale)) {
+    locales.unshift(defaultLocale);
+  }
+  const routing = raw.routing === "prefix-always" || raw.routing === "prefix-except-default" ? raw.routing : DEFAULT_ROUTING;
+  return { errors, i18n: { defaultLocale, locales, routing } };
+}
+function localeUrlPrefix(locale, i18n) {
+  if (i18n === null) {
+    return "";
+  }
+  const canonical = canonicalizeLocale(locale);
+  if (canonical === null || !i18n.locales.includes(canonical)) {
+    return "";
+  }
+  if (canonical === i18n.defaultLocale && i18n.routing === "prefix-except-default") {
+    return "";
+  }
+  return `/${canonical.toLowerCase()}`;
+}
+
+// src/shared.ts
+var DEFAULTS = {
+  archive: false,
+  contentMode: "summary",
+  dateField: "date",
+  description: "",
+  formats: ["atom", "json"],
+  output: "/feed",
+  pageSize: 20,
+  title: "",
+  updatedField: "updated"
+};
+function normalizeFeedConfig(section, siteLanguage) {
+  const out = {};
+  if (!section || typeof section !== "object") {
+    return out;
+  }
+  for (const [key, raw] of Object.entries(section)) {
+    if (!raw || typeof raw !== "object") {
+      continue;
+    }
+    const cfg = raw;
+    out[key] = {
+      archive: cfg.archive ?? DEFAULTS.archive,
+      author: cfg.author ?? null,
+      basePath: normalizeBasePath(cfg.basePath ?? "/"),
+      collection: cfg.collection ?? key,
+      contentMode: cfg.contentMode ?? DEFAULTS.contentMode,
+      dateField: cfg.dateField ?? DEFAULTS.dateField,
+      description: cfg.description ?? DEFAULTS.description,
+      formats: cfg.formats ?? [...DEFAULTS.formats],
+      language: cfg.language ?? siteLanguage ?? null,
+      output: cfg.output ?? DEFAULTS.output,
+      pageSize: cfg.pageSize ?? DEFAULTS.pageSize,
+      title: cfg.title ?? DEFAULTS.title,
+      updatedField: cfg.updatedField ?? DEFAULTS.updatedField
+    };
+  }
+  return out;
+}
+function normalizeBasePath(p) {
+  const withSlash = p.startsWith("/") ? p : `/${p}`;
+  return withSlash.endsWith("/") ? withSlash : `${withSlash}/`;
+}
+function entryUrl(siteUrl, basePath, id, trailingSlash) {
+  const path = trailingSlash === "never" ? `${basePath}${id}` : `${basePath}${id}/`;
+  return new URL(path, siteUrl).href;
+}
+function readDate(value) {
+  if (typeof value !== "string" || value === "") {
+    return null;
+  }
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return `${value}T00:00:00Z`;
+  }
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/.test(value) ? value : null;
+}
+function entryToItem(entry, feed, siteUrl, trailingSlash) {
+  const data = entry.data ?? {};
+  const meta = entry._meta ?? {};
+  const url = entryUrl(siteUrl, feed.basePath, entry.id, trailingSlash);
+  const published = readDate(data[feed.dateField]) ?? readDate(meta.mtime);
+  const { author } = data;
+  return {
+    authorName: typeof author === "string" ? author : author?.name ?? feed.author?.name ?? null,
+    contentHtml: feed.contentMode === "full" ? String(entry.body ?? "") : null,
+    id: url,
+    published,
+    summary: typeof data.description === "string" ? data.description : typeof meta.excerpt === "string" ? meta.excerpt : "",
+    title: typeof data.title === "string" ? data.title : entry.id,
+    updated: readDate(data[feed.updatedField]) ?? published,
+    url
+  };
+}
+function sortItems(items) {
+  return [...items].toSorted((a, b) => {
+    if (a.published === b.published) {
+      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    }
+    if (a.published === null) {
+      return 1;
+    }
+    if (b.published === null) {
+      return -1;
+    }
+    return a.published < b.published ? 1 : -1;
+  });
+}
+function feedUpdated(items) {
+  let newest = null;
+  for (const item of items) {
+    const stamp = item.updated ?? item.published;
+    if (stamp !== null && (newest === null || stamp > newest)) {
+      newest = stamp;
+    }
+  }
+  return newest;
+}
+function paginate(items, pageSize) {
+  if (items.length <= pageSize) {
+    return { archives: [], current: [...items] };
+  }
+  const current = items.slice(0, pageSize);
+  const oldestFirst = items.slice(pageSize).toReversed();
+  const archives = [];
+  for (let i = 0;i < oldestFirst.length; i += pageSize) {
+    archives.push(oldestFirst.slice(i, i + pageSize).toReversed());
+  }
+  return { archives, current };
+}
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function feedPath(output, ext, archiveIndex) {
+  const base = output.startsWith("/") ? output : `/${output}`;
+  return archiveIndex === undefined ? `${base}.${ext}` : `${base}/archive/${archiveIndex + 1}.${ext}`;
+}
+
+// src/atom.ts
+var ATOM_NS = "http://www.w3.org/2005/Atom";
+var HISTORY_NS = "http://purl.org/syndication/history/1.0";
+function tag(name, value, indent = "  ") {
+  return value === null || value === undefined || value === "" ? "" : `${indent}<${name}>${escapeXml(value)}</${name}>
+`;
+}
+function link(rel, href, type) {
+  const t = type === undefined ? "" : ` type="${type}"`;
+  return `  <link rel="${rel}" href="${escapeXml(href)}"${t}/>
+`;
+}
+function renderEntry(item) {
+  const inner = "    ";
+  const author = item.authorName === null ? "" : `${inner}<author>
+${inner}  <name>${escapeXml(item.authorName)}</name>
+${inner}</author>
+`;
+  return [
+    `  <entry>
+`,
+    tag("id", item.id, inner),
+    tag("title", item.title, inner),
+    `${inner}<link rel="alternate" href="${escapeXml(item.url)}"/>
+`,
+    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>
+`,
+    `  </entry>
+`
+  ].join("");
+}
+function renderAtom(page) {
+  const { feed, items, siteUrl } = page;
+  const ns = page.complete ? ` xmlns:fh="${HISTORY_NS}"` : "";
+  const lang = feed.language === null ? "" : ` xml:lang="${escapeXml(feed.language)}"`;
+  const head = [
+    `<?xml version="1.0" encoding="utf-8"?>
+`,
+    `<feed xmlns="${ATOM_NS}"${ns}${lang}>
+`,
+    tag("id", page.selfUrl),
+    tag("title", feed.title === "" ? "Feed" : feed.title),
+    tag("subtitle", feed.description),
+    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/>
+` : "",
+    feed.author?.name === undefined ? "" : `  <author>
+    <name>${escapeXml(feed.author.name)}</name>
+${feed.author.uri === undefined ? "" : `    <uri>${escapeXml(feed.author.uri)}</uri>
+`}${feed.author.email === undefined ? "" : `    <email>${escapeXml(feed.author.email)}</email>
+`}  </author>
+`
+  ];
+  return `${head.join("")}${items.map((i) => renderEntry(i)).join("")}</feed>
+`;
+}
+function atomUrl(siteUrl, output, archiveIndex) {
+  return new URL(feedPath(output, "xml", archiveIndex), siteUrl).href;
+}
+
+// src/json-feed.ts
+var VERSION = "https://jsonfeed.org/version/1.1";
+function renderJsonFeed(page) {
+  const { feed, items, siteUrl } = page;
+  const doc = {
+    description: feed.description === "" ? undefined : feed.description,
+    feed_url: page.selfUrl,
+    home_page_url: new URL(feed.basePath, siteUrl).href,
+    language: feed.language ?? undefined,
+    next_url: page.nextUrl,
+    title: feed.title === "" ? "Feed" : feed.title,
+    version: VERSION,
+    ...feed.author?.name === undefined ? {} : { authors: [{ name: feed.author.name }] },
+    items: items.map((item) => {
+      const out = { id: item.id, title: item.title, url: item.url };
+      if (item.contentHtml !== null) {
+        out.content_html = item.contentHtml;
+      } else {
+        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;
+    })
+  };
+  return `${JSON.stringify(doc, null, 2)}
+`;
+}
+function jsonFeedUrl(siteUrl, output, archiveIndex) {
+  return new URL(feedPath(output, "json", archiveIndex), siteUrl).href;
+}
+
+// src/feed.ts
+var MEDIA_TYPES = { atom: "application/atom+xml", json: "application/feed+json" };
+function siteUrlOf(projectConfig) {
+  const url = projectConfig?.url;
+  return typeof url === "string" && url !== "" ? url : null;
+}
+function feedLocales(projectConfig, collection) {
+  const { i18n } = resolveI18n(projectConfig ?? {});
+  const content = projectConfig?.content;
+  const source = content?.[collection]?.source;
+  const localized = typeof source === "string" && source.includes("{locale}");
+  return { i18n, locales: i18n !== null && localized ? i18n.locales : [] };
+}
+function localeVariant(feed, locale, i18n) {
+  const prefix = localeUrlPrefix(locale, i18n);
+  return {
+    ...feed,
+    basePath: `${prefix}${feed.basePath}`,
+    language: locale,
+    output: `${prefix}${feed.output}`
+  };
+}
+var Feed = {
+  projectData(sectionValue, ctx) {
+    return normalizeFeedConfig(sectionValue, ctx?.projectConfig?.defaults?.lang);
+  },
+  head(sectionValue, ctx) {
+    const siteUrl = siteUrlOf(ctx.projectConfig);
+    if (siteUrl === null) {
+      return [];
+    }
+    const config = normalizeFeedConfig(sectionValue, ctx.projectConfig?.defaults?.lang);
+    const entries = [];
+    for (const feed of Object.values(config)) {
+      const { i18n, locales } = feedLocales(ctx.projectConfig, feed.collection);
+      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;
+  },
+  emit(sectionValue, ctx) {
+    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;
+    const trailingSlash = String(ctx.projectConfig?.build?.trailingSlash ?? "always");
+    const files = [];
+    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;
+      }
+      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, entries, siteUrl, trailingSlash) {
+  const items = sortItems(entries.map((e) => entryToItem(e, feed, siteUrl, trailingSlash)));
+  const files = [];
+  const { archives, current } = feed.archive ? paginate(items, feed.pageSize) : { archives: [], current: items.slice(0, feed.pageSize) };
+  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")
+      });
+      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;
+}
+export {
+  Feed
+};

package/jx-extension.json

@@ -0,0 +1,7 @@
+{
+  "name": "@jxsuite/feed",
+  "title": "Feeds",
+  "description": "Atom (RFC 4287) and JSON Feed generation from content collections, with RFC 5005 archives and automatic <link rel=\"alternate\"> discovery",
+  "classes": { "Feed": "./src/Feed.class.json" },
+  "schemas": { "project": "./schemas/project.fragment.schema.json" }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@jxsuite/feed",
+  "version": "0.1.0",
+  "description": "Syndication feeds for Jx: Atom (RFC 4287) and JSON Feed emitted from content collections at build time",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "extensions/feed"
+  },
+  "files": [
+    "src/",
+    "dist",
+    "jx-extension.json",
+    "schemas/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/feed.ts",
+    "./atom": "./src/atom.ts",
+    "./json-feed": "./src/json-feed.ts",
+    "./shared": "./src/shared.ts",
+    "./jx-extension.json": "./jx-extension.json",
+    "./schemas/project.fragment.schema.json": "./schemas/project.fragment.schema.json",
+    "./Feed.class.json": "./src/Feed.class.json"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "prepare": "bun build src/feed.ts --outdir=dist --format=esm --target=node",
+    "build": "bun run prepare",
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0"
+  },
+  "jx": "./jx-extension.json"
+}

package/schemas/project.fragment.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schema/extensions/feed/v1",
+  "title": "@jxsuite/feed project section",
+  "type": "object",
+  "properties": {
+    "feed": {
+      "type": "object",
+      "description": "Syndication feeds generated from content collections (@jxsuite/feed)",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["collection", "basePath"],
+        "additionalProperties": false,
+        "properties": {
+          "collection": {
+            "type": "string",
+            "description": "The content collection this feed syndicates"
+          },
+          "basePath": {
+            "type": "string",
+            "pattern": "^/",
+            "description": "URL prefix the collection's entries are served under, e.g. \"/blog/\""
+          },
+          "title": { "type": "string" },
+          "description": { "type": "string" },
+          "formats": {
+            "type": "array",
+            "items": { "enum": ["atom", "json"] },
+            "default": ["atom", "json"],
+            "description": "RSS 2.0 is deliberately not offered: it has no standards body and every reader handles Atom."
+          },
+          "output": {
+            "type": "string",
+            "pattern": "^/",
+            "default": "/feed",
+            "description": "Base path; .xml and .json are appended"
+          },
+          "pageSize": { "type": "integer", "minimum": 1, "default": 20 },
+          "archive": {
+            "type": "boolean",
+            "default": false,
+            "description": "Emit RFC 5005 archived feeds for entries beyond pageSize"
+          },
+          "author": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "uri": { "type": "string" },
+              "email": { "type": "string" }
+            }
+          },
+          "dateField": { "type": "string", "default": "date" },
+          "updatedField": { "type": "string", "default": "updated" },
+          "contentMode": { "enum": ["full", "summary", "none"], "default": "summary" },
+          "language": {
+            "type": "string",
+            "description": "BCP 47 language tag; defaults to defaults.lang"
+          }
+        }
+      }
+    }
+  }
+}