npm - @canonical/react-ssr - Versions diffs - 0.22.0 → 0.24.0 - Mend

@canonical/react-ssr 0.22.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

package/dist/esm/bin/serve-express.js +86 -0
package/dist/esm/bin/serve-express.js.map +1 -0
package/dist/esm/index.js +3 -2
package/dist/esm/index.js.map +1 -1
package/dist/esm/lib/adapter/index.js +2 -0
package/dist/esm/lib/adapter/index.js.map +1 -0
package/dist/esm/lib/adapter/mime.js +85 -0
package/dist/esm/lib/adapter/mime.js.map +1 -0
package/dist/esm/lib/adapter/types.js +10 -0
package/dist/esm/lib/adapter/types.js.map +1 -0
package/dist/esm/lib/index.js +4 -0
package/dist/esm/lib/index.js.map +1 -0
package/dist/esm/lib/renderer/Extractor.js +172 -0
package/dist/esm/lib/renderer/Extractor.js.map +1 -0
package/dist/esm/lib/renderer/JSXRenderer.js +283 -0
package/dist/esm/lib/renderer/JSXRenderer.js.map +1 -0
package/dist/esm/lib/renderer/SitemapRenderer.js +241 -0
package/dist/esm/lib/renderer/SitemapRenderer.js.map +1 -0
package/dist/esm/lib/renderer/TextRenderer.js +124 -0
package/dist/esm/lib/renderer/TextRenderer.js.map +1 -0
package/dist/esm/lib/renderer/constants.js.map +1 -0
package/dist/esm/lib/renderer/index.js +6 -0
package/dist/esm/lib/renderer/index.js.map +1 -0
package/dist/esm/lib/renderer/types.js +10 -0
package/dist/esm/lib/renderer/types.js.map +1 -0
package/dist/esm/lib/server/index.js +3 -0
package/dist/esm/lib/server/index.js.map +1 -0
package/dist/esm/lib/server/serveStream.js +53 -0
package/dist/esm/lib/server/serveStream.js.map +1 -0
package/dist/esm/lib/server/serveString.js +49 -0
package/dist/esm/lib/server/serveString.js.map +1 -0
package/dist/types/bin/serve-express.d.ts +24 -0
package/dist/types/bin/serve-express.d.ts.map +1 -0
package/dist/types/index.d.ts +3 -2
package/dist/types/index.d.ts.map +1 -1
package/dist/types/lib/adapter/index.d.ts +3 -0
package/dist/types/lib/adapter/index.d.ts.map +1 -0
package/dist/types/lib/adapter/mime.d.ts +43 -0
package/dist/types/lib/adapter/mime.d.ts.map +1 -0
package/dist/types/lib/adapter/types.d.ts +85 -0
package/dist/types/lib/adapter/types.d.ts.map +1 -0
package/dist/types/lib/index.d.ts +4 -0
package/dist/types/lib/index.d.ts.map +1 -0
package/dist/types/lib/renderer/Extractor.d.ts +93 -0
package/dist/types/lib/renderer/Extractor.d.ts.map +1 -0
package/dist/types/lib/renderer/JSXRenderer.d.ts +163 -0
package/dist/types/lib/renderer/JSXRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/SitemapRenderer.d.ts +153 -0
package/dist/types/lib/renderer/SitemapRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/TextRenderer.d.ts +83 -0
package/dist/types/lib/renderer/TextRenderer.d.ts.map +1 -0
package/dist/types/lib/renderer/constants.d.ts.map +1 -0
package/dist/types/lib/renderer/index.d.ts +7 -0
package/dist/types/lib/renderer/index.d.ts.map +1 -0
package/dist/types/lib/renderer/types.d.ts +161 -0
package/dist/types/lib/renderer/types.d.ts.map +1 -0
package/dist/types/lib/server/index.d.ts +3 -0
package/dist/types/lib/server/index.d.ts.map +1 -0
package/dist/types/lib/server/serveStream.d.ts +41 -0
package/dist/types/lib/server/serveStream.d.ts.map +1 -0
package/dist/types/lib/server/serveString.d.ts +37 -0
package/dist/types/lib/server/serveString.d.ts.map +1 -0
package/package.json +37 -17
package/dist/esm/renderer/Extractor.js +0 -127
package/dist/esm/renderer/Extractor.js.map +0 -1
package/dist/esm/renderer/JSXRenderer.js +0 -168
package/dist/esm/renderer/JSXRenderer.js.map +0 -1
package/dist/esm/renderer/constants.js.map +0 -1
package/dist/esm/renderer/index.js +0 -4
package/dist/esm/renderer/index.js.map +0 -1
package/dist/esm/renderer/types.js +0 -2
package/dist/esm/renderer/types.js.map +0 -1
package/dist/esm/server/index.js +0 -2
package/dist/esm/server/index.js.map +0 -1
package/dist/esm/server/serve-express.js +0 -58
package/dist/esm/server/serve-express.js.map +0 -1
package/dist/esm/server/serve.js +0 -41
package/dist/esm/server/serve.js.map +0 -1
package/dist/types/renderer/Extractor.d.ts +0 -68
package/dist/types/renderer/Extractor.d.ts.map +0 -1
package/dist/types/renderer/JSXRenderer.d.ts +0 -71
package/dist/types/renderer/JSXRenderer.d.ts.map +0 -1
package/dist/types/renderer/constants.d.ts.map +0 -1
package/dist/types/renderer/index.d.ts +0 -5
package/dist/types/renderer/index.d.ts.map +0 -1
package/dist/types/renderer/types.d.ts +0 -35
package/dist/types/renderer/types.d.ts.map +0 -1
package/dist/types/server/index.d.ts +0 -2
package/dist/types/server/index.d.ts.map +0 -1
package/dist/types/server/serve-express.d.ts +0 -3
package/dist/types/server/serve-express.d.ts.map +0 -1
package/dist/types/server/serve.d.ts +0 -30
package/dist/types/server/serve.d.ts.map +0 -1
/package/dist/esm/{renderer → lib/renderer}/constants.js +0 -0
/package/dist/types/{renderer → lib/renderer}/constants.d.ts +0 -0

package/dist/esm/lib/renderer/JSXRenderer.js ADDED Viewed

@@ -0,0 +1,283 @@
+import { createElement } from "react";
+import { renderToPipeableStream as reactRenderToPipeableStream, renderToReadableStream as reactRenderToReadableStream, renderToString as reactRenderToString, } from "react-dom/server";
+import { INITIAL_DATA_KEY } from "./constants.js";
+import Extractor from "./Extractor.js";
+/**
+ * Server-side renderer for a React component.
+ *
+ * Accepts a React `ServerEntrypoint` component, optional initial data for
+ * hydration, and an optional HTML shell string (from a Vite build) whose
+ * `<head>` tags are extracted and injected into the rendered output.
+ *
+ * Three rendering strategies are available:
+ *
+ * - **ReadableStream** (`renderToReadableStream`) — returns a web `ReadableStream`.
+ *   Works natively with Bun, Deno, Cloudflare Workers, and any runtime that
+ *   supports the Web Streams API. Supports Suspense and progressive rendering.
+ *
+ * - **PipeableStream** (`renderToPipeableStream`) — returns a Node.js pipeable stream.
+ *   Works with Express, Fastify, and Node's built-in `http` module. Supports Suspense
+ *   and progressive rendering.
+ *
+ * - **String** (`renderToString`) — returns the full HTML as a string. All Suspense
+ *   boundaries resolve synchronously. The output is cacheable and works with Vite
+ *   HMR in dev mode.
+ *
+ * All strategies inject `<script>` and `<link>` tags from the HTML shell via
+ * React's `bootstrapScripts` / `bootstrapModules` mechanism, and embed
+ * `initialData` as a global `window.__INITIAL_DATA__` variable for client
+ * hydration.
+ *
+ * The renderer is transport-agnostic — it never writes to a response object.
+ * HTTP status codes and metadata are exposed via `statusCode` and `statusReady`
+ * for the consumer to use when constructing the response.
+ *
+ * @typeParam TComponent - The server entrypoint component type.
+ * @typeParam InitialData - Shape of the data embedded for client hydration.
+ */
+export default class JSXRenderer {
+    Component;
+    initialData;
+    options;
+    extractor;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Starts at 200 and is set to 500 if a shell error occurs during streaming.
+     * For `renderToString`, it is always 200 (errors throw instead).
+     *
+     * Read this after the render method returns (for `renderToReadableStream` and
+     * `renderToString`) or after awaiting `statusReady` (for `renderToPipeableStream`).
+     */
+    statusCode = 200;
+    /**
+     * Resolves when `statusCode` is determined.
+     *
+     * For `renderToReadableStream` and `renderToString`, this is already resolved
+     * by the time the method returns. For `renderToPipeableStream`, it resolves
+     * asynchronously when the shell is ready or errors.
+     */
+    statusReady = Promise.resolve();
+    /**
+     * Create a renderer bound to a specific component and initial data.
+     *
+     * If `options.htmlString` is provided, the HTML is parsed once to extract
+     * `<head>` elements. These elements are then available as React elements
+     * via `getComponentProps()` for injection during rendering.
+     *
+     * @param Component - The React server entrypoint component.
+     * @param initialData - Data to embed in `window.__INITIAL_DATA__` for client hydration.
+     * @param options - Renderer configuration: locale, HTML shell, and stream options.
+     */
+    constructor(Component, initialData = {}, options = {}) {
+        this.Component = Component;
+        this.initialData = initialData;
+        this.options = options;
+        this.extractor = this.options.htmlString
+            ? new Extractor(this.options.htmlString)
+            : undefined;
+    }
+    /**
+     * Return the locale for the rendered page.
+     *
+     * Defaults to `"en"` when no `defaultLocale` was provided in options.
+     * The locale is passed as the `lang` prop to the server entrypoint component,
+     * which typically sets it as the `<html lang>` attribute.
+     */
+    getLocale() {
+        return this.options.defaultLocale || "en";
+    }
+    /**
+     * Assemble the props passed to the server entrypoint component.
+     *
+     * Combines the locale, initial data, and (when an HTML shell was provided)
+     * the extracted script, link, and other head elements into a single props
+     * object conforming to `ServerEntrypointProps`.
+     */
+    getComponentProps() {
+        return {
+            lang: this.getLocale(),
+            scriptElements: this.extractor?.getScriptElements(),
+            linkElements: this.extractor?.getLinkElements(),
+            otherHeadElements: this.extractor?.getOtherHeadElements(),
+            initialData: this.initialData,
+        };
+    }
+    /**
+     * Extract `src` URLs from script elements that match a given loading strategy.
+     *
+     * Filters the provided React `<script>` elements by their `type` attribute:
+     * `"module"` selects ES module scripts, `"classic"` selects everything else.
+     * Returns only the `src` values, discarding inline scripts that have no `src`.
+     *
+     * @param scripts - React elements representing `<script>` tags.
+     * @param type - `"module"` for ES modules, `"classic"` for traditional scripts.
+     * @returns An array of script source URLs.
+     */
+    getScriptSourcesByType(scripts, type) {
+        return scripts
+            .map((script) => script)
+            .filter((script) => {
+            if (type === "module") {
+                return script.props.type === "module";
+            }
+            return script.props.type !== "module";
+        })
+            .map((script) => script.props.src)
+            .filter((src) => typeof src === "string");
+    }
+    /**
+     * Merge renderer-managed options into the user-provided stream options.
+     *
+     * Populates three React streaming options unless the caller already supplied them:
+     *
+     * - `bootstrapScriptContent` — a `<script>` body that assigns `initialData` to
+     *   `window.__INITIAL_DATA__`. The JSON is escaped to prevent `</script>` injection.
+     * - `bootstrapScripts` — `src` URLs for classic (non-module) scripts extracted from
+     *   the HTML shell. React strips `<script>` tags during streaming, so these must
+     *   be re-injected through this mechanism.
+     * - `bootstrapModules` — same as above, for ES module scripts.
+     *
+     * @param props - The assembled component props (used to read `initialData` and `scriptElements`).
+     * @returns A merged options object safe to pass to either streaming API.
+     */
+    enrichRendererOptions(props) {
+        const enrichedOptions = {
+            ...this.options.renderToPipeableStreamOptions,
+        };
+        if (!enrichedOptions.bootstrapScriptContent) {
+            if (props.initialData) {
+                enrichedOptions.bootstrapScriptContent = `window.${INITIAL_DATA_KEY} = ${JSON.stringify(props.initialData).replace(/</g, "\\u003c")}`;
+            }
+        }
+        if (!enrichedOptions.bootstrapScripts) {
+            if (props.scriptElements) {
+                enrichedOptions.bootstrapScripts = this.getScriptSourcesByType(props.scriptElements, "classic");
+            }
+        }
+        if (!enrichedOptions.bootstrapModules) {
+            if (props.scriptElements) {
+                enrichedOptions.bootstrapModules = this.getScriptSourcesByType(props.scriptElements, "module");
+            }
+        }
+        return enrichedOptions;
+    }
+    /**
+     * Render the component to a web `ReadableStream`.
+     *
+     * Uses `react-dom/server.renderToReadableStream` for environments that support
+     * the Web Streams API (Bun, Deno, Cloudflare Workers, browsers). Supports
+     * Suspense and progressive rendering.
+     *
+     * On shell error, `statusCode` is set to 500 and a fallback HTML stream is
+     * returned. On success, `statusCode` is 200.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @param signal - Optional `AbortSignal` for request cancellation.
+     * @returns A `ReadableStream` of the rendered HTML.
+     */
+    renderToReadableStream = async (signal) => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const { onError: onErrorCallback,
+        // Strip pipeable-only callbacks — they don't exist on RenderToReadableStreamOptions
+        onShellReady: _onShellReady, onShellError: _onShellError, onAllReady: _onAllReady, ...options } = this.enrichRendererOptions(props);
+        try {
+            const stream = await reactRenderToReadableStream(jsx, {
+                ...options,
+                ...(this.options.renderToReadableStreamOptions ?? {}),
+                signal,
+                onError: (error, errorInfo) => {
+                    onErrorCallback?.(error, errorInfo);
+                    console.error(error);
+                },
+            });
+            this.statusCode = 200;
+            this.statusReady = Promise.resolve();
+            return stream;
+        }
+        catch (error) {
+            console.error(error);
+            this.statusCode = 500;
+            this.statusReady = Promise.resolve();
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(new TextEncoder().encode("<h1>Something went wrong</h1>"));
+                    controller.close();
+                },
+            });
+        }
+    };
+    /**
+     * Render the component to a Node.js pipeable stream.
+     *
+     * Uses `react-dom/server.renderToPipeableStream` for Node.js environments
+     * (Express, Fastify, plain `http.createServer`). Supports Suspense and
+     * progressive rendering.
+     *
+     * Returns `{ pipe, abort }` synchronously. The `statusCode` is set
+     * asynchronously when the shell is ready or errors — await `statusReady`
+     * before reading it.
+     *
+     * @note This method is impure — it mutates `statusCode` and `statusReady`.
+     *
+     * @returns The pipe/abort handles for the rendered stream.
+     */
+    renderToPipeableStream = () => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const { onShellError: onShellErrorCallback, onShellReady: onShellReadyCallback, onAllReady: onAllReadyCallback, onError: onErrorCallback, ...options } = this.enrichRendererOptions(props);
+        const errorRef = { current: undefined };
+        let resolveStatus;
+        this.statusReady = new Promise((resolve) => {
+            resolveStatus = resolve;
+        });
+        const jsxStream = reactRenderToPipeableStream(jsx, {
+            ...options,
+            onError(error, errorInfo) {
+                onErrorCallback?.(error, errorInfo);
+                errorRef.current = error;
+                console.error(error);
+            },
+            onShellError: (error) => {
+                onShellErrorCallback?.(error);
+                this.statusCode = 500;
+                resolveStatus();
+                console.error(error);
+            },
+            onShellReady: () => {
+                onShellReadyCallback?.();
+                /* v8 ignore next -- errorRef.current is set by onError which fires before onShellReady in edge cases */
+                this.statusCode = errorRef.current ? 500 : 200;
+                resolveStatus();
+            },
+            onAllReady() {
+                onAllReadyCallback?.();
+            },
+        });
+        return { pipe: jsxStream.pipe, abort: jsxStream.abort };
+    };
+    /**
+     * Render the component to a complete HTML string.
+     *
+     * Uses `react-dom/server.renderToString` to produce the full HTML
+     * synchronously. All Suspense boundaries resolve before the method returns.
+     * The output is cacheable and compatible with Vite's HMR in dev mode.
+     *
+     * Sets `statusCode` to 200 on success. On error, throws (consumer catches).
+     *
+     * @note This method is impure — it mutates `statusCode`.
+     *
+     * @returns The complete HTML string.
+     */
+    renderToString = () => {
+        const props = this.getComponentProps();
+        const jsx = createElement(this.Component, props);
+        const html = reactRenderToString(jsx);
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return html;
+    };
+}
+//# sourceMappingURL=JSXRenderer.js.map

package/dist/esm/lib/renderer/JSXRenderer.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"JSXRenderer.js","sourceRoot":"","sources":["../../../../src/lib/renderer/JSXRenderer.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/renderer/SitemapRenderer.js ADDED Viewed

@@ -0,0 +1,241 @@
+import { Readable } from "node:stream";
+/**
+ * Renders an XML sitemap from a set of async data sources.
+ *
+ * Unlike `JSXRenderer`, this renderer produces XML (not HTML) and does not use
+ * React. The render pipeline is functional: each stage returns data rather than
+ * mutating instance state, so calling render methods multiple times produces
+ * identical results for the same underlying data.
+ *
+ * Implements the same three render methods as `JSXRenderer` — `renderToReadableStream`,
+ * `renderToPipeableStream`, and `renderToString` — with the same `statusCode` /
+ * `statusReady` metadata contract. This allows consumers to use either renderer
+ * interchangeably.
+ *
+ * @example
+ * ```ts
+ * const renderer = new SitemapRenderer(
+ *   [() => fetchPages(), () => fetchPosts()],
+ *   { baseUrl: "https://example.com", defaultChangefreq: "weekly" },
+ * );
+ *
+ * const stream = await renderer.renderToReadableStream();
+ * return new Response(stream, {
+ *   status: renderer.statusCode,
+ *   headers: { "Content-Type": "application/xml; charset=utf-8" },
+ * });
+ * ```
+ */
+export default class SitemapRenderer {
+    getters;
+    config;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Set to 200 on successful render. Errors from getters propagate as
+     * thrown exceptions rather than setting this to 500 — the consumer's
+     * error handler decides the status code for unexpected failures.
+     */
+    statusCode = 200;
+    /**
+     * Resolves when `statusCode` is determined.
+     *
+     * For all three render methods on `SitemapRenderer`, this resolves by
+     * the time the method's returned Promise settles (or synchronously for
+     * the portions that are sync).
+     */
+    statusReady = Promise.resolve();
+    /**
+     * Create a sitemap renderer.
+     *
+     * @param getters - Async functions that each return a batch of sitemap items.
+     *   Called concurrently via `Promise.all` during rendering.
+     * @param config - Base URL and optional defaults for changefreq / priority.
+     */
+    constructor(getters, config) {
+        this.getters = getters;
+        this.config = config;
+    }
+    /**
+     * Load sitemap items from all configured getters.
+     *
+     * Calls every getter concurrently and flattens the results into a single
+     * array. This is the only async step in the pipeline.
+     *
+     * @note This method is impure — it calls external async data sources.
+     * @returns A flat array of raw sitemap items from all getters.
+     */
+    async loadItems() {
+        const results = await Promise.all(this.getters.map((getter) => getter()));
+        return results.flat();
+    }
+    /**
+     * Resolve URLs and apply defaults to raw sitemap items.
+     *
+     * For each item:
+     * - Relative `loc` values are resolved against `config.baseUrl`. An empty
+     *   `loc` resolves to the base URL itself.
+     * - `lastmod` dates are formatted to `YYYY-MM-DD` (ISO 8601 date-only).
+     * - Missing `changefreq` and `priority` are filled from `config` defaults.
+     *
+     * @param items - Raw items as returned by `loadItems`.
+     * @returns A new array of items with resolved URLs and applied defaults.
+     */
+    formatItems(items) {
+        return items.map((item) => ({
+            loc: item.loc.length
+                ? new URL(item.loc, this.config.baseUrl).href
+                : this.config.baseUrl,
+            lastmod: item.lastmod != null
+                ? SitemapRenderer.formatDate(item.lastmod)
+                : undefined,
+            changefreq: item.changefreq ?? this.config.defaultChangefreq,
+            priority: item.priority ?? this.config.defaultPriority,
+        }));
+    }
+    /**
+     * Format a `Date` object or ISO string to a `YYYY-MM-DD` date string.
+     *
+     * The Sitemaps protocol specifies W3C Datetime format; the date-only
+     * variant (`YYYY-MM-DD`) is the most common form used in practice.
+     *
+     * @param date - A `Date` instance or an ISO 8601 date/datetime string.
+     * @returns The date formatted as `YYYY-MM-DD`.
+     */
+    static formatDate(date) {
+        const d = typeof date === "string" ? new Date(date) : date;
+        return d.toISOString().slice(0, 10);
+    }
+    /**
+     * Escape the five XML special characters in a string.
+     *
+     * Prevents malformed XML when interpolating user-supplied URLs that may
+     * contain `&` (common in query strings), `<`, `>`, `"`, or `'`.
+     *
+     * @param value - The raw string to escape.
+     * @returns The string with `&`, `<`, `>`, `"`, and `'` replaced by their XML entities.
+     */
+    static escapeXml(value) {
+        return value
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+    /**
+     * Serialise a list of formatted sitemap items into an XML sitemap string.
+     *
+     * Produces a complete `<?xml>` document with a `<urlset>` root element
+     * conforming to the Sitemaps 0.9 schema. Only non-null optional fields
+     * (`lastmod`, `changefreq`, `priority`) are included in the output.
+     *
+     * @param items - Formatted items (URLs resolved, dates formatted).
+     * @returns The complete XML sitemap as a string.
+     */
+    toXml(items) {
+        const urlEntries = items
+            .map((item) => {
+            const parts = [
+                `    <loc>${SitemapRenderer.escapeXml(String(item.loc))}</loc>`,
+            ];
+            if (item.lastmod != null) {
+                parts.push(`    <lastmod>${SitemapRenderer.escapeXml(String(item.lastmod))}</lastmod>`);
+            }
+            if (item.changefreq != null) {
+                parts.push(`    <changefreq>${item.changefreq}</changefreq>`);
+            }
+            if (item.priority != null) {
+                parts.push(`    <priority>${item.priority}</priority>`);
+            }
+            return `  <url>\n${parts.join("\n")}\n  </url>`;
+        })
+            .join("\n");
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+            urlEntries,
+            "</urlset>",
+        ].join("\n");
+    }
+    /**
+     * Build the full XML string by loading items, applying formatting, and
+     * serialising to XML.
+     */
+    async buildXml() {
+        const rawItems = await this.loadItems();
+        const items = this.formatItems(rawItems);
+        return this.toXml(items);
+    }
+    /**
+     * Render the sitemap to a web `ReadableStream`.
+     *
+     * Loads items from all getters, formats them, serialises to XML, and
+     * wraps the result in a `ReadableStream`. Sets `statusCode` to 200.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @param _signal - Accepted for API compatibility with `JSXRenderer`. Not used.
+     * @returns A `ReadableStream` of the XML sitemap.
+     */
+    renderToReadableStream = async (_signal) => {
+        const xml = await this.buildXml();
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return new ReadableStream({
+            start(controller) {
+                controller.enqueue(new TextEncoder().encode(xml));
+                controller.close();
+            },
+        });
+    };
+    /**
+     * Render the sitemap to a Node.js pipeable stream.
+     *
+     * Returns `{ pipe, abort }` synchronously. The actual XML generation is
+     * async (getters are called), so data is pushed to the stream when ready.
+     * `statusReady` resolves when the XML is built and `statusCode` is set.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @returns The pipe/abort handles for the XML stream.
+     */
+    renderToPipeableStream = () => {
+        /* v8 ignore next -- read() is a required no-op for push-based Readable streams */
+        const readable = new Readable({ read() { } });
+        let aborted = false;
+        this.statusReady = this.buildXml().then((xml) => {
+            this.statusCode = 200;
+            if (!aborted) {
+                readable.push(xml);
+                readable.push(null);
+            }
+        });
+        return {
+            pipe: (destination) => readable.pipe(destination),
+            abort: () => {
+                aborted = true;
+                readable.destroy();
+            },
+        };
+    };
+    /**
+     * Render the sitemap to a complete XML string.
+     *
+     * Loads items from all getters, formats them, and returns the serialised
+     * XML. Sets `statusCode` to 200.
+     *
+     * Async because the getters are async.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @returns The complete XML sitemap string.
+     */
+    renderToString = async () => {
+        const xml = await this.buildXml();
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return xml;
+    };
+}
+//# sourceMappingURL=SitemapRenderer.js.map

package/dist/esm/lib/renderer/SitemapRenderer.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"SitemapRenderer.js","sourceRoot":"","sources":["../../../../src/lib/renderer/SitemapRenderer.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/renderer/TextRenderer.js ADDED Viewed

@@ -0,0 +1,124 @@
+import { Readable } from "node:stream";
+/**
+ * Renders a plain-text document from async data sources.
+ *
+ * Produces output suitable for `llms.txt`, `humans.txt`, `security.txt`, or
+ * any text file that requires dynamic data (e.g. fetching page descriptions
+ * from a CMS for an LLM context file).
+ *
+ * The renderer is intentionally minimal — it accepts an array of async getters,
+ * each returning a string, and concatenates the results. No structure is imposed.
+ * The consumer controls formatting entirely.
+ *
+ * Implements the same three render methods and `statusCode` / `statusReady`
+ * contract as `JSXRenderer` and `SitemapRenderer`.
+ *
+ * @example
+ * ```ts
+ * const renderer = new TextRenderer([
+ *   async () => "# My App\n\nContext for LLMs about this application.\n",
+ *   async () => {
+ *     const pages = await fetchPages();
+ *     return pages.map(p => `- ${p.title}: ${p.url}`).join("\n");
+ *   },
+ * ]);
+ *
+ * const stream = await renderer.renderToReadableStream();
+ * return new Response(stream, {
+ *   status: renderer.statusCode,
+ *   headers: { "Content-Type": "text/plain; charset=utf-8" },
+ * });
+ * ```
+ */
+export default class TextRenderer {
+    getters;
+    /**
+     * HTTP status code determined during rendering.
+     *
+     * Set to 200 on successful render. Errors from getters propagate as
+     * thrown exceptions — the consumer's error handler decides the status code.
+     */
+    statusCode = 200;
+    /**
+     * Resolves when `statusCode` is determined.
+     */
+    statusReady = Promise.resolve();
+    /**
+     * Create a text renderer.
+     *
+     * @param getters - Async functions that each return a string. Called
+     *   sequentially (order matters) and concatenated into the final document.
+     */
+    constructor(getters) {
+        this.getters = getters;
+    }
+    /**
+     * Build the full text by calling all getters sequentially and concatenating.
+     */
+    async buildText() {
+        const parts = [];
+        for (const getter of this.getters) {
+            parts.push(await getter());
+        }
+        return parts.join("");
+    }
+    /**
+     * Render to a web `ReadableStream`.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     *
+     * @param _signal - Accepted for API compatibility. Not used.
+     * @returns A `ReadableStream` of the plain-text document.
+     */
+    renderToReadableStream = async (_signal) => {
+        const text = await this.buildText();
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return new ReadableStream({
+            start(controller) {
+                controller.enqueue(new TextEncoder().encode(text));
+                controller.close();
+            },
+        });
+    };
+    /**
+     * Render to a Node.js pipeable stream.
+     *
+     * Returns `{ pipe, abort }` synchronously. Data is pushed when ready.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     */
+    renderToPipeableStream = () => {
+        /* v8 ignore next -- read() is a required no-op for push-based Readable streams */
+        const readable = new Readable({ read() { } });
+        let aborted = false;
+        this.statusReady = this.buildText().then((text) => {
+            this.statusCode = 200;
+            if (!aborted) {
+                readable.push(text);
+                readable.push(null);
+            }
+        });
+        return {
+            pipe: (destination) => readable.pipe(destination),
+            abort: () => {
+                aborted = true;
+                readable.destroy();
+            },
+        };
+    };
+    /**
+     * Render to a complete string.
+     *
+     * Async because the getters are async.
+     *
+     * @note This method is impure — it calls external data sources and mutates `statusCode`.
+     */
+    renderToString = async () => {
+        const text = await this.buildText();
+        this.statusCode = 200;
+        this.statusReady = Promise.resolve();
+        return text;
+    };
+}
+//# sourceMappingURL=TextRenderer.js.map

package/dist/esm/lib/renderer/TextRenderer.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"TextRenderer.js","sourceRoot":"","sources":["../../../../src/lib/renderer/TextRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,OAAO,OAAO,YAAY;IAoBA;IAnB/B;;;;;OAKG;IACI,UAAU,GAAG,GAAG,CAAC;IAExB;;OAEG;IACI,WAAW,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEtD;;;;;OAKG;IACH,YAA+B,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;IAAG,CAAC;IAEjE;;OAEG;IACO,KAAK,CAAC,SAAS;QACvB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;OAOG;IACH,sBAAsB,GAAG,KAAK,EAC5B,OAAqB,EACI,EAAE;QAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAErC,OAAO,IAAI,cAAc,CAAC;YACxB,KAAK,CAAC,UAAU;gBACd,UAAU,CAAC,OAAO,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACnD,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC;IAEF;;;;;;OAMG;IACH,sBAAsB,GAAG,GAAyB,EAAE;QAClD,kFAAkF;QAClF,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,KAAI,CAAC,EAAE,CAAC,CAAC;QAC7C,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAChD,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;YACtB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACpB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,IAAI,EAAE,CAAkC,WAAc,EAAE,EAAE,CACxD,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC;YAC5B,KAAK,EAAE,GAAG,EAAE;gBACV,OAAO,GAAG,IAAI,CAAC;gBACf,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,CAAC;SACF,CAAC;IACJ,CAAC,CAAC;IAEF;;;;;;OAMG;IACH,cAAc,GAAG,KAAK,IAAqB,EAAE;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;CACH"}

package/dist/esm/lib/renderer/constants.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/lib/renderer/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC"}