effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/FiberMap.d.ts

@@ -12,7 +12,8 @@ declare 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"
  *
@@ -21,8 +22,8 @@ declare 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)
@@ -30,8 +31,8 @@ declare 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>]> {
     readonly [TypeId]: typeof TypeId;
@@ -44,7 +45,12 @@ export interface FiberMap<in out K, out A = unknown, out E = unknown> extends Pi
     };
 }
 /**
- * @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"
  *
@@ -57,8 +63,8 @@ export interface FiberMap<in out K, out A = unknown, out E = unknown> extends Pi
  * })
  * ```
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export declare const isFiberMap: (u: unknown) => u is FiberMap<unknown>;
 /**
@@ -68,7 +74,8 @@ export declare const isFiberMap: (u: unknown) => u is FiberMap<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"
  *
@@ -85,14 +92,20 @@ export declare const isFiberMap: (u: unknown) => u is FiberMap<unknown>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <K, A = unknown, E = unknown>() => Effect.Effect<FiberMap<K, A, E>, never, Scope.Scope>;
 /**
- * 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"
  *
@@ -103,25 +116,31 @@ export declare const make: <K, A = unknown, E = unknown>() => Effect.Effect<Fibe
  *   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 declare const makeRuntime: <R, K, E = unknown, A = unknown>() => Effect.Effect<(<XE extends E, XA extends A>(key: K, effect: Effect.Effect<XA, XE, R>, options?: (Effect.RunOptions & {
     readonly onlyIfMissing?: boolean | undefined;
 }) | undefined) => Fiber.Fiber<XA, XE>), never, Scope.Scope | R>;
 /**
- * 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"
  *
@@ -140,88 +159,112 @@ export declare const makeRuntime: <R, K, E = unknown, A = unknown>() => Effect.E
  * })
  * ```
  *
- * @since 3.13.0
  * @category constructors
+ * @since 3.13.0
  */
 export declare const makeRuntimePromise: <R, K, A = unknown, E = unknown>() => Effect.Effect<(<XE extends E, XA extends A>(key: K, effect: Effect.Effect<XA, XE, R>, options?: (Effect.RunOptions & {
     readonly onlyIfMissing?: boolean | undefined;
 }) | undefined) => Promise<XA>), never, Scope.Scope | R>;
 /**
- * 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 declare 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, fiber: Fiber.Fiber<XA, XE>, options?: {
         readonly onlyIfMissing?: boolean | undefined;
         readonly propagateInterruption?: boolean | undefined;
     } | 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>, key: K, fiber: Fiber.Fiber<XA, XE>, options?: {
         readonly onlyIfMissing?: boolean | undefined;
@@ -229,84 +272,108 @@ export declare const setUnsafe: {
     } | undefined): 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
  */
 export declare 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, fiber: Fiber.Fiber<XA, XE>, options?: {
         readonly onlyIfMissing?: boolean | undefined;
         readonly propagateInterruption?: boolean | undefined;
     } | 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>, key: K, fiber: Fiber.Fiber<XA, XE>, options?: {
         readonly onlyIfMissing?: boolean | undefined;
@@ -316,82 +383,94 @@ export declare 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 declare 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>>;
 };
@@ -400,28 +479,32 @@ export declare 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 declare const get: {
     /**
@@ -429,28 +512,32 @@ export declare 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>>>;
     /**
@@ -458,35 +545,40 @@ export declare 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>>>;
 };
 /**
  * Check if a key exists in the FiberMap.
  *
- * @example
+ * **Example** (Checking if a key exists unsafely)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -494,7 +586,7 @@ export declare 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
@@ -502,14 +594,15 @@ export declare const get: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const hasUnsafe: {
     /**
      * Check if a key exists in the FiberMap.
      *
-     * @example
+     * **Example** (Checking if a key exists unsafely)
+     *
      * ```ts
      * import { Effect, FiberMap } from "effect"
      *
@@ -517,7 +610,7 @@ export declare 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
@@ -525,14 +618,15 @@ export declare 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"
      *
@@ -540,7 +634,7 @@ export declare 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
@@ -548,8 +642,8 @@ export declare const hasUnsafe: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <K, A, E>(self: FiberMap<K, A, E>, key: K): boolean;
 };
@@ -557,7 +651,8 @@ export declare 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"
  *
@@ -565,7 +660,7 @@ export declare 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")
@@ -576,15 +671,16 @@ export declare const hasUnsafe: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -592,7 +688,7 @@ export declare 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")
@@ -603,15 +699,16 @@ export declare 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"
      *
@@ -619,7 +716,7 @@ export declare 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")
@@ -630,15 +727,16 @@ export declare 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>;
 };
 /**
  * Remove a fiber from the FiberMap, interrupting it if it exists.
  *
- * @example
+ * **Example** (Removing a fiber)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -658,14 +756,15 @@ export declare const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const remove: {
     /**
      * Remove a fiber from the FiberMap, interrupting it if it exists.
      *
-     * @example
+     * **Example** (Removing a fiber)
+     *
      * ```ts
      * import { Effect, FiberMap } from "effect"
      *
@@ -685,14 +784,15 @@ export declare 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"
      *
@@ -712,15 +812,16 @@ export declare 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>;
 };
 /**
  * Remove all fibers from the FiberMap, interrupting them.
  *
- * @example
+ * **Example** (Clearing all fibers)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -741,15 +842,18 @@ export declare const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const clear: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void>;
 /**
- * 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"
  *
@@ -760,24 +864,27 @@ export declare const clear: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<
  *   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 declare 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"
      *
@@ -788,17 +895,17 @@ export declare 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>, key: K, options?: {
         readonly onlyIfMissing?: boolean | undefined;
@@ -806,10 +913,13 @@ export declare const run: {
         readonly startImmediately?: boolean | undefined;
     } | undefined): <R, XE extends E, XA extends A>(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"
      *
@@ -820,17 +930,17 @@ export declare 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>, key: K, effect: Effect.Effect<XA, XE, R>, options?: {
         readonly onlyIfMissing?: boolean | undefined;
@@ -839,9 +949,14 @@ export declare const run: {
     } | undefined): Effect.Effect<Fiber.Fiber<XA, XE>, never, R>;
 };
 /**
- * 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"
  *
@@ -857,25 +972,31 @@ export declare const run: {
  *   const run = yield* FiberMap.runtime(map)<Users>()
  *
  *   // run some effects and add the fibers to the map
- *   run("effect-a", Effect.andThen(Users.asEffect(), (_) => _.getAll))
- *   run("effect-b", Effect.andThen(Users.asEffect(), (_) => _.getAll))
+ *   run("effect-a", Effect.andThen(Users, (_) => _.getAll))
+ *   run("effect-b", Effect.andThen(Users, (_) => _.getAll))
  * }).pipe(
  *   Effect.scoped // The fibers will be interrupted when the scope is closed
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const runtime: <K, A, E>(self: FiberMap<K, A, E>) => <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(key: K, effect: Effect.Effect<XA, XE, R>, options?: Effect.RunOptions & {
     readonly onlyIfMissing?: boolean | undefined;
     readonly propagateInterruption?: boolean | undefined;
 } | undefined) => Fiber.Fiber<XA, XE>), never, R>;
 /**
- * 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"
  *
@@ -895,8 +1016,8 @@ export declare const runtime: <K, A, E>(self: FiberMap<K, A, E>) => <R = never>(
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export declare const runtimePromise: <K, A, E>(self: FiberMap<K, A, E>) => <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(key: K, effect: Effect.Effect<XA, XE, R>, options?: (Effect.RunOptions & {
     readonly onlyIfMissing?: boolean | undefined;
@@ -905,7 +1026,8 @@ export declare const runtimePromise: <K, A, E>(self: FiberMap<K, A, E>) => <R =
 /**
  * Get the number of fibers currently in the FiberMap.
  *
- * @example
+ * **Example** (Checking the map size)
+ *
  * ```ts
  * import { Effect, FiberMap } from "effect"
  *
@@ -922,15 +1044,20 @@ export declare const runtimePromise: <K, A, E>(self: FiberMap<K, A, E>) => <R =
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const size: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<number>;
 /**
- * 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"
  *
@@ -943,15 +1070,16 @@ export declare const size: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<n
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare 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"
  *
@@ -972,8 +1100,8 @@ export declare const join: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<v
  * })
  * ```
  *
- * @since 3.13.0
  * @category combinators
+ * @since 3.13.0
  */
 export declare const awaitEmpty: <K, A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void, E>;
 export {};