effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/unstable/http/HttpPlatform.ts

@@ -7,19 +7,6 @@
  * 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
  */
 import * as Context from "../../Context.ts"

package/src/unstable/http/HttpRouter.ts

@@ -1,43 +1,11 @@
 /**
- * Layer-based server-side routing for Effect HTTP applications.
- *
- * `HttpRouter` collects routes and router middleware while an application layer
- * is being built, then exposes the registered route table as an
- * `HttpServerResponse` effect for each incoming `HttpServerRequest`. Use it for
- * APIs, webhooks, and Fetch handlers that want request-scoped services, schema
- * decoding, and typed middleware to participate in the same `Layer` graph as
- * the rest of the application.
- *
- * **Mental model**
- *
- * Route layers do not handle requests immediately. They register `Route` values
- * into the current `HttpRouter`; `serve`, `toHttpEffect`, and `toWebHandler`
- * build the layer, read the completed router, and run the matching handler for
- * each request. During a request, the router provides `HttpServerRequest`,
- * `Scope`, parsed search parameters, and `RouteContext`, so handlers can decode
- * path, search, and body data or access services supplied by router middleware.
- *
- * **Common tasks**
- *
- * - Register individual routes with `add` or batches with `addAll`.
- * - Group routes under a prefix with `addAll(..., { prefix })` or
- *   `router.prefixed`.
- * - Decode route, search, and JSON body data with `schemaPathParams`,
- *   `schemaParams`, `schemaNoBody`, and `schemaJson`.
- * - Apply route-scoped middleware with `middleware(...).layer`, or install
- *   global router middleware for all routes.
- * - Serve the layer with `serve` or create a Fetch-compatible handler with
- *   `toWebHandler`.
- *
- * **Gotchas**
- *
- * Paths must be absolute `/` paths or the wildcard `*`. `HEAD` falls back to
- * `GET`, and wildcard paths ending in `/*` also match the prefix path itself.
- * For prefixed routes the matched prefix is removed from
- * `HttpServerRequest.url` before the handler sees it. Middleware passed to
- * `serve` wraps the wider server chain; use router middleware when you need to
- * provide request dependencies, handle configured route errors, or change the
- * response that will be sent.
+ * Builds server-side routers for Effect HTTP applications.
+ *
+ * `HttpRouter` collects routes and middleware while an application layer is
+ * being built. Once the router is complete, it handles each
+ * `HttpServerRequest` by finding a matching route and producing an
+ * `HttpServerResponse`. The module also includes helpers for route definitions,
+ * prefixes, parameters, request decoding, CORS, and running the router.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServer.ts

@@ -1,34 +1,11 @@
 /**
- * Runtime boundary for serving Effect HTTP responses on a concrete HTTP server.
+ * Service for serving Effect HTTP responses on a concrete HTTP server.
  *
- * `HttpServer` is the service implemented by platform adapters and consumed by
- * routers, API layers, tests, and applications that start serving from a
- * `Layer`. It exposes the listening address and a `serve` operation that runs
- * an `HttpServerResponse` effect for each incoming request.
- *
- * **Mental model**
- *
- * The server owns the listener and supplies `HttpServerRequest` for every
- * request. The application effect only describes how to produce a response, so
- * request-scoped data comes from the server while the rest of the environment is
- * still provided by the surrounding layer graph. `serve` ties listener lifetime
- * to a layer scope, and `serveEffect` performs the same work inside an explicit
- * `Scope`.
- *
- * **Common tasks**
- *
- * - Build a server service from a platform adapter with `make`.
- * - Serve an HTTP app with `serve` or `serveEffect`.
- * - Format or log the listening address with `formatAddress`,
- *   `addressFormattedWith`, `logAddress`, or `withLogAddress`.
- * - Create a test client that targets the running server with `makeTestClient`
- *   or `layerTestClient`.
- *
- * **Gotchas**
- *
- * Middleware is applied at the server boundary, after the server has supplied
- * the request service. Test clients only support TCP addresses, and rewrite
- * `0.0.0.0` to `127.0.0.1` for local requests.
+ * Platform adapters provide `HttpServer`, and routers or applications consume
+ * it to run an `HttpServerResponse` effect for each incoming request. The
+ * service exposes the listening address, while this module also includes helpers
+ * for address formatting, server logging, and clients that target the current
+ * server in tests.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerError.ts

@@ -1,36 +1,12 @@
 /**
- * Error model used by the unstable HTTP server runtime.
+ * Describes failures raised while handling HTTP server requests.
  *
- * This module defines the tagged failures that can occur while a server accepts
- * a request, matches a route, runs a handler, or builds and sends a response.
+ * `HttpServerError` covers failures that happen while accepting a request,
+ * matching a route, running a handler, or building and sending a response.
  * Request-scoped failures keep the request that caused them, and response
- * failures keep the response that was being produced, so applications can log,
- * report, or translate failures without reconstructing HTTP context.
- *
- * **Mental model**
- *
- * {@link HttpServerError} wraps a concrete {@link HttpServerErrorReason}.
- * {@link RequestParseError}, {@link RouteNotFound}, and {@link InternalError}
- * describe failures before or during request handling, while
- * {@link ResponseError} describes a failure tied to a response that was already
- * being built or sent. {@link ServeError} represents lower-level server
- * implementation failures outside an individual handler response.
- *
- * **Common tasks**
- *
- * Use {@link isHttpServerError} to refine unknown failures, inspect `request`
- * and `response` when reporting failures, and use {@link causeResponse} or
- * {@link exitResponse} when a handler cause or exit must be translated into the
- * HTTP response sent to the client.
- *
- * **Gotchas**
- *
- * The default response mapping is intentionally small: request parse errors
- * become `400`, route misses become ignored `404` failures, internal and
- * response errors become `500`, client aborts marked with {@link ClientAbort}
- * become `499`, and server-side interrupts become `503`. A
- * {@link ResponseError} does not reuse the failed response when converted; it
- * produces an empty `500` because that response may be invalid or partly sent.
+ * failures keep the response being produced. This module also includes helpers
+ * for turning failed causes or exits into HTTP responses and an annotation for
+ * interrupts caused by client aborts.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerRequest.ts

@@ -1,37 +1,12 @@
 /**
- * Server-side access to the current incoming HTTP request.
+ * Provides server-side access to the current incoming HTTP request.
  *
- * This module defines the `HttpServerRequest` context service used by HTTP
- * handlers, middleware, schema decoders, multipart parsers, WebSocket upgrades,
- * and adapters. A request value carries the method, URL, original URL, headers,
- * cookies, remote address, body stream, and platform source object, plus helpers
- * for converting to and from Effect client requests and Web `Request` values.
- *
- * **Mental model**
- *
- * Server handlers read the current request from context. Metadata such as the
- * method, URL, headers, and cookies is available directly, while body access is
- * effectful because reading, parsing, schema decoding, or multipart persistence
- * can fail. Schema helpers decode cookies, headers, search parameters, JSON
- * bodies, URL-encoded bodies, multipart bodies, and form JSON without each
- * handler needing to parse raw values by hand.
- *
- * **Common tasks**
- *
- * - Inspect request metadata or derive a modified request view.
- * - Decode cookies, headers, search parameters, or body content with schemas.
- * - Upgrade a request to a WebSocket channel.
- * - Convert between server requests, client requests, and Web `Request` values.
- *
- * **Gotchas**
- *
- * Streaming request bodies may be single-use depending on the underlying
- * platform. Cached accessors such as text, JSON, URL parameters, array buffers,
- * and persisted multipart data reuse the first read. Multipart persistence
- * requires `Scope`, `FileSystem`, and `Path` services. Search parameter decoding
- * depends on the `ParsedSearchParams` service being provided by the router or
- * adapter, and body size limits are controlled through the re-exported
- * `MaxBodySize` fiber reference.
+ * `HttpServerRequest` is the context service used by handlers, middleware,
+ * schema decoders, multipart parsers, WebSocket upgrades, and adapters. A
+ * request stores its method, URL, original URL, headers, cookies, remote
+ * address, body stream, and platform source object. This module also includes
+ * request conversions and schema decoders for cookies, headers, search
+ * parameters, JSON, forms, URL-encoded bodies, and multipart bodies.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerRespondable.ts

@@ -1,34 +1,10 @@
 /**
- * Protocol for values that can render themselves as HTTP server responses.
+ * Converts supported values into HTTP server responses.
  *
- * This module lets server-side domain errors, HTTP API errors, and helper
- * values describe the response they should send to a client. Implement
- * `Respondable` when a value should choose its own status, headers, cookies, or
- * body during route error handling without forcing every call site to construct
- * an `HttpServerResponse` directly.
- *
- * **Mental model**
- *
- * A respondable value owns the last step from domain-level information to an
- * `HttpServerResponse`. Server error handling can ask the value for a response,
- * while unknown failures still go through a caller-provided fallback response.
- * Existing `HttpServerResponse` values are already respondable for conversion
- * purposes and are returned directly.
- *
- * **Common tasks**
- *
- * Use `toResponse` when the value is known to implement the protocol and
- * conversion failures should become defects. Use `toResponseOrElse` when
- * handling unknown failures from route effects and a fallback response should be
- * used when no conversion is available. Use `toResponseOrElseDefect` for defect
- * recovery, where only explicit response-like values receive special handling.
- *
- * **Gotchas**
- *
- * Fallback conversion is intentionally conservative. Schema errors become `400`
- * responses, no-such-element errors become `404` responses, and other values use
- * the supplied fallback. The fallback helpers also catch failures raised while
- * running a respondable conversion; `toResponse` does not.
+ * Server-side errors and helper values can implement `Respondable` when they
+ * know which status, headers, cookies, or body should be sent to the client.
+ * This module detects those values and converts them to `HttpServerResponse`
+ * values, with fallback handling for schema errors and missing values.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpServerResponse.ts

@@ -1,45 +1,12 @@
 /**
- * The `HttpServerResponse` module provides immutable response values for Effect
- * HTTP servers. Handlers return an {@link HttpServerResponse}, then the runtime
- * converts it to a platform response such as a Web `Response`.
- *
- * **Mental model**
- *
- * - A response is a status, optional status text, headers, cookies, and an HTTP
- *   body.
- * - Constructors set practical defaults: {@link empty} uses `204`,
- *   {@link redirect} uses `302`, and body constructors use `200`.
- * - Body metadata is reflected into headers when a response is created or when
- *   the body is replaced.
- * - Cookies are stored separately from the normal header map and become
- *   `Set-Cookie` headers during conversion.
- * - Constructors that encode data can return effects when encoding may fail.
- *
- * **Common tasks**
- *
- * - Create empty, redirect, text, HTML, JSON, or URL-encoded responses with
- *   {@link empty}, {@link redirect}, {@link text}, {@link html}, {@link json},
- *   {@link schemaJson}, or {@link urlParams}.
- * - Send binary, raw, form-data, stream, or file bodies with {@link uint8Array},
- *   {@link raw}, {@link formData}, {@link stream}, {@link file}, or
- *   {@link fileWeb}.
- * - Adjust status, headers, and bodies with {@link setStatus},
- *   {@link setHeader}, {@link setHeaders}, and {@link setBody}.
- * - Manage cookies with {@link setCookie}, {@link expireCookie},
- *   {@link removeCookie}, and their unsafe variants.
- * - Convert responses with {@link toWeb}, {@link fromWeb},
- *   {@link toClientResponse}, and {@link fromClientResponse}.
- *
- * **Gotchas**
- *
- * - Body content type and content length override existing `content-type` and
- *   `content-length` headers when body metadata is present.
- * - {@link json} and {@link schemaJson} capture encoding failures in the Effect
- *   error channel; {@link jsonUnsafe} throws instead.
- * - {@link setCookie} and {@link expireCookie} validate cookie output in the
- *   Effect error channel; unsafe cookie helpers throw on invalid cookies.
- * - `Set-Cookie` headers are produced from the response cookie collection, not
- *   by manually editing the normal header map.
+ * Describes immutable responses returned by Effect HTTP handlers.
+ *
+ * An `HttpServerResponse` stores the status, optional status text, headers,
+ * cookies, and body that the server runtime later turns into a platform
+ * response such as a Web `Response`. This module includes constructors for
+ * common response bodies, helpers for updating response data, file response
+ * support through `HttpPlatform`, and conversions to or from Web and Effect
+ * HTTP client responses.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpStaticServer.ts

@@ -1,36 +1,11 @@
 /**
- * Static file serving for Effect HTTP applications.
+ * Serves static files for Effect HTTP applications.
  *
- * `HttpStaticServer` turns HTTP requests into file responses rooted at a
- * configured directory. Use {@link make} when you need an application value, or
- * {@link layer} when static files should be mounted onto an `HttpRouter`,
- * optionally under a URL prefix.
- *
- * **Mental model**
- *
- * The request path is decoded, normalized, and resolved below `root`. Invalid
- * paths, null bytes, and `..` traversal outside `root` fail as route-not-found
- * errors. A matching file is served through `HttpPlatform.fileResponse`, a
- * matching directory serves `index` when configured, and `spa: true` falls back
- * to the index file for extensionless HTML requests.
- *
- * **Common tasks**
- *
- * - Serve a public assets directory with {@link make}
- * - Mount static assets beside API routes with {@link layer}
- * - Add `Cache-Control` headers with `cacheControl`
- * - Extend MIME type detection with `mimeTypes`
- * - Support single-page application routing with `spa: true`
- *
- * **Gotchas**
- *
- * - {@link layer} installs `GET` routes only; handle other methods elsewhere.
- * - Dotfiles are served when they live under `root`; keep secrets outside the
- *   served tree.
- * - Symlinks or generated files reachable from `root` may expose more than
- *   expected.
- * - Conditional requests and byte ranges depend on metadata supplied by
- *   `HttpPlatform`.
+ * `HttpStaticServer` turns request paths into file responses under a configured
+ * root directory. It can be used as an application value or mounted onto an
+ * `HttpRouter`, and it handles index files, optional single-page application
+ * fallback, MIME type headers, cache-control headers, byte ranges, and
+ * conditional `304 Not Modified` responses.
  *
  * @since 4.0.0
  */

package/src/unstable/http/HttpTraceContext.ts

@@ -6,30 +6,6 @@
  * HTTP clients use it to continue the current span across outgoing requests, and
  * server middleware uses it to parent request spans from upstream services.
  *
- * **Mental model**
- *
- * Propagation is metadata, not tracing storage. {@link toHeaders} serializes the
- * current span into HTTP headers for the next service. {@link fromHeaders}
- * inspects incoming headers and returns an external parent span when a supported
- * propagation format is present.
- *
- * **Common tasks**
- *
- * - Add outbound propagation headers with {@link toHeaders}
- * - Decode an inbound parent span with {@link fromHeaders}
- * - Use {@link w3c}, {@link b3}, or {@link xb3} directly when an adapter needs a
- *   specific propagation format
- *
- * **Gotchas**
- *
- * - 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
- * - Missing or unsupported trace context decodes to `Option.none`, so callers
- *   should start a new trace when no parent is returned
- *
  * @since 4.0.0
  */
 import * as Option from "../../Option.ts"

package/src/unstable/http/Multipart.ts

@@ -1,41 +1,12 @@
 /**
  * Parses and persists HTTP `multipart/form-data` request bodies.
  *
- * `Multipart` turns incoming byte streams into typed {@link Part} values. Text
- * parts become decoded {@link Field} values, while upload parts remain streamed
- * {@link File} values until they are collected or written to scoped temporary
- * files. The persisted representation can then be decoded with schemas for
- * request handlers that receive fields and uploaded files together.
- *
- * **Mental model**
- *
- * Multipart parsing is incremental. {@link makeChannel} consumes request body
- * chunks and emits fields or files as soon as the parser reaches each part. A
- * `File` owns a one-shot byte stream for that upload; {@link toPersisted}
- * drains those file streams into scoped paths and collects text fields into a
- * {@link Persisted} record.
- *
- * **Common tasks**
- *
- * - Parse a request body stream into {@link Part} values with {@link makeChannel}.
- * - Persist parsed parts with {@link toPersisted} before schema decoding.
- * - Decode persisted forms with {@link schemaPersisted}, {@link schemaJson},
- *   {@link PersistedFileSchema}, or {@link SingleFileSchema}.
- * - Configure parser limits with {@link limitsServices} or the `Max*` context
- *   references.
- *
- * **Gotchas**
- *
- * Multipart request bodies are usually one-shot streams. Read each file stream
- * once, and use `contentEffect` only when the file is small enough to hold in
- * memory. Paths produced by {@link toPersisted} are scoped resources and stop
- * being valid when the scope closes. Client-provided file names are metadata,
- * not trusted filesystem paths.
- *
- * **See also**
- *
- * {@link Part}, {@link Field}, {@link File}, {@link Persisted},
- * {@link makeChannel}, {@link toPersisted}.
+ * `Multipart` turns incoming byte streams into typed form parts. Text parts
+ * become decoded fields, while upload parts stay as streamed files until they
+ * are collected or written to scoped temporary files. The persisted
+ * representation can then be decoded with schemas for handlers that receive
+ * fields and uploaded files together. This module also includes multipart error
+ * types, schema helpers for persisted files, and parser limit settings.
  *
  * @since 4.0.0
  */

package/src/unstable/http/Multipasta/HeadersParser.ts

@@ -1,4 +1,9 @@
 /**
+ * Re-exports the `multipasta` header parser used by multipart HTTP parsing.
+ *
+ * This module keeps the parser available from the Effect HTTP namespace without
+ * wrapping or changing it.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Multipasta/Node.ts

@@ -1,4 +1,9 @@
 /**
+ * Re-exports the Node.js multipart helpers from `multipasta`.
+ *
+ * This module keeps the Node-specific parser helpers available from the Effect
+ * HTTP namespace without wrapping or changing them.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Multipasta/Search.ts

@@ -1,4 +1,9 @@
 /**
+ * Re-exports the multipart search helpers from `multipasta`.
+ *
+ * This module keeps the search helpers available from the Effect HTTP namespace
+ * without wrapping or changing them.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Multipasta/Web.ts

@@ -1,4 +1,9 @@
 /**
+ * Re-exports the Web multipart helpers from `multipasta`.
+ *
+ * This module keeps the Web-specific parser helpers available from the Effect
+ * HTTP namespace without wrapping or changing them.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Multipasta.ts

@@ -1,4 +1,10 @@
 /**
+ * Re-exports the `multipasta` multipart parser used by the unstable HTTP
+ * modules.
+ *
+ * This module keeps the parser types and helpers available from the Effect HTTP
+ * namespace without wrapping or changing them.
+ *
  * @since 4.0.0
  */
 

package/src/unstable/http/Template.ts

@@ -1,31 +1,10 @@
 /**
- * Effect-aware template literal rendering for HTTP response text.
+ * Builds HTTP response text from template literals.
  *
- * This module backs HTTP response helpers that accept template tags, especially
- * HTML responses assembled from plain values, optional values, effects, and
- * streams. It keeps template interpolation in the Effect type system so dynamic
- * fragments can contribute errors and service requirements to the final
- * response-producing program.
- *
- * **Mental model**
- *
- * `make` evaluates effectful interpolations and returns one complete string.
- * `stream` emits static template text together with effect and stream
- * interpolations as a `Stream`. Plain primitive values are converted to text,
- * arrays are concatenated without separators, and `Option.none`, `null`, and
- * `undefined` render as empty text.
- *
- * **Common tasks**
- *
- * Use `make` when the entire rendered body should be available before creating
- * the response. Use `stream` when a response can be emitted incrementally, for
- * example when part of an HTML page is produced by an existing stream.
- *
- * **Gotchas**
- *
- * Templates do not escape HTML, encode bytes, set content types, or compute
- * content lengths. Escape or encode untrusted values before interpolation and
- * choose the response constructor that matches the rendered body.
+ * Template interpolations can be plain values, optional values, effects, or
+ * streams. The resulting effect or stream keeps the errors and service
+ * requirements from any effectful interpolations, which lets response helpers
+ * assemble dynamic text without losing type information.
  *
  * @since 4.0.0
  */

package/src/unstable/http/Url.ts

@@ -1,33 +1,10 @@
 /**
- * Immutable helpers for parsing and editing platform `URL` values.
+ * Parses and edits platform `URL` values.
  *
- * This module keeps the WHATWG `URL` object as the URL representation used by
- * HTTP clients and servers, then adds safe parsing and pipeable setters for
- * credentials, host, path, protocol, query, and hash components. Query strings
- * can be read, replaced, or transformed through `UrlParams` so repeated keys and
- * key/value encoding stay explicit.
- *
- * **Mental model**
- *
- * `fromString` returns a `Result` instead of throwing when URL construction
- * fails. Setters never mutate the original `URL`; each one clones the input and
- * assigns the requested component on the clone. Use `mutate` when several
- * component assignments should happen on the same clone.
- *
- * **Common tasks**
- *
- * - Parse absolute URLs, or resolve relative URL strings against a base URL.
- * - Pipe setters to adjust host, protocol, path, credentials, search, or hash.
- * - Extract query parameters with `urlParams`.
- * - Replace or transform query parameters with `setUrlParams` and
- *   `modifyUrlParams`.
- *
- * **Gotchas**
- *
- * Relative input needs an explicit base. Component assignment and serialization
- * follow platform `URL` rules, so values may be normalized or percent-encoded.
- * `setPassword` accepts `Redacted` input, but the resulting `URL` still contains
- * the actual credential and should be treated as sensitive when serialized.
+ * The HTTP modules use the standard `URL` object as their URL representation.
+ * This module adds safe parsing and helpers that return updated copies when
+ * changing credentials, host, path, protocol, query, or hash parts. Query
+ * strings can also be read or updated through `UrlParams`.
  *
  * @since 4.0.0
  */

package/src/unstable/http/UrlParams.ts

@@ -1,39 +1,11 @@
 /**
- * Immutable URL query parameters represented as ordered string pairs.
+ * Models URL query parameters as ordered string pairs.
  *
- * This module is the shared query-parameter model for HTTP client request
- * queries, URL-encoded form bodies, and server-side decoding. A `UrlParams`
- * value can be built from records, iterables, or native `URLSearchParams`, then
- * inspected, appended, replaced, removed, serialized, converted to a `URL`, or
+ * `UrlParams` is used for HTTP client query strings, URL-encoded form bodies,
+ * and server-side decoding. Values can be built from records, iterables, or
+ * native `URLSearchParams`, then updated, serialized, converted to a `URL`, or
  * decoded with schemas.
  *
- * **Mental model**
- *
- * The core representation is a list of `[key, value]` string pairs. Duplicate
- * keys and pair order are preserved by `make`, `fromInput`, iteration, and
- * append-style operations. Record input is a convenience layer: primitive values
- * become strings, arrays become repeated parameters, nested records use bracket
- * notation, and `undefined` fields are skipped.
- *
- * **Common tasks**
- *
- * - Build query parameters from plain records, tuples, or `URLSearchParams`.
- * - Read the first, last, or all values for a key.
- * - Replace, append, transform, or remove keys without mutating the original.
- * - Serialize a query string, merge parameters into a URL, or decode records and
- *   JSON fields with schemas.
- *
- * **Gotchas**
- *
- * Use `getAll` when every duplicate value matters. `set` and `setAll` replace
- * existing values for matching keys, while `append` and `appendAll` preserve
- * them. Serialization through `toString` and `makeUrl` delegates to the platform
- * `URLSearchParams` / `URL` implementations, so pass decoded strings rather
- * than pre-encoded query fragments. Record-based and schema-based conversions
- * 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
  */
 import * as Arr from "../../Array.ts"