/**
* Web-standard `Response` helpers — the server-side entry point.
*
* These turn a document straight into an HTTP response, which is what a
* Next.js **Route Handler**, a Remix loader, a Hono/Elysia route or any
* Fetch-API server actually needs:
*
* ```ts
* // app/invoice/route.ts
* import { renderToResponse } from 'pdfnative-react';
*
* export async function GET() {
* return renderToResponse(, { fileName: 'invoice.pdf' });
* }
* ```
*
* By default the body is a `ReadableStream` fed by the engine's page-by-page
* generator, so peak memory stays flat and the client sees bytes immediately.
* Pass `buffered: true` when you need a `Content-Length` up front.
*
* Nothing here touches the DOM or React client APIs — **do not** add
* `'use client'` to this module.
*
* Not a Server Component or a `'use server'` file, though: this package drives a
* React reconciler, which needs `createContext`, and React's `react-server`
* export condition does not provide it. Route Handlers are not in the RSC layer,
* which is why they work. See `docs/SERVER.md`.
*
* @packageDocumentation
*/
import type { ReactNode } from 'react';
import { renderToBytes, renderToStream } from './render.js';
import { optionsWithFonts } from './fonts.js';
import type { RenderOptions } from './types.js';
/** Options for {@link renderToResponse} / {@link renderSpecToResponse}. */
export interface PdfResponseOptions extends RenderOptions {
/** Filename advertised in `Content-Disposition`. Default: `'document.pdf'`. */
readonly fileName?: string;
/**
* `'inline'` renders in the browser's PDF viewer, `'attachment'` forces a
* download. Default: `'inline'`.
*/
readonly disposition?: 'inline' | 'attachment';
/**
* Buffer the whole PDF before responding, which allows a `Content-Length`
* header. Default: `false` (stream with constant memory).
*/
readonly buffered?: boolean;
/** HTTP status code. Default: `200`. */
readonly status?: number;
/**
* `Cache-Control` response header (e.g. `'private, max-age=60'`).
* Default: unset — PDF responses are not cached unless you opt in.
*/
readonly cacheControl?: string;
/**
* `ETag` response header. A string is sent verbatim (bring your own
* validator, e.g. derived from the data that fed the document). `true`
* derives a strong validator from the rendered bytes — which requires the
* whole PDF up front, so it implies `buffered: true`.
*
* Only the header is set; answer `If-None-Match` with a `304` in your own
* handler, where the `Request` lives.
*/
readonly etag?: string | true;
/** Extra response headers, merged last so they can override the defaults. */
readonly headers?: HeadersInit;
}
/**
* Build an RFC 6266 `Content-Disposition` value, adding the `filename*`
* parameter only when the name is not plain ASCII.
*/
function contentDisposition(disposition: 'inline' | 'attachment', fileName: string): string {
const ascii = fileName.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
// RFC 8187 ext-values allow only `attr-char`. `encodeURIComponent` leaves
// ' ( ) ! * ~ unescaped — and a raw apostrophe is actively harmful, since a
// strict parser splits the ext-value on ' (charset'lang'value) and would
// mis-read the filename. Percent-escape the stragglers.
const encoded = encodeURIComponent(fileName).replace(
/['()!*~]/g,
(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
);
const base = `${disposition}; filename="${ascii}"`;
return encoded === ascii ? base : `${base}; filename*=UTF-8''${encoded}`;
}
/** Adapt the engine's async byte generator to a web `ReadableStream`. */
function toReadableStream(source: AsyncGenerator): ReadableStream {
return new ReadableStream({
async pull(controller) {
const next = await source.next();
if (next.done === true) {
controller.close();
return;
}
controller.enqueue(next.value);
},
async cancel() {
// Let the generator run its cleanup when the client disconnects.
await source.return(undefined);
},
});
}
/**
* A strong `ETag` from the rendered bytes: 64-bit FNV-1a plus the length.
* Change detection, not cryptography — dependency-free and runs everywhere,
* including runtimes without `crypto.subtle`.
*/
function strongEtag(bytes: Uint8Array): string {
const PRIME = 0x100000001b3n;
let hash = 0xcbf29ce484222325n;
for (const byte of bytes) {
hash ^= BigInt(byte);
hash = (hash * PRIME) & 0xffffffffffffffffn;
}
return `"${hash.toString(16).padStart(16, '0')}-${bytes.byteLength.toString(16)}"`;
}
function buildHeaders(
options: PdfResponseOptions | undefined,
byteLength?: number,
computedEtag?: string,
): Headers {
const headers = new Headers({
'content-type': 'application/pdf',
'content-disposition': contentDisposition(
options?.disposition ?? 'inline',
options?.fileName ?? 'document.pdf',
),
});
if (byteLength !== undefined) headers.set('content-length', String(byteLength));
if (options?.cacheControl !== undefined) headers.set('cache-control', options.cacheControl);
const etag = typeof options?.etag === 'string' ? options.etag : computedEtag;
if (etag !== undefined) headers.set('etag', etag);
if (options?.headers) {
// Merge last so callers can override any default (e.g. cache-control).
new Headers(options.headers).forEach((value, key) => headers.set(key, value));
}
return headers;
}
/**
* Render a document straight to a web-standard `Response`.
*
* Streams by default. Works in Node ≥ 22, the Edge runtime, Deno, Bun and
* Cloudflare Workers — anywhere `Response` and `ReadableStream` exist.
*
* @param node - A React element whose root is ``.
* @param options - Render options plus response shaping (filename, disposition…).
*/
export async function renderToResponse(
node: ReactNode,
options?: PdfResponseOptions,
): Promise {
const resolved = await optionsWithFonts(options);
const status = options?.status ?? 200;
// `etag: true` needs the whole PDF to hash, so it implies buffering.
if (options?.buffered === true || options?.etag === true) {
const bytes = renderToBytes(node, resolved);
return new Response(bytes as BodyInit, {
status,
headers: buildHeaders(
options,
bytes.byteLength,
options?.etag === true ? strongEtag(bytes) : undefined,
),
});
}
const stream = toReadableStream(renderToStream(node, resolved));
return new Response(stream, { status, headers: buildHeaders(options) });
}