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

package/src/unstable/http/HttpServer.ts

@@ -37,6 +37,8 @@ import type { HttpServerResponse } from "./HttpServerResponse.ts"
 /**
  * Service tag for an HTTP server runtime.
  *
+ * **Details**
+ *
  * The service can serve an HTTP response effect and exposes the address where the
  * server is listening.
  *
@@ -66,6 +68,8 @@ export class HttpServer extends Context.Service<HttpServer, {
 /**
  * Address where an HTTP server is listening.
  *
+ * **Details**
+ *
  * The address is either a TCP host and port or a Unix domain socket path.
  *
  * @category address
@@ -117,6 +121,8 @@ export const make = (
  * Creates a layer that starts serving an HTTP response effect with the current
  * `HttpServer`.
  *
+ * **Details**
+ *
  * The request service is supplied by the server for each request; the returned
  * layer still requires the server, a scope, and any non-request dependencies of
  * the response effect or middleware.
@@ -129,6 +135,8 @@ export const serve: {
    * Creates a layer that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the returned
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
@@ -143,6 +151,8 @@ export const serve: {
    * Creates a layer that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the returned
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
@@ -161,6 +171,8 @@ export const serve: {
    * Creates a layer that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the returned
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
@@ -173,6 +185,8 @@ export const serve: {
    * Creates a layer that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the returned
    * layer still requires the server, a scope, and any non-request dependencies of
    * the response effect or middleware.
@@ -204,6 +218,8 @@ export const serve: {
  * Effect that starts serving an HTTP response effect with the current
  * `HttpServer`.
  *
+ * **Details**
+ *
  * The request service is supplied by the server for each request; the effect
  * requires a scope and any non-request dependencies of the response effect or
  * middleware.
@@ -216,6 +232,8 @@ export const serveEffect: {
    * Effect that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the effect
    * requires a scope and any non-request dependencies of the response effect or
    * middleware.
@@ -230,6 +248,8 @@ export const serveEffect: {
    * Effect that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the effect
    * requires a scope and any non-request dependencies of the response effect or
    * middleware.
@@ -248,6 +268,8 @@ export const serveEffect: {
    * Effect that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the effect
    * requires a scope and any non-request dependencies of the response effect or
    * middleware.
@@ -260,6 +282,8 @@ export const serveEffect: {
    * Effect that starts serving an HTTP response effect with the current
    * `HttpServer`.
    *
+   * **Details**
+   *
    * The request service is supplied by the server for each request; the effect
    * requires a scope and any non-request dependencies of the response effect or
    * middleware.
@@ -287,6 +311,8 @@ export const serveEffect: {
 /**
  * Formats a server address as a display string.
  *
+ * **Details**
+ *
  * TCP addresses are formatted as `http://host:port`; Unix socket addresses are
  * formatted as `unix://path`.
  *
@@ -343,8 +369,14 @@ export const withLogAddress = <A, E, R>(
 /**
  * Builds an `HttpClient` that sends requests to the current test HTTP server.
  *
+ * **Details**
+ *
  * For TCP servers, requests are prefixed with the server URL and `0.0.0.0` is
- * rewritten to `127.0.0.1`. Unix socket addresses are not supported.
+ * rewritten to `127.0.0.1`.
+ *
+ * **Gotchas**
+ *
+ * Unix socket addresses are not supported.
  *
  * @category Testing
  * @since 4.0.0
@@ -381,6 +413,8 @@ export const layerTestClient: Layer.Layer<
  * Testing layer that provides the platform services commonly needed by HTTP
  * server tests.
  *
+ * **Details**
+ *
  * It includes `HttpPlatform`, `Path`, a weak ETag generator, and a no-op
  * `FileSystem`.
  *

package/src/unstable/http/HttpServerError.ts

@@ -39,6 +39,8 @@ const TypeId = "~effect/http/HttpServerError"
 /**
  * Tagged error for failures that occur while handling an HTTP server request.
  *
+ * **Details**
+ *
  * It wraps a `HttpServerErrorReason`, exposes the associated request and optional
  * response, and can be converted to an HTTP response through the `Respondable`
  * protocol.
@@ -90,6 +92,8 @@ export class HttpServerError extends Data.TaggedError("HttpServerError")<{
 /**
  * Error describing a failure to parse or read an incoming request.
  *
+ * **Details**
+ *
  * When converted to a response it produces an empty `400` response.
  *
  * @category error
@@ -121,6 +125,8 @@ export class RequestParseError extends Data.TaggedError("RequestParseError")<{
 /**
  * Error indicating that no route matched the incoming request.
  *
+ * **Details**
+ *
  * When converted to a response it produces an empty `404` response, and it is
  * ignored by the error reporter.
  *
@@ -150,6 +156,8 @@ export class RouteNotFound extends Data.TaggedError("RouteNotFound")<{
 /**
  * Error describing an unexpected server-side failure while handling a request.
  *
+ * **Details**
+ *
  * When converted to a response it produces an empty `500` response.
  *
  * @category error
@@ -189,6 +197,8 @@ export const isHttpServerError = (u: unknown): u is HttpServerError => hasProper
 /**
  * Error describing a failure related to an HTTP response.
  *
+ * **Details**
+ *
  * It carries the request and response involved in the failure. When converted to
  * a response it produces an empty `500` response.
  *
@@ -224,9 +234,7 @@ export class ResponseError extends Data.TaggedError("ResponseError")<{
 export type RequestError = RequestParseError | RouteNotFound | InternalError
 
 /**
- * Reason carried by an `HttpServerError`.
- *
- * It is either a request-level error or a response-level error.
+ * Reason carried by an `HttpServerError`, either a request-level error or a response-level error.
  *
  * @category error
  * @since 4.0.0
@@ -247,6 +255,8 @@ export class ServeError extends Data.TaggedError("ServeError")<{
  * Context annotation used to mark an interrupt as caused by the client aborting
  * the request.
  *
+ * **Details**
+ *
  * `causeResponse` uses this annotation to map a pure client abort to a `499`
  * response instead of a server abort response.
  *
@@ -272,6 +282,8 @@ const formatRequestMessage = (reason: string, description: string | undefined, i
  * Converts a failed handler cause into the HTTP response that should be sent and
  * the cause that should be reported.
  *
+ * **Details**
+ *
  * Respondable failures and defects can choose their own response, defects that
  * are already `HttpServerResponse` values are used directly, and pure interrupts
  * produce either `499` for client aborts or `503` for server aborts.
@@ -327,6 +339,8 @@ export const causeResponse = <E>(
 /**
  * Synchronously derives an HTTP response from a failed handler cause.
  *
+ * **Details**
+ *
  * If the cause contains a defect that is already an `HttpServerResponse`, that
  * response is used and removed from the remaining cause. Otherwise the response
  * defaults to `500`.

package/src/unstable/http/HttpServerRequest.ts

@@ -45,6 +45,8 @@ import * as UrlParams from "./UrlParams.ts"
 
 export {
   /**
+   * Re-exports the `MaxBodySize` fiber reference for configuring request body limits.
+   *
    * @category fiber refs
    * @since 4.0.0
    */
@@ -62,6 +64,8 @@ export const TypeId = "~effect/http/HttpServerRequest"
 /**
  * Server-side representation of an incoming HTTP request.
  *
+ * **Details**
+ *
  * It extends `HttpIncomingMessage` with request metadata, parsed cookies,
  * multipart accessors, WebSocket upgrade support, and a `modify` method for
  * creating adjusted request views.
@@ -108,6 +112,8 @@ export const HttpServerRequest: Context.Service<HttpServerRequest, HttpServerReq
 /**
  * Request-scoped service containing parsed search parameters.
  *
+ * **Details**
+ *
  * Each key maps to a string value, or to an array when the parameter appears more
  * than once.
  *
@@ -122,6 +128,8 @@ export class ParsedSearchParams extends Context.Service<
 /**
  * Converts a `URL` object's search parameters into a record.
  *
+ * **Details**
+ *
  * Repeated parameters are represented as arrays in insertion order.
  *
  * @category search params
@@ -147,6 +155,8 @@ export const searchParamsFromURL = (url: URL): ReadonlyRecord<string, string | A
 /**
  * Creates a channel backed by the current request's upgraded socket.
  *
+ * **Details**
+ *
  * The channel reads incoming socket messages and writes byte chunks to the
  * socket, failing if the request cannot be upgraded or the socket fails.
  *
@@ -217,6 +227,8 @@ export const schemaSearchParams = <
 /**
  * Reads the current request body as JSON and decodes it with the supplied schema.
  *
+ * **Details**
+ *
  * The effect can fail if the body cannot be read or parsed, or if schema decoding
  * fails.
  *
@@ -238,6 +250,8 @@ const isMultipart = (request: HttpServerRequest) =>
 /**
  * Decodes the current request body as form data.
  *
+ * **Details**
+ *
  * Multipart requests are persisted and decoded as multipart data; other form
  * requests are decoded from URL-encoded body parameters.
  *
@@ -286,6 +300,8 @@ export const schemaBodyUrlParams = <
  * Persists the current multipart request body and decodes it with the supplied
  * schema.
  *
+ * **Details**
+ *
  * The effect requires the services needed to persist multipart files, including a
  * scope, file system, and path service.
  *
@@ -310,6 +326,8 @@ export const schemaBodyMultipart = <A, I extends Partial<Multipart.Persisted>, R
 /**
  * Creates a decoder for a JSON value stored in a form field.
  *
+ * **Details**
+ *
  * For multipart requests, the named multipart field is decoded as JSON. For
  * URL-encoded requests, the named parameter is decoded as JSON and then decoded
  * with the supplied schema.
@@ -355,6 +373,8 @@ export const schemaBodyFormJson = <A, I, RD, RE>(
 /**
  * Creates an `HttpServerRequest` view of an `HttpClientRequest`.
  *
+ * **Details**
+ *
  * If the client request can be converted to an absolute URL, that URL is used as
  * the original URL.
  *
@@ -372,6 +392,8 @@ export const fromClientRequest = (request: HttpClientRequest.HttpClientRequest):
 /**
  * Wraps a Web `Request` as an `HttpServerRequest`.
  *
+ * **Details**
+ *
  * The request's current URL is stored without the scheme and host, while the
  * original Web URL remains available as `originalUrl`.
  *
@@ -384,6 +406,8 @@ export const fromWeb = (request: globalThis.Request): HttpServerRequest =>
 /**
  * Converts an `HttpServerRequest` into an `HttpClientRequest`.
  *
+ * **Details**
+ *
  * The converted request preserves the method, headers, body stream, and a URL
  * derived from the request when possible.
  *
@@ -967,6 +991,8 @@ const textDecoder = new TextDecoder()
 /**
  * Attempts to construct an absolute `URL` for a server request.
  *
+ * **Details**
+ *
  * The host comes from the `host` header, defaulting to `localhost`, and the
  * protocol is `https` only when `x-forwarded-proto` is `https`; invalid URLs
  * return `Option.none`.
@@ -987,6 +1013,8 @@ export const toURL = (self: HttpServerRequest): Option.Option<URL> => {
 /**
  * Converts an `HttpServerRequest` to a Web `Request` as a `Result`.
  *
+ * **Details**
+ *
  * If the source is already a Web `Request`, it is returned unchanged. Otherwise
  * an absolute URL is derived from the request; invalid URLs fail with a
  * `RequestParseError`.
@@ -1027,6 +1055,8 @@ export const toWebResult = (self: HttpServerRequest, options?: {
 /**
  * Converts an `HttpServerRequest` to a Web `Request` in `Effect`.
  *
+ * **Details**
+ *
  * The current context is used when streaming the request body into the Web
  * request.
  *

package/src/unstable/http/HttpServerRespondable.ts

@@ -37,6 +37,8 @@ export const symbol = "~effect/http/HttpServerRespondable"
 /**
  * Protocol for values that can be converted into an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * Implement the protocol method to describe the response that should be sent for
  * the value.
  *
@@ -61,6 +63,8 @@ const notFound = Response.empty({ status: 404 })
 /**
  * Converts a `Respondable` value into an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * If the value is already an HTTP server response it is returned directly; errors
  * from the response conversion are converted to defects.
  *
@@ -78,6 +82,8 @@ export const toResponse = (self: Respondable): Effect.Effect<HttpServerResponse>
  * Attempts to convert an unknown value into an `HttpServerResponse`, falling back
  * to the supplied response when no conversion is available.
  *
+ * **Details**
+ *
  * `HttpServerResponse` and `Respondable` values are used directly, schema errors
  * become `400` responses, and no-such-element errors become `404` responses.
  *
@@ -102,6 +108,8 @@ export const toResponseOrElse = (u: unknown, orElse: HttpServerResponse): Effect
  * Attempts to convert an unknown defect into an `HttpServerResponse`, falling
  * back to the supplied response when no conversion is available.
  *
+ * **Details**
+ *
  * Only `HttpServerResponse` and `Respondable` values receive special handling.
  *
  * @category accessors