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

package/src/FiberMap.ts

@@ -1,4 +1,39 @@
 /**
+ * The `FiberMap` module provides a scoped, mutable collection for managing
+ * fibers by key. A `FiberMap<K, A, E>` owns a set of running fibers, interrupts
+ * them when its scope closes, and automatically removes each entry when the
+ * corresponding fiber completes.
+ *
+ * **Mental model**
+ *
+ * - A `FiberMap` is a keyed registry of fibers with lifecycle management
+ * - Keys identify the currently active fiber for a logical task or resource
+ * - Adding a fiber under an existing key interrupts the previous fiber by default
+ * - Completed fibers remove themselves from the map if they are still current
+ * - Closing the map's scope interrupts every fiber that remains in the map
+ * - The map can surface the first non-ignored managed fiber failure via {@link join}
+ *
+ * **Common tasks**
+ *
+ * - Create a scoped map: {@link make}
+ * - Fork effects into the map: {@link run}
+ * - Add existing fibers: {@link set}
+ * - Create captured runners: {@link makeRuntime}, {@link runtime}
+ * - Bridge to Promise-based callers: {@link makeRuntimePromise}, {@link runtimePromise}
+ * - Inspect entries: {@link get}, {@link has}, {@link size}
+ * - Stop work: {@link remove}, {@link clear}
+ * - Coordinate completion or failure: {@link awaitEmpty}, {@link join}
+ *
+ * **Gotchas**
+ *
+ * - `FiberMap` is scoped; use it with `Effect.scoped` or another scope owner so
+ *   managed fibers are interrupted when the scope closes
+ * - Reusing a key is a replacement operation unless `onlyIfMissing` is enabled
+ * - `join` waits for the map to fail or close; use {@link awaitEmpty} to wait
+ *   until all currently managed fibers have completed
+ * - The `Unsafe` variants mutate synchronously and should only be used when the
+ *   caller already controls the surrounding execution context
+ *
  * @since 2.0.0
  */
 import * as Cause from "./Cause.ts"
@@ -25,7 +60,8 @@ const TypeId = "~effect/FiberMap"
  * Scope is closed, all fibers in the map will be interrupted. Fibers are
  * automatically removed from the map when they complete.
  *
- * @example
+ * **Example** (Managing fibers in a map)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -34,8 +70,8 @@ const TypeId = "~effect/FiberMap"
  *   const map = yield* FiberMap.make<string>()
  *
  *   // Add some fibers to the map
- *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
- *   yield* FiberMap.run(map, "task2", Effect.succeed("World"))
+ *   yield* FiberMap.run(map, "task1", Effect.never)
+ *   yield* FiberMap.run(map, "task2", Effect.never)
  *
  *   // Get the size of the map
  *   const size = yield* FiberMap.size(map)
@@ -43,8 +79,8 @@ const TypeId = "~effect/FiberMap"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface FiberMap<in out K, out A = unknown, out E = unknown>
   extends Pipeable, Inspectable.Inspectable, Iterable<[K, Fiber.Fiber<A, E>]>
@@ -60,7 +96,12 @@ export interface FiberMap<in out K, out A = unknown, out E = unknown>
 }
 
 /**
- * @example
+ * Returns `true` if a value is a `FiberMap`.
+ *
+ * This is a type guard that checks for the `FiberMap` runtime marker.
+ *
+ * **Example** (Checking if a value is a FiberMap)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -73,8 +114,8 @@ export interface FiberMap<in out K, out A = unknown, out E = unknown>
  * })
  * ```
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export const isFiberMap = (u: unknown): u is FiberMap<unknown> => Predicate.hasProperty(u, TypeId)
 
@@ -112,7 +153,8 @@ const makeUnsafe = <K, A = unknown, E = unknown>(
  * You can add fibers to the map using `FiberMap.set` or `FiberMap.run`, and the fibers will
  * be automatically removed from the FiberMap when they complete.
  *
- * @example
+ * **Example** (Creating a scoped FiberMap)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -129,8 +171,8 @@ const makeUnsafe = <K, A = unknown, E = unknown>(
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <K, A = unknown, E = unknown>(): Effect.Effect<FiberMap<K, A, E>, never, Scope.Scope> =>
   Effect.acquireRelease(
@@ -152,9 +194,15 @@ export const make = <K, A = unknown, E = unknown>(): Effect.Effect<FiberMap<K, A
   )
 
 /**
- * Create an Effect run function that is backed by a FiberMap.
+ * Creates a scoped run function that forks effects into a new `FiberMap`.
+ *
+ * Each call stores the forked fiber under the supplied key and returns that
+ * fiber. If the key already has a fiber, the previous fiber is interrupted
+ * unless `onlyIfMissing` is set. All managed fibers are interrupted when the
+ * map's scope closes.
+ *
+ * **Example** (Creating a scoped runtime)
  *
- * @example
  * ```ts
  * import { Effect, Fiber, FiberMap } from "effect"
  *
@@ -165,16 +213,16 @@ export const make = <K, A = unknown, E = unknown>(): Effect.Effect<FiberMap<K, A
  *   const fiber1 = run("task1", Effect.succeed("Hello"))
  *   const fiber2 = run("task2", Effect.succeed("World"))
  *
- *   // Await the results
- *   const result1 = yield* Fiber.await(fiber1)
- *   const result2 = yield* Fiber.await(fiber2)
+ *   // Join the fibers to get their successful values
+ *   const result1 = yield* Fiber.join(fiber1)
+ *   const result2 = yield* Fiber.join(fiber2)
  *
  *   console.log(result1, result2) // "Hello", "World"
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const makeRuntime = <R, K, E = unknown, A = unknown>(): Effect.Effect<
   <XE extends E, XA extends A>(
@@ -195,10 +243,16 @@ export const makeRuntime = <R, K, E = unknown, A = unknown>(): Effect.Effect<
   )
 
 /**
- * Create an Effect run function that is backed by a FiberMap.
- * Returns a Promise instead of a Fiber for more convenient use with async/await.
+ * Creates a scoped run function that forks effects into a new `FiberMap` and
+ * returns a `Promise` for each effect result.
+ *
+ * Each call stores the fiber under the supplied key, interrupting any previous
+ * fiber for that key unless `onlyIfMissing` is set. The returned Promise
+ * resolves with the effect's success value or rejects with the squashed failure
+ * cause.
+ *
+ * **Example** (Creating a promise runtime)
  *
- * @example
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -217,8 +271,8 @@ export const makeRuntime = <R, K, E = unknown, A = unknown>(): Effect.Effect<
  * })
  * ```
  *
- * @since 3.13.0
  * @category constructors
+ * @since 3.13.0
  */
 export const makeRuntimePromise = <R, K, A = unknown, E = unknown>(): Effect.Effect<
   <XE extends E, XA extends A>(
@@ -245,53 +299,69 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
 ))
 
 /**
- * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
- * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+ * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
+ * mutation.
+ *
+ * When the fiber completes, it is removed from the map. If the key already has
+ * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+ * in that case the new fiber is interrupted and the existing entry is kept.
+ *
+ * **Example** (Adding a fiber unsafely)
  *
- * @example
  * ```ts
- * import { Effect, Fiber, FiberMap } from "effect"
+ * import { Deferred, Effect, Fiber, FiberMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const map = yield* FiberMap.make<string>()
+ *   const deferred = yield* Deferred.make<string>()
  *
  *   // Create a fiber and add it to the map
- *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+ *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
  *   FiberMap.setUnsafe(map, "greeting", fiber)
  *
- *   // The fiber will be automatically removed when it completes
- *   const result = yield* Fiber.await(fiber)
+ *   yield* Deferred.succeed(deferred, "Hello")
+ *
+ *   // Join the fiber to get its successful value
+ *   const result = yield* Fiber.join(fiber)
  *   console.log(result) // "Hello"
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const setUnsafe: {
   /**
-   * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
-   * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+   * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
+   * mutation.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+   * in that case the new fiber is interrupted and the existing entry is kept.
+   *
+   * **Example** (Adding a fiber unsafely)
    *
-   * @example
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Create a fiber and add it to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   FiberMap.setUnsafe(map, "greeting", fiber)
    *
-   *   // The fiber will be automatically removed when it completes
-   *   const result = yield* Fiber.await(fiber)
+   *   yield* Deferred.succeed(deferred, "Hello")
+   *
+   *   // Join the fiber to get its successful value
+   *   const result = yield* Fiber.join(fiber)
    *   console.log(result) // "Hello"
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E, XE extends E, XA extends A>(
     key: K,
@@ -302,28 +372,36 @@ export const setUnsafe: {
     } | undefined
   ): (self: FiberMap<K, A, E>) => void
   /**
-   * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
-   * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+   * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
+   * mutation.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+   * in that case the new fiber is interrupted and the existing entry is kept.
+   *
+   * **Example** (Adding a fiber unsafely)
    *
-   * @example
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Create a fiber and add it to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   FiberMap.setUnsafe(map, "greeting", fiber)
    *
-   *   // The fiber will be automatically removed when it completes
-   *   const result = yield* Fiber.await(fiber)
+   *   yield* Deferred.succeed(deferred, "Hello")
+   *
+   *   // Join the fiber to get its successful value
+   *   const result = yield* Fiber.join(fiber)
    *   console.log(result) // "Hello"
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E, XE extends E, XA extends A>(
     self: FiberMap<K, A, E>,
@@ -382,55 +460,71 @@ export const setUnsafe: {
 })
 
 /**
- * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
- * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+ * Adds a fiber to the `FiberMap` under a key.
+ *
+ * When the fiber completes, it is removed from the map. If the key already has
+ * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+ * in that case the new fiber is interrupted and the existing entry is kept.
+ *
  * This is the Effect-wrapped version of `setUnsafe`.
  *
- * @example
+ * **Example** (Adding a fiber)
+ *
  * ```ts
- * import { Effect, Fiber, FiberMap } from "effect"
+ * import { Deferred, Effect, Fiber, FiberMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const map = yield* FiberMap.make<string>()
+ *   const deferred = yield* Deferred.make<string>()
  *
  *   // Create a fiber and add it to the map using Effect
- *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+ *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
  *   yield* FiberMap.set(map, "greeting", fiber)
  *
- *   // The fiber will be automatically removed when it completes
- *   const result = yield* Fiber.await(fiber)
+ *   yield* Deferred.succeed(deferred, "Hello")
+ *
+ *   // Join the fiber to get its successful value
+ *   const result = yield* Fiber.join(fiber)
  *   console.log(result) // "Hello"
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const set: {
   /**
-   * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
-   * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+   * Adds a fiber to the `FiberMap` under a key.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+   * in that case the new fiber is interrupted and the existing entry is kept.
+   *
    * This is the Effect-wrapped version of `setUnsafe`.
    *
-   * @example
+   * **Example** (Adding a fiber)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Create a fiber and add it to the map using Effect
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   yield* FiberMap.set(map, "greeting", fiber)
    *
-   *   // The fiber will be automatically removed when it completes
-   *   const result = yield* Fiber.await(fiber)
+   *   yield* Deferred.succeed(deferred, "Hello")
+   *
+   *   // Join the fiber to get its successful value
+   *   const result = yield* Fiber.join(fiber)
    *   console.log(result) // "Hello"
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E, XE extends E, XA extends A>(
     key: K,
@@ -441,29 +535,37 @@ export const set: {
     } | undefined
   ): (self: FiberMap<K, A, E>) => Effect.Effect<void>
   /**
-   * Add a fiber to the FiberMap. When the fiber completes, it will be removed from the FiberMap.
-   * If the key already exists in the FiberMap, the previous fiber will be interrupted.
+   * Adds a fiber to the `FiberMap` under a key.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, that previous fiber is interrupted unless `onlyIfMissing` is set;
+   * in that case the new fiber is interrupted and the existing entry is kept.
+   *
    * This is the Effect-wrapped version of `setUnsafe`.
    *
-   * @example
+   * **Example** (Adding a fiber)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Create a fiber and add it to the map using Effect
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   yield* FiberMap.set(map, "greeting", fiber)
    *
-   *   // The fiber will be automatically removed when it completes
-   *   const result = yield* Fiber.await(fiber)
+   *   yield* Deferred.succeed(deferred, "Hello")
+   *
+   *   // Join the fiber to get its successful value
+   *   const result = yield* Fiber.join(fiber)
    *   console.log(result) // "Hello"
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E, XE extends E, XA extends A>(
     self: FiberMap<K, A, E>,
@@ -487,82 +589,94 @@ export const set: {
 /**
  * Retrieve a fiber from the FiberMap.
  *
- * @example
+ * **Example** (Retrieving a fiber unsafely)
+ *
  * ```ts
- * import { Effect, Fiber, FiberMap } from "effect"
+ * import { Deferred, Effect, Fiber, FiberMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const map = yield* FiberMap.make<string>()
+ *   const deferred = yield* Deferred.make<string>()
  *
  *   // Add a fiber to the map
- *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+ *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
  *   FiberMap.setUnsafe(map, "greeting", fiber)
  *
  *   // Retrieve the fiber
  *   const retrieved = FiberMap.getUnsafe(map, "greeting")
  *   if (retrieved._tag === "Some") {
- *     const result = yield* Fiber.await(retrieved.value)
+ *     yield* Deferred.succeed(deferred, "Hello")
+ *
+ *     const result = yield* Fiber.join(retrieved.value)
  *     console.log(result) // "Hello"
  *   }
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const getUnsafe: {
   /**
    * Retrieve a fiber from the FiberMap.
    *
-   * @example
+   * **Example** (Retrieving a fiber unsafely)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Add a fiber to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   FiberMap.setUnsafe(map, "greeting", fiber)
    *
    *   // Retrieve the fiber
    *   const retrieved = FiberMap.getUnsafe(map, "greeting")
    *   if (retrieved._tag === "Some") {
-   *     const result = yield* Fiber.await(retrieved.value)
+   *     yield* Deferred.succeed(deferred, "Hello")
+   *
+   *     const result = yield* Fiber.join(retrieved.value)
    *     console.log(result) // "Hello"
    *   }
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Option.Option<Fiber.Fiber<A, E>>
   /**
    * Retrieve a fiber from the FiberMap.
    *
-   * @example
+   * **Example** (Retrieving a fiber unsafely)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Add a fiber to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   FiberMap.setUnsafe(map, "greeting", fiber)
    *
    *   // Retrieve the fiber
    *   const retrieved = FiberMap.getUnsafe(map, "greeting")
    *   if (retrieved._tag === "Some") {
-   *     const result = yield* Fiber.await(retrieved.value)
+   *     yield* Deferred.succeed(deferred, "Hello")
+   *
+   *     const result = yield* Fiber.join(retrieved.value)
    *     console.log(result) // "Hello"
    *   }
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K): Option.Option<Fiber.Fiber<A, E>>
 } = dual(
@@ -577,28 +691,32 @@ export const getUnsafe: {
  *
  * Returns an `Option` wrapped in `Effect`.
  *
- * @example
+ * **Example** (Retrieving a fiber)
+ *
  * ```ts
- * import { Effect, Fiber, FiberMap } from "effect"
+ * import { Deferred, Effect, Fiber, FiberMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const map = yield* FiberMap.make<string>()
+ *   const deferred = yield* Deferred.make<string>()
  *
  *   // Add a fiber to the map
- *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+ *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
  *   yield* FiberMap.set(map, "greeting", fiber)
  *
  *   // Retrieve the fiber with error handling
  *   const retrieved = yield* FiberMap.get(map, "greeting")
  *   if (retrieved._tag === "Some") {
- *     const result = yield* Fiber.await(retrieved.value)
+ *     yield* Deferred.succeed(deferred, "Hello")
+ *
+ *     const result = yield* Fiber.join(retrieved.value)
  *     console.log(result) // "Hello"
  *   }
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const get: {
   /**
@@ -606,28 +724,32 @@ export const get: {
    *
    * Returns an `Option` wrapped in `Effect`.
    *
-   * @example
+   * **Example** (Retrieving a fiber)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Add a fiber to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   yield* FiberMap.set(map, "greeting", fiber)
    *
    *   // Retrieve the fiber with error handling
    *   const retrieved = yield* FiberMap.get(map, "greeting")
    *   if (retrieved._tag === "Some") {
-   *     const result = yield* Fiber.await(retrieved.value)
+   *     yield* Deferred.succeed(deferred, "Hello")
+   *
+   *     const result = yield* Fiber.join(retrieved.value)
    *     console.log(result) // "Hello"
    *   }
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<Option.Option<Fiber.Fiber<A, E>>>
   /**
@@ -635,28 +757,32 @@ export const get: {
    *
    * Returns an `Option` wrapped in `Effect`.
    *
-   * @example
+   * **Example** (Retrieving a fiber)
+   *
    * ```ts
-   * import { Effect, Fiber, FiberMap } from "effect"
+   * import { Deferred, Effect, Fiber, FiberMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const map = yield* FiberMap.make<string>()
+   *   const deferred = yield* Deferred.make<string>()
    *
    *   // Add a fiber to the map
-   *   const fiber = yield* Effect.forkChild(Effect.succeed("Hello"))
+   *   const fiber = yield* Effect.forkChild(Deferred.await(deferred))
    *   yield* FiberMap.set(map, "greeting", fiber)
    *
    *   // Retrieve the fiber with error handling
    *   const retrieved = yield* FiberMap.get(map, "greeting")
    *   if (retrieved._tag === "Some") {
-   *     const result = yield* Fiber.await(retrieved.value)
+   *     yield* Deferred.succeed(deferred, "Hello")
+   *
+   *     const result = yield* Fiber.join(retrieved.value)
    *     console.log(result) // "Hello"
    *   }
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K): Effect.Effect<Option.Option<Fiber.Fiber<A, E>>>
 } = dual(
@@ -668,7 +794,8 @@ export const get: {
 /**
  * Check if a key exists in the FiberMap.
  *
- * @example
+ * **Example** (Checking if a key exists unsafely)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -676,7 +803,7 @@ export const get: {
  *   const map = yield* FiberMap.make<string>()
  *
  *   // Add a fiber to the map
- *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+ *   yield* FiberMap.run(map, "task1", Effect.never)
  *
  *   // Check if keys exist
  *   console.log(FiberMap.hasUnsafe(map, "task1")) // true
@@ -684,14 +811,15 @@ export const get: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const hasUnsafe: {
   /**
    * Check if a key exists in the FiberMap.
    *
-   * @example
+   * **Example** (Checking if a key exists unsafely)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -699,7 +827,7 @@ export const hasUnsafe: {
    *   const map = yield* FiberMap.make<string>()
    *
    *   // Add a fiber to the map
-   *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+   *   yield* FiberMap.run(map, "task1", Effect.never)
    *
    *   // Check if keys exist
    *   console.log(FiberMap.hasUnsafe(map, "task1")) // true
@@ -707,14 +835,15 @@ export const hasUnsafe: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => boolean
   /**
    * Check if a key exists in the FiberMap.
    *
-   * @example
+   * **Example** (Checking if a key exists unsafely)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -722,7 +851,7 @@ export const hasUnsafe: {
    *   const map = yield* FiberMap.make<string>()
    *
    *   // Add a fiber to the map
-   *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+   *   yield* FiberMap.run(map, "task1", Effect.never)
    *
    *   // Check if keys exist
    *   console.log(FiberMap.hasUnsafe(map, "task1")) // true
@@ -730,8 +859,8 @@ export const hasUnsafe: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K): boolean
 } = dual(
@@ -744,7 +873,8 @@ export const hasUnsafe: {
  * Check if a key exists in the FiberMap.
  * This is the Effect-wrapped version of `hasUnsafe`.
  *
- * @example
+ * **Example** (Checking if a key exists)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -752,7 +882,7 @@ export const hasUnsafe: {
  *   const map = yield* FiberMap.make<string>()
  *
  *   // Add a fiber to the map
- *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+ *   yield* FiberMap.run(map, "task1", Effect.never)
  *
  *   // Check if keys exist using Effect
  *   const exists1 = yield* FiberMap.has(map, "task1")
@@ -763,15 +893,16 @@ export const hasUnsafe: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Check if a key exists in the FiberMap.
    * This is the Effect-wrapped version of `hasUnsafe`.
    *
-   * @example
+   * **Example** (Checking if a key exists)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -779,7 +910,7 @@ export const has: {
    *   const map = yield* FiberMap.make<string>()
    *
    *   // Add a fiber to the map
-   *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+   *   yield* FiberMap.run(map, "task1", Effect.never)
    *
    *   // Check if keys exist using Effect
    *   const exists1 = yield* FiberMap.has(map, "task1")
@@ -790,15 +921,16 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<boolean>
   /**
    * Check if a key exists in the FiberMap.
    * This is the Effect-wrapped version of `hasUnsafe`.
    *
-   * @example
+   * **Example** (Checking if a key exists)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -806,7 +938,7 @@ export const has: {
    *   const map = yield* FiberMap.make<string>()
    *
    *   // Add a fiber to the map
-   *   yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
+   *   yield* FiberMap.run(map, "task1", Effect.never)
    *
    *   // Check if keys exist using Effect
    *   const exists1 = yield* FiberMap.has(map, "task1")
@@ -817,8 +949,8 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K): Effect.Effect<boolean>
 } = dual(
@@ -829,7 +961,8 @@ export const has: {
 /**
  * Remove a fiber from the FiberMap, interrupting it if it exists.
  *
- * @example
+ * **Example** (Removing a fiber)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -849,14 +982,15 @@ export const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const remove: {
   /**
    * Remove a fiber from the FiberMap, interrupting it if it exists.
    *
-   * @example
+   * **Example** (Removing a fiber)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -876,14 +1010,15 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void>
   /**
    * Remove a fiber from the FiberMap, interrupting it if it exists.
    *
-   * @example
+   * **Example** (Removing a fiber)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -903,15 +1038,16 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual<
   /**
    * Remove a fiber from the FiberMap, interrupting it if it exists.
    *
-   * @example
+   * **Example** (Removing a fiber)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -931,14 +1067,15 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K>(key: K) => <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void>,
   /**
    * Remove a fiber from the FiberMap, interrupting it if it exists.
    *
-   * @example
+   * **Example** (Removing a fiber)
+   *
    * ```ts
    * import { Effect, FiberMap } from "effect"
    *
@@ -958,8 +1095,8 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(self: FiberMap<K, A, E>, key: K) => Effect.Effect<void>
 >(2, (self, key) =>
@@ -977,7 +1114,8 @@ export const remove: {
 /**
  * Remove all fibers from the FiberMap, interrupting them.
  *
- * @example
+ * **Example** (Clearing all fibers)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -998,8 +1136,8 @@ export const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const clear = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void> =>
   Effect.suspend(() => {
@@ -1020,10 +1158,13 @@ const constInterruptedFiber = (function() {
 })()
 
 /**
- * Run an Effect and add the forked fiber to the FiberMap.
- * When the fiber completes, it will be removed from the FiberMap.
+ * Forks an Effect and stores the resulting fiber in the `FiberMap` under a key.
+ *
+ * When the fiber completes, it is removed from the map. If the key already has
+ * a fiber, the previous fiber is interrupted unless `onlyIfMissing` is set.
+ *
+ * **Example** (Forking effects into a map)
  *
- * @example
  * ```ts
  * import { Effect, Fiber, FiberMap } from "effect"
  *
@@ -1034,24 +1175,27 @@ const constInterruptedFiber = (function() {
  *   const fiber1 = yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
  *   const fiber2 = yield* FiberMap.run(map, "task2", Effect.succeed("World"))
  *
- *   // Wait for the results
- *   const result1 = yield* Fiber.await(fiber1)
- *   const result2 = yield* Fiber.await(fiber2)
+ *   // Join the fibers to get their successful values
+ *   const result1 = yield* Fiber.join(fiber1)
+ *   const result2 = yield* Fiber.join(fiber2)
  *
  *   console.log(result1, result2) // "Hello", "World"
  *   console.log(yield* FiberMap.size(map)) // 0 (fibers are removed after completion)
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const run: {
   /**
-   * Run an Effect and add the forked fiber to the FiberMap.
-   * When the fiber completes, it will be removed from the FiberMap.
+   * Forks an Effect and stores the resulting fiber in the `FiberMap` under a key.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, the previous fiber is interrupted unless `onlyIfMissing` is set.
+   *
+   * **Example** (Forking effects into a map)
    *
-   * @example
    * ```ts
    * import { Effect, Fiber, FiberMap } from "effect"
    *
@@ -1062,17 +1206,17 @@ export const run: {
    *   const fiber1 = yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
    *   const fiber2 = yield* FiberMap.run(map, "task2", Effect.succeed("World"))
    *
-   *   // Wait for the results
-   *   const result1 = yield* Fiber.await(fiber1)
-   *   const result2 = yield* Fiber.await(fiber2)
+   *   // Join the fibers to get their successful values
+   *   const result1 = yield* Fiber.join(fiber1)
+   *   const result2 = yield* Fiber.join(fiber2)
    *
    *   console.log(result1, result2) // "Hello", "World"
    *   console.log(yield* FiberMap.size(map)) // 0 (fibers are removed after completion)
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E>(
     self: FiberMap<K, A, E>,
@@ -1086,10 +1230,13 @@ 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 FiberMap.
-   * When the fiber completes, it will be removed from the FiberMap.
+   * Forks an Effect and stores the resulting fiber in the `FiberMap` under a key.
+   *
+   * When the fiber completes, it is removed from the map. If the key already has
+   * a fiber, the previous fiber is interrupted unless `onlyIfMissing` is set.
+   *
+   * **Example** (Forking effects into a map)
    *
-   * @example
    * ```ts
    * import { Effect, Fiber, FiberMap } from "effect"
    *
@@ -1100,17 +1247,17 @@ export const run: {
    *   const fiber1 = yield* FiberMap.run(map, "task1", Effect.succeed("Hello"))
    *   const fiber2 = yield* FiberMap.run(map, "task2", Effect.succeed("World"))
    *
-   *   // Wait for the results
-   *   const result1 = yield* Fiber.await(fiber1)
-   *   const result2 = yield* Fiber.await(fiber2)
+   *   // Join the fibers to get their successful values
+   *   const result1 = yield* Fiber.join(fiber1)
+   *   const result2 = yield* Fiber.join(fiber2)
    *
    *   console.log(result1, result2) // "Hello", "World"
    *   console.log(yield* FiberMap.size(map)) // 0 (fibers are removed after completion)
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <K, A, E, R, XE extends E, XA extends A>(
     self: FiberMap<K, A, E>,
@@ -1153,9 +1300,14 @@ const runImpl = <K, 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 FiberMap.
+ * Captures the current runtime and returns a function for forking effects into
+ * an existing `FiberMap`.
+ *
+ * Each call stores the forked fiber under the supplied key. If that key already
+ * has a fiber, the previous fiber is interrupted unless `onlyIfMissing` is set.
+ *
+ * **Example** (Capturing a runtime)
  *
- * @example
  * ```ts
  * import { Effect, FiberMap, Context } from "effect"
  *
@@ -1178,8 +1330,8 @@ const runImpl = <K, A, E, R, XE extends E, XA extends A>(
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const runtime: <K, A, E>(
   self: FiberMap<K, A, E>
@@ -1224,10 +1376,16 @@ export const runtime: <K, A, E>(
   )
 
 /**
- * Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberMap.
- * Returns a Promise instead of a Fiber for convenience.
+ * Captures the current runtime and returns a function for running effects in
+ * an existing `FiberMap` as Promises.
+ *
+ * Each call stores the forked fiber under the supplied key, interrupting any
+ * previous fiber for that key unless `onlyIfMissing` is set. The Promise
+ * resolves with the effect's success value or rejects with the squashed failure
+ * cause.
+ *
+ * **Example** (Running effects as promises)
  *
- * @example
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -1247,8 +1405,8 @@ export const runtime: <K, A, E>(
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export const runtimePromise = <K, A, E>(self: FiberMap<K, A, E>): <R = never>() => Effect.Effect<
   <XE extends E, XA extends A>(
@@ -1289,7 +1447,8 @@ export const runtimePromise = <K, A, E>(self: FiberMap<K, A, E>): <R = never>()
 /**
  * Get the number of fibers currently in the FiberMap.
  *
- * @example
+ * **Example** (Checking the map size)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -1306,17 +1465,22 @@ export const runtimePromise = <K, A, E>(self: FiberMap<K, A, E>): <R = never>()
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const size = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<number> =>
   Effect.sync(() => self.state._tag === "Closed" ? 0 : MutableHashMap.size(self.state.backing))
 
 /**
- * Join all fibers in the FiberMap. If any of the Fiber's in the map terminate with a failure,
- * the returned Effect will terminate with the first failure that occurred.
+ * Waits for the `FiberMap` to fail or close.
+ *
+ * The returned Effect fails with the first managed fiber failure that is not
+ * ignored by the map's interruption rules. Normal successful completion
+ * removes fibers from the map; use `awaitEmpty` to wait until the map has no
+ * fibers.
+ *
+ * **Example** (Joining failing fibers)
  *
- * @example
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -1329,8 +1493,8 @@ export const size = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const join = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =>
   Deferred.await(self.deferred as Deferred.Deferred<void, E>)
@@ -1339,7 +1503,8 @@ export const join = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =
  * Wait for the FiberMap to be empty.
  * This will wait for all currently running fibers to complete.
  *
- * @example
+ * **Example** (Waiting for an empty map)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -1360,8 +1525,8 @@ export const join = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export const awaitEmpty = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =>
   Effect.whileLoop({