effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/unstable/http/HttpServerResponse.d.ts

@@ -1,4 +1,24 @@
 /**
+ * Server-side HTTP response values and constructors for Effect HTTP handlers.
+ *
+ * This module defines `HttpServerResponse`, the immutable response model returned
+ * from routers and server effects, together with constructors for empty,
+ * redirect, text, HTML, JSON, URL-encoded, raw, form-data, stream, and file
+ * bodies. It also includes combinators for adjusting status, headers, cookies,
+ * and bodies, plus conversions to and from Web `Response` and client responses.
+ *
+ * Response constructors choose status defaults for common cases: `204` for
+ * `empty`, `302` for `redirect`, and `200` for responses with bodies. Body
+ * metadata is mirrored into headers, so content type and content length carried
+ * by the body are written to `content-type` and `content-length`, overriding
+ * existing values when present. JSON helpers can fail while encoding or
+ * serializing unless the unsafe constructor is used.
+ *
+ * Cookies are tracked separately from the normal header map so they can be
+ * encoded as `Set-Cookie` headers when converting to platform responses. Use the
+ * effectful cookie helpers when invalid cookie names, values, or options should
+ * stay in the Effect error channel.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts";
@@ -21,8 +41,13 @@ import * as Template from "./Template.ts";
 import * as UrlParams from "./UrlParams.ts";
 declare const TypeId = "~effect/http/HttpServerResponse";
 /**
- * @since 4.0.0
+ * Server-side HTTP response model.
+ *
+ * A response contains a status, optional status text, headers, cookies, and an
+ * HTTP body that can later be converted to platform-specific response types.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface HttpServerResponse extends Inspectable.Inspectable, Pipeable, ErrorReporter.Reportable {
     readonly [TypeId]: typeof TypeId;
@@ -33,8 +58,10 @@ export interface HttpServerResponse extends Inspectable.Inspectable, Pipeable, E
     readonly body: Body.HttpBody;
 }
 /**
- * @since 4.0.0
+ * Common options accepted by HTTP server response constructors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Options {
     readonly status?: number | undefined;
@@ -45,105 +72,190 @@ export interface Options {
     readonly contentLength?: number | undefined;
 }
 /**
+ * Option variants used by response constructors with different body metadata
+ * rules.
+ *
  * @since 4.0.0
  */
 export declare namespace Options {
     /**
-     * @since 4.0.0
+     * Response options for constructors whose body determines its own content type
+     * and content length.
+     *
      * @category models
+     * @since 4.0.0
      */
     interface WithContent extends Omit<Options, "contentType" | "contentLength"> {
     }
     /**
-     * @since 4.0.0
+     * Response options for constructors that allow overriding the content type while
+     * deriving the content length from the body.
+     *
      * @category models
+     * @since 4.0.0
      */
     interface WithContentType extends Omit<Options, "contentLength"> {
     }
 }
 /**
+ * Returns `true` when the supplied value is an `HttpServerResponse`.
+ *
+ * @category guards
  * @since 4.0.0
  */
 export declare const isHttpServerResponse: (u: unknown) => u is HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates an empty HTTP response.
+ *
+ * The default status is `204`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const empty: (options?: Options.WithContent | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a redirect response with a `Location` header.
+ *
+ * The default status is `302`; custom headers are merged with the generated
+ * `Location` header.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const redirect: (location: string | URL, options?: Options.WithContent | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates an HTTP response whose body is a `Uint8Array`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const uint8Array: (body: Uint8Array, options?: Options.WithContentType) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates an HTTP response whose body is a string.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const text: (body: string, options?: Options.WithContentType) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates an HTML response with the `text/html` content type.
+ *
+ * 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.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const html: {
     /**
-     * @since 4.0.0
+     * Creates an HTML response with the `text/html` content type.
+     *
+     * 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.
+     *
      * @category constructors
+     * @since 4.0.0
      */
     <A extends ReadonlyArray<Template.Interpolated>>(strings: TemplateStringsArray, ...args: A): Effect.Effect<HttpServerResponse, Template.Interpolated.Error<A[number]>, Template.Interpolated.Context<A[number]>>;
     /**
-     * @since 4.0.0
+     * Creates an HTML response with the `text/html` content type.
+     *
+     * 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.
+     *
      * @category constructors
+     * @since 4.0.0
      */
     (html: string): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Creates a streaming HTML response from a template.
+ *
+ * The template is encoded as a byte stream and can use streaming interpolated
+ * values from the current context.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const htmlStream: <A extends ReadonlyArray<Template.InterpolatedWithStream>>(strings: TemplateStringsArray, ...args: A) => Effect.Effect<HttpServerResponse, never, Template.Interpolated.Context<A[number]>>;
 /**
- * @since 4.0.0
+ * Creates a JSON HTTP response.
+ *
+ * The body is serialized with `JSON.stringify`; serialization errors are captured
+ * as `HttpBodyError` failures.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const json: (body: unknown, options?: Options.WithContentType | undefined) => Effect.Effect<HttpServerResponse, Body.HttpBodyError>;
 /**
- * @since 4.0.0
+ * Creates a JSON response constructor backed by a schema encoder.
+ *
+ * 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.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const schemaJson: <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, options?: ParseOptions | undefined) => (body: A, options?: Options.WithContentType | undefined) => Effect.Effect<HttpServerResponse, Body.HttpBodyError, RE>;
 /**
- * @since 4.0.0
+ * Creates a JSON HTTP response synchronously.
+ *
+ * Unlike `json`, serialization errors from `JSON.stringify` are not captured in
+ * `Effect`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const jsonUnsafe: (body: unknown, options?: Options.WithContentType | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a response from URL parameters using the
+ * `application/x-www-form-urlencoded` content type by default.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const urlParams: (body: UrlParams.Input, options?: Options.WithContentType | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a response with a raw body value.
+ *
+ * Use this when the underlying runtime already understands the body value, such
+ * as a Web `Response`, `Blob`, or `ReadableStream`; the body is passed through
+ * for later platform conversion.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const raw: (body: unknown, options?: Options | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a response whose body is a Web `FormData` value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const formData: (body: FormData, options?: Options.WithContent | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a streaming response from a stream of byte chunks.
+ *
+ * Optional response metadata can supply the status, headers, content type, and
+ * content length.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const stream: <E>(body: Stream.Stream<Uint8Array, E>, options?: Options | undefined) => HttpServerResponse;
 /**
- * @since 4.0.0
+ * Creates a streamed file response for a file system path.
+ *
+ * The effect requires `HttpPlatform`, can fail with a platform error, and supports
+ * options for status, headers, offset, and byte range.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const file: (path: string, options?: (Options & {
     readonly bytesToRead?: FileSystem.SizeInput | undefined;
@@ -151,8 +263,13 @@ export declare const file: (path: string, options?: (Options & {
     readonly offset?: FileSystem.SizeInput | undefined;
 }) | undefined) => Effect.Effect<HttpServerResponse, PlatformError, HttpPlatform>;
 /**
- * @since 4.0.0
+ * Creates a streamed file response for a Web `File`-like value.
+ *
+ * The effect requires `HttpPlatform` and supports options for status, headers,
+ * offset, and byte range.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fileWeb: (file: Body.HttpBody.FileLike, options?: (Options.WithContent & {
     readonly bytesToRead?: FileSystem.SizeInput | undefined;
@@ -160,173 +277,309 @@ export declare const fileWeb: (file: Body.HttpBody.FileLike, options?: (Options.
     readonly offset?: FileSystem.SizeInput | undefined;
 }) | undefined) => Effect.Effect<HttpServerResponse, never, HttpPlatform>;
 /**
- * @since 4.0.0
+ * Returns a response with the specified header set to the supplied value.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setHeader: {
     /**
-     * @since 4.0.0
+     * Returns a response with the specified header set to the supplied value.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (key: string, value: string): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Returns a response with the specified header set to the supplied value.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, key: string, value: string): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Returns a response with all supplied headers set on the existing header map.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setHeaders: {
     /**
-     * @since 4.0.0
+     * Returns a response with all supplied headers set on the existing header map.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (input: Headers.Input): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Returns a response with all supplied headers set on the existing header map.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, input: Headers.Input): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Returns a response with the cookie of the specified name removed.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const removeCookie: {
     /**
-     * @since 4.0.0
+     * Returns a response with the cookie of the specified name removed.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (name: string): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Returns a response with the cookie of the specified name removed.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, name: string): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Returns a response with its cookie collection replaced by the supplied cookies.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const replaceCookies: {
     /**
-     * @since 4.0.0
+     * Returns a response with its cookie collection replaced by the supplied cookies.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (cookies: Cookies.Cookies): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Returns a response with its cookie collection replaced by the supplied cookies.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, cookies: Cookies.Cookies): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Sets a cookie on the response.
+ *
+ * The effect fails with `CookiesError` if the cookie name, value, or options are
+ * invalid.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setCookie: {
     /**
-     * @since 4.0.0
+     * Sets a cookie on the response.
+     *
+     * The effect fails with `CookiesError` if the cookie name, value, or options are
+     * invalid.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (name: string, value: string, options?: Cookies.Cookie["options"]): (self: HttpServerResponse) => Effect.Effect<HttpServerResponse, Cookies.CookiesError>;
     /**
-     * @since 4.0.0
+     * Sets a cookie on the response.
+     *
+     * The effect fails with `CookiesError` if the cookie name, value, or options are
+     * invalid.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, name: string, value: string, options?: Cookies.Cookie["options"]): Effect.Effect<HttpServerResponse, Cookies.CookiesError>;
 };
 /**
- * @since 4.0.0
+ * Expires a cookie on an `HttpServerResponse`.
+ *
+ * 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.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const expireCookie: {
     /**
-     * @since 4.0.0
+     * Expires a cookie on an `HttpServerResponse`.
+     *
+     * 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.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (name: string, options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">): (self: HttpServerResponse) => Effect.Effect<HttpServerResponse, Cookies.CookiesError>;
     /**
-     * @since 4.0.0
+     * Expires a cookie on an `HttpServerResponse`.
+     *
+     * 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.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, name: string, options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">): Effect.Effect<HttpServerResponse, Cookies.CookiesError>;
 };
 /**
- * @since 4.0.0
+ * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
+ * encoded.
+ *
+ * Use `setCookie` when cookie errors should be represented as `CookiesError`
+ * failures.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setCookieUnsafe: {
     /**
-     * @since 4.0.0
+     * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
+     * encoded.
+     *
+     * Use `setCookie` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (name: string, value: string, options?: Cookies.Cookie["options"]): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
+     * encoded.
+     *
+     * Use `setCookie` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, name: string, value: string, options?: Cookies.Cookie["options"]): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+ * cannot be encoded.
+ *
+ * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+ * failures.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const expireCookieUnsafe: {
     /**
-     * @since 4.0.0
+     * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+     * cannot be encoded.
+     *
+     * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (name: string, options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+     * cannot be encoded.
+     *
+     * Use `expireCookie` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, name: string, options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Updates the cookies attached to an `HttpServerResponse` using the supplied
+ * function.
+ *
+ * The original response is not mutated; a new response is returned with the
+ * callback result as its cookie collection.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const updateCookies: {
     /**
-     * @since 4.0.0
+     * Updates the cookies attached to an `HttpServerResponse` using the supplied
+     * function.
+     *
+     * The original response is not mutated; a new response is returned with the
+     * callback result as its cookie collection.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (f: (cookies: Cookies.Cookies) => Cookies.Cookies): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Updates the cookies attached to an `HttpServerResponse` using the supplied
+     * function.
+     *
+     * The original response is not mutated; a new response is returned with the
+     * callback result as its cookie collection.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, f: (cookies: Cookies.Cookies) => Cookies.Cookies): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Merges additional cookies into the cookies attached to an
+ * `HttpServerResponse`.
+ *
+ * The original response is not mutated; a new response is returned with the merged
+ * cookie collection.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const mergeCookies: {
     /**
-     * @since 4.0.0
+     * Merges additional cookies into the cookies attached to an
+     * `HttpServerResponse`.
+     *
+     * The original response is not mutated; a new response is returned with the merged
+     * cookie collection.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (cookies: Cookies.Cookies): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Merges additional cookies into the cookies attached to an
+     * `HttpServerResponse`.
+     *
+     * The original response is not mutated; a new response is returned with the merged
+     * cookie collection.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, cookies: Cookies.Cookies): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Sets multiple cookies on an `HttpServerResponse`.
+ *
+ * Each input entry contains a cookie name, value, and optional cookie options. The
+ * returned effect fails with `CookiesError` if any cookie cannot be encoded.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setCookies: {
     /**
-     * @since 4.0.0
+     * Sets multiple cookies on an `HttpServerResponse`.
+     *
+     * Each input entry contains a cookie name, value, and optional cookie options. The
+     * returned effect fails with `CookiesError` if any cookie cannot be encoded.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (cookies: Iterable<readonly [
         name: string,
@@ -334,8 +587,13 @@ export declare const setCookies: {
         options?: Cookies.Cookie["options"]
     ]>): (self: HttpServerResponse) => Effect.Effect<HttpServerResponse, Cookies.CookiesError, never>;
     /**
-     * @since 4.0.0
+     * Sets multiple cookies on an `HttpServerResponse`.
+     *
+     * Each input entry contains a cookie name, value, and optional cookie options. The
+     * returned effect fails with `CookiesError` if any cookie cannot be encoded.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, cookies: Iterable<readonly [
         name: string,
@@ -344,13 +602,25 @@ export declare const setCookies: {
     ]>): Effect.Effect<HttpServerResponse, Cookies.CookiesError, never>;
 };
 /**
- * @since 4.0.0
+ * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
+ * be encoded.
+ *
+ * Use `setCookies` when cookie errors should be represented as `CookiesError`
+ * failures.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setCookiesUnsafe: {
     /**
-     * @since 4.0.0
+     * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
+     * be encoded.
+     *
+     * Use `setCookies` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (cookies: Iterable<readonly [
         name: string,
@@ -358,8 +628,14 @@ export declare const setCookiesUnsafe: {
         options?: Cookies.Cookie["options"]
     ]>): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
+     * be encoded.
+     *
+     * Use `setCookies` when cookie errors should be represented as `CookiesError`
+     * failures.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, cookies: Iterable<readonly [
         name: string,
@@ -368,60 +644,108 @@ export declare const setCookiesUnsafe: {
     ]>): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Replaces the body of an `HttpServerResponse`.
+ *
+ * When the body carries a content type or content length, the returned response
+ * includes the corresponding headers.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setBody: {
     /**
-     * @since 4.0.0
+     * Replaces the body of an `HttpServerResponse`.
+     *
+     * When the body carries a content type or content length, the returned response
+     * includes the corresponding headers.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (body: Body.HttpBody): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Replaces the body of an `HttpServerResponse`.
+     *
+     * When the body carries a content type or content length, the returned response
+     * includes the corresponding headers.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, body: Body.HttpBody): HttpServerResponse;
 };
 /**
- * @since 4.0.0
+ * Sets the HTTP status code of an `HttpServerResponse`.
+ *
+ * When `statusText` is omitted, the existing status text is preserved.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export declare const setStatus: {
     /**
-     * @since 4.0.0
+     * Sets the HTTP status code of an `HttpServerResponse`.
+     *
+     * When `statusText` is omitted, the existing status text is preserved.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (status: number, statusText?: string | undefined): (self: HttpServerResponse) => HttpServerResponse;
     /**
-     * @since 4.0.0
+     * Sets the HTTP status code of an `HttpServerResponse`.
+     *
+     * When `statusText` is omitted, the existing status text is preserved.
+     *
      * @category combinators
+     * @since 4.0.0
      */
     (self: HttpServerResponse, status: number, statusText?: string | undefined): HttpServerResponse;
 };
 /**
+ * Converts an `HttpServerResponse` to a Web `Response`.
+ *
+ * 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.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export declare const toWeb: (response: HttpServerResponse, options?: {
     readonly withoutBody?: boolean | undefined;
     readonly context?: Context.Context<never> | undefined;
 }) => Response;
 /**
+ * Wraps an `HttpServerResponse` as an `HttpClientResponse`.
+ *
+ * An optional request can be supplied for client-response metadata and decode
+ * errors.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export declare const toClientResponse: (response: HttpServerResponse, options?: {
     readonly request?: HttpClientRequest.HttpClientRequest | undefined;
 }) => HttpClientResponse.HttpClientResponse;
 /**
+ * Converts an `HttpClientResponse` to an `HttpServerResponse`.
+ *
+ * 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.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export declare const fromClientResponse: (response: HttpClientResponse.HttpClientResponse) => HttpServerResponse;
 /**
+ * Converts a Web `Response` to an `HttpServerResponse`.
+ *
+ * `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.
+ *
+ * @category converting
  * @since 4.0.0
- * @category conversions
  */
 export declare const fromWeb: (response: Response) => HttpServerResponse;
 export {};