effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/http/HttpServerResponse.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"
@@ -31,8 +51,13 @@ import * as UrlParams from "./UrlParams.ts"
 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
@@ -44,8 +69,10 @@ export interface HttpServerResponse extends Inspectable.Inspectable, Pipeable, E
 }
 
 /**
- * @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
@@ -57,30 +84,45 @@ export interface Options {
 }
 
 /**
+ * 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
    */
   export 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
    */
   export interface WithContentType extends Omit<Options, "contentLength"> {}
 }
 
 /**
+ * Returns `true` when the supplied value is an `HttpServerResponse`.
+ *
  * @since 4.0.0
  */
 export const isHttpServerResponse = (u: unknown): u is HttpServerResponse => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Creates an empty HTTP response.
+ *
+ * The default status is `204`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const empty = (
   options?: Options.WithContent | undefined
@@ -93,8 +135,13 @@ export const empty = (
   })
 
 /**
- * @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 const redirect = (
   location: string | URL,
@@ -112,8 +159,10 @@ export const redirect = (
 }
 
 /**
- * @since 4.0.0
+ * Creates an HTTP response whose body is a `Uint8Array`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const uint8Array = (
   body: Uint8Array,
@@ -143,8 +192,10 @@ const getContentType = (
 }
 
 /**
- * @since 4.0.0
+ * Creates an HTTP response whose body is a string.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const text = (
   body: string,
@@ -163,13 +214,25 @@ export const text = (
 }
 
 /**
- * @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 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,
@@ -177,8 +240,14 @@ export const html: {
     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
 } = (
@@ -193,8 +262,13 @@ export const html: {
 }
 
 /**
- * @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 const htmlStream = <
   A extends ReadonlyArray<Template.InterpolatedWithStream>
@@ -219,8 +293,13 @@ export const htmlStream = <
   )
 
 /**
- * @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 const json = (
   body: unknown,
@@ -238,8 +317,14 @@ export const json = (
 }
 
 /**
- * @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 const schemaJson = <A, I, RD, RE>(
   schema: Schema.Codec<A, I, RD, RE>,
@@ -263,8 +348,13 @@ export const schemaJson = <A, I, RD, 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 const jsonUnsafe = (
   body: unknown,
@@ -281,8 +371,11 @@ export const jsonUnsafe = (
 }
 
 /**
- * @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 const urlParams = (
   body: UrlParams.Input,
@@ -302,8 +395,14 @@ export const urlParams = (
 }
 
 /**
- * @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 const raw = (
   body: unknown,
@@ -321,8 +420,10 @@ export const raw = (
   })
 
 /**
- * @since 4.0.0
+ * Creates a response whose body is a Web `FormData` value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const formData = (
   body: FormData,
@@ -337,8 +438,13 @@ export const formData = (
   })
 
 /**
- * @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 const stream = <E>(
   body: Stream.Stream<Uint8Array, E>,
@@ -366,8 +472,13 @@ const HttpPlatformKey = Context.Service<
 >("effect/http/HttpPlatform" satisfies typeof HttpPlatform.key)
 
 /**
- * @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 const file = (
   path: string,
@@ -379,11 +490,16 @@ export const file = (
     })
     | undefined
 ): Effect.Effect<HttpServerResponse, PlatformError, HttpPlatform> =>
-  Effect.flatMap(HttpPlatformKey.asEffect(), (platform) => platform.fileResponse(path, options))
+  Effect.flatMap(HttpPlatformKey, (platform) => platform.fileResponse(path, options))
 
 /**
- * @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 const fileWeb = (
   file: Body.HttpBody.FileLike,
@@ -395,21 +511,27 @@ export const fileWeb = (
     })
     | undefined
 ): Effect.Effect<HttpServerResponse, never, HttpPlatform> =>
-  Effect.flatMap(HttpPlatformKey.asEffect(), (platform) => platform.fileWebResponse(file, options))
+  Effect.flatMap(HttpPlatformKey, (platform) => platform.fileWebResponse(file, options))
 
 /**
- * @since 4.0.0
+ * Returns a response with the specified header set to the supplied value.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export 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
 } = dual(
@@ -422,18 +544,24 @@ export const setHeader: {
 )
 
 /**
- * @since 4.0.0
+ * Returns a response with all supplied headers set on the existing header map.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export 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
 } = dual(
@@ -446,18 +574,24 @@ export const setHeaders: {
 )
 
 /**
- * @since 4.0.0
+ * Returns a response with the cookie of the specified name removed.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export 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
 } = dual(
@@ -470,18 +604,24 @@ export const removeCookie: {
 )
 
 /**
- * @since 4.0.0
+ * Returns a response with its cookie collection replaced by the supplied cookies.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export 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
 } = dual(
@@ -490,20 +630,35 @@ export const replaceCookies: {
 )
 
 /**
- * @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 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,
@@ -520,7 +675,7 @@ export const setCookie: {
     options?: Cookies.Cookie["options"]
   ): Effect.Effect<HttpServerResponse, Cookies.CookiesError> =>
     Effect.map(
-      Cookies.set(self.cookies, name, value, options).asEffect(),
+      Effect.fromResult(Cookies.set(self.cookies, name, value, options)),
       (cookies) =>
         makeResponse({
           ...self,
@@ -530,13 +685,23 @@ export const setCookie: {
 )
 
 /**
- * @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 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,
@@ -545,8 +710,13 @@ export const expireCookie: {
     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,
@@ -561,7 +731,7 @@ export const expireCookie: {
     options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">
   ): Effect.Effect<HttpServerResponse, Cookies.CookiesError> =>
     Effect.map(
-      Cookies.expireCookie(self.cookies, name, options).asEffect(),
+      Effect.fromResult(Cookies.expireCookie(self.cookies, name, options)),
       (cookies) =>
         makeResponse({
           ...self,
@@ -571,18 +741,36 @@ export const expireCookie: {
 )
 
 /**
- * @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 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,
@@ -605,21 +793,39 @@ export const setCookieUnsafe: {
 )
 
 /**
- * @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 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,
@@ -640,18 +846,36 @@ export const expireCookieUnsafe: {
 )
 
 /**
- * @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 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
 } = dual(
@@ -667,18 +891,36 @@ export const updateCookies: {
 )
 
 /**
- * @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 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
 } = dual(
@@ -688,13 +930,23 @@ export const mergeCookies: {
 )
 
 /**
- * @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 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<
@@ -708,8 +960,13 @@ export const setCookies: {
     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,
@@ -733,7 +990,7 @@ export const setCookies: {
       ]
     >
   ): Effect.Effect<HttpServerResponse, Cookies.CookiesError> =>
-    Effect.map(Cookies.setAll(self.cookies, cookies).asEffect(), (cookies) =>
+    Effect.map(Effect.fromResult(Cookies.setAll(self.cookies, cookies)), (cookies) =>
       makeResponse({
         ...self,
         cookies
@@ -741,13 +998,25 @@ export const setCookies: {
 )
 
 /**
- * @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 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<
@@ -759,8 +1028,14 @@ export const setCookiesUnsafe: {
     >
   ): (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,
@@ -791,18 +1066,33 @@ export const setCookiesUnsafe: {
 )
 
 /**
- * @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 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
 } = dual(
@@ -811,18 +1101,30 @@ export const setBody: {
 )
 
 /**
- * @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 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
 } = dual(
@@ -840,8 +1142,14 @@ export const setStatus: {
 )
 
 /**
- * @since 4.0.0
+ * 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 conversions
+ * @since 4.0.0
  */
 export const toWeb = (
   response: HttpServerResponse,
@@ -911,8 +1219,13 @@ export const toWeb = (
 }
 
 /**
- * @since 4.0.0
+ * Wraps an `HttpServerResponse` as an `HttpClientResponse`.
+ *
+ * An optional request can be supplied for client-response metadata and decode
+ * errors.
+ *
  * @category conversions
+ * @since 4.0.0
  */
 export const toClientResponse = (
   response: HttpServerResponse,
@@ -1125,8 +1438,13 @@ class ServerHttpClientResponse extends Inspectable.Class implements HttpClientRe
 const textDecoder = new TextDecoder()
 
 /**
- * @since 4.0.0
+ * 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 conversions
+ * @since 4.0.0
  */
 export const fromClientResponse = (
   response: HttpClientResponse.HttpClientResponse
@@ -1211,8 +1529,13 @@ const makeResponse = (options: {
 }
 
 /**
- * @since 4.0.0
+ * 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 conversions
+ * @since 4.0.0
  */
 export const fromWeb = (response: Response): HttpServerResponse => {
   const headers = new globalThis.Headers(response.headers)