effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/FiberHandle.ts

@@ -1,4 +1,43 @@
 /**
+ * The `FiberHandle` module provides a scoped handle for managing the lifecycle
+ * of at most one fiber at a time. A `FiberHandle<A, E>` can hold one
+ * `Fiber<A, E>`; when a new fiber is installed, the previous fiber is
+ * interrupted unless the operation is configured with `onlyIfMissing`.
+ *
+ * **Mental model**
+ *
+ * - A handle is either open with zero or one current fiber, or closed by its
+ *   surrounding `Scope`
+ * - Closing the scope interrupts the current fiber and prevents new work from
+ *   being accepted
+ * - Completed fibers remove themselves from the handle, so the handle can be
+ *   reused for later work
+ * - Replacing a fiber uses the handle's internal interruption id, allowing
+ *   expected replacement interruptions to be distinguished from real failures
+ *
+ * **Common tasks**
+ *
+ * - Create a scoped handle: {@link make}
+ * - Fork an effect into the handle: {@link run}
+ * - Store an existing fiber: {@link set}
+ * - Read or clear the current fiber: {@link get}, {@link clear}
+ * - Capture runtime-specific runners: {@link makeRuntime}, {@link runtime}
+ * - Run handled effects as Promises: {@link makeRuntimePromise},
+ *   {@link runtimePromise}
+ * - Wait for failure or closure: {@link join}
+ * - Wait until the current fiber is gone: {@link awaitEmpty}
+ *
+ * **Gotchas**
+ *
+ * - The handle never contains more than one live fiber; starting or setting
+ *   another fiber interrupts the previous one by default
+ * - Use `onlyIfMissing` when a call should leave an already running fiber in
+ *   place instead of replacing it
+ * - `join` observes the handle's failure/close signal; successful fiber
+ *   completion only empties the handle
+ * - `awaitEmpty` waits for the fiber that is current when it starts; later
+ *   calls to {@link run} or {@link set} can install new work
+ *
  * @since 2.0.0
  */
 import * as Cause from "./Cause.ts"
@@ -20,7 +59,13 @@ import type * as Scope from "./Scope.ts"
 const TypeId = "~effect/FiberHandle"
 
 /**
- * @example
+ * Scoped handle that manages at most one fiber.
+ *
+ * The current fiber is interrupted when the handle's scope closes, and managed
+ * fibers are removed from the handle when they complete.
+ *
+ * **Example** (Managing a single fiber)
+ *
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -35,8 +80,8 @@ const TypeId = "~effect/FiberHandle"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable, Inspectable.Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -50,7 +95,12 @@ export interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable,
 }
 
 /**
- * @example
+ * Returns `true` if a value is a `FiberHandle`.
+ *
+ * This is a type guard that checks for the `FiberHandle` runtime marker.
+ *
+ * **Example** (Checking fiber handles)
+ *
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -62,8 +112,8 @@ export interface FiberHandle<out A = unknown, out E = unknown> extends Pipeable,
  * })
  * ```
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export const isFiberHandle = (u: unknown): u is FiberHandle => Predicate.hasProperty(u, TypeId)
 
@@ -92,7 +142,8 @@ const makeUnsafe = <A = unknown, E = unknown>(): FiberHandle<A, E> => {
  * You can add a fiber to the handle using `FiberHandle.run`, and the fiber will
  * be automatically removed from the FiberHandle when it completes.
  *
- * @example
+ * **Example** (Creating a scoped fiber handle)
+ *
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -110,8 +161,8 @@ const makeUnsafe = <A = unknown, E = unknown>(): FiberHandle<A, E> => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A = unknown, E = unknown>(): Effect.Effect<FiberHandle<A, E>, never, Scope.Scope> =>
   Effect.acquireRelease(
@@ -130,9 +181,14 @@ export const make = <A = unknown, E = unknown>(): Effect.Effect<FiberHandle<A, E
   )
 
 /**
- * Create an Effect run function that is backed by a FiberHandle.
+ * Creates a scoped run function that forks effects into a new `FiberHandle`.
+ *
+ * Each call returns the forked fiber, stores it in the handle, and interrupts
+ * the previous fiber unless `onlyIfMissing` is set. The managed fiber is
+ * interrupted when the handle's scope closes.
+ *
+ * **Example** (Running effects with a fiber handle)
  *
- * @example
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -149,8 +205,8 @@ export const make = <A = unknown, E = unknown>(): Effect.Effect<FiberHandle<A, E
  * }).pipe(Effect.scoped)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const makeRuntime = <R, E = unknown, A = unknown>(): Effect.Effect<
   <XE extends E, XA extends A>(
@@ -173,9 +229,15 @@ export const makeRuntime = <R, E = unknown, A = unknown>(): Effect.Effect<
   )
 
 /**
- * Create an Effect run function that is backed by a FiberHandle.
+ * Creates a scoped run function that forks effects into a new `FiberHandle`
+ * and returns a `Promise` for each effect result.
+ *
+ * Each call stores the fiber in the handle and interrupts the previous fiber
+ * unless `onlyIfMissing` is set. The returned Promise resolves with the
+ * effect's success value or rejects with the squashed failure cause.
+ *
+ * **Example** (Running effects as promises)
  *
- * @example
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -189,8 +251,8 @@ export const makeRuntime = <R, E = unknown, A = unknown>(): Effect.Effect<
  * }).pipe(Effect.scoped)
  * ```
  *
- * @since 3.13.0
  * @category constructors
+ * @since 3.13.0
  */
 export const makeRuntimePromise = <R = never, A = unknown, E = unknown>(): Effect.Effect<
   <XE extends E, XA extends A>(
@@ -220,7 +282,8 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * Set the fiber in a FiberHandle. When the fiber completes, it will be removed from the FiberHandle.
  * If a fiber is already running, it will be interrupted unless `options.onlyIfMissing` is set.
  *
- * @example
+ * **Example** (Setting a fiber unsafely)
+ *
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -237,15 +300,16 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const setUnsafe: {
   /**
    * Set the fiber in a FiberHandle. When the fiber completes, it will be removed from the FiberHandle.
    * If a fiber is already running, it will be interrupted unless `options.onlyIfMissing` is set.
    *
-   * @example
+   * **Example** (Setting a fiber unsafely)
+   *
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -262,8 +326,8 @@ export const setUnsafe: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, XE extends E, XA extends A>(
     fiber: Fiber.Fiber<XA, XE>,
@@ -276,7 +340,8 @@ export const setUnsafe: {
    * Set the fiber in a FiberHandle. When the fiber completes, it will be removed from the FiberHandle.
    * If a fiber is already running, it will be interrupted unless `options.onlyIfMissing` is set.
    *
-   * @example
+   * **Example** (Setting a fiber unsafely)
+   *
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -293,8 +358,8 @@ export const setUnsafe: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, XE extends E, XA extends A>(
     self: FiberHandle<A, E>,
@@ -351,7 +416,8 @@ export const setUnsafe: {
  * If a fiber already exists in the `FiberHandle`, it will be interrupted
  * unless `options.onlyIfMissing` is set.
  *
- * @example
+ * **Example** (Setting a fiber safely)
+ *
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -368,8 +434,8 @@ export const setUnsafe: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const set: {
   /**
@@ -379,7 +445,8 @@ export const set: {
    * If a fiber already exists in the `FiberHandle`, it will be interrupted
    * unless `options.onlyIfMissing` is set.
    *
-   * @example
+   * **Example** (Setting a fiber safely)
+   *
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -396,8 +463,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, XE extends E, XA extends A>(
     fiber: Fiber.Fiber<XA, XE>,
@@ -413,7 +480,8 @@ export const set: {
    * If a fiber already exists in the `FiberHandle`, it will be interrupted
    * unless `options.onlyIfMissing` is set.
    *
-   * @example
+   * **Example** (Setting a fiber safely)
+   *
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -430,8 +498,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, XE extends E, XA extends A>(
     self: FiberHandle<A, E>,
@@ -459,7 +527,8 @@ export const set: {
 /**
  * Retrieve the fiber from the FiberHandle.
  *
- * @example
+ * **Example** (Reading the current fiber unsafely)
+ *
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -477,8 +546,8 @@ export const set: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export function getUnsafe<A, E>(self: FiberHandle<A, E>): Option.Option<Fiber.Fiber<A, E>> {
   return self.state._tag === "Closed" ? Option.none() : Option.fromUndefinedOr(self.state.fiber)
@@ -487,7 +556,8 @@ export function getUnsafe<A, E>(self: FiberHandle<A, E>): Option.Option<Fiber.Fi
 /**
  * Retrieve the fiber from the FiberHandle.
  *
- * @example
+ * **Example** (Reading the current fiber)
+ *
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -506,15 +576,19 @@ export function getUnsafe<A, E>(self: FiberHandle<A, E>): Option.Option<Fiber.Fi
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export function get<A, E>(self: FiberHandle<A, E>): Effect.Effect<Option.Option<Fiber.Fiber<A, E>>> {
   return Effect.suspend(() => Effect.succeed(getUnsafe(self)))
 }
 
 /**
- * @example
+ * Interrupts the fiber currently stored in the `FiberHandle`, if any, and
+ * leaves the handle empty.
+ *
+ * **Example** (Clearing a fiber handle)
+ *
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -533,8 +607,8 @@ export function get<A, E>(self: FiberHandle<A, E>): Effect.Effect<Option.Option<
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const clear = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void> =>
   Effect.uninterruptibleMask((restore) => {
@@ -562,10 +636,14 @@ const constInterruptedFiber = (function() {
 })()
 
 /**
- * Run an Effect and add the forked fiber to the FiberHandle.
- * When the fiber completes, it will be removed from the FiberHandle.
+ * Forks an Effect and stores the resulting fiber in the `FiberHandle`.
+ *
+ * The handle manages only one fiber: running a new effect interrupts the
+ * previous fiber unless `onlyIfMissing` is set. When the managed fiber
+ * completes, it is removed from the handle.
+ *
+ * **Example** (Running an effect in a fiber handle)
  *
- * @example
  * ```ts
  * import { Effect, Fiber, FiberHandle } from "effect"
  *
@@ -584,15 +662,19 @@ const constInterruptedFiber = (function() {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const run: {
   /**
-   * Run an Effect and add the forked fiber to the FiberHandle.
-   * When the fiber completes, it will be removed from the FiberHandle.
+   * Forks an Effect and stores the resulting fiber in the `FiberHandle`.
+   *
+   * The handle manages only one fiber: running a new effect interrupts the
+   * previous fiber unless `onlyIfMissing` is set. When the managed fiber
+   * completes, it is removed from the handle.
+   *
+   * **Example** (Running an effect in a fiber handle)
    *
-   * @example
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -611,8 +693,8 @@ export const run: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E>(
     self: FiberHandle<A, E>,
@@ -625,10 +707,14 @@ export const run: {
     effect: Effect.Effect<XA, XE, R>
   ) => Effect.Effect<Fiber.Fiber<XA, XE>, never, R>
   /**
-   * Run an Effect and add the forked fiber to the FiberHandle.
-   * When the fiber completes, it will be removed from the FiberHandle.
+   * Forks an Effect and stores the resulting fiber in the `FiberHandle`.
+   *
+   * The handle manages only one fiber: running a new effect interrupts the
+   * previous fiber unless `onlyIfMissing` is set. When the managed fiber
+   * completes, it is removed from the handle.
+   *
+   * **Example** (Running an effect in a fiber handle)
    *
-   * @example
    * ```ts
    * import { Effect, Fiber, FiberHandle } from "effect"
    *
@@ -647,8 +733,8 @@ export const run: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E, R, XE extends E, XA extends A>(
     self: FiberHandle<A, E>,
@@ -687,9 +773,14 @@ const runImpl = <A, E, R, XE extends E, XA extends A>(
   })
 
 /**
- * Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberHandle.
+ * Captures the current runtime and returns a function for forking effects into
+ * an existing `FiberHandle`.
+ *
+ * Each call returns the forked fiber, stores it in the handle, and interrupts
+ * the previous fiber unless `onlyIfMissing` is set.
+ *
+ * **Example** (Capturing a runtime for fiber handles)
  *
- * @example
  * ```ts
  * import { Effect, FiberHandle, Context } from "effect"
  *
@@ -714,8 +805,8 @@ const runImpl = <A, E, R, XE extends E, XA extends A>(
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const runtime: <A, E>(
   self: FiberHandle<A, E>
@@ -762,12 +853,15 @@ export const runtime: <A, E>(
   )
 
 /**
- * Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberHandle.
+ * Captures the current runtime and returns a function for running effects in
+ * an existing `FiberHandle` as Promises.
+ *
+ * Each call stores the forked fiber in the handle and interrupts the previous
+ * fiber unless `onlyIfMissing` is set. The Promise resolves with the effect's
+ * success value or rejects with the squashed failure cause.
  *
- * The returned run function will return Promise's that will resolve when the
- * fiber completes.
+ * **Example** (Capturing a runtime for promises)
  *
- * @example
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -782,8 +876,8 @@ export const runtime: <A, E>(
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export const runtimePromise = <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<
   <XE extends E, XA extends A>(
@@ -827,10 +921,15 @@ export const runtimePromise = <A, E>(self: FiberHandle<A, E>): <R = never>() =>
   )
 
 /**
- * If any of the Fiber's in the handle terminate with a failure,
- * the returned Effect will terminate with the first failure that occurred.
+ * Waits for the `FiberHandle` to fail or close.
+ *
+ * The returned Effect fails with the first managed fiber failure that is not
+ * ignored by the handle's interruption rules. Normal successful completion of
+ * a managed fiber only removes it from the handle; use `awaitEmpty` to wait
+ * for the current fiber to finish.
+ *
+ * **Example** (Propagating fiber failures)
  *
- * @example
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -843,8 +942,8 @@ export const runtimePromise = <A, E>(self: FiberHandle<A, E>): <R = never>() =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const join = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void, E> =>
   Deferred.await(self.deferred as Deferred.Deferred<void, E>)
@@ -852,7 +951,8 @@ export const join = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void, E> =>
 /**
  * Wait for the fiber in the FiberHandle to complete.
  *
- * @example
+ * **Example** (Waiting for a fiber to complete)
+ *
  * ```ts
  * import { Effect, FiberHandle } from "effect"
  *
@@ -869,8 +969,8 @@ export const join = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void, E> =>
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export const awaitEmpty = <A, E>(self: FiberHandle<A, E>): Effect.Effect<void, E> =>
   Effect.suspend(() => {