HttpServerResponse
Describes immutable responses returned by Effect HTTP handlers.
An HttpServerResponse stores the status, optional status text, headers, cookies, and body that the server runtime later turns into a platform response such as a Web Response. This module includes constructors for common response bodies, helpers for updating response data, file response support through HttpPlatform, and conversions to or from Web and Effect HTTP client responses.
Combinators
expireCookie
Signature
declare const expireCookie: {
(
name: string,
options?: Omit<
{
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
"expires" | "maxAge"
>,
): (self: HttpServerResponse) => Effect<HttpServerResponse, CookiesError>;
(
self: HttpServerResponse,
name: string,
options?: Omit<
{
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
"expires" | "maxAge"
>,
): Effect<HttpServerResponse, CookiesError>;
};expireCookieUnsafe
Sets an expired cookie on an HttpServerResponse, throwing if the expiration cookie cannot be encoded.
When to use
Use when you need to expire one trusted cookie and want encoding failures to throw instead of being represented as CookiesError failures.
Signature
declare const expireCookieUnsafe: {
(
name: string,
options?: Omit<
{
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
"expires" | "maxAge"
>,
): (self: HttpServerResponse) => HttpServerResponse;
(
self: HttpServerResponse,
name: string,
options?: Omit<
{
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
"expires" | "maxAge"
>,
): HttpServerResponse;
};mergeCookies
Merges additional cookies into the cookies attached to an HttpServerResponse.
Details
The original response is not mutated; a new response is returned with the merged cookie collection.
Signature
declare const mergeCookies: {
(cookies: Cookies): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, cookies: Cookies): HttpServerResponse;
};removeCookie
Returns a response with the cookie of the specified name removed.
Signature
declare const removeCookie: {
(name: string): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, name: string): HttpServerResponse;
};removeHeader
Returns a response with the specified header removed.
Signature
declare const removeHeader: {
(key: string): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, key: string): HttpServerResponse;
};replaceCookies
Returns a response with its cookie collection replaced by the supplied cookies.
Signature
declare const replaceCookies: {
(cookies: Cookies): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, cookies: Cookies): HttpServerResponse;
};Replaces the body of an HttpServerResponse.
Details
When the body carries a content type or content length, the returned response includes the corresponding headers.
Signature
declare const setBody: {
(body: HttpBody): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, body: HttpBody): HttpServerResponse;
};Sets a cookie on the response.
Details
The effect fails with CookiesError if the cookie name, value, or options are invalid.
Signature
declare const setCookie: {
(
name: string,
value: string,
options?: {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
): (self: HttpServerResponse) => Effect<HttpServerResponse, CookiesError>;
(
self: HttpServerResponse,
name: string,
value: string,
options?: {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
): Effect<HttpServerResponse, CookiesError>;
};setCookies
Sets multiple cookies on an HttpServerResponse.
Details
Each input entry contains a cookie name, value, and optional cookie options. The returned effect fails with CookiesError if any cookie cannot be encoded.
Signature
declare const setCookies: {
(
cookies: Iterable<
readonly [
string,
string,
(
| {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
}
| undefined
),
]
>,
): (self: HttpServerResponse) => Effect<HttpServerResponse, CookiesError, never>;
(
self: HttpServerResponse,
cookies: Iterable<
readonly [
string,
string,
(
| {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
}
| undefined
),
]
>,
): Effect<HttpServerResponse, CookiesError, never>;
};setCookiesUnsafe
Sets multiple cookies on an HttpServerResponse, throwing if any cookie cannot be encoded.
When to use
Use when you need to set multiple trusted cookies and want encoding failures to throw instead of being represented as CookiesError failures.
Signature
declare const setCookiesUnsafe: {
(
cookies: Iterable<
readonly [
string,
string,
(
| {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
}
| undefined
),
]
>,
): (self: HttpServerResponse) => HttpServerResponse;
(
self: HttpServerResponse,
cookies: Iterable<
readonly [
string,
string,
(
| {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
}
| undefined
),
]
>,
): HttpServerResponse;
};setCookieUnsafe
Sets a cookie on an HttpServerResponse, throwing if the cookie cannot be encoded.
When to use
Use when you need to set one trusted cookie and want encoding failures to throw instead of being represented as CookiesError failures.
Signature
declare const setCookieUnsafe: {
(
name: string,
value: string,
options?: {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
): (self: HttpServerResponse) => HttpServerResponse;
(
self: HttpServerResponse,
name: string,
value: string,
options?: {
readonly domain?: string;
readonly expires?: Date;
readonly httpOnly?: boolean;
readonly maxAge?: Duration.Input;
readonly partitioned?: boolean;
readonly path?: string;
readonly priority?: "low" | "medium" | "high";
readonly sameSite?: "lax" | "strict" | "none";
readonly secure?: boolean;
},
): HttpServerResponse;
};Returns a response with the specified header set to the supplied value.
Signature
declare const setHeader: {
(key: string, value: string): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, key: string, value: string): HttpServerResponse;
};setHeaders
Returns a response with all supplied headers set on the existing header map.
Signature
declare const setHeaders: {
(input: Input): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, input: Input): HttpServerResponse;
};Sets the HTTP status code of an HttpServerResponse.
Details
When statusText is omitted, the existing status text is preserved.
Signature
declare const setStatus: {
(status: number, statusText?: string): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, status: number, statusText?: string): HttpServerResponse;
};updateCookies
Updates the cookies attached to an HttpServerResponse using the supplied function.
Details
The original response is not mutated; a new response is returned with the callback result as its cookie collection.
Signature
declare const updateCookies: {
(f: (cookies: Cookies) => Cookies): (self: HttpServerResponse) => HttpServerResponse;
(self: HttpServerResponse, f: (cookies: Cookies) => Cookies): HttpServerResponse;
};Constructors
Creates an empty HTTP response.
Details
The default status is 204.
Signature
declare function empty(options?: WithContent): HttpServerResponse;Creates a streamed file response for a file system path.
Details
The effect requires HttpPlatform, can fail with a platform error, and supports options for status, headers, offset, and byte range.
Signature
declare function file(
path: string,
options?: Options & {
readonly bytesToRead?: SizeInput;
readonly chunkSize?: SizeInput;
readonly offset?: SizeInput;
},
): Effect<HttpServerResponse, PlatformError, HttpPlatform>;Creates a streamed file response for a Web File-like value.
Details
The effect requires HttpPlatform and supports options for status, headers, offset, and byte range.
Signature
declare function fileWeb(
file: FileLike,
options?: WithContent & {
readonly bytesToRead?: SizeInput;
readonly chunkSize?: SizeInput;
readonly offset?: SizeInput;
},
): Effect<HttpServerResponse, never, HttpPlatform>;Creates a response whose body is a Web FormData value.
Signature
declare function formData(body: FormData, options?: WithContent): HttpServerResponse;Creates an HTML response with the text/html content type.
Details
Passing a string returns a response directly. Using it as a template tag returns an effect so interpolated values can be rendered with their required services and errors.
Signature
declare const html: {
<A extends readonly Array<Interpolated>>(strings: TemplateStringsArray, ...args: A): Effect<HttpServerResponse, Error<A[number]>, Context<A[number]>>;
(html: string): HttpServerResponse;
}htmlStream
Creates a streaming HTML response from a template.
Details
The template is encoded as a byte stream and can use streaming interpolated values from the current context.
Signature
declare function htmlStream<A extends readonly Array<InterpolatedWithStream>>(strings: TemplateStringsArray, ...args: A): Effect<HttpServerResponse, never, Context<A[number]>>Creates a JSON HTTP response.
Details
The body is serialized with JSON.stringify; serialization errors are captured as HttpBodyError failures.
Signature
declare function json(
body: unknown,
options?: WithContentType,
): Effect<HttpServerResponse, HttpBodyError>;jsonUnsafe
Creates a JSON HTTP response synchronously.
When to use
Use when the response body is known to be JSON-serializable and you need a synchronous HttpServerResponse.
Gotchas
Unlike json, serialization errors from JSON.stringify are not captured in Effect.
Signature
declare function jsonUnsafe(body: unknown, options?: WithContentType): HttpServerResponse;Creates a response with a raw body value.
When to use
Use when you want to pass through a body value already understood by the underlying runtime, such as a Web Response, Blob, or ReadableStream, for later platform conversion.
Signature
declare function raw(body: unknown, options?: Options): HttpServerResponse;Creates a redirect response with a Location header.
Details
The default status is 302; custom headers are merged with the generated Location header.
Signature
declare function redirect(location: string | URL, options?: WithContent): HttpServerResponse;schemaJson
Creates a JSON response constructor backed by a schema encoder.
Details
The returned function encodes the value with the supplied schema before serializing it as JSON, and can fail with HttpBodyError if schema encoding or JSON serialization fails.
Signature
declare function schemaJson<A, RE>(
schema: ConstraintCodec<A, unknown, unknown, RE>,
options?: ParseOptions,
): (body: A, options?: WithContentType) => Effect<HttpServerResponse, HttpBodyError, RE>;Creates a streaming response from a stream of byte chunks.
Details
Optional response metadata can supply the status, headers, content type, and content length.
Signature
declare function stream<E>(
body: Stream<Uint8Array<ArrayBufferLike>, E>,
options?: Options,
): HttpServerResponse;Creates an HTTP response whose body is a string.
Signature
declare function text(body: string, options?: WithContentType): HttpServerResponse;uint8Array
Creates an HTTP response whose body is a Uint8Array.
Signature
declare function uint8Array(body: Uint8Array, options?: WithContentType): HttpServerResponse;Creates a response from URL parameters using the application/x-www-form-urlencoded content type by default.
Signature
declare function urlParams(body: Input, options?: WithContentType): HttpServerResponse;Converting
fromClientResponse
Converts an HttpClientResponse to an HttpServerResponse.
Details
The response body is streamed from the client response. Set-Cookie headers are removed from the header map and represented in the response cookie collection.
Signature
declare function fromClientResponse(response: HttpClientResponse): HttpServerResponse;Converts a Web Response to an HttpServerResponse.
Details
Set-Cookie headers are parsed into the response cookie collection and removed from the header map. A present Web body is exposed as a stream body.
Signature
declare function fromWeb(response: Response): HttpServerResponse;toClientResponse
Wraps an HttpServerResponse as an HttpClientResponse.
Details
An optional request can be supplied for client-response metadata and decode errors.
Signature
declare function toClientResponse(
response: HttpServerResponse,
options?: {
readonly request?: HttpClientRequest;
},
): HttpClientResponse;Converts an HttpServerResponse to a Web Response.
Details
Cookies are appended as Set-Cookie headers. Stream bodies are converted using the supplied context, and withoutBody can be used for responses such as HEAD responses.
Signature
declare function toWeb(
response: HttpServerResponse,
options?: {
readonly context?: Context<never>;
readonly withoutBody?: boolean;
},
): Response;Guards
isHttpServerResponse
Returns true when the supplied value is an HttpServerResponse.
Signature
declare function isHttpServerResponse(u: unknown): u is HttpServerResponse;Models
HttpServerResponse interface
Server-side HTTP response model.
Details
A response contains a status, optional status text, headers, cookies, and an HTTP body that can later be converted to platform-specific response types.
Signature
interface HttpServerResponse extends Inspectable, Pipeable, Reportable {
readonly "~effect/http/HttpServerResponse": "~effect/http/HttpServerResponse";
readonly body: HttpBody;
readonly cookies: Cookies;
readonly headers: Headers;
readonly status: number;
readonly statusText?: string;
}Options
Common options accepted by HTTP server response constructors.
Signature
interface Options {
readonly contentLength?: number;
readonly contentType?: string;
readonly cookies?: Cookies;
readonly headers?: Input;
readonly status?: number;
readonly statusText?: string;
}
Sets an expired cookie on an
HttpServerResponse.Details
Returns an effect because cookie encoding can fail. The original response is not mutated; the effect succeeds with a response containing the updated cookie set.