effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/Result.ts

@@ -316,7 +316,6 @@ export declare namespace Result {
  *
  * - Use when you have a value and want to lift it into the `Result` type
  * - The error type `E` defaults to `never`
- * - Does not mutate input; allocates a new `Success` wrapper
  *
  * **Example** (Wrapping a value)
  *
@@ -347,7 +346,6 @@ export const succeed: <A>(right: A) => Result<A> = result.succeed
  * **Details**
  *
  * - The success type `A` defaults to `never`
- * - Does not mutate input; allocates a new `Failure` wrapper
  *
  * **Example** (Creating a failure)
  *
@@ -371,12 +369,17 @@ export const fail: <E>(left: E) => Result<never, E> = result.fail
 const void_: Result<void> = succeed(void 0)
 export {
   /**
-   * A pre-built `Result<void>` holding `undefined` as its success value.
+   * Provides a pre-built successful `Result` that carries `undefined`.
+   *
+   * **When to use**
+   *
+   * Use when a success should signal completion without carrying a meaningful
+   * value.
    *
    * **Details**
    *
-   * - Use when you need a `Result` that represents "completed with no meaningful value"
-   * - Equivalent to `Result.succeed(undefined)` but avoids an extra allocation
+   * This is equivalent to `Result.succeed(undefined)`, but reuses a shared
+   * `Success` wrapper instead of allocating one each time.
    *
    * **Example** (Using void result)
    *
@@ -389,7 +392,7 @@ export {
    * // Output: true
    * ```
    *
-   * @see {@link succeed}
+   * @see {@link succeed} to create a Success with a specific value
    *
    * @category constructors
    * @since 3.13.0
@@ -398,14 +401,31 @@ export {
 }
 
 /**
- * A pre-built failed `Result` whose failure value is `undefined`.
+ * Provides a pre-built failed `Result` whose failure value is `undefined`.
+ *
+ * **When to use**
+ *
+ * Use when a failure should act only as a control signal and no failure value
+ * is needed.
  *
  * **Details**
  *
  * This is equivalent to `Result.fail(undefined)` with type
- * `Result<never, void>`, but avoids allocating a new `Failure` wrapper.
+ * `Result<never, void>`, but reuses a shared `Failure` wrapper instead of
+ * allocating one each time.
+ *
+ * **Example** (Using a failure without a payload)
+ *
+ * ```ts
+ * import { Result } from "effect"
+ *
+ * const result = Result.failVoid
+ *
+ * console.log(Result.isFailure(result))
+ * // Output: true
+ * ```
  *
- * @see {@link fail}
+ * @see {@link fail} to create a Failure with a specific value
  *
  * @category constructors
  * @since 4.0.0
@@ -664,7 +684,7 @@ const try_: {
 
 export {
   /**
-   * Wraps a synchronous computation that may throw into a `Result`.
+   * Wraps a synchronous computation that may throw into a `Result` safely.
    *
    * **Details**
    *
@@ -700,7 +720,7 @@ export {
 }
 
 /**
- * Tests whether a value is a `Result` (either `Success` or `Failure`).
+ * Checks whether a value is a `Result` (either `Success` or `Failure`).
  *
  * **When to use**
  *
@@ -911,7 +931,6 @@ export const makeEquivalence = <A, E>(
  *
  * - Applies `onSuccess` if the result is a `Success`
  * - Applies `onFailure` if the result is a `Failure`
- * - Returns a new `Result`; does not mutate the input
  *
  * **Example** (Mapping both channels)
  *
@@ -949,7 +968,6 @@ export const mapBoth: {
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
-   * - Returns a new `Result`; does not mutate the input
    *
    * **Example** (Mapping both channels)
    *
@@ -992,7 +1010,6 @@ export const mapBoth: {
    *
    * - Applies `onSuccess` if the result is a `Success`
    * - Applies `onFailure` if the result is a `Failure`
-   * - Returns a new `Result`; does not mutate the input
    *
    * **Example** (Mapping both channels)
    *
@@ -1043,7 +1060,6 @@ export const mapBoth: {
  *
  * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
  * - If the result is a `Success`, returns it as-is
- * - Does not mutate the input
  *
  * **Example** (Adding context to an error)
  *
@@ -1076,7 +1092,6 @@ export const mapError: {
    *
    * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
    * - If the result is a `Success`, returns it as-is
-   * - Does not mutate the input
    *
    * **Example** (Adding context to an error)
    *
@@ -1109,7 +1124,6 @@ export const mapError: {
    *
    * - If the result is a `Failure`, applies `f` to the error and returns a new `Failure`
    * - If the result is a `Success`, returns it as-is
-   * - Does not mutate the input
    *
    * **Example** (Adding context to an error)
    *
@@ -1149,7 +1163,6 @@ export const mapError: {
  *
  * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
  * - If the result is a `Failure`, returns it as-is
- * - Does not mutate the input
  * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
  *
  * **Example** (Doubling the success value)
@@ -1185,7 +1198,6 @@ export const map: {
    *
    * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
    * - If the result is a `Failure`, returns it as-is
-   * - Does not mutate the input
    * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
    *
    * **Example** (Doubling the success value)
@@ -1221,7 +1233,6 @@ export const map: {
    *
    * - If the result is a `Success`, applies `f` to the value and returns a new `Success`
    * - If the result is a `Failure`, returns it as-is
-   * - Does not mutate the input
    * - Use {@link flatMap} if `f` returns a `Result` (to avoid nested Results)
    *
    * **Example** (Doubling the success value)
@@ -2351,7 +2362,7 @@ export const flatMap: {
 )
 
 /**
- * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+ * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
  *
  * **When to use**
  *
@@ -2399,7 +2410,7 @@ export const flatMap: {
  */
 export const andThen: {
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2447,7 +2458,7 @@ export const andThen: {
    */
   <A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2495,7 +2506,7 @@ export const andThen: {
    */
   <A2, E2>(f: Result<A2, E2>): <A, E>(self: Result<A, E>) => Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2543,7 +2554,7 @@ export const andThen: {
    */
   <A, A2>(f: (a: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2591,7 +2602,7 @@ export const andThen: {
    */
   <A2>(right: NotFunction<A2>): <A, E>(self: Result<A, E>) => Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2639,7 +2650,7 @@ export const andThen: {
    */
   <A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2687,7 +2698,7 @@ export const andThen: {
    */
   <A, E, A2, E2>(self: Result<A, E>, f: Result<A2, E2>): Result<A2, E | E2>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2735,7 +2746,7 @@ export const andThen: {
    */
   <A, E, A2>(self: Result<A, E>, f: (a: A) => A2): Result<A2, E>
   /**
-   * A flexible variant of {@link flatMap} that accepts multiple input shapes.
+   * Provides a flexible variant of {@link flatMap} that accepts multiple input shapes.
    *
    * **When to use**
    *
@@ -2905,7 +2916,7 @@ export const flip = <A, E>(self: Result<A, E>): Result<E, A> =>
   isFailure(self) ? succeed(self.failure) : fail(self.success)
 
 /**
- * Generator-based syntax for composing `Result` values sequentially.
+ * Provides generator-based syntax for composing `Result` values sequentially.
  *
  * **When to use**
  *
@@ -2959,7 +2970,7 @@ export const gen: Gen.Gen<ResultTypeLambda> = (...args) => {
 // -------------------------------------------------------------------------------------
 
 /**
- * Starting point for the "do notation" simulation with `Result`.
+ * Provides the starting point for the "do notation" simulation with `Result`.
  *
  * **When to use**
  *
@@ -3405,12 +3416,17 @@ export const transposeMapOption = dual<
 >(2, (self, f) => option_.isNone(self) ? succeedNone : map(f(self.value), option_.some))
 
 /**
- * A pre-built `Result<Option<never>>` that succeeds with `None`.
+ * Provides a pre-built `Result<Option<never>>` that succeeds with `None`.
+ *
+ * **When to use**
+ *
+ * Use when an optional success should be absent, such as the `None` branch of
+ * `transposeOption` or `transposeMapOption`.
  *
  * **Details**
  *
- * - Equivalent to `Result.succeed(Option.none())` but avoids an extra allocation
- * - Useful with {@link transposeOption} patterns
+ * This is equivalent to `Result.succeed(Option.none())`, but reuses a shared
+ * `Success` wrapper instead of allocating one each time.
  *
  * **Example** (Using succeedNone)
  *
@@ -3422,6 +3438,8 @@ export const transposeMapOption = dual<
  * ```
  *
  * @see {@link succeedSome} for the `Some` counterpart
+ * @see {@link transposeOption} to transpose an Option that already contains a Result
+ * @see {@link transposeMapOption} to map and transpose an Option in one step
  *
  * @category constructors
  * @since 4.0.0

package/src/Runtime.ts

@@ -399,7 +399,7 @@ export const getErrorExitCode = (u: unknown): number => {
 export type errorReported = "~effect/Runtime/errorReported"
 
 /**
- * Runtime marker that controls default `runMain` error logging for an error.
+ * Defines the runtime marker that controls default `runMain` error logging for an error.
  *
  * **When to use**
  *

package/src/Schedule.ts

@@ -885,9 +885,8 @@ export const addDelay: {
   ))
 
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * merges their outputs.
  *
  * **Example** (Sequencing quick and slow retries)
  *
@@ -927,9 +926,8 @@ export const addDelay: {
  */
 export const andThen: {
   /**
-   * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-   * schedule to completion. Once the left schedule is complete, the right (i.e.
-   * `other`) schedule will be executed to completion.
+   * Returns a schedule that runs `self` to completion, then runs `other`, and
+   * merges their outputs.
    *
    * **Example** (Sequencing quick and slow retries)
    *
@@ -971,9 +969,8 @@ export const andThen: {
     self: Schedule<Output, Input, Error, Env>
   ) => Schedule<Output | Output2, Input & Input2, Error | Error2, Env | Env2>
   /**
-   * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-   * schedule to completion. Once the left schedule is complete, the right (i.e.
-   * `other`) schedule will be executed to completion.
+   * Returns a schedule that runs `self` to completion, then runs `other`, and
+   * merges their outputs.
    *
    * **Example** (Sequencing quick and slow retries)
    *
@@ -1022,9 +1019,8 @@ export const andThen: {
   map(andThenResult(self, other), (result) => effect.succeed(Result.merge(result))))
 
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * preserves which schedule produced each output.
  *
  * **Details**
  *
@@ -1066,9 +1062,8 @@ export const andThen: {
  */
 export const andThenResult: {
   /**
-   * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-   * schedule to completion. Once the left schedule is complete, the right (i.e.
-   * `other`) schedule will be executed to completion.
+   * Returns a schedule that runs `self` to completion, then runs `other`, and
+   * preserves which schedule produced each output.
    *
    * **Details**
    *
@@ -1112,9 +1107,8 @@ export const andThenResult: {
     self: Schedule<Output, Input, Error, Env>
   ) => Schedule<Result.Result<Output2, Output>, Input & Input2, Error | Error2, Env | Env2>
   /**
-   * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-   * schedule to completion. Once the left schedule is complete, the right (i.e.
-   * `other`) schedule will be executed to completion.
+   * Returns a schedule that runs `self` to completion, then runs `other`, and
+   * preserves which schedule produced each output.
    *
    * **Details**
    *
@@ -1186,9 +1180,8 @@ export const andThenResult: {
       if (currentStep) return currentStep(now, input)
       return toStep<
         /**
-         * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-         * schedule to completion. Once the left schedule is complete, the right (i.e.
-         * `other`) schedule will be executed to completion.
+         * Returns a schedule that runs `self` to completion, then runs `other`, and
+         * preserves which schedule produced each output.
          *
          * **Details**
          *
@@ -1230,9 +1223,8 @@ export const andThenResult: {
          */
         Result.Result<Output, Output2>,
         /**
-         * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-         * schedule to completion. Once the left schedule is complete, the right (i.e.
-         * `other`) schedule will be executed to completion.
+         * Returns a schedule that runs `self` to completion, then runs `other`, and
+         * preserves which schedule produced each output.
          *
          * **Details**
          *
@@ -1274,9 +1266,8 @@ export const andThenResult: {
          */
         Input & Input2,
         /**
-         * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-         * schedule to completion. Once the left schedule is complete, the right (i.e.
-         * `other`) schedule will be executed to completion.
+         * Returns a schedule that runs `self` to completion, then runs `other`, and
+         * preserves which schedule produced each output.
          *
          * **Details**
          *
@@ -1318,9 +1309,8 @@ export const andThenResult: {
          */
         Error | Error2,
         /**
-         * Returns a new `Schedule` that will first execute the left (i.e. `self`)
-         * schedule to completion. Once the left schedule is complete, the right (i.e.
-         * `other`) schedule will be executed to completion.
+         * Returns a schedule that runs `self` to completion, then runs `other`, and
+         * preserves which schedule produced each output.
          *
          * **Details**
          *
@@ -3694,7 +3684,8 @@ export const eitherWith: {
   )))
 
 /**
- * A schedule that always recurs and returns the total elapsed duration since the first recurrence.
+ * Schedule that always recurs and returns the total elapsed duration since the
+ * first recurrence.
  *
  * **Details**
  *
@@ -3728,7 +3719,7 @@ export const elapsed: Schedule<Duration.Duration> = fromStepWithMetadata(
 )
 
 /**
- * A schedule that always recurs, but will wait a certain amount between
+ * Schedule that always recurs, but will wait a certain amount between
  * repetitions, given by `base * factor.pow(n)`, where `n` is the number of
  * repetitions so far. Returns the current duration between recurrences.
  *
@@ -3788,7 +3779,7 @@ export const exponential = (
 }
 
 /**
- * A schedule that always recurs, increasing delays by summing the preceding
+ * Schedule that always recurs, increasing delays by summing the preceding
  * two delays (similar to the Fibonacci sequence). Returns the current
  * duration between recurrences.
  *
@@ -4378,8 +4369,9 @@ export const passthrough = <Output, Input, Error, Env>(
  *
  * **When to use**
  *
- * Use when you use `recurs` for a counter schedule with no additional delay. Use `take` to
- * limit an existing schedule while preserving its output and delay behavior.
+ * Use when you need a counter schedule with no additional delay. Use `take`
+ * to limit an existing schedule while preserving its output and delay
+ * behavior.
  *
  * **Gotchas**
  *
@@ -6139,7 +6131,7 @@ export {
 }
 
 /**
- * A schedule that divides the timeline to `interval`-long windows, and sleeps
+ * Schedule that divides the timeline to `interval`-long windows, and sleeps
  * until the nearest window boundary every time it recurs.
  *
  * **Details**

package/src/Scheduler.ts

@@ -130,7 +130,7 @@ class PriorityBuckets {
 }
 
 /**
- * A scheduler implementation that batches queued tasks and dispatches them by
+ * Provides a scheduler implementation that batches queued tasks and dispatches them by
  * priority.
  *
  * **When to use**
@@ -245,7 +245,7 @@ class MixedSchedulerDispatcher implements SchedulerDispatcher {
 }
 
 /**
- * A service reference that controls the maximum number of operations a fiber
+ * Context reference that controls the maximum number of operations a fiber
  * can perform before yielding control back to the scheduler.
  *
  * **When to use**
@@ -269,7 +269,7 @@ export const MaxOpsBeforeYield = Context.Reference<number>("effect/Scheduler/Max
 })
 
 /**
- * A service reference that controls whether the runtime should bypass scheduler
+ * Context reference that controls whether the runtime should bypass scheduler
  * yield checks. When set to `true`, the fiber run loop won't call
  * `Scheduler.shouldYield`.
  *