Res

The Res class represents an HTTP response with automatic body serialization, cookie handling, and header management. It provides static helpers for common response patterns like redirects, file streaming, and Server-Sent Events.

Usage

Basic response

import { C } from "@ozanarslan/corpus";

new C.Route("/hello", () => {
	return new C.Res("Hello World");
});

With status and headers

new C.Route("/created", () => {
	return new C.Res(
		{ id: 1 },
		{
			status: C.Status.CREATED,
			headers: { [C.CommonHeaders.Location]: "/items/1" },
		},
	);
});

Setting cookies

The following is the recommended pattern because Res init can also receive another Res instance and typescript doesn't do a great job differentiating an object with a class.

new C.Route("/login", (c) => {
	c.res.cookies.set({
		name: "session",
		value: "abc123",
		httpOnly: true,
		secure: true,
	});

	return { success: true };
});

Accessing the native response

const cres = new C.Res("data");
cres.response; // Returns native Web API Response

Constructor Parameters

data (optional)

ResBody<R>

The response body. Automatically serialized based on type. See Body Serialization.

init (optional)

ResInit | Res

Response options or another Res to copy from.

type ResInit = {
	cookies?: CookiesInit;
	headers?: CHeadersInit;
	status?: Status;
	statusText?: string;
};

Properties

Static Methods

redirect

static redirect(url: string | URL, init?: ResInit): Res

Creates a redirect response. Defaults to 302 Found.

return C.Res.redirect("/new-path");
return C.Res.redirect("/new-path", {
	status: C.Status.MOVED_PERMANENTLY,
});

permanentRedirect

static permanentRedirect(url: string | URL, init?: Omit<ResInit, "status">): Res

301 Moved Permanently redirect.

temporaryRedirect

static temporaryRedirect(url: string | URL, init?: Omit<ResInit, "status">): Res

307 Temporary Redirect.

seeOther

static seeOther(url: string | URL, init?: Omit<ResInit, "status">): Res

303 See Other (redirect with GET).

sse

static sse(source: SseSource, init?: Omit<ResInit, "status">, retry?: number): Res

Server-Sent Events stream.

return C.Res.sse((send) => {
	const interval = setInterval(() => {
		send({ data: { time: Date.now() }, event: "tick" });
	}, 1000);

	return () => clearInterval(interval); // cleanup
});

ndjson

static ndjson(source: NdjsonSource, init?: Omit<ResInit, "status">): Res

Newline-delimited JSON stream.

return C.Res.ndjson((send) => {
	for (const item of largeDataset) {
		send(item);
	}
});

streamFile

static async streamFile(filePath: string, disposition?: "attachment" | "inline", init?: Omit<ResInit, "status">): Promise<Res<ReadableStream>>

Stream a file from disk. Uses Content-Type from file extension. Defaults to attachment disposition.

return await C.Res.streamFile("assets/video.mp4", "inline");

Throws Exception with 404 if file not found.

file

static async file(filePath: string, init?: ResInit): Promise<Res<string>>

Read entire file into memory as string. Sets Content-Length header.

return await C.Res.file("assets/doc.txt");

Throws Exception with 404 if file not found.

Body Serialization

The body is automatically serialized based on its type: