effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/http/HttpBody.ts

@@ -42,6 +42,8 @@ export const isHttpBody = (u: unknown): u is HttpBody => Predicate.hasProperty(u
 /**
  * Represents an HTTP request body.
  *
+ * **Details**
+ *
  * Supported variants include empty bodies, raw bodies, byte arrays, `FormData`, and streams of bytes.
  *
  * @category models
@@ -58,6 +60,8 @@ export declare namespace HttpBody {
   /**
    * Common protocol implemented by all HTTP body variants.
    *
+   * **Details**
+   *
    * It carries the variant tag plus optional `contentType` and `contentLength` metadata.
    *
    * @category models
@@ -108,6 +112,8 @@ export class HttpBodyError extends Data.TaggedError("HttpBodyError")<{
 /**
  * Reason for an `HttpBodyError`.
  *
+ * **Details**
+ *
  * `JsonError` represents a `JSON.stringify` failure; `SchemaError` represents a schema encoding issue.
  *
  * @category errors
@@ -209,6 +215,8 @@ export const raw = (
 /**
  * HTTP body variant backed by a `Uint8Array`.
  *
+ * **Details**
+ *
  * It stores the bytes, content type, and byte length.
  *
  * @category models
@@ -245,6 +253,8 @@ export class Uint8Array extends Proto {
 /**
  * Creates a byte-array HTTP body.
  *
+ * **Details**
+ *
  * The content type defaults to `application/octet-stream`, and the content length is the byte array length.
  *
  * @category constructors
@@ -258,6 +268,8 @@ const encoder = new TextEncoder()
 /**
  * Creates a UTF-8 encoded text HTTP body.
  *
+ * **Details**
+ *
  * The content type defaults to `text/plain`.
  *
  * @category constructors
@@ -269,6 +281,8 @@ export const text = (body: string, contentType?: string): Uint8Array =>
 /**
  * Creates a JSON HTTP body using `JSON.stringify`, throwing if serialization fails.
  *
+ * **Details**
+ *
  * The content type defaults to `application/json`.
  *
  * @category constructors
@@ -280,6 +294,8 @@ export const jsonUnsafe = (body: unknown, contentType?: string): Uint8Array =>
 /**
  * Creates a JSON HTTP body in an `Effect`.
  *
+ * **Details**
+ *
  * `JSON.stringify` failures are captured as `HttpBodyError` values, and the content type defaults to `application/json`.
  *
  * @category constructors
@@ -294,6 +310,8 @@ export const json = (body: unknown, contentType?: string): Effect.Effect<Uint8Ar
 /**
  * Creates a JSON body constructor that first encodes values with the schema's JSON codec.
  *
+ * **Details**
+ *
  * Schema encoding issues and JSON serialization failures are returned as `HttpBodyError` values.
  *
  * @category constructors
@@ -323,6 +341,8 @@ export const urlParams = (urlParams: UrlParams.UrlParams, contentType?: string):
 /**
  * HTTP body variant backed by Web `FormData`.
  *
+ * **Details**
+ *
  * The content type and content length are left unset so the runtime can supply multipart boundaries.
  *
  * @category models
@@ -360,6 +380,8 @@ export const formData = (body: globalThis.FormData): FormData => new FormData(bo
 /**
  * Record input accepted by `formDataRecord`.
  *
+ * **Details**
+ *
  * Each field may be a single coercible value or an array of coercible values.
  *
  * @category models
@@ -370,6 +392,8 @@ export type FormDataInput = Record<string, FormDataCoercible | ReadonlyArray<For
 /**
  * Value that can be appended by `formDataRecord`.
  *
+ * **Details**
+ *
  * `File` and `Blob` values are appended directly, primitive values are converted to strings, and `null` or `undefined` values are skipped.
  *
  * @category models
@@ -391,6 +415,8 @@ const appendFormDataValue = (formData: globalThis.FormData, key: string, value:
 /**
  * Creates a `FormData` HTTP body from a record.
  *
+ * **Details**
+ *
  * Array fields append each item under the same key; primitive values are stringified, `File` and `Blob` values are appended directly, and nullish values are skipped.
  *
  * @category constructors
@@ -445,6 +471,8 @@ export class Stream extends Proto {
 /**
  * Creates a streaming HTTP body from a stream of byte chunks.
  *
+ * **Details**
+ *
  * The content type defaults to `application/octet-stream`; content length is optional.
  *
  * @category constructors
@@ -459,6 +487,8 @@ export const stream = (
 /**
  * Creates a streaming HTTP body for a file path.
  *
+ * **Details**
+ *
  * The effect requires `FileSystem`, stats the file to set the content length, and can fail with `PlatformError`.
  *
  * @category constructors
@@ -487,6 +517,8 @@ export const file = (
 /**
  * Creates a streaming HTTP body for a file path using already-known file information.
  *
+ * **Details**
+ *
  * The effect requires `FileSystem`, uses the provided file size as the content length, and can fail with `PlatformError`.
  *
  * @category constructors

package/src/unstable/http/HttpClient.ts

@@ -78,6 +78,8 @@ export declare namespace HttpClient {
   /**
    * Parameterized HTTP client that may fail with `E` and require environment `R`.
    *
+   * **Details**
+   *
    * It exposes preprocessing, postprocessing, direct request execution, and method-specific helpers.
    *
    * @category models
@@ -255,6 +257,8 @@ export const options: (url: string | URL, options?: HttpClientRequest.Options.No
 /**
  * Transforms a client by wrapping the response effect for each request.
  *
+ * **Details**
+ *
  * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
  *
  * @category mapping & sequencing
@@ -264,6 +268,8 @@ export const transform: {
   /**
    * Transforms a client by wrapping the response effect for each request.
    *
+   * **Details**
+   *
    * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
    *
    * @category mapping & sequencing
@@ -278,6 +284,8 @@ export const transform: {
   /**
    * Transforms a client by wrapping the response effect for each request.
    *
+   * **Details**
+   *
    * The transformation receives both the response effect and the original request, allowing it to change success, error, and environment behavior.
    *
    * @category mapping & sequencing
@@ -357,6 +365,8 @@ const catch_: {
 
 export {
   /**
+   * Handles all client failures with an effectful recovery function and returns a transformed client.
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -669,6 +679,8 @@ export const filterStatusOk: <E, R>(self: HttpClient.With<E, R>) => HttpClient.W
 /**
  * Constructs an `HttpClient.With` from a preprocessing function and a postprocessing function.
  *
+ * **Details**
+ *
  * `execute` applies preprocessing to the request and then passes the resulting request effect to postprocessing.
  *
  * @category constructors
@@ -712,6 +724,8 @@ const Proto = {
 /**
  * Constructs an `HttpClient` from a low-level request runner.
  *
+ * **Details**
+ *
  * The runner receives the request, resolved URL, abort signal, and current fiber. The client wrapper handles URL construction failures, tracing and propagation, header redaction, and aborting non-scoped requests on interruption.
  *
  * @category constructors
@@ -961,6 +975,8 @@ export declare namespace Retry {
   /**
    * Computes the client type returned by `retry` for a given set of retry options.
    *
+   * **Details**
+   *
    * The result includes errors and requirements introduced by schedules and effectful retry predicates.
    *
    * @category error handling
@@ -1026,8 +1042,12 @@ export const retry: {
 /**
  * Retries common transient errors, such as rate limiting, timeouts or network issues.
  *
+ * **When to use**
+ *
  * Use `retryOn` to focus on retrying errors, transient responses, or both.
  *
+ * **Details**
+ *
  * Specifying a `while` predicate allows you to consider other errors as
  * transient, and is ignored in "response-only" mode.
  *
@@ -1038,8 +1058,12 @@ export const retryTransient: {
   /**
    * Retries common transient errors, such as rate limiting, timeouts or network issues.
    *
+   * **When to use**
+   *
    * Use `retryOn` to focus on retrying errors, transient responses, or both.
    *
+   * **Details**
+   *
    * Specifying a `while` predicate allows you to consider other errors as
    * transient, and is ignored in "response-only" mode.
    *
@@ -1069,8 +1093,12 @@ export const retryTransient: {
   /**
    * Retries common transient errors, such as rate limiting, timeouts or network issues.
    *
+   * **When to use**
+   *
    * Use `retryOn` to focus on retrying errors, transient responses, or both.
    *
+   * **Details**
+   *
    * Specifying a `while` predicate allows you to consider other errors as
    * transient, and is ignored in "response-only" mode.
    *
@@ -1102,8 +1130,12 @@ export const retryTransient: {
   /**
    * Retries common transient errors, such as rate limiting, timeouts or network issues.
    *
+   * **When to use**
+   *
    * Use `retryOn` to focus on retrying errors, transient responses, or both.
    *
+   * **Details**
+   *
    * Specifying a `while` predicate allows you to consider other errors as
    * transient, and is ignored in "response-only" mode.
    *
@@ -1116,8 +1148,12 @@ export const retryTransient: {
   /**
    * Retries common transient errors, such as rate limiting, timeouts or network issues.
    *
+   * **When to use**
+   *
    * Use `retryOn` to focus on retrying errors, transient responses, or both.
    *
+   * **Details**
+   *
    * Specifying a `while` predicate allows you to consider other errors as
    * transient, and is ignored in "response-only" mode.
    *
@@ -1179,6 +1215,8 @@ export declare namespace WithRateLimiter {
   /**
    * Options used to configure `withRateLimiter`.
    *
+   * **Details**
+   *
    * They define the backing limiter, initial limit window, keying strategy, algorithm, token cost, and whether response headers update future limits.
    *
    * @category rate limiting
@@ -1221,6 +1259,8 @@ export declare namespace WithRateLimiter {
 /**
  * Applies request rate limiting using the `RateLimiter` service.
  *
+ * **Details**
+ *
  * It can update limits by inspecting common rate limit response headers and
  * automatically retries HTTP `429` responses (or `HttpClientError` values
  * wrapping a `429` response) by forcing the retry back through the limiter.
@@ -1232,6 +1272,8 @@ export const withRateLimiter: {
   /**
    * Applies request rate limiting using the `RateLimiter` service.
    *
+   * **Details**
+   *
    * It can update limits by inspecting common rate limit response headers and
    * automatically retries HTTP `429` responses (or `HttpClientError` values
    * wrapping a `429` response) by forcing the retry back through the limiter.
@@ -1245,6 +1287,8 @@ export const withRateLimiter: {
   /**
    * Applies request rate limiting using the `RateLimiter` service.
    *
+   * **Details**
+   *
    * It can update limits by inspecting common rate limit response headers and
    * automatically retries HTTP `429` responses (or `HttpClientError` values
    * wrapping a `429` response) by forcing the retry back through the limiter.

package/src/unstable/http/HttpClientRequest.ts

@@ -211,6 +211,8 @@ const del: (url: string | URL, options?: Options.NoUrl) => HttpClientRequest = m
 
 export {
   /**
+   * Creates a `DELETE` request for the specified URL.
+   *
    * @category constructors
    * @since 4.0.0
    */

package/src/unstable/http/HttpClientResponse.ts

@@ -36,16 +36,22 @@ import * as UrlParams from "./UrlParams.ts"
 
 export {
   /**
+   * Creates a decoder that reads a response JSON body and decodes it with the supplied schema.
+   *
    * @category schemas
    * @since 4.0.0
    */
   schemaBodyJson,
   /**
+   * Creates a decoder that reads response URL-encoded body parameters and decodes them with the supplied schema.
+   *
    * @category schemas
    * @since 4.0.0
    */
   schemaBodyUrlParams,
   /**
+   * Creates a decoder that validates and decodes response headers with the supplied schema.
+   *
    * @category schemas
    * @since 4.0.0
    */

package/src/unstable/http/HttpEffect.ts

@@ -129,6 +129,8 @@ const handledSymbol = Symbol.for("effect/http/HttpEffect/handled")
 /**
  * Disables automatic closing for an HTTP request scope.
  *
+ * **Gotchas**
+ *
  * Use only when another owner will close the scope; otherwise resources attached
  * to the request scope can leak.
  *
@@ -203,6 +205,8 @@ export const appendPreResponseHandler = (handler: PreResponseHandler): Effect.Ef
 
 export {
   /**
+   * Registers a pre-response handler for the supplied HTTP server request.
+   *
    * @category fiber refs
    * @since 4.0.0
    */

package/src/unstable/http/HttpPlatform.ts

@@ -145,6 +145,8 @@ export const make: (impl: {
  * Provides the default `HttpPlatform` implementation for serving file paths and
  * `File`-like values as streamed HTTP responses.
  *
+ * **Details**
+ *
  * The layer uses the `FileSystem` and weak ETag services to add file metadata
  * headers such as `etag` and `last-modified`.
  *

package/src/unstable/http/HttpRouter.ts

@@ -44,6 +44,8 @@ const TypeId = "~effect/http/HttpRouter"
 /**
  * Service interface for registering HTTP routes and middleware.
  *
+ * **Details**
+ *
  * An `HttpRouter` can add routes, apply path prefixes, install global middleware,
  * and expose the registered routes as an Effect that handles the current server
  * request.
@@ -101,7 +103,6 @@ export interface HttpRouter {
 
 /**
  * Service tag for the HTTP router used while constructing an HTTP application.
- *
  * Route and middleware layers require this service to register themselves with
  * the router.
  *
@@ -115,6 +116,8 @@ export const HttpRouter: Context.Service<HttpRouter, HttpRouter> = Context.Servi
 /**
  * Constructs an empty `HttpRouter` service.
  *
+ * **Details**
+ *
  * The returned router accepts route and middleware registrations and later routes
  * the current `HttpServerRequest` to the matching `HttpServerResponse`.
  *
@@ -250,6 +253,8 @@ function sliceRequestUrl(request: HttpServerRequest.HttpServerRequest, prefix: s
 /**
  * Context reference for low-level router configuration.
  *
+ * **Details**
+ *
  * The value is passed to the route matcher when an `HttpRouter` is created and
  * defaults to an empty configuration.
  *
@@ -264,6 +269,8 @@ export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
 /**
  * Request-scoped service containing information about the matched route.
  *
+ * **Details**
+ *
  * It provides the route definition and the path parameters captured by the route
  * matcher.
  *
@@ -290,6 +297,8 @@ export const params: Effect.Effect<
 /**
  * Decodes a schema from the current request and its JSON body.
  *
+ * **Details**
+ *
  * The input passed to the schema includes the request method, URL, headers,
  * cookies, path parameters, search parameters, and parsed JSON body. The effect
  * fails if the body cannot be parsed or the schema decode fails.
@@ -345,6 +354,8 @@ export const schemaJson = <
 /**
  * Decodes a schema from the current request without reading the request body.
  *
+ * **Details**
+ *
  * The input passed to the schema includes the request method, URL, headers,
  * cookies, path parameters, and search parameters.
  *
@@ -396,6 +407,8 @@ export const schemaNoBody = <
 /**
  * Decodes a schema from the current route path parameters and search parameters.
  *
+ * **Details**
+ *
  * When the same key appears in both sources, the path parameter value is used.
  *
  * @category schemas
@@ -432,6 +445,8 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  * Creates a layer that accesses the current `HttpRouter` service and runs the
  * supplied effect.
  *
+ * **When to use**
+ *
  * Use it to register routes or middleware with the router during layer
  * construction.
  *
@@ -542,6 +557,8 @@ export const layer: Layer.Layer<HttpRouter> = Layer.effect(HttpRouter)(make)
  * Builds an application layer with a router and returns the router as an HTTP
  * handler effect.
  *
+ * **Details**
+ *
  * The returned effect handles the current `HttpServerRequest` in the current
  * `Scope`; route request markers are converted into the ordinary requirements of
  * the returned handler.
@@ -572,6 +589,8 @@ const RouteTypeId = "~effect/http/HttpRouter/Route"
 /**
  * Description of a registered HTTP route.
  *
+ * **Details**
+ *
  * A route pairs an HTTP method and path pattern with a response handler, plus
  * metadata used for prefix handling and interruptibility.
  *
@@ -627,6 +646,8 @@ const makeRoute = <E, R>(options: {
 /**
  * Constructs a `Route` from an HTTP method, path, and handler.
  *
+ * **Details**
+ *
  * The handler may be a static response, an effect that produces a response, or a
  * function from the current request to a response effect. Set `uninterruptible` to
  * prevent the route handler from being made interruptible while it runs.
@@ -658,9 +679,8 @@ export const route = <E = never, R = never>(
   })
 
 /**
- * Path pattern accepted by the router.
- *
- * Routes must use an absolute path beginning with `/` or the wildcard `*`.
+ * Path pattern accepted by the router. Routes must use an absolute path
+ * beginning with `/` or the wildcard `*`.
  *
  * @category PathInput
  * @since 4.0.0
@@ -674,6 +694,8 @@ const removeTrailingSlash = (
 /**
  * Adds a path prefix to a route path.
  *
+ * **Details**
+ *
  * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
  * `*` becomes a wildcard route under the prefix.
  *
@@ -684,6 +706,8 @@ export const prefixPath: {
   /**
    * Adds a path prefix to a route path.
    *
+   * **Details**
+   *
    * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
    * `*` becomes a wildcard route under the prefix.
    *
@@ -694,6 +718,8 @@ export const prefixPath: {
   /**
    * Adds a path prefix to a route path.
    *
+   * **Details**
+   *
    * Trailing slashes are removed from the prefix; `/` becomes the prefix itself and
    * `*` becomes a wildcard route under the prefix.
    *
@@ -711,6 +737,8 @@ export const prefixPath: {
 /**
  * Returns a copy of a route with its path prefixed.
  *
+ * **Details**
+ *
  * The prefix is also tracked on the route so that, when the route handles a
  * request, the matched prefix can be removed from the request URL seen by the
  * handler.
@@ -722,6 +750,8 @@ export const prefixRoute: {
   /**
    * Returns a copy of a route with its path prefixed.
    *
+   * **Details**
+   *
    * The prefix is also tracked on the route so that, when the route handles a
    * request, the matched prefix can be removed from the request URL seen by the
    * handler.
@@ -733,6 +763,8 @@ export const prefixRoute: {
   /**
    * Returns a copy of a route with its path prefixed.
    *
+   * **Details**
+   *
    * The prefix is also tracked on the route so that, when the route handles a
    * request, the matched prefix can be removed from the request URL seen by the
    * handler.
@@ -826,6 +858,8 @@ const MiddlewareTypeId = "~effect/http/HttpRouter/Middleware"
 /**
  * Composable descriptor for route-scoped HTTP router middleware.
  *
+ * **Details**
+ *
  * Its `layer` can be provided to route layers, and `combine` composes middleware
  * while tracking provided services, handled errors, and remaining requirements at
  * the type level.
@@ -876,6 +910,8 @@ export interface Middleware<
 /**
  * Create a middleware layer that can be used to modify requests and responses.
  *
+ * **Details**
+ *
  * By default, the middleware only affects the routes that it is provided to.
  *
  * If you want to create a middleware that applies globally to all routes, pass
@@ -1061,6 +1097,8 @@ export declare namespace middleware {
   /**
    * Overloaded constructor type for router middleware.
    *
+   * **Details**
+   *
    * It builds either a route-scoped `Middleware` or, when `global` is `true`, a
    * layer that installs middleware for all routes. The type tracks provided
    * services, handled errors, middleware failures, and remaining requirements.
@@ -1239,13 +1277,12 @@ export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.On
     /**
      * Middleware to apply to the HTTP server.
      *
-     * NOTE: This middleware is applied to the entire HTTP server chain,
-     * including the sending of the response. This means that modifications
-     * to the response **WILL NOT** be reflected in the final response sent to the
-     * client.
+     * **Gotchas**
      *
-     * Use HttpRouter.middleware to create middleware that can modify the
-     * response.
+     * This middleware is applied to the entire HTTP server chain, including the
+     * sending of the response. Changes to the response are not reflected in the
+     * final response sent to the client. Use `HttpRouter.middleware` when
+     * middleware must modify the response.
      */
     readonly middleware?: (
       effect: Effect.Effect<
@@ -1286,6 +1323,8 @@ export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.On
  * Builds a Fetch-compatible request handler from an HTTP router application
  * layer.
  *
+ * **Details**
+ *
  * The result contains a `handler` function that converts Web `Request` values to
  * Web `Response` values and a `dispose` function for releasing the layer
  * resources.
@@ -1313,13 +1352,12 @@ export const toWebHandler = <
     /**
      * Middleware to apply to the HTTP server.
      *
-     * NOTE: This middleware is applied to the entire HTTP server chain,
-     * including the sending of the response. This means that modifications
-     * to the response **WILL NOT** be reflected in the final response sent to the
-     * client.
+     * **Gotchas**
      *
-     * Use HttpRouter.middleware to create middleware that can modify the
-     * response.
+     * This middleware is applied to the entire HTTP server chain, including the
+     * sending of the response. Changes to the response are not reflected in the
+     * final response sent to the client. Use `HttpRouter.middleware` when
+     * middleware must modify the response.
      */
     readonly middleware?: (
       effect: Effect.Effect<