interface IResponse
Since 0.1.0

Runtime-agnostic response builder. Configuration methods (status, header) chain; terminal methods (json, text, send, redirect) produce the HandlerResult a route handler returns.

Examples

Example 1

app.router.get('/users/:id', (ctx) => {
  return ctx.response.status(200).json({ id: ctx.params.id });
});

Methods

status(code: number): IResponse

Sets the response status code.

header(
name: string,
value: string
): IResponse

Sets a response header.

appendHeader(
name: string,
value: string
): IResponse

Appends a response header, preserving any existing values for the same name rather than replacing them (unlike IResponse.header, which overwrites). This is the correct way to emit multiple headers of the same name — most notably several Set-Cookie headers (e.g. an access cookie plus a refresh cookie, or deleting several cookies at once).

json<T>(body: T): HandlerResult

Sends a JSON response.

text(body: string): HandlerResult

Sends a plain-text response.

Since 0.2.0
html(body: string): HandlerResult

Sends an HTML response.

The text/html; charset=utf-8 media type is set explicitly — a bare text/html lets a browser sniff the encoding.

Sends a raw byte response.

redirect(
url: string,
status?: number
): HandlerResult

Sends a redirect response.

Sends a streaming response body.

Accepts a web-standard ReadableStream so that a handler can flush bytes progressively over a long-lived connection instead of buffering a whole body before send. This is the shared foundation for Server-Sent Events (Milestone 43), React SSR streaming (Milestone 44), large file downloads (storage-plugin, Milestone 28), and export / report responses.

Because the runtime maps the response to a web-standard new Response(streamBody, { status, headers }), streaming is free on every platform (Node via Hono, Deno, Bun, Cloudflare Workers) with no buffer-then-send.

Returns a snapshot of the current response state (status, headers, body). Enables middleware to inspect the response after next() returns — required for transparent response caching.

The returned object is a READ view, not a defensive copy: headers is the live Headers instance backing the response. Treat it as read-only — mutating it mutates the response. (No copy is taken deliberately: cloning a Headers collapses repeated Set-Cookie values into one comma-joined header, which would corrupt multi-cookie responses.)

Returns a discriminated union keyed on streaming: when false, body is Uint8Array | string | null (buffered); when true, body is a ReadableStream<Uint8Array> (live stream). Middleware that reads the body (e.g. cache middleware) must check streaming first to avoid draining a live stream.

Usage

import { type IResponse } from "common/src/index.ts";