Response Helpers

All response helpers take an IRoutupEvent as the first argument. Most send helpers return a Response object. Header helpers mutate event.response.headers in place.

Send Helpers

sendRedirect

Redirect the client to another URL. Sends an HTML body with a <meta> refresh as a fallback.

declare function sendRedirect(
    event: IRoutupEvent,
    location: string,
    statusCode?: number,
): Response;

return sendRedirect(event, '/login', 302);

sendFile

Send a file with support for range requests, ETag generation, and automatic content-type detection.

declare function sendFile(
    event: IRoutupEvent,
    options: SendFileOptions,
): Promise<Response>;

The SendFileOptions type:

type SendFileOptions = {
    stats: () => Promise<SendFileStats> | SendFileStats;
    content: (
        options: SendFileContentOptions,
    ) => Promise<ReadableStream | ArrayBuffer | Uint8Array> | ReadableStream | ArrayBuffer | Uint8Array;
    attachment?: boolean;
    name?: string;
};

import fs from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { Readable } from 'node:stream';

return await sendFile(event, {
    stats: () => fs.stat(filePath),
    content: (opts) => Readable.toWeb(createReadStream(filePath, opts)) as ReadableStream,
    name: 'report.pdf',
});

sendStream

Wrap a ReadableStream in a Response.

declare function sendStream(
    event: IRoutupEvent,
    stream: ReadableStream,
): Response;

const stream = new ReadableStream({ /* ... */ });
return sendStream(event, stream);

sendCreated

Send a 201 Created response with optional body data.

declare function sendCreated(
    event: IRoutupEvent,
    data?: unknown,
): Promise<Response>;

return sendCreated(event, { id: 1, name: 'New Item' });

sendAccepted

Send a 202 Accepted response with optional body data.

declare function sendAccepted(
    event: IRoutupEvent,
    data?: unknown,
): Promise<Response>;

return sendAccepted(event, { status: 'processing' });

sendFormat

Perform content negotiation and send the response in the format the client prefers. Falls back to the default handler if no format matches.

declare function sendFormat(
    event: IRoutupEvent,
    formats: {
        default: () => unknown;
        [contentType: string]: () => unknown;
    },
): Response | unknown | undefined;

return sendFormat(event, {
    default: () => ({ ok: true }),
    'application/json': () => ({ ok: true }),
    'text/html': () => '<p>OK</p>',
});

Header Helpers

setResponseHeaderAttachment

Set the Content-Disposition header to attachment. When a filename is provided, adds the filename directive and sets Content-Type based on the file extension.

declare function setResponseHeaderAttachment(
    event: IRoutupEvent,
    filename?: string,
): void;

setResponseHeaderAttachment(event, 'data.csv');

setResponseHeaderContentType

Set the Content-Type response header. Optionally skip if a content type is already set.

declare function setResponseHeaderContentType(
    event: IRoutupEvent,
    type: string,
    ifNotExists?: boolean,
): void;

setResponseHeaderContentType(event, 'application/json');

setResponseCacheHeaders

Set Cache-Control and Last-Modified headers based on the provided options.

declare function setResponseCacheHeaders(
    event: IRoutupEvent,
    options?: ResponseCacheHeadersOptions,
): void;

The ResponseCacheHeadersOptions type:

type ResponseCacheHeadersOptions = {
    maxAge?: number;
    modifiedTime?: string | Date;
    cacheControls?: string[];
};

setResponseCacheHeaders(event, {
    maxAge: 3600,
    modifiedTime: stats.mtime,
});

appendResponseHeader

Append a value to an existing response header (or create it).

declare function appendResponseHeader(
    event: IRoutupEvent,
    name: string,
    value: string | string[],
): void;

appendResponseHeader(event, 'Set-Cookie', 'session=abc; Path=/');

appendResponseHeaderDirective

Append a directive to an existing response header value (or create the header). Deduplicates directives.

declare function appendResponseHeaderDirective(
    event: IRoutupEvent,
    name: string,
    value: string | string[],
): void;

appendResponseHeaderDirective(event, 'Cache-Control', 'no-cache');

Status Helpers

isResponseGone

Check whether the response has already been dispatched (i.e., event.dispatched is true).

declare function isResponseGone(event: IRoutupEvent): boolean;

setResponseGone

Mark the response as dispatched.

declare function setResponseGone(event: IRoutupEvent): void;

Event Stream (SSE)

createEventStream

Create a Server-Sent Events stream. Returns a handle with methods to write events, end the stream, and the underlying Response.

declare function createEventStream(
    event: IRoutupEvent,
    options?: EventStreamOptions,
): EventStreamHandle;

The EventStreamOptions type:

type EventStreamOptions = {
    maxMessageSize?: number;
};

The EventStreamHandle type:

type EventStreamHandle = {
    write(message: string | EventStreamMessage): void;
    end(): void;
    response: Response;
};

type EventStreamMessage = {
    id?: string;
    retry?: number;
    data: string;
    event?: string;
};

import { defineCoreHandler, createEventStream } from 'routup';

defineCoreHandler((event) => {
    const stream = createEventStream(event);

    let count = 0;
    const interval = setInterval(() => {
        stream.write(`count: ${count}`);
        count++;

        if (count > 100) {
            stream.end();
            clearInterval(interval);
        }
    }, 1000);

    return stream.response;
});

Utility

setResponseContentTypeByFileName

Set the Content-Type header based on a file's extension.

declare function setResponseContentTypeByFileName(
    event: IRoutupEvent,
    fileName: string,
): void;

setResponseContentTypeByFileName(event, 'image.png');