effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/eventlog/SqlEventLogServerUnencrypted.ts

@@ -7,35 +7,6 @@
  * dialect-specific tables for the server remote id, per-store sequence state,
  * plaintext entries, and session authentication bindings.
  *
- * **Mental model**
- *
- * Each server store is an append-only SQL sequence. A write transaction ensures
- * the store row exists, locks its next sequence, inserts the plaintext entry
- * rows, advances the sequence, and publishes the committed remote entries to
- * in-process subscribers. A change stream first reads the SQL backlog from the
- * requested sequence, applies compaction, and then continues with entries
- * published by this process.
- *
- * **Common tasks**
- *
- * - Persist an unencrypted event-log server across process restarts.
- * - Use database backup, replication, and transactional ordering for remote
- *   event-log entries.
- * - Choose table names with `entryTablePrefix` and `remoteIdTable`, or tune
- *   insert batching with `insertBatchSize`.
- *
- * **Gotchas**
- *
- * Entry payloads are intentionally written as plaintext bytes. Use this storage
- * only when the database, transport, backups, logs, and operators are trusted,
- * or when encryption is handled outside this module. Live notifications are
- * process-local after the initial SQL backlog read, so multi-process
- * deployments need routing, reconnect/backfill behavior, or an external
- * notification channel for writes made elsewhere. Writes also rely on SQL
- * transactions and store-level locking, so deployments should provision
- * compatible isolation behavior and account for dialect-specific binary and
- * text column limits.
- *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"

package/src/unstable/http/Cookies.ts

@@ -1,63 +1,11 @@
 /**
- * Immutable HTTP cookie values and collections for request and response
- * workflows.
+ * Models HTTP cookies and cookie collections for requests and responses.
  *
- * The module models a validated {@link Cookie}, an immutable {@link Cookies}
- * collection keyed by cookie name, and the conversions needed around HTTP
- * headers. Use it to read request `Cookie` headers, build cookies with standard
- * attributes, merge or remove cookies immutably, expire cookies, and emit
- * response `Set-Cookie` headers.
- *
- * **Mental model**
- *
- * - A `Cookie` stores both the decoded `value` and the encoded `valueEncoded`
- *   used in headers
- * - A `Cookies` collection contains at most one cookie per name; later writes,
- *   merges, and iterable inputs replace earlier cookies with the same name
- * - `Cookie` request headers carry name/value pairs, while `Set-Cookie`
- *   response headers carry one cookie plus optional attributes
- * - Safe constructors return `Result` failures for invalid names, values,
- *   domains, paths, or infinite `Max-Age` values
- *
- * **Common tasks**
- *
- * - Create cookies: {@link makeCookie}, {@link makeCookieUnsafe}
- * - Build collections: {@link empty}, {@link fromIterable},
- *   {@link fromSetCookie}, {@link fromReadonlyRecord}
- * - Read values: {@link get}, {@link getValue}, {@link toRecord},
- *   {@link isEmpty}
- * - Update collections: {@link set}, {@link setUnsafe}, {@link setAll},
- *   {@link setCookie}, {@link setAllCookie}, {@link remove}, {@link merge}
- * - Expire cookies: {@link expireCookie}, {@link expireCookieUnsafe}
- * - Encode and decode headers: {@link toCookieHeader},
- *   {@link toSetCookieHeaders}, {@link serializeCookie}, {@link parseHeader}
- *
- * **Gotchas**
- *
- * - Use {@link toCookieHeader} for an outbound request `Cookie` header and
- *   {@link toSetCookieHeaders} for response `Set-Cookie` headers.
- * - Parsing is intentionally tolerant: malformed `Set-Cookie` input can be
- *   ignored, unsupported attributes are skipped, and percent-decoding falls
- *   back to the original text.
- * - Security attributes such as `HttpOnly`, `Secure`, `SameSite`, and
- *   `Partitioned` are serialized when present, but browser policy enforces
- *   their final behavior.
- *
- * **Example** (Serializing a session cookie)
- *
- * ```ts
- * import { Cookies } from "effect/unstable/http"
- *
- * const cookies = Cookies.setUnsafe(Cookies.empty, "session", "abc123", {
- *   httpOnly: true,
- *   path: "/",
- *   sameSite: "lax",
- *   secure: true
- * })
- *
- * console.log(Cookies.toSetCookieHeaders(cookies))
- * // ["session=abc123; Path=/; HttpOnly; Secure; SameSite=Lax"]
- * ```
+ * A `Cookie` stores a name, value, encoded value, and standard cookie
+ * attributes. A `Cookies` value is an immutable collection keyed by cookie
+ * name. This module parses request `Cookie` headers, builds response
+ * `Set-Cookie` headers, and provides helpers for adding, removing, merging, and
+ * expiring cookies.
  *
  * @since 4.0.0
  */

package/src/unstable/http/Etag.ts

@@ -6,28 +6,6 @@
  * cached content with `If-None-Match`, or protect writes with preconditions such
  * as `If-Match`.
  *
- * **Mental model**
- *
- * A strong ETag represents byte-for-byte identity for the selected
- * representation. A weak ETag represents a validator that is useful for cache
- * revalidation but not for operations that require exact byte identity. The
- * `Weak` and `Strong` models store the raw tag value; `toString` adds the
- * required quotes and the `W/` prefix for weak tags.
- *
- * **Common tasks**
- *
- * - Format an `Etag` value for an HTTP header with `toString`.
- * - Provide a `Generator` service with `layer` for strong metadata-derived tags.
- * - Use `layerWeak` when size and modification time are good cache validators
- *   but not a byte-for-byte guarantee.
- *
- * **Gotchas**
- *
- * The built-in generator derives tags only from file size and modification time.
- * Choose the strong layer only when that metadata changes for every byte-level
- * content change. This module formats ETags but does not parse incoming ETag
- * headers or implement conditional request logic.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/http/FetchHttpClient.ts

@@ -6,29 +6,6 @@
  * runtimes, and Node.js environments where `globalThis.fetch` is available, or
  * anywhere a compatible fetch function can be supplied.
  *
- * **Mental model**
- *
- * `layer` installs an `HttpClient` whose runtime boundary is a call to `fetch`.
- * The `Fetch` reference chooses the fetch function and defaults to
- * `globalThis.fetch`. The `RequestInit` service supplies default fetch options
- * such as credentials, redirects, cache behavior, or other platform-specific
- * settings. Request-specific method, headers, body, and abort signal are written
- * by the client for each call.
- *
- * **Common tasks**
- *
- * Provide `layer` when an Effect program should run outbound HTTP through the
- * current platform. Override `Fetch` in tests or custom runtimes to capture
- * requests or route them to a different implementation. Provide `RequestInit`
- * when all requests made by this client should share fetch defaults.
- *
- * **Gotchas**
- *
- * Fetch behavior is platform behavior: CORS, cookies, redirect handling, aborts,
- * and streaming support can differ across runtimes. Stream request bodies are
- * sent as Web streams with `duplex: "half"` for runtimes that require it, and
- * `content-length` is removed so fetch can manage body framing.
- *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"

package/src/unstable/http/FindMyWay.ts

@@ -1,4 +1,10 @@
 /**
+ * Re-exports the `find-my-way-ts` router package used by the unstable HTTP
+ * routing modules.
+ *
+ * This module keeps the router types and helpers available from the Effect HTTP
+ * namespace without wrapping or changing them.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Headers.ts

@@ -1,56 +1,10 @@
 /**
- * Immutable HTTP header collections for the unstable HTTP modules.
+ * Models HTTP headers for the unstable HTTP client and server modules.
  *
- * This module defines the `Headers` data type used by HTTP client and server
- * request / response models. It converts records or iterables into a
- * predictable lowercase map, provides pipeable operations for reading and
- * updating header values, and integrates with inspection redaction so sensitive
- * header names can be masked before logging or serialization.
- *
- * ## Mental model
- *
- * A `Headers` value is a plain immutable record whose keys are normalized
- * header names and whose values are strings. Safe constructors and lookups
- * lowercase names because HTTP header names are case-insensitive, and
- * combinators return new `Headers` values instead of mutating the original
- * collection.
- *
- * ## Common tasks
- *
- * - Build headers from records or entry iterables with {@link fromInput}.
- * - Read values with {@link get} or check presence with {@link has}.
- * - Add, replace, merge, or remove headers with {@link set}, {@link setAll},
- *   {@link merge}, {@link remove}, and {@link removeMany}.
- * - Mask sensitive names before inspection with {@link redact} and
- *   {@link CurrentRedactedNames}.
- *
- * ## Gotchas
- *
- * Each lowercase header name stores one string. Record array values are joined
- * with `", "`, iterable input keeps the last value for duplicate names, and
- * later set / merge operations replace earlier values. This is convenient for
- * most headers but does not preserve repeated field lines such as `Set-Cookie`;
- * use cookie-specific HTTP modules when cookie multiplicity matters.
- *
- * **Example** (Normalize and update headers)
- *
- * ```ts
- * import { Option } from "effect"
- * import { Headers } from "effect/unstable/http"
- *
- * const headers = Headers.fromInput({
- *   "Content-Type": "application/json",
- *   accept: ["application/json", "text/plain"]
- * })
- *
- * const contentType = Headers.get(headers, "content-type")
- * if (Option.isSome(contentType)) {
- *   console.log(contentType.value)
- * }
- *
- * const next = Headers.set(headers, "authorization", "Bearer token")
- * console.log(Headers.has(next, "Authorization")) // true
- * ```
+ * `Headers` values are immutable maps keyed by lowercase header name. This
+ * module converts common header inputs into that shape, provides helpers for
+ * reading and updating header values, and redacts configured sensitive headers
+ * when values are inspected.
  *
  * @since 4.0.0
  */
@@ -108,9 +62,10 @@ export interface Headers extends Redactable.Redactable {
   readonly [key: string]: string
 }
 
-const Proto = Object.create(null)
-
-Object.defineProperties(Proto, {
+// the properties are folded into the initializer (rather than a separate
+// `Object.defineProperties(Proto, ...)` statement) so the whole definition
+// is pure-annotated by the build and tree-shakable.
+const Proto = Object.defineProperties(Object.create(null), {
   [TypeId]: {
     value: TypeId
   },

package/src/unstable/http/HttpBody.ts

@@ -1,57 +1,13 @@
 /**
- * Describes the body attached to outgoing HTTP requests and server responses.
- *
- * `HttpBody` is the transport-facing representation used by the HTTP modules
- * before a platform adapter turns a request or response into a concrete Web,
- * Node, or other runtime value. Each body variant carries the payload plus the
- * metadata an adapter can safely know ahead of time, such as `contentType` and
- * `contentLength`.
- *
- * **Mental model**
- *
- * - {@link empty} represents an absent body.
- * - {@link uint8Array}, {@link text}, {@link jsonUnsafe}, {@link json}, and
- *   {@link urlParams} build in-memory byte bodies with content metadata.
- * - {@link formData} and {@link formDataRecord} keep multipart data as
- *   `FormData` so the runtime can generate the boundary.
- * - {@link stream} represents a stream of `Uint8Array` chunks and may omit the
- *   content length when the final size is not known.
- * - {@link raw} is the escape hatch for platform-specific body values that an
- *   adapter already knows how to send.
- *
- * **Common tasks**
- *
- * - Send text, bytes, JSON, URL-encoded data, multipart forms, or files.
- * - Use {@link json} or {@link jsonSchema} when JSON encoding failures should
- *   be represented as `HttpBodyError` values.
- * - Use {@link file} or {@link fileFromInfo} when file metadata should become
- *   `contentType` / `contentLength` metadata for the adapter.
- * - Use {@link isHttpBody} when accepting unknown values at an integration
- *   boundary.
- *
- * **Gotchas**
- *
- * - {@link jsonUnsafe} calls `JSON.stringify` directly and can throw; prefer
- *   {@link json} in effectful code.
- * - `FormData` bodies intentionally leave `contentType` unset because setting a
- *   multipart header without the generated boundary produces invalid requests.
- * - Stream bodies may not have a `contentLength`; code that requires one must
- *   provide it explicitly when constructing the stream body.
- *
- * **Example** (Creating common body variants)
- *
- * ```ts
- * import { HttpBody, UrlParams } from "effect/unstable/http"
- * import * as assert from "node:assert"
- *
- * const textBody = HttpBody.text("hello")
- * const jsonBody = HttpBody.jsonUnsafe({ name: "Ada" })
- * const formBody = HttpBody.urlParams(UrlParams.fromInput({ q: "effect" }))
- *
- * assert.equal(textBody.contentType, "text/plain")
- * assert.equal(jsonBody.contentType, "application/json")
- * assert.equal(formBody.contentType, "application/x-www-form-urlencoded")
- * ```
+ * Describes HTTP request and response bodies before they reach a platform
+ * adapter.
+ *
+ * `HttpBody` is the shared body representation used by the HTTP modules. Each
+ * variant stores the payload together with metadata that can be known before
+ * sending it, such as `contentType` and `contentLength`. This module includes
+ * body constructors for common payload shapes, support for schema-encoded JSON
+ * bodies, streaming and file-backed bodies, and the error type used when body
+ * construction fails.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpClient.ts

@@ -1,38 +1,13 @@
 /**
- * Dependency-injected HTTP client for executing outgoing requests from Effect
- * programs.
- *
- * This module defines the `HttpClient` service used by platform clients,
- * tests, and API-specific clients. It executes immutable `HttpClientRequest`
- * values, returns `HttpClientResponse` values, and keeps outbound HTTP behind a
- * service boundary so call sites do not depend on a concrete runtime transport.
- *
- * **Mental model**
- *
- * A client is an `execute` function plus method helpers such as `get`, `post`,
- * and `del`. Before a request reaches the runtime, it passes through a
- * preprocessing pipeline. After the runtime returns a response, it passes
- * through a postprocessing pipeline. Combinators such as `mapRequest`,
- * `filterStatusOk`, `retry`, `followRedirects`, `withCookiesRef`, and
- * `withRateLimiter` return a new client with behavior layered around the
- * previous one.
- *
- * **Common tasks**
- *
- * Use method helpers for straightforward calls, construct `HttpClientRequest`
- * values directly when a request is assembled across several steps, and use
- * `make` or `makeWith` when adapting a lower-level transport. Use
- * `filterStatus` or `filterStatusOk` when non-success HTTP statuses should fail
- * the Effect. Use `withScope` when response resources should live for a
- * surrounding scope instead of only the individual request.
- *
- * **Gotchas**
- *
- * Receiving a response is a successful Effect even for non-2xx statuses unless
- * a status filter has been applied. `mapRequestInput` prepends work before
- * existing request middleware, while `mapRequest` appends after it. Without
- * `withScope`, non-scoped responses are attached to an abort controller so
- * interruption can clean up the request.
+ * Provides the service used to run outgoing HTTP requests.
+ *
+ * `HttpClient` executes immutable `HttpClientRequest` values and returns
+ * `HttpClientResponse` values. Keeping HTTP behind this service lets programs,
+ * tests, and generated API clients use the same request model without depending
+ * on one concrete platform transport. This module includes request accessors,
+ * constructors and layers, request and response transformations, status
+ * filtering, retries, rate limiting, cookies, redirect handling, scoped request
+ * abortion, and tracing support.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpClientError.ts

@@ -7,26 +7,6 @@
  * failures uniformly while still matching on the reason `_tag` for retry
  * policy, logging, metrics, and user-facing messages.
  *
- * **Mental model**
- *
- * A client error reason belongs to one of two families. Request errors happen
- * before a response exists: `TransportError`, `EncodeError`, and
- * `InvalidUrlError`. Response errors include the response that triggered them:
- * `StatusCodeError`, `DecodeError`, and `EmptyBodyError`.
- *
- * **Common tasks**
- *
- * - Use `isHttpClientError` at untyped boundaries.
- * - Read `request` for the method and URL associated with any client failure.
- * - Match on `reason._tag` when different failures need different recovery.
- * - Read `response` only for response errors or after checking that it exists.
- *
- * **Gotchas**
- *
- * `response` is `undefined` for transport, encoding, and invalid URL failures.
- * Preserve the original `cause` when constructing reason classes so lower-level
- * platform or decoding details are not lost.
- *
  * @since 4.0.0
  */
 import * as Data from "../../Data.ts"

package/src/unstable/http/HttpClientRequest.ts

@@ -1,42 +1,11 @@
 /**
- * Immutable outgoing HTTP client requests.
+ * Describes immutable outgoing HTTP client requests.
  *
  * `HttpClientRequest` is the request model shared by Effect HTTP clients and
  * platform adapters. A request stores its method, URL, query parameters, hash,
- * headers, and body as structured data, and this module provides constructors,
- * pipeable update helpers, body encoders, and Web `Request` conversions.
- *
- * **Mental model**
- *
- * Request builders start from {@link empty} and return a new request for every
- * change. The base URL, query parameters, and hash stay separate until
- * conversion, so code can update them independently before calling
- * {@link toUrl}, {@link toWebResult}, or {@link toWeb}. Body helpers delegate to
- * `HttpBody` and update `Content-Type` and `Content-Length` when the selected
- * body carries that metadata.
- *
- * **Common tasks**
- *
- * - Start a request with {@link get}, {@link post}, {@link put},
- *   {@link patch}, or another method constructor.
- * - Add authentication or accepted media types with {@link basicAuth},
- *   {@link bearerToken}, {@link accept}, or {@link acceptJson}.
- * - Change URL parts with {@link setUrl}, {@link prependUrl},
- *   {@link appendUrl}, {@link setUrlParam}, {@link appendUrlParam}, and
- *   {@link setHash}.
- * - Attach payloads with {@link bodyJson}, {@link bodyUrlParams},
- *   {@link bodyFormData}, {@link bodyStream}, or {@link bodyFile}.
- * - Bridge Web platform values with {@link fromWeb}, {@link toWebResult}, and
- *   {@link toWeb}.
- *
- * **Gotchas**
- *
- * Passing a `URL` extracts its search parameters and fragment into structured
- * fields, while a string URL is kept as provided. Use the `setUrlParam` helpers
- * to replace query values, and the `appendUrlParam` helpers when repeated keys
- * should be preserved. `FormData` bodies intentionally leave multipart boundary
- * headers to the runtime, so `setBody` removes explicit content headers for
- * them.
+ * headers, and body as structured data. This module includes constructors,
+ * helpers for updating requests, body encoders for common payloads, and
+ * conversions to and from Web `Request` values.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpClientResponse.ts

@@ -1,39 +1,11 @@
 /**
- * HTTP client response values, status helpers, and body decoders.
+ * Represents responses returned by the Effect HTTP client.
  *
- * This module represents responses produced by the Effect HTTP client. An
- * {@link HttpClientResponse} keeps the original request together with the
- * response status, headers, cookies, and effectful body accessors inherited from
- * the shared incoming-message model.
- *
- * **Mental model**
- *
- * A response is a successful client result unless a status filter turns it into
- * a failure. {@link fromWeb} adapts a platform `Response`, body readers decode
- * the underlying Web response, and schema helpers combine status, headers, and
- * decoded body data when validating API-specific responses.
- *
- * **Common tasks**
- *
- * - Branch on exact or status-class handlers with {@link matchStatus}.
- * - Fail non-accepted statuses with {@link filterStatus} or
- *   {@link filterStatusOk}.
- * - Decode JSON response envelopes with {@link schemaJson}.
- * - Decode status and headers without reading a body with {@link schemaNoBody}.
- * - Stream response bytes from an effect with {@link stream}.
- *
- * **Gotchas**
- *
- * HTTP status codes are data, not errors, until a filter is applied. `json`
- * parses an empty text body as `null`. Body readers fail with `HttpClientError`
- * when decoding fails, and the raw stream fails when no body is present.
- * Headers use the HTTP `Headers` module's lowercase, single-value map, while
- * response cookies are parsed separately from `Set-Cookie` headers.
- *
- * **See also**
- *
- * {@link HttpClientResponse}, {@link fromWeb}, {@link matchStatus},
- * {@link schemaJson}, {@link filterStatus}.
+ * An `HttpClientResponse` keeps the original request together with the response
+ * status, headers, cookies, and body accessors from the shared incoming-message
+ * model. This module includes constructors, schema-based decoders, helpers for
+ * streaming response bodies, and utilities for matching or filtering by HTTP
+ * status.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpEffect.ts

@@ -1,38 +1,10 @@
 /**
- * Bridges Effect HTTP server programs with platform request handlers.
+ * Runs Effect HTTP server handlers at platform boundaries.
  *
- * This module runs effects that produce `HttpServerResponse` values at the edge
- * of a server runtime. It can turn an Effect handler into a Web `Request`
- * handler, build that handler from a `Layer`, adapt an existing Web handler back
- * into an Effect server effect, apply HTTP middleware, translate failures into
- * responses, and run pre-response hooks immediately before a response is sent.
- *
- * **Mental model**
- *
- * Each incoming platform request becomes an `HttpServerRequest` in the Effect
- * context plus a request `Scope`. The server effect produces a response, or
- * fails with a cause that is converted into an HTTP response. Web handler
- * adapters fork the Effect program, resolve the platform `Response` promise when
- * the response is handled, and interrupt the fiber when the request aborts.
- * Streaming responses transfer scope ownership to the body stream so resources
- * remain open until the stream exits.
- *
- * **Common tasks**
- *
- * Use `toWebHandler` for a handler with no extra services, `toWebHandlerWith`
- * when each request may provide additional context, `toWebHandlerLayer` or
- * `toWebHandlerLayerWith` when services come from a layer that must later be
- * disposed, and `fromWebHandler` when embedding a Web-standard handler inside an
- * Effect HTTP server. Use pre-response handlers to adjust headers, cookies, or
- * status before the response is converted to the platform response type.
- *
- * **Gotchas**
- *
- * Layer-backed handlers return a `dispose` function for the layer scope; call it
- * when the hosting runtime shuts down. Pre-response handlers run before bytes
- * are sent, not after a streaming body has started. Web adapters handle
- * streaming scope transfer automatically, but lower-level integrations that call
- * `toHandled` directly must preserve request scope ownership themselves.
+ * This module turns effects that produce `HttpServerResponse` values into Web
+ * `Request` handlers and other server adapters. It also applies middleware,
+ * converts failures into responses, runs hooks before a response is sent, and
+ * manages request scopes for streamed responses.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpIncomingMessage.ts

@@ -1,27 +1,11 @@
 /**
- * Shared utilities for reading and decoding incoming HTTP messages.
+ * Common model for incoming HTTP messages.
  *
- * `HttpIncomingMessage` is the common body-and-header surface used by HTTP
- * server requests and client responses. It keeps transport-specific metadata in
- * the surrounding request and response modules while this module focuses on
- * headers, optional remote address information, byte streams, buffered body
- * views, and schema decoders for JSON bodies, URL-encoded bodies, and headers.
- *
- * Use these helpers in middleware, route handlers, client response processing,
- * and adapters when code should work with any incoming message instead of a
- * concrete request or response type. Body access is effectful because reading,
- * parsing, and decoding can fail; use `stream` when bytes should stay
- * streaming, and use `text`, `json`, `urlParamsBody`, or `arrayBuffer` when a
- * buffered view is appropriate. Some runtimes expose bodies as one-shot Web
- * streams, so prefer one body representation per message and let each
- * implementation's cached accessors handle repeated reads where available.
- *
- * Headers use the HTTP `Headers` module's lowercase, single-value map, so
- * repeated values may already have been combined or normalized by the adapter.
- * Decode headers with `schemaHeaders` when their shape matters. For form
- * bodies, `urlParamsBody` handles URL-encoded payloads; multipart support lives
- * on `HttpServerRequest`, with `MaxBodySize` providing the shared limit
- * reference used by multipart parsing.
+ * `HttpIncomingMessage` is used by server requests and client responses to
+ * expose headers, an optional remote address, and body accessors. This module
+ * provides decoders for JSON bodies, URL-encoded bodies, and headers, plus the
+ * shared body-size setting and inspection helper used by request and response
+ * implementations.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpMethod.ts

@@ -1,34 +1,10 @@
 /**
- * HTTP method literals and helpers shared by the unstable HTTP client, server,
- * and routing APIs.
+ * Defines supported HTTP method names for the unstable HTTP modules.
  *
- * This module keeps the supported method vocabulary in one place: the
- * {@link HttpMethod} union, {@link all} set, {@link allShort} mapping,
- * {@link hasBody} body classification helper, and {@link isHttpMethod} runtime
- * refinement. Values are uppercase string literals such as `"GET"` and
- * `"POST"`, matching the method tokens used by the HTTP APIs in this package.
- *
- * **Mental model**
- *
- * {@link HttpMethod} is the complete set this module recognizes.
- * {@link HttpMethod.NoBody} is the subset treated as bodyless (`GET`, `HEAD`,
- * `OPTIONS`, and `TRACE`), and {@link HttpMethod.WithBody} is the remaining
- * subset accepted by request builders that can carry a body.
- *
- * **Common tasks**
- *
- * Use {@link isHttpMethod} before accepting an unknown value as an HTTP method,
- * {@link hasBody} to narrow a method before attaching a body, {@link all} for
- * membership checks or iteration, and {@link allShort} when deriving the short
- * constructor names used by request helpers.
- *
- * **Gotchas**
- *
- * Lowercase method names are not valid {@link HttpMethod} values. The body
- * split is a typed helper convention, not a full statement of every
- * wire-protocol edge case: `DELETE` is treated as able to carry a body, while
- * `GET` helpers are treated as bodyless even though some systems may send a
- * body on the wire.
+ * Values are uppercase string literals such as `"GET"` and `"POST"`, matching
+ * the method tokens used by HTTP requests and routes. This module also includes
+ * helpers for checking whether a method can carry a request body and whether an
+ * unknown value is one of the supported methods.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpMiddleware.ts

@@ -1,25 +1,12 @@
 /**
- * Server-side HTTP middleware for wrapping `HttpServerResponse` effects with
- * cross-cutting request and response behavior.
+ * Wraps HTTP server apps with request and response behavior.
  *
  * A middleware is a function from one HTTP server app effect to another. The app
- * is evaluated with the current `HttpServerRequest` service in its context, so
- * middleware in this module can inspect or rewrite the request, provide
- * request-scoped services, attach pre-response hooks, or observe the app exit
- * while preserving normal Effect error and interruption semantics.
- *
- * Use this module for common server concerns such as access logging, trace span
- * creation, trusting forwarded proxy headers, parsing search parameters, and
- * adding CORS handling. Middleware can be applied directly when serving an
- * `HttpServer` / `HttpEffect` app or registered through `HttpRouter.middleware`
- * for route-scoped or global behavior.
- *
- * Middleware composition is order-sensitive, and each middleware may change the
- * wrapped effect's requirements or error channel. These functions expect a
- * per-request `HttpServerRequest` to be present; context-providing middleware
- * should wrap handlers before they access the provided service, and
- * error-handling middleware should be installed where its transformed error type
- * matches the surrounding app or router registration.
+ * runs with the current `HttpServerRequest` in its context, so middleware can
+ * inspect or rewrite the request, provide request-scoped services, attach hooks
+ * before the response is sent, or observe the app exit. This module includes
+ * middleware for response logging, server tracing, forwarded proxy headers,
+ * parsed search parameters, and CORS response headers.
  *
  * @since 4.0.0
  */