effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/Filter.ts

@@ -46,8 +46,10 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
 /**
  * Represents a filter function that can transform inputs to outputs or filter them out.
  *
- * A filter takes an input value and either returns a boxed pass value or
- * the special `fail` type to indicate the value should be filtered out.
+ * **Details**
+ *
+ * A filter takes an input value and either returns a boxed pass value or the
+ * special `fail` type to indicate the value should be filtered out.
  *
  * **Example** (Defining a positive number filter)
  *
@@ -71,8 +73,11 @@ export interface Filter<in Input, out Pass = Input, out Fail = Input> {
 /**
  * Represents an effectful filter function that can produce Effects.
  *
- * Similar to a regular Filter, but the filtering operation itself can be effectful,
- * allowing for asynchronous operations, error handling, and dependency injection.
+ * **Details**
+ *
+ * Similar to a regular `Filter`, but the filtering operation itself can be
+ * effectful, allowing for asynchronous operations, error handling, and
+ * dependency injection.
  *
  * **Example** (Defining an effectful user filter)
  *
@@ -116,6 +121,8 @@ export interface FilterEffect<
 /**
  * Creates a Filter from a function that returns either a `pass` or `fail` value.
  *
+ * **Details**
+ *
  * This is the primary constructor for creating custom filters. The function
  * should return either `Result.succeed(value)` or `Result.fail(value)`.
  *
@@ -143,9 +150,11 @@ export const make = <Input, Pass, Fail>(
 /**
  * Creates an effectful Filter from a function that returns an Effect.
  *
+ * **Details**
+ *
  * This constructor is used when the filtering operation needs to perform
- * effectful computations, such as async operations, error handling, or
- * accessing services from the environment.
+ * effectful computations, such as async operations, error handling, or accessing
+ * services from the environment.
  *
  * **Example** (Creating effectful filters)
  *
@@ -220,6 +229,8 @@ export {
 /**
  * Creates a Filter from a predicate or refinement function.
  *
+ * **Details**
+ *
  * This is a convenient way to create filters from boolean-returning functions.
  * When the predicate returns true, the input value is passed through unchanged.
  * When it returns false, the `fail` type is returned.
@@ -246,6 +257,8 @@ export const fromPredicate: {
   /**
    * Creates a Filter from a predicate or refinement function.
    *
+   * **Details**
+   *
    * This is a convenient way to create filters from boolean-returning functions.
    * When the predicate returns true, the input value is passed through unchanged.
    * When it returns false, the `fail` type is returned.
@@ -272,6 +285,8 @@ export const fromPredicate: {
   /**
    * Creates a Filter from a predicate or refinement function.
    *
+   * **Details**
+   *
    * This is a convenient way to create filters from boolean-returning functions.
    * When the predicate returns true, the input value is passed through unchanged.
    * When it returns false, the `fail` type is returned.
@@ -299,9 +314,8 @@ export const fromPredicate: {
   predicate(input) ? Result.succeed(input as B) : Result.fail(input)
 
 /**
- * Creates a `Filter` from a function that returns an `Option`.
- *
- * `Some(value)` passes with `value`. `None` fails with the original input.
+ * Creates a `Filter` from a function that returns an `Option`; `Some(value)`
+ * passes with `value`, and `None` fails with the original input.
  *
  * @category constructors
  * @since 4.0.0
@@ -548,6 +562,8 @@ export const or: {
 /**
  * Combines two filters and applies a function to their results.
  *
+ * **Details**
+ *
  * Both filters must succeed (not return `fail`) for the combination to succeed.
  * If both filters pass, their outputs are combined using the provided function.
  *
@@ -558,6 +574,8 @@ export const zipWith: {
   /**
    * Combines two filters and applies a function to their results.
    *
+   * **Details**
+   *
    * Both filters must succeed (not return `fail`) for the combination to succeed.
    * If both filters pass, their outputs are combined using the provided function.
    *
@@ -568,6 +586,8 @@ export const zipWith: {
   /**
    * Combines two filters and applies a function to their results.
    *
+   * **Details**
+   *
    * Both filters must succeed (not return `fail`) for the combination to succeed.
    * If both filters pass, their outputs are combined using the provided function.
    *
@@ -595,8 +615,10 @@ export const zipWith: {
 /**
  * Combines two filters into a tuple of their results.
  *
- * Both filters must succeed for the combination to succeed. If both pass,
- * their outputs are combined into a tuple.
+ * **Details**
+ *
+ * Both filters must succeed for the combination to succeed. If both pass, their
+ * outputs are combined into a tuple.
  *
  * **Example** (Zipping filters)
  *
@@ -616,8 +638,10 @@ export const zip: {
   /**
    * Combines two filters into a tuple of their results.
    *
-   * Both filters must succeed for the combination to succeed. If both pass,
-   * their outputs are combined into a tuple.
+   * **Details**
+   *
+   * Both filters must succeed for the combination to succeed. If both pass, their
+   * outputs are combined into a tuple.
    *
    * **Example** (Zipping filters)
    *
@@ -639,8 +663,10 @@ export const zip: {
   /**
    * Combines two filters into a tuple of their results.
    *
-   * Both filters must succeed for the combination to succeed. If both pass,
-   * their outputs are combined into a tuple.
+   * **Details**
+   *
+   * Both filters must succeed for the combination to succeed. If both pass, their
+   * outputs are combined into a tuple.
    *
    * **Example** (Zipping filters)
    *
@@ -862,8 +888,10 @@ export const compose: {
 })
 
 /**
- * Composes two filters sequentially, passing the successful output of the
- * first filter to the second.
+ * Composes two filters sequentially, passing the successful output of the first
+ * filter to the second.
+ *
+ * **Details**
  *
  * If either filter fails, the returned filter fails with the original input
  * instead of the intermediate failure value.
@@ -873,8 +901,10 @@ export const compose: {
  */
 export const composePassthrough: {
   /**
-   * Composes two filters sequentially, passing the successful output of the
-   * first filter to the second.
+   * Composes two filters sequentially, passing the successful output of the first
+   * filter to the second.
+   *
+   * **Details**
    *
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.
@@ -884,8 +914,10 @@ export const composePassthrough: {
    */
   <InputL, PassL, PassR, FailR>(right: Filter<PassL, PassR, FailR>): <FailL>(left: Filter<InputL, PassL, FailL>) => Filter<InputL, PassR, InputL>
   /**
-   * Composes two filters sequentially, passing the successful output of the
-   * first filter to the second.
+   * Composes two filters sequentially, passing the successful output of the first
+   * filter to the second.
+   *
+   * **Details**
    *
    * If either filter fails, the returned filter fails with the original input
    * instead of the intermediate failure value.

package/src/Formatter.ts

@@ -56,16 +56,15 @@ import * as Predicate from "./Predicate.ts"
 import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
 
 /**
- * A callable interface representing a function that converts a `Value` into a
- * `Format` (defaults to `string`).
+ * A callable interface representing a function that converts a `Value` into a `Format`, which defaults to `string`.
  *
- * When to use:
- * - You want to type a formatting / rendering function generically.
- * - You are building a pipeline that accepts pluggable formatters.
+ * **When to use**
  *
- * Behavior:
- * - Pure callable type; carries no runtime implementation.
- * - Contravariant in `Value`, covariant in `Format`.
+ * Use `Formatter` when you want to type a formatting or rendering function generically, or when you are building a pipeline that accepts pluggable formatters.
+ *
+ * **Details**
+ *
+ * This is a pure callable type and carries no runtime implementation. It is contravariant in `Value` and covariant in `Format`.
  *
  * **Example** (Define a custom formatter)
  *
@@ -78,8 +77,8 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  * // HELLO
  * ```
  *
- * See also: {@link format}, {@link formatJson}
- *
+ * @see {@link format}
+ * @see {@link formatJson}
  * @category models
  * @since 4.0.0
  */
@@ -90,14 +89,16 @@ export interface Formatter<in Value, out Format = string> {
 /**
  * Converts any JavaScript value into a human-readable string.
  *
- * When to use:
+ * **When to use**
+ *
  * - Pretty-printing values for debugging, logging, or error messages.
  * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
  *   or class instances that `JSON.stringify` cannot represent.
  * - You want circular references shown as `"[Circular]"` instead of
  *   throwing.
  *
- * Behavior:
+ * **Details**
+ *
  * - Does not mutate input.
  * - Output is **not** valid JSON; use {@link formatJson} when you need
  *   parseable JSON.
@@ -113,8 +114,6 @@ export interface Formatter<in Value, out Format = string> {
  * - Arrays/objects with 0–1 entries are inline; larger ones are
  *   pretty-printed when `space` is set.
  * - Circular references are replaced with `"[Circular]"`.
- *
- * Options:
  * - `space` — indentation unit (number of spaces, or a string like
  *   `"\t"`). Defaults to `0` (compact).
  * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
@@ -154,8 +153,8 @@ export interface Formatter<in Value, out Format = string> {
  * // {"name":"loop","self":[Circular]}
  * ```
  *
- * See also: {@link formatJson}, {@link Formatter}
- *
+ * @see {@link formatJson}
+ * @see {@link Formatter}
  * @category formatting
  * @since 2.0.0
  */
@@ -288,12 +287,14 @@ function safeToString(input: any): string {
 /**
  * Safely stringifies a value to JSON, silently dropping circular references.
  *
- * When to use:
+ * **When to use**
+ *
  * - You need valid JSON output (unlike {@link format}).
  * - The input may contain circular references and you want them silently
  *   omitted rather than throwing a `TypeError`.
  *
- * Behavior:
+ * **Details**
+ *
  * - Does not mutate input.
  * - Uses `JSON.stringify` internally with a replacer that tracks the
  *   current object ancestry.
@@ -303,8 +304,6 @@ function safeToString(input: any): string {
  * - Types not supported by JSON (`BigInt`, `Symbol`, `undefined`,
  *   functions) follow standard `JSON.stringify` behavior (omitted or
  *   `null` in arrays).
- *
- * Options:
  * - `space` — indentation unit (number of spaces, or a string like
  *   `"\t"`). Defaults to `0` (compact).
  *
@@ -340,8 +339,8 @@ function safeToString(input: any): string {
  * // }
  * ```
  *
- * See also: {@link format}, {@link Formatter}
- *
+ * @see {@link format}
+ * @see {@link Formatter}
  * @category serialization
  * @since 4.0.0
  */

package/src/Function.ts

@@ -70,21 +70,14 @@ export interface FunctionTypeLambda extends TypeLambda {
 }
 
 /**
- * Creates a function that can be used in a data-last (aka `pipe`able) or
- * data-first style.
+ * Creates a function that can be called in data-first style or data-last
+ * (`pipe`-friendly) style.
  *
- * The first parameter to `dual` is either the arity of the uncurried function
- * or a predicate that determines if the function is being used in a data-first
- * or data-last style.
- *
- * Using the arity is the most common use case, but there are some cases where
- * you may want to use a predicate. For example, if you have a function that
- * takes an optional argument, you can use a predicate to determine if the
- * function is being used in a data-first or data-last style.
+ * **Details**
  *
- * You can pass either the arity of the uncurried function or a predicate
- * which determines if the function is being used in a data-first or
- * data-last style.
+ * Pass either the arity of the uncurried function or a predicate that decides
+ * whether the current call is data-first. Arity is the common case. Use a
+ * predicate when optional arguments make arity ambiguous.
  *
  * **Example** (Using arity to determine data-first or data-last style)
  *
@@ -136,21 +129,14 @@ export interface FunctionTypeLambda extends TypeLambda {
  */
 export const dual: {
   /**
-   * Creates a function that can be used in a data-last (aka `pipe`able) or
-   * data-first style.
+   * Creates a function that can be called in data-first style or data-last
+   * (`pipe`-friendly) style.
    *
-   * The first parameter to `dual` is either the arity of the uncurried function
-   * or a predicate that determines if the function is being used in a data-first
-   * or data-last style.
+   * **Details**
    *
-   * Using the arity is the most common use case, but there are some cases where
-   * you may want to use a predicate. For example, if you have a function that
-   * takes an optional argument, you can use a predicate to determine if the
-   * function is being used in a data-first or data-last style.
-   *
-   * You can pass either the arity of the uncurried function or a predicate
-   * which determines if the function is being used in a data-first or
-   * data-last style.
+   * Pass either the arity of the uncurried function or a predicate that decides
+   * whether the current call is data-first. Arity is the common case. Use a
+   * predicate when optional arguments make arity ambiguous.
    *
    * **Example** (Using arity to determine data-first or data-last style)
    *
@@ -202,21 +188,14 @@ export const dual: {
    */
   <DataLast extends (...args: Array<any>) => any, DataFirst extends (...args: Array<any>) => any>(arity: Parameters<DataFirst>["length"], body: DataFirst): DataLast & DataFirst
   /**
-   * Creates a function that can be used in a data-last (aka `pipe`able) or
-   * data-first style.
-   *
-   * The first parameter to `dual` is either the arity of the uncurried function
-   * or a predicate that determines if the function is being used in a data-first
-   * or data-last style.
+   * Creates a function that can be called in data-first style or data-last
+   * (`pipe`-friendly) style.
    *
-   * Using the arity is the most common use case, but there are some cases where
-   * you may want to use a predicate. For example, if you have a function that
-   * takes an optional argument, you can use a predicate to determine if the
-   * function is being used in a data-first or data-last style.
+   * **Details**
    *
-   * You can pass either the arity of the uncurried function or a predicate
-   * which determines if the function is being used in a data-first or
-   * data-last style.
+   * Pass either the arity of the uncurried function or a predicate that decides
+   * whether the current call is data-first. Arity is the common case. Use a
+   * predicate when optional arguments make arity ambiguous.
    *
    * **Example** (Using arity to determine data-first or data-last style)
    *
@@ -409,6 +388,8 @@ export const satisfies = <A>() => <B extends A>(b: B) => b
 /**
  * Returns the input value with a different static type.
  *
+ * **Gotchas**
+ *
  * This is a type-level cast only; it performs no runtime validation or
  * conversion.
  *
@@ -420,6 +401,8 @@ export const cast: <A, B>(a: A) => B = identity as any
 /**
  * Creates a zero-argument function that always returns the provided value.
  *
+ * **When to use**
+ *
  * Use `constant` when an API expects a thunk or callback and every invocation
  * should return the same value.
  *
@@ -611,10 +594,18 @@ export const compose: {
 } = dual(2, <A, B, C>(ab: (a: A) => B, bc: (b: B) => C): (a: A) => C => (a) => bc(ab(a)))
 
 /**
- * The `absurd` function is a stub for cases where a value of type `never` is encountered in your code,
- * meaning that it should be impossible for this code to be executed.
+ * Marks an impossible branch by accepting a `never` value and returning any
+ * type.
+ *
+ * **When to use**
  *
- * This function is particularly useful when it's necessary to specify that certain cases are impossible.
+ * Use `absurd` when exhaustive checks prove a branch cannot be reached, but
+ * TypeScript still needs a return value.
+ *
+ * **Gotchas**
+ *
+ * Calling `absurd` throws, because a value of type `never` should be
+ * impossible at runtime.
  *
  * **Example** (Handling impossible values)
  *
@@ -672,17 +663,30 @@ export const tupled = <A extends ReadonlyArray<unknown>, B>(f: (...a: A) => B):
 export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (...a: A) => B => (...a) => f(a)
 
 /**
- * Pipes the value of an expression into a pipeline of functions.
+ * Pipes the value of an expression through a left-to-right sequence of
+ * functions.
+ *
+ * **When to use**
+ *
+ * Use `pipe` with data-last functions to build readable transformation
+ * pipelines and to write method-style chains as ordinary function calls.
  *
  * **Details**
  *
- * The `pipe` function is a utility that allows us to compose functions in a
- * readable and sequential manner. It takes the output of one function and
- * passes it as the input to the next function in the pipeline. This enables us
- * to build complex transformations by chaining multiple functions together.
+ * `pipe` takes an initial value, passes it to the first function, then passes
+ * each result to the next function in order. The final function result is
+ * returned.
+ *
+ * **Gotchas**
+ *
+ * Each function passed after the initial value must accept a single argument,
+ * because `pipe` calls each step with only the previous result.
  *
  * **Example** (Showing pipeline syntax)
  *
+ * In this example, `1` is passed to the first function, and each result becomes
+ * the input for the next function.
+ *
  * ```ts
  * import { pipe } from "effect"
  *
@@ -696,26 +700,6 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * console.log(result) // "result: 4"
  * ```
  *
- * In this syntax, `1` is the initial value, and each function is applied in
- * sequence. The result of each function becomes the input for the next
- * function, and the final result is returned.
- *
- * Here's an illustration of how `pipe` works:
- *
- * ```
- * ┌───┐    ┌───────┐    ┌─────────────┐    ┌────────┐
- * │ 1 │───►│ add 1 │───►│ multiply 2  │───►│ format │───► "result: 4"
- * └───┘    └───────┘    └─────────────┘    └────────┘
- * ```
- *
- * It's important to note that functions passed to `pipe` must have a **single
- * argument** because they are only called with a single argument.
- *
- * **When to Use**
- *
- * This is useful in combination with data-last functions as a simulation of
- * methods:
- *
  * **Example** (Chaining methods before conversion)
  *
  * ```ts
@@ -728,10 +712,10 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * console.log(result) // [6, 8]
  * ```
  *
- * becomes:
- *
  * **Example** (Rewriting method chains with pipe)
  *
+ * The same transformation can be written with data-last functions.
+ *
  * ```ts
  * import { Array, pipe } from "effect"
  *
@@ -748,7 +732,7 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * console.log(result) // [6, 8]
  * ```
  *
- * **Example** (Chaining Arithmetic Operations)
+ * **Example** (Chaining arithmetic operations)
  *
  * ```ts
  * import { pipe } from "effect"
@@ -1237,9 +1221,12 @@ export function pipe(a: unknown, ...args: Array<any>): unknown {
 }
 
 /**
- * Performs left-to-right function composition. The first argument may have any arity, the remaining arguments must be unary.
+ * Performs left-to-right function composition.
+ *
+ * **Details**
  *
- * See also [`pipe`](#pipe).
+ * The first function may have any arity. Every following function must be
+ * unary. See also [`pipe`](#pipe).
  *
  * **Example** (Composing functions left to right)
  *
@@ -1426,6 +1413,8 @@ export function flow(
 /**
  * Creates a compile-time placeholder for a value of any type.
  *
+ * **Gotchas**
+ *
  * `hole` is intended for temporary development use. If the placeholder is
  * evaluated at runtime, it throws.
  *
@@ -1449,10 +1438,13 @@ export function flow(
 export const hole: <T>() => T = cast(absurd)
 
 /**
- * The SK combinator, also known as the "S-K combinator" or "S-combinator", is a fundamental combinator in the
- * lambda calculus and the SKI combinator calculus.
+ * The SK combinator, also known as the "S-K combinator" or "S-combinator", is
+ * a fundamental combinator in the lambda calculus and the SKI combinator
+ * calculus.
+ *
+ * **When to use**
  *
- * This function is useful for discarding the first argument passed to it and returning the second argument.
+ * Use `SK` to discard the first argument and return the second argument.
  *
  * **Example** (Discarding the first argument)
  *