effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Fiber.ts

@@ -1,73 +1,54 @@
 /**
- * This module provides utilities for working with `Fiber`, the fundamental unit of
- * concurrency in Effect. Fibers are lightweight, user-space threads that allow
- * multiple Effects to run concurrently with structured concurrency guarantees.
- *
- * Key characteristics of Fibers:
- * - **Lightweight**: Much lighter than OS threads, you can create millions
- * - **Structured concurrency**: Parent fibers manage child fiber lifecycles
- * - **Cancellation safety**: Proper resource cleanup when interrupted
- * - **Cooperative**: Fibers yield control at effect boundaries
- * - **Traceable**: Each fiber has an ID for debugging and monitoring
- *
- * Common patterns:
- * - **Fork and join**: Start concurrent work and wait for results
- * - **Race conditions**: Run multiple effects, take the first to complete
- * - **Supervision**: Monitor and restart failed fibers
- * - **Resource management**: Ensure proper cleanup on interruption
- *
- * **Example** (Running effects in fibers)
+ * The `Fiber` module provides operations for handles returned by forking
+ * effects. A `Fiber<A, E>` is a lightweight runtime execution of an `Effect`
+ * that may still be running, may already have completed, and can be observed or
+ * interrupted by other fibers.
+ *
+ * Applications create fibers with operations such as `Effect.forkChild`,
+ * `Effect.forkScoped`, `Effect.forkIn`, or `Effect.forkDetach`, then use this
+ * module to wait for results, inspect exits, or cancel work that is no longer
+ * needed.
+ *
+ * **Mental model**
+ *
+ * - A fiber is a handle to a running or completed effect, not the effect itself
+ * - {@link await_ await} observes completion as an `Exit` without failing the current
+ *   effect
+ * - {@link join} waits for success and propagates the fiber's failure into the
+ *   current effect
+ * - {@link interrupt} requests cancellation and waits until the target fiber
+ *   finishes running finalizers
+ * - Group operations such as {@link awaitAll}, {@link joinAll}, and
+ *   {@link interruptAll} apply the same ideas to collections of fibers
+ *
+ * **Common tasks**
+ *
+ * - Wait for one fiber with {@link await_ await} or {@link join}
+ * - Wait for many fibers with {@link awaitAll} or {@link joinAll}
+ * - Stop work with {@link interrupt}, {@link interruptAs},
+ *   {@link interruptAll}, or {@link interruptAllAs}
+ * - Recognize fiber handles with {@link isFiber}
+ * - Link a manually managed fiber to a `Scope` with {@link runIn}
+ *
+ * **Gotchas**
+ *
+ * - `await` gives you an `Exit`; use `join` when the current effect should fail
+ *   if the fiber failed
+ * - Interruption is cooperative, so a fiber can continue through
+ *   uninterruptible regions and finalizers before it finishes
+ * - `joinAll` stops waiting on the first failure, but it does not interrupt the
+ *   remaining fibers for you
+ *
+ * **Example** (Joining a forked effect)
  *
  * ```ts
- * import { Console, Effect, Fiber } from "effect"
- *
- * // Basic fiber operations
- * const basicExample = Effect.gen(function*() {
- *   // Fork an effect to run concurrently
- *   const fiber = yield* Effect.forkChild(
- *     Effect.gen(function*() {
- *       yield* Effect.sleep("2 seconds")
- *       yield* Console.log("Background task completed")
- *       return "background result"
- *     })
- *   )
- *
- *   // Do other work while the fiber runs
- *   yield* Console.log("Doing other work...")
- *   yield* Effect.sleep("1 second")
- *
- *   // Wait for the fiber to complete
- *   const result = yield* Fiber.join(fiber)
- *   yield* Console.log(`Fiber result: ${result}`)
- * })
- *
- * // Joining multiple fibers
- * const joinExample = Effect.gen(function*() {
- *   const task1 = Effect.delay(Effect.succeed("task1"), "1 second")
- *   const task2 = Effect.delay(Effect.succeed("task2"), "2 seconds")
- *
- *   // Start both effects as fibers
- *   const fiber1 = yield* Effect.forkChild(task1)
- *   const fiber2 = yield* Effect.forkChild(task2)
- *
- *   // Wait for both to complete
- *   const result1 = yield* Fiber.join(fiber1)
- *   const result2 = yield* Fiber.join(fiber2)
- *   return [result1, result2] // ["task1", "task2"]
- * })
+ * import { Effect, Fiber } from "effect"
  *
- * // Parallel execution with structured concurrency
- * const parallelExample = Effect.gen(function*() {
- *   const tasks = [1, 2, 3, 4, 5].map((n) =>
- *     Effect.gen(function*() {
- *       yield* Effect.sleep(`${n * 100} millis`)
- *       return n * n
- *     })
- *   )
+ * const program = Effect.gen(function*() {
+ *   const fiber = yield* Effect.forkChild(Effect.succeed(42))
+ *   const value = yield* Fiber.join(fiber)
  *
- *   // Run all tasks in parallel, wait for all to complete
- *   const results = yield* Effect.all(tasks, { concurrency: "unbounded" })
- *   return results // [1, 4, 9, 16, 25]
+ *   return value
  * })
  * ```
  *
@@ -96,6 +77,23 @@ const TypeId = `~effect/Fiber/${version}`
  * Effects concurrently while maintaining structured concurrency and
  * cancellation safety.
  *
+ * **When to use**
+ *
+ * Use to observe, join, interrupt, or coordinate work that has already been
+ * forked.
+ *
+ * **Details**
+ *
+ * A fiber exposes both safe Effect-based operations, such as {@link await_ await},
+ * {@link join}, and {@link interrupt}, and low-level runtime fields used by
+ * the scheduler and runtime internals.
+ *
+ * **Gotchas**
+ *
+ * Prefer the exported functions in this module over calling `interruptUnsafe`
+ * or `pollUnsafe` directly. The unsafe methods are immediate runtime hooks and
+ * do not provide the same Effect-based sequencing guarantees.
+ *
  * **Example** (Awaiting a forked fiber)
  *
  * ```ts
@@ -144,6 +142,15 @@ export interface Fiber<out A, out E = never> extends Pipeable {
  * The Fiber namespace contains utility types and functions for working with fibers.
  * It provides type-level utilities for fiber operations and variance encoding.
  *
+ * **When to use**
+ *
+ * Use to reference type-level helpers associated with `Fiber`.
+ *
+ * **Details**
+ *
+ * The namespace currently exposes type-level support used by the `Fiber`
+ * interface. Runtime operations are exported as module-level functions.
+ *
  * **Example** (Working with fiber types)
  *
  * ```ts
@@ -172,6 +179,11 @@ export declare namespace Fiber {
    * Variance encoding for the Fiber type, specifying covariance in both the
    * success type `A` and the error type `E`.
    *
+   * **When to use**
+   *
+   * Use to carry the success and error type parameters for `Fiber` in Effect's
+   * type machinery.
+   *
    * **Example** (Upcasting fibers safely)
    *
    * ```ts
@@ -196,6 +208,21 @@ export {
   /**
    * Waits for a fiber to complete and returns its exit value.
    *
+   * **When to use**
+   *
+   * Use when you need to inspect whether the fiber succeeded,
+   * failed, died, or was interrupted without propagating the failure.
+   *
+   * **Details**
+   *
+   * The returned Effect always succeeds with an `Exit` describing the fiber's
+   * outcome.
+   *
+   * **Gotchas**
+   *
+   * This does not flatten the fiber result into the current Effect. Use
+   * {@link join} when you want fiber failures to fail the current Effect.
+   *
    * **Example** (Awaiting a fiber exit)
    *
    * ```ts
@@ -217,6 +244,20 @@ export {
  * Waits for all fibers in the provided iterable to complete and returns
  * an array of their exit values.
  *
+ * **When to use**
+ *
+ * Use when you need every fiber outcome as data, including failures and
+ * interruptions.
+ *
+ * **Details**
+ *
+ * The returned array is ordered like the input iterable.
+ *
+ * **Gotchas**
+ *
+ * Failures are captured as `Exit.Failure` values. Use {@link joinAll} when you
+ * want the first failed fiber to fail the returned Effect.
+ *
  * **Example** (Awaiting multiple fiber exits)
  *
  * ```ts
@@ -248,6 +289,16 @@ export const awaitAll: <A extends Fiber<any, any>>(
  * Joins a fiber, blocking until it completes. If the fiber succeeds,
  * returns its value. If it fails, the error is propagated.
  *
+ * **When to use**
+ *
+ * Use when the forked fiber is part of the current workflow and
+ * its failure should fail the current Effect.
+ *
+ * **Gotchas**
+ *
+ * Joining a failed fiber propagates the fiber's Cause. Use {@link await_ await} when
+ * you need to inspect the `Exit` instead of failing.
+ *
  * **Example** (Joining a fiber)
  *
  * ```ts
@@ -260,6 +311,8 @@ export const awaitAll: <A extends Fiber<any, any>>(
  * })
  * ```
  *
+ * @see {@link await_ await} for inspecting the fiber outcome as an Exit
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -268,12 +321,24 @@ export const join: <A, E>(self: Fiber<A, E>) => Effect<A, E> = effect.fiberJoin
 /**
  * Waits for all fibers to succeed and returns their values in input order.
  *
+ * **When to use**
+ *
+ * Use when every fiber must succeed and you want the successful values rather
+ * than the `Exit` values.
+ *
  * **Details**
  *
  * If any fiber fails, the returned `Effect` fails with that fiber's cause and
  * stops waiting for additional results. This does not interrupt the remaining
  * fibers.
  *
+ * **Gotchas**
+ *
+ * A failure stops waiting, but it does not interrupt any other fibers. Use
+ * {@link interruptAll} separately when remaining fibers should be stopped.
+ *
+ * @see {@link awaitAll} for collecting every fiber outcome as an Exit
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -291,6 +356,19 @@ export const joinAll: <A extends Iterable<Fiber<any, any>>>(
  * Interrupts a fiber, causing it to stop executing and clean up any
  * acquired resources.
  *
+ * **When to use**
+ *
+ * Use when a forked fiber is no longer needed and should be cancelled.
+ *
+ * **Details**
+ *
+ * The returned Effect completes only after the interrupted fiber has completed.
+ *
+ * **Gotchas**
+ *
+ * Interruption is cooperative. A fiber can continue running while it is inside
+ * uninterruptible work or finalizers.
+ *
  * **Example** (Interrupting a fiber)
  *
  * ```ts
@@ -305,6 +383,9 @@ export const joinAll: <A extends Iterable<Fiber<any, any>>>(
  * })
  * ```
  *
+ * @see {@link interruptAs} for specifying the interrupting fiber ID
+ * @see {@link await_ await} for observing the interrupted fiber's Exit
+ *
  * @category interruption
  * @since 2.0.0
  */
@@ -314,6 +395,20 @@ export const interrupt: <A, E>(self: Fiber<A, E>) => Effect<void> = effect.fiber
  * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
  * tracking which fiber initiated the interruption.
  *
+ * **When to use**
+ *
+ * Use when runtime diagnostics or tracing should attribute the interruption to
+ * a specific fiber ID.
+ *
+ * **Details**
+ *
+ * The returned Effect completes only after the interrupted fiber has completed.
+ *
+ * **Gotchas**
+ *
+ * The supplied ID affects the recorded interruptor. It does not make
+ * interruption synchronous or force uninterruptible regions to stop early.
+ *
  * **Example** (Interrupting a fiber as another fiber)
  *
  * ```ts
@@ -330,6 +425,8 @@ export const interrupt: <A, E>(self: Fiber<A, E>) => Effect<void> = effect.fiber
  * })
  * ```
  *
+ * @see {@link interrupt} for using the current fiber as the interruptor
+ *
  * @category interruption
  * @since 2.0.0
  */
@@ -338,6 +435,20 @@ export const interruptAs: {
    * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
    * tracking which fiber initiated the interruption.
    *
+   * **When to use**
+   *
+   * Use when runtime diagnostics or tracing should attribute the interruption to
+   * a specific fiber ID.
+   *
+   * **Details**
+   *
+   * The returned Effect completes only after the interrupted fiber has completed.
+   *
+   * **Gotchas**
+   *
+   * The supplied ID affects the recorded interruptor. It does not make
+   * interruption synchronous or force uninterruptible regions to stop early.
+   *
    * **Example** (Interrupting a fiber as another fiber)
    *
    * ```ts
@@ -354,6 +465,8 @@ export const interruptAs: {
    * })
    * ```
    *
+   * @see {@link interrupt} for using the current fiber as the interruptor
+   *
    * @category interruption
    * @since 2.0.0
    */
@@ -365,6 +478,20 @@ export const interruptAs: {
    * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
    * tracking which fiber initiated the interruption.
    *
+   * **When to use**
+   *
+   * Use when runtime diagnostics or tracing should attribute the interruption to
+   * a specific fiber ID.
+   *
+   * **Details**
+   *
+   * The returned Effect completes only after the interrupted fiber has completed.
+   *
+   * **Gotchas**
+   *
+   * The supplied ID affects the recorded interruptor. It does not make
+   * interruption synchronous or force uninterruptible regions to stop early.
+   *
    * **Example** (Interrupting a fiber as another fiber)
    *
    * ```ts
@@ -381,6 +508,8 @@ export const interruptAs: {
    * })
    * ```
    *
+   * @see {@link interrupt} for using the current fiber as the interruptor
+   *
    * @category interruption
    * @since 2.0.0
    */
@@ -395,6 +524,20 @@ export const interruptAs: {
  * Interrupts all fibers in the provided iterable, causing them to stop executing
  * and clean up any acquired resources.
  *
+ * **When to use**
+ *
+ * Use when a group of forked fibers is no longer needed.
+ *
+ * **Details**
+ *
+ * The current fiber is recorded as the interruptor. The returned Effect
+ * completes only after all interrupted fibers have completed.
+ *
+ * **Gotchas**
+ *
+ * Interruption is cooperative for each fiber. The returned Effect can wait for
+ * uninterruptible work and finalizers in any interrupted fiber.
+ *
  * **Example** (Interrupting multiple fibers)
  *
  * ```ts
@@ -434,6 +577,8 @@ export const interruptAs: {
  * })
  * ```
  *
+ * @see {@link interruptAllAs} for specifying the interrupting fiber ID
+ *
  * @category interruption
  * @since 2.0.0
  */
@@ -446,6 +591,21 @@ export const interruptAll: <A extends Iterable<Fiber<any, any>>>(
  * interrupting fiber. This allows you to control which fiber is considered the source
  * of the interruption, which can be useful for debugging and tracing.
  *
+ * **When to use**
+ *
+ * Use to interrupt several fibers while recording a specific fiber ID as the
+ * interruptor.
+ *
+ * **Details**
+ *
+ * The returned Effect completes only after all interrupted fibers have
+ * completed.
+ *
+ * **Gotchas**
+ *
+ * The supplied ID affects the recorded interruptor. It does not make
+ * interruption synchronous or force uninterruptible regions to stop early.
+ *
  * **Example** (Interrupting multiple fibers as another fiber)
  *
  * ```ts
@@ -480,6 +640,8 @@ export const interruptAll: <A extends Iterable<Fiber<any, any>>>(
  * })
  * ```
  *
+ * @see {@link interruptAll} for using the current fiber as the interruptor
+ *
  * @category interruption
  * @since 2.0.0
  */
@@ -489,6 +651,21 @@ export const interruptAllAs: {
    * interrupting fiber. This allows you to control which fiber is considered the source
    * of the interruption, which can be useful for debugging and tracing.
    *
+   * **When to use**
+   *
+   * Use to interrupt several fibers while recording a specific fiber ID as the
+   * interruptor.
+   *
+   * **Details**
+   *
+   * The returned Effect completes only after all interrupted fibers have
+   * completed.
+   *
+   * **Gotchas**
+   *
+   * The supplied ID affects the recorded interruptor. It does not make
+   * interruption synchronous or force uninterruptible regions to stop early.
+   *
    * **Example** (Interrupting multiple fibers as another fiber)
    *
    * ```ts
@@ -523,6 +700,8 @@ export const interruptAllAs: {
    * })
    * ```
    *
+   * @see {@link interruptAll} for using the current fiber as the interruptor
+   *
    * @category interruption
    * @since 2.0.0
    */
@@ -532,6 +711,21 @@ export const interruptAllAs: {
    * interrupting fiber. This allows you to control which fiber is considered the source
    * of the interruption, which can be useful for debugging and tracing.
    *
+   * **When to use**
+   *
+   * Use to interrupt several fibers while recording a specific fiber ID as the
+   * interruptor.
+   *
+   * **Details**
+   *
+   * The returned Effect completes only after all interrupted fibers have
+   * completed.
+   *
+   * **Gotchas**
+   *
+   * The supplied ID affects the recorded interruptor. It does not make
+   * interruption synchronous or force uninterruptible regions to stop early.
+   *
    * **Example** (Interrupting multiple fibers as another fiber)
    *
    * ```ts
@@ -566,6 +760,8 @@ export const interruptAllAs: {
    * })
    * ```
    *
+   * @see {@link interruptAll} for using the current fiber as the interruptor
+   *
    * @category interruption
    * @since 2.0.0
    */
@@ -576,6 +772,16 @@ export const interruptAllAs: {
  * Tests if a value is a Fiber. This is a type guard that can be used to
  * determine if an unknown value is a Fiber instance.
  *
+ * **When to use**
+ *
+ * Use when checking values at boundaries where an unknown value may be a
+ * runtime fiber.
+ *
+ * **Details**
+ *
+ * The check looks for the internal Fiber type ID marker and does not inspect
+ * the fiber's current state.
+ *
  * **Example** (Checking for fibers)
  *
  * ```ts
@@ -611,6 +817,16 @@ export const isFiber = (
  * Returns the current fiber if called from within a fiber context,
  * otherwise returns `undefined`.
  *
+ * **When to use**
+ *
+ * Use when you need low-level runtime integrations that need access to the currently
+ * executing fiber.
+ *
+ * **Gotchas**
+ *
+ * This is a synchronous accessor, not an Effect. It returns `undefined` outside
+ * an active fiber runtime context.
+ *
  * **Example** (Getting the current fiber)
  *
  * ```ts
@@ -632,36 +848,69 @@ export const getCurrent: () => Fiber<any, any> | undefined = effect.getCurrentFi
 /**
  * Links a fiber to a `Scope` and returns the same fiber.
  *
+ * **When to use**
+ *
+ * Use when a manually managed fiber should be interrupted when a Scope closes.
+ *
  * **Details**
  *
  * When the scope is closed, the fiber is interrupted. If the scope is already
  * closed, the fiber is interrupted immediately.
  *
- * @category Scope
+ * **Gotchas**
+ *
+ * This does not wait for the fiber to complete. It only registers the
+ * interruption finalizer and returns the same fiber.
+ *
+ * @see {@link interrupt} for interrupting and waiting for completion
+ *
+ * @category resource management
  * @since 4.0.0
  */
 export const runIn: {
   /**
    * Links a fiber to a `Scope` and returns the same fiber.
    *
+   * **When to use**
+   *
+   * Use when a manually managed fiber should be interrupted when a Scope closes.
+   *
    * **Details**
    *
    * When the scope is closed, the fiber is interrupted. If the scope is already
    * closed, the fiber is interrupted immediately.
    *
-   * @category Scope
+   * **Gotchas**
+   *
+   * This does not wait for the fiber to complete. It only registers the
+   * interruption finalizer and returns the same fiber.
+   *
+   * @see {@link interrupt} for interrupting and waiting for completion
+   *
+   * @category resource management
    * @since 4.0.0
    */
   (scope: Scope): <A, E>(self: Fiber<A, E>) => Fiber<A, E>
   /**
    * Links a fiber to a `Scope` and returns the same fiber.
    *
+   * **When to use**
+   *
+   * Use when a manually managed fiber should be interrupted when a Scope closes.
+   *
    * **Details**
    *
    * When the scope is closed, the fiber is interrupted. If the scope is already
    * closed, the fiber is interrupted immediately.
    *
-   * @category Scope
+   * **Gotchas**
+   *
+   * This does not wait for the fiber to complete. It only registers the
+   * interruption finalizer and returns the same fiber.
+   *
+   * @see {@link interrupt} for interrupting and waiting for completion
+   *
+   * @category resource management
    * @since 4.0.0
    */
   <A, E>(self: Fiber<A, E>, scope: Scope): Fiber<A, E>