effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/http/Template.ts

@@ -1,4 +1,19 @@
 /**
+ * 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
  */
 import * as Effect from "../../Effect.ts"
@@ -7,18 +22,30 @@ import * as Option from "../../Option.ts"
 import * as Stream from "../../Stream.ts"
 
 /**
+ * Primitive value that can be interpolated into an HTTP template.
+ *
  * @category models
  * @since 4.0.0
  */
 export type PrimitiveValue = string | number | bigint | boolean | null | undefined
 
 /**
+ * Primitive template interpolation value.
+ *
+ * Arrays are rendered by converting each element to a string and concatenating the
+ * results.
+ *
  * @category models
  * @since 4.0.0
  */
 export type Primitive = PrimitiveValue | ReadonlyArray<PrimitiveValue>
 
 /**
+ * Value accepted by the string template constructor.
+ *
+ * Interpolations can be primitive values, optional primitive values, or effects
+ * that produce primitive values.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -28,17 +55,27 @@ export type Interpolated =
   | Effect.Effect<Primitive, any, any>
 
 /**
+ * Value accepted by the streaming template constructor.
+ *
+ * In addition to normal interpolations, stream interpolations can emit primitive
+ * values over time.
+ *
  * @category models
  * @since 4.0.0
  */
 export type InterpolatedWithStream = Interpolated | Stream.Stream<Primitive, any, any>
 
 /**
- * @category models
+ * Namespace containing type-level helpers for template interpolations.
+ *
  * @since 4.0.0
  */
 export declare namespace Interpolated {
   /**
+   * Extracts the required context from an effect or stream interpolation.
+   *
+   * Plain values and `Option` interpolations contribute no context.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -49,6 +86,10 @@ export declare namespace Interpolated {
     : never
 
   /**
+   * Extracts the error type from an effect or stream interpolation.
+   *
+   * Plain values and `Option` interpolations contribute no error type.
+   *
    * @category models
    * @since 4.0.0
    */
@@ -60,6 +101,11 @@ export declare namespace Interpolated {
 }
 
 /**
+ * Creates an effectful string from a template literal.
+ *
+ * Primitive and `Option` interpolations are rendered immediately. Effect
+ * interpolations are evaluated and rendered before the final string is produced.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -113,6 +159,12 @@ export function make<A extends ReadonlyArray<Interpolated>>(
 }
 
 /**
+ * Creates a stream of strings from a template literal.
+ *
+ * Static text is emitted with interpolated values. Effect interpolations are
+ * evaluated as stream chunks, and stream interpolations are flattened into the
+ * output.
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/http/Url.ts

@@ -1,4 +1,18 @@
 /**
+ * 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
  */
 import * as Cause from "../../Cause.ts"
@@ -24,11 +38,11 @@ import * as UrlParams from "./UrlParams.ts"
  * `base`. This is especially useful when dealing with URLs that might not be
  * fully qualified.
  *
- * **Example**
+ * **Example** (Parsing absolute and relative URLs)
  *
  * ```ts
- * import { Url } from "effect/unstable/http"
  * import { Result } from "effect"
+ * import { Url } from "effect/unstable/http"
  *
  * // Parse an absolute URL
  * //
@@ -54,8 +68,8 @@ import * as UrlParams from "./UrlParams.ts"
  * // Output: Parsed relative URL: https://example.com/relative-path
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const fromString: {
   /**
@@ -75,11 +89,11 @@ export const fromString: {
    * `base`. This is especially useful when dealing with URLs that might not be
    * fully qualified.
    *
-   * **Example**
+   * **Example** (Parsing absolute and relative URLs)
    *
    * ```ts
-   * import { Url } from "effect/unstable/http"
    * import { Result } from "effect"
+   * import { Url } from "effect/unstable/http"
    *
    * // Parse an absolute URL
    * //
@@ -105,8 +119,8 @@ export const fromString: {
    * // Output: Parsed relative URL: https://example.com/relative-path
    * ```
    *
+   * @category constructors
    * @since 4.0.0
-   * @category Constructors
    */
   (url: string, base?: string | URL | undefined): Result.Result<URL, Cause.IllegalArgumentError>
 } = (url, base) =>
@@ -120,7 +134,7 @@ export const fromString: {
  * This function clones the original `URL` object and applies a callback to the
  * clone, allowing multiple updates at once.
  *
- * **Example**
+ * **Example** (Mutating URL credentials)
  *
  * ```ts
  * import { Url } from "effect/unstable/http"
@@ -136,15 +150,15 @@ export const fromString: {
  * // Output: Mutated: https://user:pass@example.com/
  * ```
  *
- * @since 4.0.0
  * @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.
    *
-   * **Example**
+   * **Example** (Mutating URL credentials)
    *
    * ```ts
    * import { Url } from "effect/unstable/http"
@@ -160,15 +174,15 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @since 4.0.0
    * @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.
    *
-   * **Example**
+   * **Example** (Mutating URL credentials)
    *
    * ```ts
    * import { Url } from "effect/unstable/http"
@@ -184,8 +198,8 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @since 4.0.0
    * @category Modifiers
+   * @since 4.0.0
    */
   (self: URL, f: (url: URL) => void): URL
 } = dual(2, (self: URL, f: (url: URL) => void) => {
@@ -207,22 +221,22 @@ const immutableURLSetter = <P extends keyof URL, A = never>(property: P): {
 /**
  * Updates the hash fragment of the URL.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setHash: {
   /**
    * Updates the hash fragment of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (hash: string): (url: URL) => URL
   /**
    * Updates the hash fragment of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, hash: string): URL
 } = immutableURLSetter("hash")
@@ -230,22 +244,22 @@ export const setHash: {
 /**
  * Updates the host (domain and port) of the URL.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setHost: {
   /**
    * Updates the host (domain and port) of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (host: string): (url: URL) => URL
   /**
    * Updates the host (domain and port) of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, host: string): URL
 } = immutableURLSetter("host")
@@ -253,22 +267,22 @@ export const setHost: {
 /**
  * Updates the domain of the URL without modifying the port.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setHostname: {
   /**
    * Updates the domain of the URL without modifying the port.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (hostname: string): (url: URL) => URL
   /**
    * Updates the domain of the URL without modifying the port.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, hostname: string): URL
 } = immutableURLSetter("hostname")
@@ -276,22 +290,22 @@ export const setHostname: {
 /**
  * Replaces the entire URL string.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setHref: {
   /**
    * Replaces the entire URL string.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (href: string): (url: URL) => URL
   /**
    * Replaces the entire URL string.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, href: string): URL
 } = immutableURLSetter("href")
@@ -299,22 +313,22 @@ export const setHref: {
 /**
  * Updates the password used for authentication.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setPassword: {
   /**
    * Updates the password used for authentication.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (password: string | Redacted.Redacted): (url: URL) => URL
   /**
    * Updates the password used for authentication.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, password: string | Redacted.Redacted): URL
 } = dual(2, (url: URL, password: string | Redacted.Redacted) =>
@@ -327,22 +341,22 @@ export const setPassword: {
 /**
  * Updates the path of the URL.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setPathname: {
   /**
    * Updates the path of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (pathname: string): (url: URL) => URL
   /**
    * Updates the path of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, pathname: string): URL
 } = immutableURLSetter("pathname")
@@ -350,22 +364,22 @@ export const setPathname: {
 /**
  * Updates the port of the URL.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setPort: {
   /**
    * Updates the port of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (port: string | number): (url: URL) => URL
   /**
    * Updates the port of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, port: string | number): URL
 } = immutableURLSetter("port")
@@ -373,22 +387,22 @@ export const setPort: {
 /**
  * Updates the protocol (e.g., `http`, `https`).
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setProtocol: {
   /**
    * Updates the protocol (e.g., `http`, `https`).
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (protocol: string): (url: URL) => URL
   /**
    * Updates the protocol (e.g., `http`, `https`).
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, protocol: string): URL
 } = immutableURLSetter("protocol")
@@ -396,22 +410,22 @@ export const setProtocol: {
 /**
  * Updates the query string of the URL.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setSearch: {
   /**
    * Updates the query string of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (search: string): (url: URL) => URL
   /**
    * Updates the query string of the URL.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, search: string): URL
 } = immutableURLSetter("search")
@@ -419,22 +433,22 @@ export const setSearch: {
 /**
  * Updates the username used for authentication.
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setUsername: {
   /**
    * Updates the username used for authentication.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (username: string): (url: URL) => URL
   /**
    * Updates the username used for authentication.
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, username: string): URL
 } = immutableURLSetter("username")
@@ -448,7 +462,7 @@ export const setUsername: {
  * object using the provided `UrlParams`. It creates a new `URL` object with the
  * updated parameters, leaving the original object unchanged.
  *
- * **Example**
+ * **Example** (Replacing query parameters)
  *
  * ```ts
  * import { Url, UrlParams } from "effect/unstable/http"
@@ -465,8 +479,8 @@ export const setUsername: {
  * // Output: https://example.com/?key=value
  * ```
  *
- * @since 4.0.0
  * @category Setters
+ * @since 4.0.0
  */
 export const setUrlParams: {
   /**
@@ -478,7 +492,7 @@ export const setUrlParams: {
    * object using the provided `UrlParams`. It creates a new `URL` object with the
    * updated parameters, leaving the original object unchanged.
    *
-   * **Example**
+   * **Example** (Replacing query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -495,8 +509,8 @@ export const setUrlParams: {
    * // Output: https://example.com/?key=value
    * ```
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (urlParams: UrlParams.UrlParams): (url: URL) => URL
   /**
@@ -508,7 +522,7 @@ export const setUrlParams: {
    * object using the provided `UrlParams`. It creates a new `URL` object with the
    * updated parameters, leaving the original object unchanged.
    *
-   * **Example**
+   * **Example** (Replacing query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -525,8 +539,8 @@ export const setUrlParams: {
    * // Output: https://example.com/?key=value
    * ```
    *
-   * @since 4.0.0
    * @category Setters
+   * @since 4.0.0
    */
   (url: URL, urlParams: UrlParams.UrlParams): URL
 } = dual(2, (url: URL, searchParams: UrlParams.UrlParams) =>
@@ -543,7 +557,7 @@ export const setUrlParams: {
  * them as `UrlParams`. The resulting structure can be easily manipulated or
  * inspected.
  *
- * **Example**
+ * **Example** (Reading query parameters)
  *
  * ```ts
  * import { Url } from "effect/unstable/http"
@@ -557,8 +571,8 @@ export const setUrlParams: {
  * // Output: [ [ 'foo', 'bar' ] ]
  * ```
  *
+ * @category getters
  * @since 4.0.0
- * @category Getters
  */
 export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(url.searchParams)
 
@@ -572,7 +586,7 @@ export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(
  * writing the updated parameters back to the URL. It returns a new `URL` object
  * with the modified parameters, ensuring immutability.
  *
- * **Example**
+ * **Example** (Modifying query parameters)
  *
  * ```ts
  * import { Url, UrlParams } from "effect/unstable/http"
@@ -585,8 +599,8 @@ export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(
  * // Output: https://example.com/?foo=bar&key=value
  * ```
  *
- * @since 4.0.0
  * @category Modifiers
+ * @since 4.0.0
  */
 export const modifyUrlParams: {
   /**
@@ -599,7 +613,7 @@ export const modifyUrlParams: {
    * writing the updated parameters back to the URL. It returns a new `URL` object
    * with the modified parameters, ensuring immutability.
    *
-   * **Example**
+   * **Example** (Modifying query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -612,8 +626,8 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @since 4.0.0
    * @category Modifiers
+   * @since 4.0.0
    */
   (f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): (url: URL) => URL
   /**
@@ -626,7 +640,7 @@ export const modifyUrlParams: {
    * writing the updated parameters back to the URL. It returns a new `URL` object
    * with the modified parameters, ensuring immutability.
    *
-   * **Example**
+   * **Example** (Modifying query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -639,8 +653,8 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @since 4.0.0
    * @category Modifiers
+   * @since 4.0.0
    */
   (url: URL, f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): URL
 } = dual(2, (url: URL, f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams) =>