Res

Response building: status codes, body serialization, streaming, and cookies.

A Res is what a handler shapes on its way to a native Response. It is created lazily on Context.res, so a handler that just returns a value never constructs one; reach for it when the response needs a status, headers, cookies, or a body form that a plain return value cannot express — a file, a redirect, or a stream.

Body serialization is inferred from the value's type at Res.toNativeResponse time, so an object becomes JSON, a typed array stays binary, and a stream passes through untouched — each with a matching Content-Type unless one was set explicitly.

import { Res, Status } from "@ozanarslan/corpus";

new Res({ id: 1 }, { status: Status.CREATED });
new Res().file("./report.pdf");
new Res().redirect("/login");

Res

class

class Res<R = unknown>

A response under construction.

Everything is mutable until Res.toNativeResponse is called, so a Middleware can adjust a response a route handler already built. The body is kept as the original value rather than serialized eagerly, which is what lets the content type be inferred from it at the very end.

Headers and cookies are both lazy, so an untouched response allocates neither. The chainable methods — Res.file, Res.redirect, Res.sse and the rest — set the body and its headers together and return this.

Type parameters

• R — The body type, carried from the route's own response type.

Res.constructor()

constructor(body?: Nullable<BodyInit | R>, init?: ResInit)

Creates a response.

Parameters

• body — The body value. Serialized by resolveResBody at Res.toNativeResponse time, not now.
• init — Status, status text, headers and cookies. See ResInit.

Res.body

body: Nullable<BodyInit | R>;

The body to send. Assign any value — objects become JSON, typed arrays stay binary, streams pass through — and resolveResBody works out the rest at serialization time.

Res.status

status: number;

The status code. Defaults to Status.OK.

Res.statusText

statusText: string;

The status text. Empty by default, which lets the runtime supply the standard phrase.

Res.headers

get headers(): Headers

The response headers.

Reading them rewrites the Set-Cookie lines from Res.cookies first, so the two views never disagree — and writing Set-Cookie here feeds back into the cookie map. Values may be numbers or booleans, since patchGlobalHeaders has stringified setters.

Returns — The headers, created on first access.

Res.cookies

get cookies(): Cookies

The cookies to send, as a mutable map.

This is the authoritative view: the map is serialized into Set-Cookie whenever Res.headers is read, so deleting a cookie here removes its header. Values are percent-encoded on serialization, which is what keeps a CRLF in a cookie value from splitting the response.

Returns — The Cookies map, created on first access.

Res.toNativeResponse()

toNativeResponse(): Response

Serializes everything into a native Response.

The content type inferred from the body is applied only when none was set explicitly, so a handler's own choice always wins. X-Content-Type-Options: nosniff is set unconditionally — without it a browser will sniff a text/plain body that looks like markup and render it as HTML, turning any reflected value into XSS.

Returns — The response to send over the wire. Called by App.respond.

Res.sse()

sse(source: SseSource, retry?: number): this

Turns the response into a server-sent event stream.

Sets the body to a stream and the headers browsers require for EventSource to work — the event stream type, no caching, and a kept-alive connection.

Parameters

• source — The SseSource producing events. Return a cleanup function from it to keep the stream open indefinitely.
• retry — Reconnection delay in milliseconds, sent with every event to tell the client how long to wait before reconnecting.

Returns — This response, for chaining.

Res.ndjson()

ndjson(source: NdjsonSource): this

Turns the response into a newline-delimited JSON stream.

Each item is serialized onto its own line, so a client can parse results as they arrive instead of waiting for a whole array. Useful for large result sets and progressive output where the event semantics of Res.sse are not needed.

Parameters

• source — The NdjsonSource producing items. Return a cleanup function from it to keep the stream open indefinitely.

Returns — This response, for chaining.

Res.streamFile()

streamFile(fileOrPath: XFile | string, disposition: ContentDispositionDefinition["disposition"], ): this

Streams a file as the response body, without reading it into memory. Prefer this over Res.file for anything large.

Parameters

• fileOrPath — An XFile or a path to one.
• disposition — "inline" to display in the browser, "attachment" to prompt a download under the file's own name.

Returns — This response, for chaining.

Throws — Exception with Status.NOT_FOUND when the file does not exist.

Res.file()

file(fileOrPath: XFile | string): this

Sends a file as the response body, read into memory so it can carry an exact Content-Length. Use Res.streamFile instead for large files.

Parameters

• fileOrPath — An XFile or a path to one.

Returns — This response, for chaining.

Throws — Exception with Status.NOT_FOUND when the file does not exist.

Res.redirect()

redirect(url: string | URL, status: 301 | 302 | 303 | 307 | 308 = 302): this

Redirects the client to another URL.

Parameters

• url — Where to send the client, absolute or relative.
• status — Which redirect to use. Defaults to Status.FOUND, a temporary redirect that browsers do not cache. See Res.permanentRedirect, Res.temporaryRedirect and Res.seeOther for the named alternatives.

Returns — This response, for chaining.

Res.permanentRedirect()

permanentRedirect(url: string | URL): this

Redirects with Status.MOVED_PERMANENTLY, which browsers and search engines cache indefinitely. Use it only when the resource has really moved for good.

Parameters

• url — Where to send the client.

Returns — This response, for chaining.

Res.temporaryRedirect()

temporaryRedirect(url: string | URL): this

Redirects with Status.TEMPORARY_REDIRECT, which preserves the original method and body — unlike Status.FOUND, which clients commonly turn into a GET.

Parameters

• url — Where to send the client.

Returns — This response, for chaining.

Res.seeOther()

seeOther(url: string | URL): this

Redirects with Status.SEE_OTHER, which explicitly switches the client to a GET. This is the correct redirect after a successful POST, since it stops a refresh from resubmitting the form.

Parameters

• url — Where to send the client.

Returns — This response, for chaining.

Status

const

const Status;
type Status = ValueOf<typeof Status> | (number & {});

Commonly used HTTP status codes.

An HTTP status code. The Status constants are suggested, but any number is assignable.