@molecule/api-feed-rss 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-feed-rss` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-feed-rss is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/escape.d.ts

@@ -0,0 +1,66 @@
+/**
+ * XML / CDATA / URL escape helpers used by every serializer.
+ *
+ * **All user-supplied content MUST flow through one of these helpers**
+ * before it lands in serialized output. The serializers in this package
+ * call them defensively at every interpolation site, but consumers
+ * extending this package (e.g. adding a custom namespace) MUST do the same.
+ *
+ * @module
+ */
+/**
+ * Escape a string for inclusion in an XML text node or attribute value.
+ *
+ * Maps the five XML predefined entities:
+ * - `&` → `&`
+ * - `<` → `&lt;`
+ * - `>` → `&gt;`
+ * - `"` → `&quot;`
+ * - `'` → `&apos;`
+ *
+ * Also strips XML 1.0 illegal control characters (`U+0000`–`U+0008`,
+ * `U+000B`, `U+000C`, `U+000E`–`U+001F`). `\t`, `\n`, `\r` are preserved.
+ *
+ * @param value - Raw string. `undefined` / `null` collapse to `''`.
+ * @returns Escaped string safe for any XML position.
+ */
+export declare function escapeXml(value: string | number | boolean | null | undefined): string;
+/**
+ * Wrap an HTML payload in a `<![CDATA[ ... ]]>` section, splitting any
+ * accidental closing-marker (`]]>`) inside the payload across two CDATA
+ * sections so the result remains valid XML.
+ *
+ * Use for `<description>` / `<content:encoded>` / Atom `<content type="html">`
+ * where the body is HTML and we want to avoid double-escaping.
+ *
+ * Also strips XML 1.0 illegal control characters before wrapping (`\t`,
+ * `\n`, `\r` preserved). The CDATA payload still cannot contain raw
+ * `<![CDATA[` openers, but those are not produced by typical HTML and
+ * any literal occurrence is treated as ordinary text by browsers.
+ *
+ * @param value - Raw HTML / text. `undefined` / `null` collapse to `''`.
+ * @returns A complete CDATA section, e.g. `<![CDATA[<p>x</p>]]>`.
+ */
+export declare function wrapCdata(value: string | null | undefined): string;
+/**
+ * Escape an attribute value (alias of {@link escapeXml} kept distinct so
+ * future tightening — e.g. enforcing quote style — has a single call site).
+ *
+ * @param value - Raw attribute value.
+ * @returns Escaped string suitable for `="..."` attribute syntax.
+ */
+export declare function escapeAttr(value: string | number | boolean | null | undefined): string;
+/**
+ * Validate + escape a URL for safe use as an `href` / `src` / RSS `<link>`
+ * value. Strips `javascript:` and other dangerous schemes — those are
+ * replaced with `about:blank`.
+ *
+ * Allowed schemes (case-insensitive): `http`, `https`, `mailto`, `ftp`,
+ * `tel`, plus protocol-relative (`//...`) and absolute paths (`/...`) and
+ * relative paths (`./...`, `../...`, `name`, `name?...`, `name#...`).
+ *
+ * @param value - Raw URL. `undefined` / `null` collapse to `''`.
+ * @returns Escaped URL or `'about:blank'` for disallowed schemes.
+ */
+export declare function escapeUrl(value: string | null | undefined): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAiBrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAclE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAEtF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAYlE"}

package/dist/escape.js

@@ -0,0 +1,122 @@
+/**
+ * XML / CDATA / URL escape helpers used by every serializer.
+ *
+ * **All user-supplied content MUST flow through one of these helpers**
+ * before it lands in serialized output. The serializers in this package
+ * call them defensively at every interpolation site, but consumers
+ * extending this package (e.g. adding a custom namespace) MUST do the same.
+ *
+ * @module
+ */
+/**
+ * Escape a string for inclusion in an XML text node or attribute value.
+ *
+ * Maps the five XML predefined entities:
+ * - `&` → `&`
+ * - `<` → `&lt;`
+ * - `>` → `&gt;`
+ * - `"` → `&quot;`
+ * - `'` → `&apos;`
+ *
+ * Also strips XML 1.0 illegal control characters (`U+0000`–`U+0008`,
+ * `U+000B`, `U+000C`, `U+000E`–`U+001F`). `\t`, `\n`, `\r` are preserved.
+ *
+ * @param value - Raw string. `undefined` / `null` collapse to `''`.
+ * @returns Escaped string safe for any XML position.
+ */
+export function escapeXml(value) {
+    if (value === undefined || value === null)
+        return '';
+    const s = typeof value === 'string' ? value : String(value);
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        // Strip XML 1.0 illegal control chars (allow \t=9, \n=10, \r=13).
+        if (ch < 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d)
+            continue;
+        const c = s[i];
+        if (c === '&')
+            out += '&amp;';
+        else if (c === '<')
+            out += '&lt;';
+        else if (c === '>')
+            out += '&gt;';
+        else if (c === '"')
+            out += '&quot;';
+        else if (c === "'")
+            out += '&apos;';
+        else
+            out += c;
+    }
+    return out;
+}
+/**
+ * Wrap an HTML payload in a `<![CDATA[ ... ]]>` section, splitting any
+ * accidental closing-marker (`]]>`) inside the payload across two CDATA
+ * sections so the result remains valid XML.
+ *
+ * Use for `<description>` / `<content:encoded>` / Atom `<content type="html">`
+ * where the body is HTML and we want to avoid double-escaping.
+ *
+ * Also strips XML 1.0 illegal control characters before wrapping (`\t`,
+ * `\n`, `\r` preserved). The CDATA payload still cannot contain raw
+ * `<![CDATA[` openers, but those are not produced by typical HTML and
+ * any literal occurrence is treated as ordinary text by browsers.
+ *
+ * @param value - Raw HTML / text. `undefined` / `null` collapse to `''`.
+ * @returns A complete CDATA section, e.g. `<![CDATA[<p>x</p>]]>`.
+ */
+export function wrapCdata(value) {
+    if (value === undefined || value === null || value === '') {
+        return '<![CDATA[]]>';
+    }
+    // Strip illegal XML 1.0 control chars first.
+    let cleaned = '';
+    for (let i = 0; i < value.length; i++) {
+        const ch = value.charCodeAt(i);
+        if (ch < 0x20 && ch !== 0x09 && ch !== 0x0a && ch !== 0x0d)
+            continue;
+        cleaned += value[i];
+    }
+    // Split any embedded `]]>` so it can't terminate the CDATA early.
+    const safe = cleaned.split(']]>').join(']]]]><![CDATA[>');
+    return `<![CDATA[${safe}]]>`;
+}
+/**
+ * Escape an attribute value (alias of {@link escapeXml} kept distinct so
+ * future tightening — e.g. enforcing quote style — has a single call site).
+ *
+ * @param value - Raw attribute value.
+ * @returns Escaped string suitable for `="..."` attribute syntax.
+ */
+export function escapeAttr(value) {
+    return escapeXml(value);
+}
+/**
+ * Validate + escape a URL for safe use as an `href` / `src` / RSS `<link>`
+ * value. Strips `javascript:` and other dangerous schemes — those are
+ * replaced with `about:blank`.
+ *
+ * Allowed schemes (case-insensitive): `http`, `https`, `mailto`, `ftp`,
+ * `tel`, plus protocol-relative (`//...`) and absolute paths (`/...`) and
+ * relative paths (`./...`, `../...`, `name`, `name?...`, `name#...`).
+ *
+ * @param value - Raw URL. `undefined` / `null` collapse to `''`.
+ * @returns Escaped URL or `'about:blank'` for disallowed schemes.
+ */
+export function escapeUrl(value) {
+    if (value === undefined || value === null)
+        return '';
+    const s = String(value).trim();
+    if (s === '')
+        return '';
+    // Match `<scheme>:` (must start with a letter, then [a-z0-9+.-]).
+    const schemeMatch = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(s);
+    if (schemeMatch) {
+        const scheme = schemeMatch[1].toLowerCase();
+        const allowed = new Set(['http', 'https', 'mailto', 'ftp', 'tel']);
+        if (!allowed.has(scheme))
+            return 'about:blank';
+    }
+    return escapeXml(s);
+}

package/dist/handler.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Framework-agnostic HTTP handler factory for serving feed output at
+ * `GET /<mountPath>.{rss|atom|json}` (or any path scheme the caller wires
+ * via the `extensions` map).
+ *
+ * Returns a request handler whose signature is intentionally minimal so
+ * the same builder works with Express (`(req, res, next)` adapter), Hono,
+ * Fastify, raw Node `http`, or a worker `fetch` handler.
+ *
+ * @module
+ */
+import type { Feed, FeedOutputFormat } from './types.js';
+/**
+ * Configuration for {@link createFeedHandler}.
+ */
+export interface CreateFeedHandlerOptions {
+    /**
+     * Async loader returning the feed snapshot. Called whenever the cache is
+     * cold or expired. Must throw on data-source failure — the handler then
+     * returns `503 Service Unavailable`.
+     */
+    loadFeed: () => Promise<Feed> | Feed;
+    /**
+     * Cache TTL in milliseconds. Defaults to `60_000` (1 minute). Set to
+     * `0` to disable caching (every request re-loads).
+     */
+    cacheTtlMs?: number;
+    /**
+     * Map of URL-suffix → {@link FeedOutputFormat}.
+     *
+     * Defaults to `{ rss: 'rss-2.0', atom: 'atom-1.0', json: 'json-feed' }`.
+     *
+     * The handler reads the request path's extension via {@link FeedRequest.extension}
+     * (callers compute this from the URL — see the function-level docs).
+     */
+    extensions?: Record<string, FeedOutputFormat>;
+    /**
+     * Optional logger called on errors. Defaults to a no-op.
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Minimal request shape consumed by the generated handler.
+ */
+export interface FeedRequest {
+    /**
+     * URL extension portion — `'rss'`, `'atom'`, `'json'`, or any custom key
+     * the caller wired in {@link CreateFeedHandlerOptions.extensions}.
+     *
+     * Callers compute this from the request URL (e.g.
+     * `req.path.split('.').pop()` for Express).
+     */
+    extension: string;
+    /** Optional `If-None-Match` ETag value, for 304 short-circuiting. */
+    ifNoneMatch?: string;
+}
+/**
+ * Minimal response shape returned by the handler. Framework adapters map
+ * this onto their native response API (`res.status().set().send()` for
+ * Express, `new Response(body, { status, headers })` for fetch, etc.).
+ */
+export interface FeedResponse {
+    /** HTTP status code: `200` / `304` / `404` / `503`. */
+    status: number;
+    /** Headers — always includes `Content-Type` on `200`. */
+    headers: Record<string, string>;
+    /** Body — empty string on `304` / `404` / errors. */
+    body: string;
+}
+/**
+ * Create a framework-agnostic feed HTTP handler with built-in TTL caching.
+ *
+ * The returned handler accepts a {@link FeedRequest} and returns a
+ * {@link FeedResponse}. It serves three formats by default — RSS 2.0,
+ * Atom 1.0, JSON Feed — keyed by URL extension.
+ *
+ * **Caching** — feed payloads are cached per-format for `cacheTtlMs`
+ * (default 1 minute). Each cache entry carries an ETag computed from the
+ * payload hash; matching `If-None-Match` triggers a `304` response.
+ *
+ * **Error handling** — if `loadFeed` throws, the handler returns `503`
+ * with body `''`. The error is forwarded to `onError` if provided.
+ *
+ * **No XSS surface** — all interpolation runs through the underlying
+ * serializers (`serializeRss2` / `serializeAtom1` / `serializeJsonFeed`),
+ * which escape every user-supplied field. The handler itself never
+ * concatenates request data into the response body.
+ *
+ * @example Express adapter
+ * ```ts
+ * import express from 'express'
+ * import { createFeedHandler } from '@molecule/api-feed-rss'
+ *
+ * const handle = createFeedHandler({
+ *   loadFeed: async () => ({
+ *     title: 'Blog',
+ *     link: 'https://example.com',
+ *     description: '...',
+ *     items: await db.posts.findMany(...),
+ *   }),
+ * })
+ *
+ * const app = express()
+ * app.get('/feed.:ext', async (req, res) => {
+ *   const result = await handle({
+ *     extension: req.params.ext,
+ *     ifNoneMatch: req.get('If-None-Match'),
+ *   })
+ *   res.status(result.status).set(result.headers).send(result.body)
+ * })
+ * ```
+ *
+ * @param options - See {@link CreateFeedHandlerOptions}.
+ * @returns Async handler function `(req: FeedRequest) => Promise<FeedResponse>`.
+ */
+export declare function createFeedHandler(options: CreateFeedHandlerOptions): (req: FeedRequest) => Promise<FeedResponse>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAcxD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAEpC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAE7C;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAA;IAEd,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE/B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;CACb;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAmD7C"}

package/dist/handler.js

@@ -0,0 +1,128 @@
+/**
+ * Framework-agnostic HTTP handler factory for serving feed output at
+ * `GET /<mountPath>.{rss|atom|json}` (or any path scheme the caller wires
+ * via the `extensions` map).
+ *
+ * Returns a request handler whose signature is intentionally minimal so
+ * the same builder works with Express (`(req, res, next)` adapter), Hono,
+ * Fastify, raw Node `http`, or a worker `fetch` handler.
+ *
+ * @module
+ */
+import { FEED_CONTENT_TYPES, serializeFeed } from './serializeFeed.js';
+const DEFAULT_EXTENSIONS = {
+    rss: 'rss-2.0',
+    atom: 'atom-1.0',
+    json: 'json-feed',
+};
+/**
+ * djb2-style hash, base36-encoded — used for ETag generation. Not
+ * cryptographic; collisions are tolerable for HTTP caching.
+ *
+ * @param s - Input string.
+ * @returns Compact base36 hash.
+ */
+function hash(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) {
+        h = (h * 33) ^ s.charCodeAt(i);
+    }
+    return (h >>> 0).toString(36);
+}
+/**
+ * Create a framework-agnostic feed HTTP handler with built-in TTL caching.
+ *
+ * The returned handler accepts a {@link FeedRequest} and returns a
+ * {@link FeedResponse}. It serves three formats by default — RSS 2.0,
+ * Atom 1.0, JSON Feed — keyed by URL extension.
+ *
+ * **Caching** — feed payloads are cached per-format for `cacheTtlMs`
+ * (default 1 minute). Each cache entry carries an ETag computed from the
+ * payload hash; matching `If-None-Match` triggers a `304` response.
+ *
+ * **Error handling** — if `loadFeed` throws, the handler returns `503`
+ * with body `''`. The error is forwarded to `onError` if provided.
+ *
+ * **No XSS surface** — all interpolation runs through the underlying
+ * serializers (`serializeRss2` / `serializeAtom1` / `serializeJsonFeed`),
+ * which escape every user-supplied field. The handler itself never
+ * concatenates request data into the response body.
+ *
+ * @example Express adapter
+ * ```ts
+ * import express from 'express'
+ * import { createFeedHandler } from '@molecule/api-feed-rss'
+ *
+ * const handle = createFeedHandler({
+ *   loadFeed: async () => ({
+ *     title: 'Blog',
+ *     link: 'https://example.com',
+ *     description: '...',
+ *     items: await db.posts.findMany(...),
+ *   }),
+ * })
+ *
+ * const app = express()
+ * app.get('/feed.:ext', async (req, res) => {
+ *   const result = await handle({
+ *     extension: req.params.ext,
+ *     ifNoneMatch: req.get('If-None-Match'),
+ *   })
+ *   res.status(result.status).set(result.headers).send(result.body)
+ * })
+ * ```
+ *
+ * @param options - See {@link CreateFeedHandlerOptions}.
+ * @returns Async handler function `(req: FeedRequest) => Promise<FeedResponse>`.
+ */
+export function createFeedHandler(options) {
+    const ttl = options.cacheTtlMs ?? 60_000;
+    const extMap = { ...DEFAULT_EXTENSIONS, ...(options.extensions ?? {}) };
+    const onError = options.onError ?? (() => { });
+    const cache = new Map();
+    return async function handle(req) {
+        const ext = (req.extension ?? '').toLowerCase();
+        const format = extMap[ext];
+        if (!format) {
+            return { status: 404, headers: {}, body: '' };
+        }
+        const now = Date.now();
+        let entry = cache.get(format);
+        if (!entry || (ttl > 0 && now - entry.generatedAt > ttl) || ttl === 0) {
+            try {
+                const feed = await options.loadFeed();
+                const body = serializeFeed(feed, format);
+                entry = {
+                    body,
+                    contentType: FEED_CONTENT_TYPES[format],
+                    generatedAt: now,
+                    etag: `"${hash(body)}"`,
+                };
+                if (ttl > 0)
+                    cache.set(format, entry);
+                else
+                    cache.delete(format);
+            }
+            catch (err) {
+                onError(err);
+                return { status: 503, headers: {}, body: '' };
+            }
+        }
+        if (req.ifNoneMatch && req.ifNoneMatch === entry.etag) {
+            return {
+                status: 304,
+                headers: { ETag: entry.etag },
+                body: '',
+            };
+        }
+        return {
+            status: 200,
+            headers: {
+                'Content-Type': entry.contentType,
+                ETag: entry.etag,
+                'Cache-Control': ttl > 0 ? `public, max-age=${Math.floor(ttl / 1000)}` : 'no-store',
+            },
+            body: entry.body,
+        };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * RSS / Atom / JSON Feed **producer** for molecule.dev — pure-function
+ * serializers that turn a single normalized {@link Feed} structure into
+ * a valid RSS 2.0, Atom 1.0, or JSON Feed 1.1 document.
+ *
+ * Companion to `@molecule/api-feed-rss-parser` (the consumer side). Both
+ * packages share a similar normalized shape, so apps can ingest external
+ * feeds, store the items, and re-publish them through this package
+ * without intermediate translation layers.
+ *
+ * Apps that use this:
+ * - `blog` — emit `/feed.rss`, `/feed.atom`, `/feed.json` for posts.
+ * - `news-aggregator` — re-publish curated cross-source feeds.
+ * - `podcast` — RSS 2.0 with the iTunes namespace (set `feed.itunes`).
+ *
+ * @example One serializer per call
+ * ```ts
+ * import { serializeRss2, serializeAtom1, serializeJsonFeed } from '@molecule/api-feed-rss'
+ *
+ * const feed = {
+ *   title: 'My Blog',
+ *   link: 'https://example.com',
+ *   description: 'Posts about software',
+ *   items: [{ id: '1', title: 'Hello', link: 'https://example.com/p/1' }],
+ * }
+ *
+ * const rss = serializeRss2(feed)
+ * const atom = serializeAtom1(feed)
+ * const json = serializeJsonFeed(feed)
+ * ```
+ *
+ * @example HTTP handler with caching — Express adapter
+ * ```ts
+ * import { createFeedHandler, type Feed } from '@molecule/api-feed-rss'
+ *
+ * const loadFromDb = async (): Promise<Feed> => ({ title: 'My Feed', link: 'https://example.com', description: 'Latest posts', items: [] }) // your DB lookup
+ * const app = { get(_path: string, _fn: (req: any, res: any) => void): void {} } // your Express app
+ *
+ * const handle = createFeedHandler({
+ *   loadFeed: async () => loadFromDb(),
+ *   cacheTtlMs: 60_000,
+ * })
+ *
+ * // Serves GET /feed.rss, /feed.atom, /feed.json (keyed by extension).
+ * // The handler returns { status, headers, body } — map those onto any
+ * // framework's response (Fastify/Hono/raw http look the same).
+ * app.get('/feed.:ext', async (req, res) => {
+ *   const result = await handle({
+ *     extension: req.params.ext,
+ *     ifNoneMatch: req.get('If-None-Match'),
+ *   })
+ *   res.status(result.status).set(result.headers).send(result.body)
+ * })
+ * ```
+ *
+ * **Security**: every user-supplied field is escaped before serialization.
+ * RSS / Atom XML use {@link escapeXml} for text nodes, {@link escapeAttr}
+ * for attributes, {@link escapeUrl} for URL attributes (which neutralizes
+ * `javascript:` URIs), and {@link wrapCdata} for HTML content (with
+ * `]]>` splitting). JSON Feed relies on `JSON.stringify` for escaping.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './escape.js';
+export * from './handler.js';
+export * from './serializeAtom1.js';
+export * from './serializeFeed.js';
+export * from './serializeJsonFeed.js';
+export * from './serializeRss2.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AACtC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}