effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/http/index.ts

@@ -5,61 +5,16 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * Utilities for representing, validating, parsing, and serializing HTTP cookies.
- *
- * This module provides an immutable `Cookies` collection keyed by cookie name,
- * constructors for validated `Cookie` values, and helpers for common server and
- * client flows such as reading `Cookie` request headers, emitting `Set-Cookie`
- * response headers, merging cookie sets, and expiring cookies.
- *
- * Cookie parsing is intentionally tolerant of malformed input: unsupported or
- * invalid `Set-Cookie` attributes are ignored, values are percent-decoded on a
- * best-effort basis, and collections keep one cookie per name. Security
- * attributes such as `HttpOnly`, `Secure`, `SameSite`, and `Partitioned` are
- * serialized when present, but browsers enforce their final behavior, so set
- * them explicitly for session, cross-site, and HTTPS-sensitive cookies.
- *
  * @since 4.0.0
  */
 export * as Cookies from "./Cookies.ts"
 
 /**
- * Utilities for representing and generating HTTP entity tags.
- *
- * ETags are validators that identify a particular representation of a
- * resource. Servers commonly attach them to responses so clients and
- * intermediaries can revalidate cached content with conditional requests such
- * as `If-None-Match`, or protect updates with preconditions such as `If-Match`.
- *
- * This module models weak and strong ETags, formats them for the `ETag` header,
- * and provides generator layers that derive tags from file size and
- * modification-time metadata. Metadata-derived tags are convenient for static
- * files, but they are only as precise as the underlying metadata: choose strong
- * tags only when that metadata reliably changes for every byte-level change,
- * and use weak tags when the validator is suitable for cache revalidation but
- * not for operations that require byte-for-byte identity.
- *
  * @since 4.0.0
  */
 export * as Etag from "./Etag.ts"
 
 /**
- * Provides an `HttpClient` implementation backed by the Web Fetch API.
- *
- * Use this module when an application should run HTTP requests through the
- * platform's `fetch` implementation, such as browser code, edge runtimes, or
- * Node.js environments that provide `globalThis.fetch`. The `Fetch` reference
- * allows tests and custom runtimes to supply a different fetch function, while
- * `RequestInit` can provide defaults such as credentials, redirect behavior,
- * cache mode, or other platform-specific fetch options.
- *
- * The client translates Effect HTTP requests into fetch calls and wraps Web
- * `Response` values as `HttpClientResponse`s. Fetch implementations control
- * details such as CORS, cookies, redirect handling, and abort semantics, so
- * behavior can vary by platform. Stream request bodies are sent as Web streams
- * with `duplex: "half"` for runtimes that require it, and `content-length` is
- * omitted so fetch can manage body framing itself.
- *
  * @since 4.0.0
  */
 export * as FetchHttpClient from "./FetchHttpClient.ts"
@@ -70,459 +25,101 @@ export * as FetchHttpClient from "./FetchHttpClient.ts"
 export * as FindMyWay from "./FindMyWay.ts"
 
 /**
- * Utilities for representing and transforming HTTP headers.
- *
- * This module provides an immutable `Headers` collection for request and
- * response metadata, along with constructors and combinators for common header
- * workflows such as reading values, checking for presence, setting or merging
- * header sets, removing names, and redacting sensitive headers before
- * inspection.
- *
- * Header names are normalized to lowercase by the safe constructors and
- * lookups, matching HTTP's case-insensitive header-name semantics. Each stored
- * header name maps to a single string value: array values in record input are
- * joined with `", "`, iterable input keeps the last value for duplicate names,
- * and later values override earlier ones when setting or merging. Be careful
- * with headers that require distinct field lines, such as `set-cookie`, because
- * this representation does not preserve multiple values separately.
- *
  * @since 4.0.0
  */
 export * as Headers from "./Headers.ts"
 
 /**
- * Utilities and data types for describing outgoing HTTP body content.
- *
- * This module provides a small set of `HttpBody` variants used by HTTP client
- * requests and server responses: empty bodies, raw runtime values, in-memory
- * bytes, `FormData`, and byte streams. Constructors cover the common cases of
- * text, JSON, URL-encoded forms, multipart forms, and files while carrying the
- * content type and, when known, the content length used by platform adapters.
- *
- * Streaming bodies are represented as streams of `Uint8Array` chunks and may
- * omit `contentLength` when the size is not known ahead of time. Multipart
- * `FormData` intentionally leaves `contentType` unset so the runtime can add
- * the required boundary; setting that header manually can produce invalid
- * requests.
- *
  * @since 4.0.0
  */
 export * as HttpBody from "./HttpBody.ts"
 
 /**
- * Composable HTTP client service for executing `HttpClientRequest` values and
- * receiving `HttpClientResponse` values inside Effect programs.
- *
- * This module provides the `HttpClient` service tag, method-specific accessors,
- * constructors for low-level runtimes, and middleware-style combinators for
- * common client concerns such as request rewriting, response filtering, retries,
- * redirects, cookies, rate limiting, and tracing. It is intended for code that
- * needs dependency-injected outbound HTTP calls, reusable clients customized for
- * an API, or cross-cutting behavior layered around a concrete platform client.
- *
- * Responses are successful Effects even for non-2xx status codes unless a
- * filter such as `filterStatus` or `filterStatusOk` is applied. Request
- * middleware is ordered by whether it prepends to or appends after the existing
- * preprocessing pipeline, so use `mapRequestInput` for transformations that
- * should run before previously installed request middleware and `mapRequest`
- * for transformations that should run after it. Non-scoped responses are tied to
- * an abort controller for interruption cleanup; use `withScope` when the request
- * lifetime should instead be controlled by a surrounding `Scope`.
- *
  * @since 4.0.0
  */
 export * as HttpClient from "./HttpClient.ts"
 
 /**
- * Error types used by the HTTP client to describe failures that occur while
- * preparing requests, sending them, validating response status codes, and
- * decoding response bodies.
- *
- * The module exposes the `HttpClientError` wrapper together with the specific
- * reason classes it can carry, so applications can either handle all HTTP
- * client failures uniformly or branch on the exact `_tag` for retries, logging,
- * metrics, and user-facing messages. A common gotcha is that only response
- * errors carry an `HttpClientResponse`: transport, encoding, and invalid URL
- * failures happen before a response is available, while status-code, decode, and
- * empty-body failures preserve the response that triggered them.
- *
  * @since 4.0.0
  */
 export * as HttpClientError from "./HttpClientError.ts"
 
 /**
- * Utilities for constructing immutable outgoing HTTP client requests.
- *
- * This module models the request data passed to HTTP clients and adapters:
- * method, URL, query parameters, hash, headers, and body. It provides
- * method-specific constructors, pipeable combinators for adding authentication
- * headers and accepted media types, helpers for JSON, form, stream, and file
- * bodies, and conversions to and from the Web `Request` type.
- *
- * Request construction keeps the base URL, query parameters, and hash as
- * separate fields until conversion. Passing a `URL` extracts its search
- * parameters and fragment into those structured fields, while string URLs are
- * kept as provided. Use the `setUrlParam` helpers when replacing query values
- * and the `appendUrlParam` helpers when multiple values for the same key should
- * be preserved. Setting a body also updates `Content-Type` and
- * `Content-Length` from the body metadata when available; `FormData` leaves
- * those headers to the runtime so multipart boundaries can be generated
- * correctly.
- *
  * @since 4.0.0
  */
 export * as HttpClientRequest from "./HttpClientRequest.ts"
 
 /**
- * Utilities for inspecting, decoding, and filtering HTTP client responses.
- *
- * An `HttpClientResponse` pairs the platform `Response` with the request that
- * produced it, exposing status, headers, cookies, and effectful views of the
- * response body. Use this module after an `HttpClient` call to branch on status
- * with `matchStatus` or `filterStatus`, decode JSON or URL-encoded bodies with
- * schemas, stream bytes, or adapt a Web `Response` with `fromWeb`.
- *
- * Response bodies come from the underlying Web response and should be decoded
- * deliberately: `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 are represented by the HTTP `Headers` module's
- * single-value, lowercase map, while response cookies are parsed separately from
- * `Set-Cookie` headers. Status values are not considered errors by themselves;
- * use the provided filters or matchers when only specific status codes are
- * acceptable.
- *
  * @since 4.0.0
  */
 export * as HttpClientResponse from "./HttpClientResponse.ts"
 
 /**
- * Utilities for running HTTP server effects at the boundary between Effect and
- * platform request handlers.
- *
- * This module is used to turn an effect that produces an `HttpServerResponse`
- * into a concrete handler, such as a Web `Request` handler, while applying
- * middleware, converting failures into HTTP responses, and preserving the
- * current `HttpServerRequest` in the Effect context. It also provides hooks for
- * adjusting a response immediately before it is sent and helpers for managing
- * the request `Scope`, especially when a streaming response must own that scope
- * until the stream completes.
- *
- * Handlers built here expect the per-request context to contain
- * `HttpServerRequest` and, for scoped resources, `Scope.Scope`. Failures are
- * reported and translated through `HttpServerError` / respondable conversions,
- * so unhandled defects generally become server error responses while request
- * aborts and already-sent responses need to be handled with the provided
- * middleware and scope utilities.
- *
  * @since 4.0.0
  */
 export * as HttpEffect from "./HttpEffect.ts"
 
 /**
- * Shared utilities for reading and decoding 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.
- *
  * @since 4.0.0
  */
 export * as HttpIncomingMessage from "./HttpIncomingMessage.ts"
 
 /**
- * Defines the supported HTTP method literals shared by the unstable HTTP client,
- * server, and routing APIs.
- *
- * Use this module when constructing method-specific requests, matching incoming
- * requests, validating unknown method values, or deriving method helper names.
- * Methods are represented as uppercase string literals, so values such as `"get"`
- * are not accepted as `HttpMethod` values.
- *
- * The body classification is intentionally conservative and file-specific:
- * `GET`, `HEAD`, `OPTIONS`, and `TRACE` are modeled as bodyless methods, while
- * `POST`, `PUT`, `DELETE`, and `PATCH` are modeled as methods that can carry a
- * request body. This means `DELETE` is allowed to carry a body even though some
- * servers and intermediaries may ignore it, and `GET` request bodies are not
- * represented by these helpers even though the wire protocol does not strictly
- * forbid them.
- *
  * @since 4.0.0
  */
 export * as HttpMethod from "./HttpMethod.ts"
 
 /**
- * Server-side HTTP middleware for wrapping `HttpServerResponse` effects with
- * cross-cutting 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.
- *
  * @since 4.0.0
  */
 export * as HttpMiddleware from "./HttpMiddleware.ts"
 
 /**
- * Platform-specific support for serving files as HTTP server responses.
- *
- * `HttpPlatform` is the boundary between the portable HTTP response model and
- * the runtime that knows how to stream bytes from the host platform. Server
- * code uses this service when it needs to return local files, static assets,
- * downloads, byte ranges, or Web `File`-like values without constructing the
- * response body by hand.
- *
- * The helpers in this module enrich those responses with file metadata such as
- * `etag`, `last-modified`, and content length where available. Path-based
- * responses require `FileSystem` and can fail with `PlatformError` while
- * inspecting or streaming the file; `File`-like responses use the Web
- * `ReadableStream` and `lastModified` metadata exposed by the value.
- *
- * Provide `layer` when the default streaming implementation is suitable, or
- * use `make` to plug in a runtime-specific response constructor. The default
- * layer supplies weak ETag generation itself, but the surrounding runtime still
- * needs to provide the `FileSystem` service and run the resulting
- * `HttpServerResponse` on an HTTP server adapter that understands Effect
- * streams.
- *
  * @since 4.0.0
  */
 export * as HttpPlatform from "./HttpPlatform.ts"
 
 /**
- * Layer-based server-side HTTP routing for Effect applications.
- *
- * This module provides the `HttpRouter` service and helpers for registering
- * method/path handlers, grouping routes under prefixes, decoding request
- * schemas from route and search parameters, and turning an application layer
- * into an `HttpServer` or Fetch-compatible handler. It is intended for HTTP
- * APIs, webhooks, and other server endpoints that want request-scoped services
- * and typed middleware to be composed through `Layer`.
- *
- * Route paths must be absolute paths beginning with `/`, or the wildcard `*`.
- * Prefixed routes remove the matched prefix from the request URL seen by the
- * handler, `HEAD` requests fall back to matching `GET` routes, and wildcard
- * paths ending in `/*` also match the prefix path itself. Use router middleware
- * when you need to provide request dependencies, handle configured route errors,
- * or modify route responses; server middleware wraps the wider server chain and
- * is not the right hook for changing the final response body or headers.
- *
  * @since 4.0.0
  */
 export * as HttpRouter from "./HttpRouter.ts"
 
 /**
- * Service and helpers for running Effect HTTP applications on a concrete server
- * runtime.
- *
- * This module defines the `HttpServer` service tag used by platform integrations
- * to expose a listening server, plus accessors for serving an
- * `HttpServerResponse` effect, formatting and logging server addresses, and
- * building test clients against a running server. It is intended for low-level
- * server runtimes, router integrations, HTTP API tests, and applications that
- * need to start serving from a provided `Layer`.
- *
- * The server supplies `HttpServerRequest` for each request, so application
- * effects should rely on the server for request-scoped data while still
- * providing their other services through the surrounding environment. `serve`
- * returns a `Layer` whose listener lifetime is managed by the layer scope; use
- * `serveEffect` when composing directly in an effect with an explicit `Scope`.
- * Test clients only support TCP addresses, and rewrite `0.0.0.0` to
- * `127.0.0.1` for local requests.
- *
  * @since 4.0.0
  */
 export * as HttpServer from "./HttpServer.ts"
 
 /**
- * Error types and response conversion helpers used by the HTTP server runtime.
- *
- * This module models the failure cases that can happen around a server request:
- * malformed or unreadable requests, unmatched routes, unexpected handler
- * failures, response construction or delivery failures, and lower-level server
- * implementation failures. These errors keep the relevant request, and for
- * response failures the response that was being produced, so applications can
- * report, inspect, or translate failures without losing HTTP context.
- *
- * Most users encounter these errors when decoding request bodies, implementing
- * fallback routes, adding error reporting, or customizing how handler failures
- * become responses. Request parse errors become `400` responses, missing routes
- * become `404` responses and are ignored by the error reporter, and internal or
- * response errors become `500` responses. A `ResponseError` records the response
- * involved in the failure, but its default conversion intentionally sends an
- * empty `500` instead of reusing a response that may already be invalid or
- * partially failed. Handler causes can also contain respondable failures,
- * response defects, or interrupts; the conversion helpers preserve those
- * distinctions, including `499` for client aborts and `503` for server aborts.
- *
  * @since 4.0.0
  */
 export * as HttpServerError from "./HttpServerError.ts"
 
 /**
- * Utilities for working with the request visible to HTTP server handlers.
- *
- * This module defines `HttpServerRequest`, the request-scoped context service
- * used by server effects, middleware, schema decoders, multipart parsers,
- * WebSocket upgrades, and conversions between Effect HTTP requests, client
- * requests, and Web `Request` values. Handlers commonly use it to inspect the
- * method, URL, headers, cookies, remote address, and body, or to decode those
- * parts with schemas instead of parsing raw values by hand.
- *
- * Body access is effectful because reading, parsing, schema decoding, or
- * multipart persistence can fail. Streaming request bodies may be single-use
- * depending on the underlying platform, while cached accessors such as text,
- * JSON, URL parameters, array buffers, and persisted multipart data reuse the
- * first read. Multipart persistence also requires `Scope`, `FileSystem`, and
- * `Path` services, and search parameter decoding depends on the
- * `ParsedSearchParams` service being provided by the router or adapter.
- *
  * @since 4.0.0
  */
 export * as HttpServerRequest from "./HttpServerRequest.ts"
 
 /**
- * Protocol and conversion helpers for values that can become HTTP server
- * responses.
- *
- * This module lets server-side domain errors, HTTP API errors, and helper
- * modules describe how they should be sent to a client without constructing an
- * `HttpServerResponse` at every call site. Implement `Respondable` on values
- * that should choose their own status, headers, cookies, or body when a route
- * fails or a server helper recovers by sending a response.
- *
- * Conversion is intentionally conservative. Existing `HttpServerResponse`
- * values are returned directly, fallback conversion maps schema errors to `400`
- * and no-such-element errors to `404`, and otherwise uses the caller-provided
- * fallback. Errors raised while running a respondable conversion become defects
- * with `toResponse`, while the fallback helpers catch conversion failures and
- * use the fallback response. Defect conversion only gives special handling to
- * `HttpServerResponse` and `Respondable` values.
- *
  * @since 4.0.0
  */
 export * as HttpServerRespondable from "./HttpServerRespondable.ts"
 
 /**
- * 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
  */
 export * as HttpServerResponse from "./HttpServerResponse.ts"
 
 /**
- * Static file serving for Effect HTTP applications.
- *
- * This module builds request handlers and router layers that serve files from a
- * configured root directory. It is intended for public assets such as compiled
- * front-end bundles, images, fonts, downloads, documentation sites, and single
- * page applications that need an `index.html` fallback.
- *
- * Requests are resolved relative to the configured root after decoding and
- * normalizing the URL path. Malformed paths, null bytes, and `..` traversal
- * outside the root are rejected, but the module still serves anything the
- * configured `FileSystem` can reach below that root. Keep secrets out of the
- * served tree, be careful with symlinks or generated files, and remember that
- * dotfiles are not hidden automatically. File responses include content type,
- * optional cache control, byte-range support, and conditional request handling
- * based on the metadata supplied by `HttpPlatform`.
- *
  * @since 4.0.0
  */
 export * as HttpStaticServer from "./HttpStaticServer.ts"
 
 /**
- * Utilities for HTTP trace-context propagation.
- *
- * This module converts Effect `Tracer.Span` values to outbound tracing headers
- * and decodes inbound propagation headers into `Tracer.ExternalSpan` parents.
- * It is used by traced HTTP clients to continue the current span across an
- * outbound request, and by server middleware to parent request spans from
- * upstream services. The helpers are also useful for adapters or middleware
- * that need to bridge Effect tracing with W3C Trace Context or B3-compatible
- * systems.
- *
- * Outbound propagation writes both W3C `traceparent` and compact B3 `b3`
- * headers. Inbound decoding prefers W3C `traceparent`, then compact B3, then
- * multi-header B3 (`x-b3-*`). Header names in `Headers.Headers` are expected to
- * be lowercase; use the safe header constructors when accepting raw platform
- * headers. Invalid or unsupported header shapes simply decode to `Option.none`,
- * so callers should treat missing trace context as "start a new trace" rather
- * than as an error.
- *
  * @since 4.0.0
  */
 export * as HttpTraceContext from "./HttpTraceContext.ts"
 
 /**
- * Utilities for parsing and working with HTTP `multipart/form-data` request
- * bodies.
- *
- * This module converts multipart byte streams into typed `Part` values, either
- * as decoded text `Field` values or streamed `File` values. It is used by HTTP
- * server request handling for browser form submissions, API endpoints that
- * accept file uploads, and mixed payloads where structured fields accompany one
- * or more uploaded files. Persisted helpers collect fields into records and
- * write files into scoped temporary paths that can be decoded with schemas.
- *
- * Multipart bodies can be large and are often backed by one-shot request
- * streams, so prefer streaming file content unless the file is small enough to
- * collect with `contentEffect`. Persisted file paths are valid only while their
- * scope is open, and client-provided filenames should be treated as metadata
- * rather than trusted filesystem paths. Parser limits for part count, field
- * size, file size, total body size, and field MIME type handling are provided
- * through the module's context references.
- *
  * @since 4.0.0
  */
 export * as Multipart from "./Multipart.ts"
@@ -533,65 +130,16 @@ export * as Multipart from "./Multipart.ts"
 export * as Multipasta from "./Multipasta.ts"
 
 /**
- * Template literal helpers for rendering HTTP-oriented text with Effect values.
- *
- * This module powers response helpers that accept template tags, such as HTML
- * responses with dynamic fragments, deferred service lookups, or streaming
- * sections. Use `make` when the whole rendered value should be assembled before
- * building the response, and `stream` when parts of the template can be emitted
- * incrementally from effects or streams.
- *
- * Interpolation is intentionally simple: primitive values are converted to
- * strings, arrays are concatenated without separators, and `Option.none`,
- * `null`, and `undefined` render as empty text. The module does not escape HTML,
- * encode bytes, set content types, or compute content lengths, so callers should
- * escape or encode untrusted values and choose the appropriate response
- * constructor for the rendered output.
- *
  * @since 4.0.0
  */
 export * as Template from "./Template.ts"
 
 /**
- * Utilities for parsing and immutably updating HTTP URLs.
- *
- * This module works with the platform `URL` type used by HTTP clients and
- * servers, adding safe constructors and pipeable setters for common workflows
- * such as resolving request targets against a base URL, changing credentials,
- * host, path, protocol, query, and hash components, and reading or rewriting
- * query parameters through `UrlParams`.
- *
- * Parsing and serialization follow the platform WHATWG `URL` behavior. Relative
- * inputs need an explicit base, assigned components may be normalized or
- * percent-encoded by `URL`, and query strings should usually be handled through
- * `UrlParams` when preserving repeated keys or applying key/value encoding is
- * important.
- *
  * @since 4.0.0
  */
 export * as Url from "./Url.ts"
 
 /**
- * Utilities for representing, transforming, and serializing URL query
- * parameters.
- *
- * This module provides an immutable `UrlParams` collection backed by ordered
- * string key-value pairs. It is used for HTTP client request queries,
- * URL-encoded form bodies, and server-side decoding workflows where query
- * parameters need to be built from records, iterables, or native
- * `URLSearchParams`, then inspected, appended, replaced, removed, converted to a
- * URL, or decoded with schemas.
- *
- * Duplicate keys are preserved by the core representation and by append-style
- * operations; use `getAll` when all values matter, and note that `set` and
- * `setAll` replace existing values for matching keys. Serialization through
- * `toString` and `makeUrl` delegates to the platform `URLSearchParams` / `URL`
- * implementations, so provide decoded strings rather than pre-encoded query
- * fragments. Record-based and schema-based conversions intentionally collapse
- * repeated keys into string arrays and do not preserve the full global pair
- * ordering; `schemaJsonField` reads the first matching value for the selected
- * field.
- *
  * @since 4.0.0
  */
 export * as UrlParams from "./UrlParams.ts"

package/src/unstable/httpapi/HttpApi.ts

@@ -1,26 +1,50 @@
 /**
- * The `HttpApi` module defines the top-level contract for an Effect HTTP API.
- * An `HttpApi` names an API and collects one or more `HttpApiGroup`s, whose
- * endpoints describe the request inputs, response schemas, middleware, and
- * annotations that later drive server builders, clients, and OpenAPI
- * generation.
+ * The `HttpApi` module defines the top-level declaration for an Effect HTTP
+ * API. An {@link HttpApi} has an identifier, annotations, and a collection of
+ * groups whose endpoints describe request inputs, response schemas, middleware,
+ * and route metadata.
  *
- * Use this module when you want to compose a domain API from endpoint groups,
- * combine APIs from multiple modules, apply a shared path prefix or middleware,
- * attach annotations, or reflect over the final route shape. Implementations are
- * provided separately with `HttpApiBuilder.group`, and the completed API is
- * registered with `HttpApiBuilder.layer`.
+ * An `HttpApi` value is the shared contract consumed by server builders,
+ * generated clients, URL builders, OpenAPI generation, and reflection tools.
+ * Handler implementations are supplied later with `HttpApiBuilder.group`, and
+ * the completed API is registered with `HttpApiBuilder.layer`.
  *
- * A few composition details are worth keeping in mind: group identifiers are
- * used as keys, so adding another group with the same identifier replaces the
- * previous one; `prefix` and `middleware` are applied to the groups and
- * endpoints already present when they are called; and `addHttpApi` merges the
- * added API's annotations into its groups. During reflection, success and error
- * schemas are grouped by the HTTP status recorded on their `HttpApiSchema`
- * annotations, endpoints without an explicit success schema default to
- * `NoContent`, and middleware error schemas are included with endpoint errors.
- * Extra schemas supplied through `AdditionalSchemas` must have an `identifier`
- * annotation so they can be emitted as OpenAPI components.
+ * **Mental model**
+ *
+ * - {@link make} creates an empty API declaration with a stable identifier.
+ * - Groups are added to the API declaration, and each group owns its endpoint
+ *   declarations.
+ * - API-level prefixes, middleware, and annotations are composition operations
+ *   over the groups already present in the declaration.
+ * - {@link reflect} walks the final group and endpoint metadata with merged
+ *   annotations, status-indexed response schemas, and middleware errors.
+ *
+ * **Common tasks**
+ *
+ * - Create an API with {@link make}.
+ * - Add groups with the `add` method, or merge another API with `addHttpApi`.
+ * - Apply a shared path prefix, middleware, or annotation through the methods on
+ *   {@link HttpApi}.
+ * - Inspect the resulting route shape with {@link reflect}.
+ * - Register extra OpenAPI component schemas through {@link AdditionalSchemas}.
+ *
+ * **Gotchas**
+ *
+ * - Group identifiers are used as keys. Adding a group with the same identifier
+ *   replaces the previous group.
+ * - `prefix` and `middleware` affect the groups and endpoints already present
+ *   when those methods are called.
+ * - `addHttpApi` merges the added API's annotations into its groups.
+ * - Reflection includes middleware error schemas with endpoint errors and treats
+ *   endpoints without an explicit success schema as `NoContent`.
+ * - Schemas supplied through {@link AdditionalSchemas} must have an `identifier`
+ *   annotation so OpenAPI generation can emit them as components.
+ *
+ * **See also**
+ *
+ * - {@link make} for constructing API declarations.
+ * - {@link reflect} for inspecting groups and endpoints.
+ * - {@link AdditionalSchemas} for OpenAPI component schemas.
  *
  * @since 4.0.0
  */
@@ -54,7 +78,7 @@ export const isHttpApi = (u: unknown): u is Any => Predicate.hasProperty(u, Type
  *
  * **When to use**
  *
- * Endpoint implementations can be provided with `HttpApiBuilder.group`, and the
+ * Use when endpoint implementations can be provided with `HttpApiBuilder.group`, and the
  * completed API can be registered with `HttpApiBuilder.layer`.
  *
  * @category models
@@ -212,7 +236,7 @@ const makeProto = <Id extends string, Groups extends HttpApiGroup.Any>(
  *
  * **When to use**
  *
- * Add groups with `add` or `addHttpApi`, provide endpoint implementations with
+ * Use when add groups with `add` or `addHttpApi`, provide endpoint implementations with
  * `HttpApiBuilder.group`, and register the API with `HttpApiBuilder.layer`.
  *
  * @category constructors