effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/unstable/http/Multipart.ts

@@ -1,21 +1,41 @@
 /**
- * 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.
+ * 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}.
  *
  * @since 4.0.0
  */
@@ -193,7 +213,7 @@ export interface Persisted {
 const MultipartErrorTypeId = "~effect/http/Multipart/MultipartError"
 
 /**
- * Reason carried by a `MultipartError`.
+ * Error reason carried by a `MultipartError`.
  *
  * **Details**
  *
@@ -384,7 +404,7 @@ export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, opt
  * Parser limits are read from the multipart references, including maximum parts,
  * field size, file size, total body size, and field MIME type overrides.
  *
- * @category Config
+ * @category configuration
  * @since 4.0.0
  */
 export const makeConfig = (

package/src/unstable/http/Template.ts

@@ -1,18 +1,31 @@
 /**
- * Template literal helpers for rendering HTTP-oriented text with Effect values.
+ * Effect-aware template literal rendering for HTTP response text.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * **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.
  *
  * @since 4.0.0
  */

package/src/unstable/http/Url.ts

@@ -1,17 +1,33 @@
 /**
- * Utilities for parsing and immutably updating HTTP URLs.
+ * Immutable helpers for parsing and editing platform `URL` values.
  *
- * 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`.
+ * 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.
  *
- * 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.
+ * **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.
  *
  * @since 4.0.0
  */
@@ -22,7 +38,7 @@ import * as Result from "../../Result.ts"
 import * as UrlParams from "./UrlParams.ts"
 
 /**
- * Parses a URL string into a `URL` object, returning an `Result` type for safe
+ * Parses a URL string safely into a `URL` object, returning a `Result` type for
  * error handling.
  *
  * **Details**
@@ -73,7 +89,7 @@ import * as UrlParams from "./UrlParams.ts"
  */
 export const fromString: {
   /**
-   * Parses a URL string into a `URL` object, returning an `Result` type for safe
+   * Parses a URL string safely into a `URL` object, returning a `Result` type for
    * error handling.
    *
    * **Details**
@@ -131,8 +147,7 @@ export const fromString: {
   })
 
 /**
- * This function clones the original `URL` object and applies a callback to the
- * clone, allowing multiple updates at once.
+ * Updates a cloned `URL` with a callback, allowing multiple changes at once.
  *
  * **Example** (Mutating URL credentials)
  *
@@ -150,13 +165,12 @@ export const fromString: {
  * // Output: Mutated: https://user:pass@example.com/
  * ```
  *
- * @category Modifiers
+ * @category modifiers
  * @since 4.0.0
  */
 export const mutate: {
   /**
-   * This function clones the original `URL` object and applies a callback to the
-   * clone, allowing multiple updates at once.
+   * Updates a cloned `URL` with a callback, allowing multiple changes at once.
    *
    * **Example** (Mutating URL credentials)
    *
@@ -174,13 +188,12 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (f: (url: URL) => void): (self: URL) => URL
   /**
-   * This function clones the original `URL` object and applies a callback to the
-   * clone, allowing multiple updates at once.
+   * Updates a cloned `URL` with a callback, allowing multiple changes at once.
    *
    * **Example** (Mutating URL credentials)
    *
@@ -198,7 +211,7 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (self: URL, f: (url: URL) => void): URL
@@ -577,7 +590,7 @@ export const setUrlParams: {
 export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(url.searchParams)
 
 /**
- * Reads, modifies, and updates the query parameters of a URL.
+ * Reads the query parameters of a URL, modifies them, and updates the URL.
  *
  * **Details**
  *
@@ -599,12 +612,12 @@ export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(
  * // Output: https://example.com/?foo=bar&key=value
  * ```
  *
- * @category Modifiers
+ * @category modifiers
  * @since 4.0.0
  */
 export const modifyUrlParams: {
   /**
-   * Reads, modifies, and updates the query parameters of a URL.
+   * Reads the query parameters of a URL, modifies them, and updates the URL.
    *
    * **Details**
    *
@@ -626,12 +639,12 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): (url: URL) => URL
   /**
-   * Reads, modifies, and updates the query parameters of a URL.
+   * Reads the query parameters of a URL, modifies them, and updates the URL.
    *
    * **Details**
    *
@@ -653,7 +666,7 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (url: URL, f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): URL

package/src/unstable/http/UrlParams.ts

@@ -1,23 +1,38 @@
 /**
- * Utilities for representing, transforming, and serializing URL query
- * parameters.
+ * Immutable URL query parameters represented 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
+ * 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**
  *
- * 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.
+ * 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
  */
@@ -208,14 +223,14 @@ const fromInputNested = (input: Input): Array<[string | Array<string>, any]> =>
 }
 
 /**
- * Order-sensitive equivalence for `UrlParams`.
+ * Provides an order-sensitive `Equivalence` instance for `UrlParams`.
  *
  * **Details**
  *
  * Two values are equivalent when they contain the same key-value pairs in the same
  * order.
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<UrlParams> = Equ.make<UrlParams>((a, b) =>
@@ -322,7 +337,7 @@ export const getAll: {
 )
 
 /**
- * Returns the first value for a query parameter key.
+ * Returns the first value for a query parameter key safely.
  *
  * **Details**
  *
@@ -333,7 +348,7 @@ export const getAll: {
  */
 export const getFirst: {
   /**
-   * Returns the first value for a query parameter key.
+   * Returns the first value for a query parameter key safely.
    *
    * **Details**
    *
@@ -344,7 +359,7 @@ export const getFirst: {
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * Returns the first value for a query parameter key.
+   * Returns the first value for a query parameter key safely.
    *
    * **Details**
    *
@@ -363,7 +378,7 @@ export const getFirst: {
 )
 
 /**
- * Returns the last value for a query parameter key.
+ * Returns the last value for a query parameter key safely.
  *
  * **Details**
  *
@@ -374,7 +389,7 @@ export const getFirst: {
  */
 export const getLast: {
   /**
-   * Returns the last value for a query parameter key.
+   * Returns the last value for a query parameter key safely.
    *
    * **Details**
    *
@@ -385,7 +400,7 @@ export const getLast: {
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * Returns the last value for a query parameter key.
+   * Returns the last value for a query parameter key safely.
    *
    * **Details**
    *
@@ -628,7 +643,7 @@ export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
 }> {}
 
 /**
- * Creates a `URL` by appending `UrlParams` and an optional hash to a URL string.
+ * Creates a `URL` safely by appending `UrlParams` and an optional hash to a URL string.
  *
  * **Details**
  *
@@ -746,7 +761,7 @@ export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, strin
 export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonString, UrlParamsSchema> {}
 
 /**
- * Extract a JSON value from the first occurrence of the given `field` in the
+ * Extracts a JSON value from the first occurrence of the given `field` in the
  * `UrlParams`.
  *
  * **Example** (Decoding JSON parameter fields)