effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/unstable/http/HttpClientError.ts

@@ -48,7 +48,7 @@ export const isHttpClientError = (u: unknown): u is HttpClientError => hasProper
 /**
  * Error wrapper for HTTP client failures, exposing the failed request and the optional response through its `reason`.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class HttpClientError extends Data.TaggedError("HttpClientError")<{
@@ -103,9 +103,9 @@ const formatMessage = (reason: string, description: string | undefined, info: st
   description ? `${reason}: ${description} (${info})` : `${reason} error (${info})`
 
 /**
- * Request error for transport-level failures that occur while sending an HTTP request.
+ * Error describing transport-level failures that occur while sending an HTTP request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class TransportError extends Data.TaggedError("TransportError")<{
@@ -133,9 +133,9 @@ export class TransportError extends Data.TaggedError("TransportError")<{
 }
 
 /**
- * Request error for failures while encoding an HTTP request body.
+ * Error describing failures while encoding an HTTP request body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class EncodeError extends Data.TaggedError("EncodeError")<{
@@ -163,9 +163,9 @@ export class EncodeError extends Data.TaggedError("EncodeError")<{
 }
 
 /**
- * Request error for failures while constructing a URL from an HTTP client request.
+ * Error describing failures while constructing a URL from an HTTP client request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidUrlError extends Data.TaggedError("InvalidUrlError")<{
@@ -195,7 +195,7 @@ export class InvalidUrlError extends Data.TaggedError("InvalidUrlError")<{
 /**
  * Response error for HTTP responses rejected because of their status code.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class StatusCodeError extends Data.TaggedError("StatusCodeError")<{
@@ -227,7 +227,7 @@ export class StatusCodeError extends Data.TaggedError("StatusCodeError")<{
 /**
  * Response error for failures while decoding an HTTP response body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class DecodeError extends Data.TaggedError("DecodeError")<{
@@ -259,7 +259,7 @@ export class DecodeError extends Data.TaggedError("DecodeError")<{
 /**
  * Response error for operations that expected a response body but received an empty body.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class EmptyBodyError extends Data.TaggedError("EmptyBodyError")<{
@@ -291,7 +291,7 @@ export class EmptyBodyError extends Data.TaggedError("EmptyBodyError")<{
 /**
  * Union of HTTP client errors that occur before a response is available.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type RequestError = TransportError | EncodeError | InvalidUrlError
@@ -299,7 +299,7 @@ export type RequestError = TransportError | EncodeError | InvalidUrlError
 /**
  * Union of HTTP client errors that include an HTTP response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type ResponseError = StatusCodeError | DecodeError | EmptyBodyError
@@ -307,13 +307,14 @@ export type ResponseError = StatusCodeError | DecodeError | EmptyBodyError
 /**
  * Union of all specific failure reasons carried by `HttpClientError`.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type HttpClientErrorReason = RequestError | ResponseError
 
 /**
- * Serializable schema representation of an `HttpClientError`, preserving the specific error kind and cause.
+ * Schema for serializable HTTP client errors, preserving the specific error kind
+ * and cause.
  *
  * @category schemas
  * @since 4.0.0

package/src/unstable/http/HttpClientRequest.ts

@@ -1226,7 +1226,7 @@ const parseContentLength = (contentLength: string | null): number | undefined =>
 }
 
 /**
- * Converts an `HttpClientRequest` to a Web `Request` as a `Result`, failing when the request URL is invalid.
+ * Converts an `HttpClientRequest` safely to a Web `Request` as a `Result`, failing when the request URL is invalid.
  *
  * @category converting
  * @since 4.0.0

package/src/unstable/http/HttpEffect.ts

@@ -151,7 +151,7 @@ const handledSymbol = Symbol.for("effect/http/HttpEffect/handled")
  * Use only when another owner will close the scope; otherwise resources attached
  * to the request scope can leak.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const scopeDisableClose = (scope: Scope.Scope): void => {
@@ -159,9 +159,9 @@ export const scopeDisableClose = (scope: Scope.Scope): void => {
 }
 
 /**
- * For streaming server responses, transfers request scope ownership to the body stream so the scope closes when the stream exits.
+ * Returns a streaming server response that closes the request scope when the body stream exits.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const scopeTransferToStream = (

package/src/unstable/http/HttpMethod.ts

@@ -82,9 +82,14 @@ export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
   method !== "GET" && method !== "HEAD" && method !== "OPTIONS" && method !== "TRACE"
 
 /**
- * Set containing every supported `HttpMethod` literal.
+ * Provides a readonly set containing every supported `HttpMethod` literal.
  *
- * @category models
+ * **When to use**
+ *
+ * Use when you need to iterate over or test membership against every supported
+ * HTTP method literal.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const all: ReadonlySet<HttpMethod> = new Set([
@@ -99,9 +104,15 @@ export const all: ReadonlySet<HttpMethod> = new Set([
 ])
 
 /**
- * Tuples mapping each supported HTTP method to its short request-constructor name.
+ * Provides tuples mapping each supported HTTP method to its short
+ * request-constructor name.
  *
- * @category models
+ * **When to use**
+ *
+ * Use when you need the mapping from supported HTTP method literals to their
+ * short request-constructor names.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const allShort = [
@@ -116,7 +127,7 @@ export const allShort = [
 ] as const
 
 /**
- * Tests if a value is a `HttpMethod`.
+ * Checks whether a value is a `HttpMethod`.
  *
  * **Example** (Checking HTTP method values)
  *

package/src/unstable/http/HttpRouter.ts

@@ -65,7 +65,7 @@ import * as HttpServerResponse from "./HttpServerResponse.ts"
 const TypeId = "~effect/http/HttpRouter"
 
 /**
- * Service interface for registering HTTP routes and middleware.
+ * Defines the service interface for registering HTTP routes and middleware.
  *
  * **Details**
  *
@@ -290,14 +290,19 @@ export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
 )
 
 /**
- * Request-scoped service containing information about the matched route.
+ * Service for the matched HTTP route in the current request.
+ *
+ * **When to use**
+ *
+ * Use to read captured path parameters and route metadata while handling a
+ * request matched by the router.
  *
  * **Details**
  *
  * It provides the route definition and the path parameters captured by the route
  * matcher.
  *
- * @category RouteContext
+ * @category route context
  * @since 4.0.0
  */
 export class RouteContext extends Context.Service<RouteContext, {
@@ -887,7 +892,7 @@ const MiddlewareTypeId = "~effect/http/HttpRouter/Middleware"
  * while tracking provided services, handled errors, and remaining requirements at
  * the type level.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export interface Middleware<
@@ -988,7 +993,7 @@ export interface Middleware<
  * )
  * ```
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const middleware:
@@ -1126,7 +1131,7 @@ export declare namespace middleware {
    * layer that installs middleware for all routes. The type tracks provided
    * services, handled errors, middleware failures, and remaining requirements.
    *
-   * @category Middleware
+   * @category middleware
    * @since 4.0.0
    */
   export type Make<Provides = never, Handles = never> = {
@@ -1211,7 +1216,7 @@ export declare namespace middleware {
    * Function that transforms an HTTP response effect into another HTTP response
    * effect.
    *
-   * @category Middleware
+   * @category middleware
    * @since 4.0.0
    */
   export type Fn = (
@@ -1220,9 +1225,9 @@ export declare namespace middleware {
 }
 
 /**
- * A middleware that applies CORS headers to the HTTP response.
+ * Middleware that applies CORS headers to the HTTP response.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const cors = (
@@ -1237,7 +1242,7 @@ export const cors = (
 ): Layer.Layer<never, never, HttpRouter> => middleware(HttpMiddleware.cors(options), { global: true })
 
 /**
- * A middleware that disables the logger for some routes.
+ * Middleware that disables the logger for some routes.
  *
  * **Example** (Disabling route logging)
  *
@@ -1255,7 +1260,7 @@ export const cors = (
  * )
  * ```
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withLoggerDisabled).layer
@@ -1263,7 +1268,7 @@ export const disableLogger: Layer.Layer<never> = middleware(HttpMiddleware.withL
 /**
  * Provides request-level dependencies to some routes.
  *
- * @category Middleware
+ * @category middleware
  * @since 4.0.0
  */
 export const provideRequest =
@@ -1286,7 +1291,7 @@ export const provideRequest =
     )
 
 /**
- * Serves the provided application layer as an HTTP server.
+ * Runs the provided application layer as an HTTP server.
  *
  * @category Server
  * @since 4.0.0

package/src/unstable/http/HttpServer.ts

@@ -391,7 +391,7 @@ export const withLogAddress = <A, E, R>(
  *
  * Unix socket addresses are not supported.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const makeTestClient: Effect.Effect<
@@ -413,7 +413,7 @@ export const makeTestClient: Effect.Effect<
 /**
  * Layer that provides the test `HttpClient` created by `makeTestClient`.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const layerTestClient: Layer.Layer<
@@ -423,7 +423,7 @@ export const layerTestClient: Layer.Layer<
 > = Layer.effect(HttpClient.HttpClient)(makeTestClient)
 
 /**
- * Testing layer that provides the platform services commonly needed by HTTP
+ * Layer that provides the platform services commonly needed by HTTP
  * server tests.
  *
  * **Details**
@@ -431,7 +431,7 @@ export const layerTestClient: Layer.Layer<
  * It includes `HttpPlatform`, `Path`, a weak ETag generator, and a no-op
  * `FileSystem`.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const layerServices: Layer.Layer<

package/src/unstable/http/HttpServerError.ts

@@ -58,7 +58,7 @@ const TypeId = "~effect/http/HttpServerError"
  * response, and can be converted to an HTTP response through the `Respondable`
  * protocol.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class HttpServerError extends Data.TaggedError("HttpServerError")<{
@@ -109,7 +109,7 @@ export class HttpServerError extends Data.TaggedError("HttpServerError")<{
  *
  * When converted to a response it produces an empty `400` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class RequestParseError extends Data.TaggedError("RequestParseError")<{
@@ -143,7 +143,7 @@ export class RequestParseError extends Data.TaggedError("RequestParseError")<{
  * When converted to a response it produces an empty `404` response, and it is
  * ignored by the error reporter.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
@@ -173,7 +173,7 @@ export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
  *
  * When converted to a response it produces an empty `500` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class InternalError extends Data.TaggedError("InternalError")<{
@@ -215,7 +215,7 @@ export const isHttpServerError = (u: unknown): u is HttpServerError => hasProper
  * It carries the request and response involved in the failure. When converted to
  * a response it produces an empty `500` response.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class ResponseError extends Data.TaggedError("ResponseError")<{
@@ -241,7 +241,7 @@ export class ResponseError extends Data.TaggedError("ResponseError")<{
 /**
  * Union of errors that are tied directly to an incoming server request.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type RequestError = RequestParseError | RouteNotFound | InternalError
@@ -249,7 +249,7 @@ export type RequestError = RequestParseError | RouteNotFound | InternalError
 /**
  * Reason carried by an `HttpServerError`, either a request-level error or a response-level error.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export type HttpServerErrorReason = RequestError | ResponseError
@@ -257,7 +257,7 @@ export type HttpServerErrorReason = RequestError | ResponseError
 /**
  * Error wrapping a low-level failure from the HTTP server implementation.
  *
- * @category error
+ * @category errors
  * @since 4.0.0
  */
 export class ServeError extends Data.TaggedError("ServeError")<{
@@ -350,7 +350,7 @@ export const causeResponse = <E>(
 }
 
 /**
- * Synchronously derives an HTTP response from a failed handler cause.
+ * Derives an HTTP response from a failed handler cause synchronously.
  *
  * **Details**
  *

package/src/unstable/http/HttpServerRequest.ts

@@ -62,7 +62,12 @@ import * as UrlParams from "./UrlParams.ts"
 
 export {
   /**
-   * Re-exports the `MaxBodySize` fiber reference for configuring request body limits.
+   * Provides the `MaxBodySize` fiber reference for configuring request body limits.
+   *
+   * **When to use**
+   *
+   * Use to configure the maximum body size accepted while reading server
+   * request bodies.
    *
    * @category fiber refs
    * @since 4.0.0
@@ -117,7 +122,12 @@ export interface HttpServerRequest extends HttpIncomingMessage.HttpIncomingMessa
 }
 
 /**
- * Service tag for the current `HttpServerRequest`.
+ * Service tag for the active server-side HTTP request.
+ *
+ * **When to use**
+ *
+ * Use to access the request currently being handled by HTTP server routes and
+ * middleware.
  *
  * @category context
  * @since 4.0.0
@@ -127,7 +137,12 @@ export const HttpServerRequest: Context.Service<HttpServerRequest, HttpServerReq
 )
 
 /**
- * Request-scoped service containing parsed search parameters.
+ * Service that contains decoded URL query parameters for the current request.
+ *
+ * **When to use**
+ *
+ * Use to access query parameters that have already been parsed for the current
+ * server request.
  *
  * **Details**
  *
@@ -1006,7 +1021,7 @@ const isFormData = (u: unknown): u is FormData => typeof FormData !== "undefined
 const textDecoder = new TextDecoder()
 
 /**
- * Attempts to construct an absolute `URL` for a server request.
+ * Attempts to construct an absolute `URL` for a server request safely.
  *
  * **Details**
  *
@@ -1028,7 +1043,7 @@ export const toURL = (self: HttpServerRequest): Option.Option<URL> => {
 }
 
 /**
- * Converts an `HttpServerRequest` to a Web `Request` as a `Result`.
+ * Converts an `HttpServerRequest` safely to a Web `Request` as a `Result`.
  *
  * **Details**
  *

package/src/unstable/http/HttpServerResponse.ts

@@ -742,7 +742,7 @@ export const setCookie: {
 )
 
 /**
- * Expires a cookie on an `HttpServerResponse`.
+ * Sets an expired cookie on an `HttpServerResponse`.
  *
  * **Details**
  *
@@ -754,7 +754,7 @@ export const setCookie: {
  */
 export const expireCookie: {
   /**
-   * Expires a cookie on an `HttpServerResponse`.
+   * Sets an expired cookie on an `HttpServerResponse`.
    *
    * **Details**
    *
@@ -771,7 +771,7 @@ export const expireCookie: {
     self: HttpServerResponse
   ) => Effect.Effect<HttpServerResponse, Cookies.CookiesError>
   /**
-   * Expires a cookie on an `HttpServerResponse`.
+   * Sets an expired cookie on an `HttpServerResponse`.
    *
    * **Details**
    *
@@ -809,8 +809,8 @@ export const expireCookie: {
  *
  * **When to use**
  *
- * Use when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when setting one trusted cookie and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -822,8 +822,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -835,8 +835,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -862,26 +862,26 @@ export const setCookieUnsafe: {
 )
 
 /**
- * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+ * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
  * cannot be encoded.
  *
  * **When to use**
  *
- * Use when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when expiring one trusted cookie and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const expireCookieUnsafe: {
   /**
-   * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+   * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when expiring one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -891,13 +891,13 @@ export const expireCookieUnsafe: {
     options?: Omit<NonNullable<Cookies.Cookie["options"]>, "expires" | "maxAge">
   ): (self: HttpServerResponse) => HttpServerResponse
   /**
-   * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
+   * Sets an expired cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when expiring one trusted cookie and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1096,8 +1096,8 @@ export const setCookies: {
  *
  * **When to use**
  *
- * Use when cookie errors should be represented as `CookiesError`
- * failures.
+ * Use when setting multiple trusted cookies and encoding failures should throw
+ * instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -1109,8 +1109,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting multiple trusted cookies and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1130,8 +1130,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use when cookie errors should be represented as `CookiesError`
-   * failures.
+   * Use when setting multiple trusted cookies and encoding failures should throw
+   * instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0

package/src/unstable/http/HttpTraceContext.ts

@@ -74,7 +74,7 @@ export const toHeaders = (span: Tracer.Span): Headers.Headers =>
   })
 
 /**
- * Decodes an external span from HTTP trace propagation headers.
+ * Decodes an external span safely from HTTP trace propagation headers.
  *
  * **Details**
  *
@@ -97,7 +97,7 @@ export const fromHeaders = (headers: Headers.Headers): Option.Option<Tracer.Exte
 }
 
 /**
- * Decodes an external span from the compact B3 `b3` header.
+ * Decodes an external span safely from the compact B3 `b3` header.
  *
  * **Details**
  *
@@ -123,7 +123,7 @@ export const b3: FromHeaders = (headers) => {
 }
 
 /**
- * Decodes an external span from multi-header B3 propagation headers.
+ * Decodes an external span safely from multi-header B3 propagation headers.
  *
  * **Details**
  *
@@ -148,7 +148,7 @@ const w3cTraceId = /^[0-9a-f]{32}$/i
 const w3cSpanId = /^[0-9a-f]{16}$/i
 
 /**
- * Decodes an external span from the W3C `traceparent` header.
+ * Decodes an external span safely from the W3C `traceparent` header.
  *
  * **Details**
  *

package/src/unstable/http/Multipart.ts

@@ -213,7 +213,7 @@ export interface Persisted {
 const MultipartErrorTypeId = "~effect/http/Multipart/MultipartError"
 
 /**
- * Reason carried by a `MultipartError`.
+ * Error reason carried by a `MultipartError`.
  *
  * **Details**
  *
@@ -404,7 +404,7 @@ export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, opt
  * Parser limits are read from the multipart references, including maximum parts,
  * field size, file size, total body size, and field MIME type overrides.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const makeConfig = (