effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Result.ts

@@ -89,6 +89,11 @@ const TypeId = "~effect/data/Result"
 /**
  * A value that is either `Success<A, E>` or `Failure<A, E>`.
  *
+ * **When to use**
+ *
+ * Use when both success and failure should remain available as data and
+ * `Option` would lose failure information.
+ *
  * **Details**
  *
  * - Use {@link succeed} / {@link fail} to construct
@@ -265,7 +270,7 @@ export interface ResultUnifyIgnore {}
  * (e.g., `map`, `flatMap` abstractions). You typically do not need to
  * reference this directly.
  *
- * @category Type Lambdas
+ * @category type lambdas
  * @since 4.0.0
  */
 export interface ResultTypeLambda extends TypeLambda {
@@ -341,7 +346,7 @@ export const succeed: <A>(right: A) => Result<A> = result.succeed
  *
  * **When to use**
  *
- * Use to represent a failed computation with a typed failure value.
+ * Use to represent a failed `Result` with a typed failure value.
  *
  * **Details**
  *
@@ -373,8 +378,8 @@ export {
    *
    * **When to use**
    *
-   * Use when a success should signal completion without carrying a meaningful
-   * value.
+   * Use when you need a successful `Result` value that signals completion
+   * without carrying meaningful data.
    *
    * **Details**
    *
@@ -405,8 +410,8 @@ export {
  *
  * **When to use**
  *
- * Use when a failure should act only as a control signal and no failure value
- * is needed.
+ * Use when you need a failed `Result` value that acts only as a control signal
+ * without failure data.
  *
  * **Details**
  *
@@ -437,9 +442,8 @@ export const failVoid: Result<never, void> = fail(void 0)
  *
  * **When to use**
  *
- * Use when an input may be `null` or `undefined` and absence should be
- * represented as a `Failure` while present values should remain available as
- * `Success`.
+ * Use when you need `null` or `undefined` input to become a `Failure` while
+ * present values remain available as `Success`.
  *
  * **Details**
  *
@@ -472,9 +476,8 @@ export const fromNullishOr: {
    *
    * **When to use**
    *
-   * Use when an input may be `null` or `undefined` and absence should be
-   * represented as a `Failure` while present values should remain available as
-   * `Success`.
+   * Use when you need `null` or `undefined` input to become a `Failure` while
+   * present values remain available as `Success`.
    *
    * **Details**
    *
@@ -507,9 +510,8 @@ export const fromNullishOr: {
    *
    * **When to use**
    *
-   * Use when an input may be `null` or `undefined` and absence should be
-   * represented as a `Failure` while present values should remain available as
-   * `Success`.
+   * Use when you need `null` or `undefined` input to become a `Failure` while
+   * present values remain available as `Success`.
    *
    * **Details**
    *
@@ -745,7 +747,7 @@ export {
  *
  * @see {@link isSuccess} / {@link isFailure} to narrow to a specific variant
  *
- * @category Type Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isResult: (input: unknown) => input is Result<unknown, unknown> = result.isResult
@@ -778,7 +780,7 @@ export const isResult: (input: unknown) => input is Result<unknown, unknown> = r
  * @see {@link isSuccess} for the opposite check
  * @see {@link isResult} to check if a value is any Result
  *
- * @category Type Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E> = result.isFailure
@@ -811,7 +813,7 @@ export const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E> = re
  * @see {@link isFailure} for the opposite check
  * @see {@link isResult} to check if a value is any Result
  *
- * @category Type Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E> = result.isSuccess
@@ -821,7 +823,8 @@ export const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E> = re
  *
  * **When to use**
  *
- * Use to extract only the success value and discard failure information.
+ * Use when you need to extract the success value from a `Result` as an
+ * `Option` and discard failure information.
  *
  * **Details**
  *
@@ -853,7 +856,8 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
  *
  * **When to use**
  *
- * Use to extract only the failure value and discard successful values.
+ * Use when you need to extract the failure value from a `Result` as an
+ * `Option` and discard successful values.
  *
  * **Details**
  *
@@ -906,7 +910,7 @@ export const getFailure: <A, E>(self: Result<A, E>) => Option<E> = result.getFai
  * // Output: false
  * ```
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = <A, E>(
@@ -1265,12 +1269,16 @@ export const map: {
 /**
  * Folds a `Result` into a single value by applying one of two functions.
  *
+ * **When to use**
+ *
+ * Use when a `Result`'s success and failure branches should be collapsed into
+ * one plain output type.
+ *
  * **Details**
  *
  * - Applies `onSuccess` if the result is a `Success`
  * - Applies `onFailure` if the result is a `Failure`
  * - Both branches must return the same type (or a common supertype)
- * - Use when you need to "exit" the `Result` type and produce a plain value
  *
  * **Example** (Folding to a string)
  *
@@ -1292,19 +1300,23 @@ export const map: {
  * @see {@link merge} to extract `A | E` without mapping
  * @see {@link getOrElse} to unwrap only the success with a fallback
  *
- * @category Pattern Matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export const match: {
   /**
    * Folds a `Result` into a single value by applying one of two functions.
    *
+   * **When to use**
+   *
+   * Use when a `Result`'s success and failure branches should be collapsed into
+   * one plain output type.
+   *
    * **Details**
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
    * - Both branches must return the same type (or a common supertype)
-   * - Use when you need to "exit" the `Result` type and produce a plain value
    *
    * **Example** (Folding to a string)
    *
@@ -1326,7 +1338,7 @@ export const match: {
    * @see {@link merge} to extract `A | E` without mapping
    * @see {@link getOrElse} to unwrap only the success with a fallback
    *
-   * @category Pattern Matching
+   * @category pattern matching
    * @since 2.0.0
    */
   <E, B, A, C = B>(
@@ -1338,12 +1350,16 @@ export const match: {
   /**
    * Folds a `Result` into a single value by applying one of two functions.
    *
+   * **When to use**
+   *
+   * Use when a `Result`'s success and failure branches should be collapsed into
+   * one plain output type.
+   *
    * **Details**
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
    * - Both branches must return the same type (or a common supertype)
-   * - Use when you need to "exit" the `Result` type and produce a plain value
    *
    * **Example** (Folding to a string)
    *
@@ -1365,7 +1381,7 @@ export const match: {
    * @see {@link merge} to extract `A | E` without mapping
    * @see {@link getOrElse} to unwrap only the success with a fallback
    *
-   * @category Pattern Matching
+   * @category pattern matching
    * @since 2.0.0
    */
   <A, E, B, C = B>(
@@ -1938,7 +1954,8 @@ export const getOrElse: {
  *
  * **When to use**
  *
- * Use with APIs that represent absence as `null`.
+ * Use when you need to pass failed `Result` values to APIs that represent
+ * absence as `null`.
  *
  * **Details**
  *
@@ -1970,7 +1987,8 @@ export const getOrNull: <A, E>(self: Result<A, E>) => A | null = getOrElse(const
  *
  * **When to use**
  *
- * Use with APIs that represent absence as `undefined`.
+ * Use when you need to pass failed `Result` values to APIs that represent
+ * absence as `undefined`.
  *
  * **Details**
  *
@@ -2152,11 +2170,15 @@ export const getOrThrow: <A, E>(self: Result<A, E>) => A = getOrThrowWith(identi
  * Returns the original `Result` if it is a `Success`, otherwise applies
  * `that` to the error and returns the resulting `Result`.
  *
+ * **When to use**
+ *
+ * Use when a failure should recover into another `Result` while keeping
+ * successes unchanged.
+ *
  * **Details**
  *
  * - `Success<A>` is returned unchanged
  * - `Failure<E>` calls `that(e)` to produce a new `Result`
- * - Use to provide a recovery path or fallback computation on failure
  *
  * **Example** (Recovering from a failure)
  *
@@ -2182,11 +2204,15 @@ export const orElse: {
    * Returns the original `Result` if it is a `Success`, otherwise applies
    * `that` to the error and returns the resulting `Result`.
    *
+   * **When to use**
+   *
+   * Use when a failure should recover into another `Result` while keeping
+   * successes unchanged.
+   *
    * **Details**
    *
    * - `Success<A>` is returned unchanged
    * - `Failure<E>` calls `that(e)` to produce a new `Result`
-   * - Use to provide a recovery path or fallback computation on failure
    *
    * **Example** (Recovering from a failure)
    *
@@ -2212,11 +2238,15 @@ export const orElse: {
    * Returns the original `Result` if it is a `Success`, otherwise applies
    * `that` to the error and returns the resulting `Result`.
    *
+   * **When to use**
+   *
+   * Use when a failure should recover into another `Result` while keeping
+   * successes unchanged.
+   *
    * **Details**
    *
    * - `Success<A>` is returned unchanged
    * - `Failure<E>` calls `that(e)` to produce a new `Result`
-   * - Use to provide a recovery path or fallback computation on failure
    *
    * **Example** (Recovering from a failure)
    *
@@ -2909,7 +2939,7 @@ export const all: <const I extends Iterable<Result<any, any>> | Record<string, R
  *
  * @see {@link mapError} to transform the error without swapping
  *
- * @category utils
+ * @category transforming
  * @since 2.0.0
  */
 export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
@@ -2920,8 +2950,8 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
  *
  * **When to use**
  *
- * Use when sequential `Result` composition is clearer with generator syntax
- * than nested `flatMap` calls.
+ * Use when you need generator syntax to compose sequential `Result`
+ * computations instead of nested `flatMap` calls.
  *
  * **Details**
  *
@@ -2948,7 +2978,7 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
  * @see {@link flatMap} for point-free sequential composition
  * @see {@link all} to collect multiple independent Results
  *
- * @category Generators
+ * @category generators
  * @since 2.0.0
  */
 export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
@@ -3004,7 +3034,7 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
  * @see {@link gen} for an alternative generator-based syntax
  * @see {@link bindTo} for starting a do-notation chain from an existing Result
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const Do: Result<{}> = succeed({})
@@ -3015,8 +3045,9 @@ export const Do: Result<{}> = succeed({})
  *
  * **When to use**
  *
- * Use when adding a `Result`-producing step to a do-notation pipeline and
- * storing its successful value under a named field in the accumulated object.
+ * Use when you need to add a `Result`-producing step to a `Result`
+ * do-notation pipeline and store its successful value under a named field in
+ * the accumulated object.
  *
  * **Details**
  *
@@ -3042,7 +3073,7 @@ export const Do: Result<{}> = succeed({})
  * @see {@link let_ let} for pure computed fields
  * @see {@link bindTo} to wrap an initial Result into a named field
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bind: {
@@ -3052,8 +3083,9 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when adding a `Result`-producing step to a do-notation pipeline and
-   * storing its successful value under a named field in the accumulated object.
+   * Use when you need to add a `Result`-producing step to a `Result`
+   * do-notation pipeline and store its successful value under a named field in
+   * the accumulated object.
    *
    * **Details**
    *
@@ -3079,7 +3111,7 @@ export const bind: {
    * @see {@link let_ let} for pure computed fields
    * @see {@link bindTo} to wrap an initial Result into a named field
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <N extends string, A extends object, B, L2>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Result<B, L2>): <L1>(self: Result<A, L1>) => Result<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }, L1 | L2>
@@ -3089,8 +3121,9 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when adding a `Result`-producing step to a do-notation pipeline and
-   * storing its successful value under a named field in the accumulated object.
+   * Use when you need to add a `Result`-producing step to a `Result`
+   * do-notation pipeline and store its successful value under a named field in
+   * the accumulated object.
    *
    * **Details**
    *
@@ -3116,7 +3149,7 @@ export const bind: {
    * @see {@link let_ let} for pure computed fields
    * @see {@link bindTo} to wrap an initial Result into a named field
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <A extends object, L1, N extends string, B, L2>(
@@ -3156,7 +3189,7 @@ export const bind: {
  * @see {@link Do} to start from an empty object
  * @see {@link bind} to add more fields
  *
- * @category Do Notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bindTo: {
@@ -3190,7 +3223,7 @@ export const bindTo: {
    * @see {@link Do} to start from an empty object
    * @see {@link bind} to add more fields
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <N extends string>(name: N): <R, L>(self: Result<R, L>) => Result<Record<N, R>, L>
@@ -3224,7 +3257,7 @@ export const bindTo: {
    * @see {@link Do} to start from an empty object
    * @see {@link bind} to add more fields
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   <R, L, N extends string>(self: Result<R, L>, name: N): Result<Record<N, R>, L>
@@ -3249,7 +3282,8 @@ export {
    *
    * **When to use**
    *
-   * Use to add a pure computed field to a do-notation accumulator.
+   * Use when you need to add a derived field that cannot fail inside a
+   * do-notation pipeline.
    *
    * **Details**
    *
@@ -3274,7 +3308,7 @@ export {
    * @see {@link Do} to start the do-notation chain
    * @see {@link bind} for Result-producing fields
    *
-   * @category Do Notation
+   * @category do notation
    * @since 2.0.0
    */
   let_ as let
@@ -3283,6 +3317,11 @@ export {
 /**
  * Transforms `Option<Result<A, E>>` into `Result<Option<A>, E>`.
  *
+ * **When to use**
+ *
+ * Use when optional absence should be treated as a successful `None`, while an
+ * inner `Result` failure should still fail the whole result.
+ *
  * **Details**
  *
  * - `None` becomes `Success(None)`
@@ -3318,6 +3357,11 @@ export const transposeOption = <A = never, E = never>(
  * Maps an `Option` value with a `Result`-producing function, then transposes
  * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
  *
+ * **When to use**
+ *
+ * Use when an optional value should be validated only when present, preserving
+ * absence as a successful `None`.
+ *
  * **Details**
  *
  * - `None` becomes `Success(None)` (the function is never called)
@@ -3351,6 +3395,11 @@ export const transposeMapOption = dual<
    * Maps an `Option` value with a `Result`-producing function, then transposes
    * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
    *
+   * **When to use**
+   *
+   * Use when an optional value should be validated only when present, preserving
+   * absence as a successful `None`.
+   *
    * **Details**
    *
    * - `None` becomes `Success(None)` (the function is never called)
@@ -3384,6 +3433,11 @@ export const transposeMapOption = dual<
    * Maps an `Option` value with a `Result`-producing function, then transposes
    * the structure from `Option<Result<B, E>>` to `Result<Option<B>, E>`.
    *
+   * **When to use**
+   *
+   * Use when an optional value should be validated only when present, preserving
+   * absence as a successful `None`.
+   *
    * **Details**
    *
    * - `None` becomes `Success(None)` (the function is never called)

package/src/Runtime.ts

@@ -118,8 +118,8 @@ export interface Teardown {
  *
  * **When to use**
  *
- * Use as the standard teardown for main programs when you want conventional
- * process exit codes and support for {@link errorExitCode}.
+ * Use as the standard teardown for main programs with conventional process
+ * exit codes and support for {@link errorExitCode}.
  *
  * **Details**
  *
@@ -176,13 +176,16 @@ export const defaultTeardown: Teardown = <E, A>(
  *
  * **When to use**
  *
- * Use when building a runtime adapter for a host platform. Most applications
- * should use a platform-provided runner, such as `NodeRuntime.runMain`, rather
- * than constructing one directly.
+ * Use when building a runtime adapter for a host platform.
  *
  * **Details**
  *
- * The runner executes Effect programs as main entry points. The provided function receives a forked fiber and a teardown callback so it can install platform-specific signal handling, fiber observers, and final exit behavior.
+ * The runner executes Effect programs as main entry points. The provided
+ * function receives a forked fiber and a teardown callback so it can install
+ * platform-specific signal handling, fiber observers, and final exit behavior.
+ *
+ * Most applications should use a platform-provided runner, such as
+ * `NodeRuntime.runMain`, rather than constructing one directly.
  *
  * `disableErrorReporting` disables the automatic log emitted for unreported
  * non-interruption failures. It does not change exit-code calculation or the
@@ -403,8 +406,8 @@ export type errorReported = "~effect/Runtime/errorReported"
  *
  * **When to use**
  *
- * Use when error classes are already reported by application code and should
- * not be logged again by the default main runner.
+ * Use when you need error classes reported by application code to avoid being
+ * logged again by the default main runner.
  *
  * **Details**
  *