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

package/src/Fiber.ts

@@ -16,7 +16,8 @@
  * - **Supervision**: Monitor and restart failed fibers
  * - **Resource management**: Ensure proper cleanup on interruption
  *
- * @example
+ * **Example** (Running effects in fibers)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -95,7 +96,8 @@ const TypeId = `~effect/Fiber/${version}`
  * Effects concurrently while maintaining structured concurrency and
  * cancellation safety.
  *
- * @example
+ * **Example** (Awaiting a forked fiber)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -111,8 +113,8 @@ const TypeId = `~effect/Fiber/${version}`
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Fiber<out A, out E = never> extends Pipeable {
   readonly [TypeId]: Fiber.Variance<A, E>
@@ -142,7 +144,8 @@ export interface Fiber<out A, out E = never> extends Pipeable {
  * The Fiber namespace contains utility types and functions for working with fibers.
  * It provides type-level utilities for fiber operations and variance encoding.
  *
- * @example
+ * **Example** (Working with fiber types)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -162,15 +165,16 @@ export interface Fiber<out A, out E = never> extends Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export declare namespace Fiber {
   /**
    * Variance encoding for the Fiber type, specifying covariance in both the
    * success type `A` and the error type `E`.
    *
-   * @example
+   * **Example** (Upcasting fibers safely)
+   *
    * ```ts
    * import type { Fiber } from "effect"
    *
@@ -179,8 +183,8 @@ export declare namespace Fiber {
    * const upcast: Fiber.Fiber<unknown, unknown> = fiber
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export interface Variance<out A, out E = never> {
     readonly _A: Covariant<A>
@@ -193,7 +197,8 @@ export {
   /**
    * Waits for a fiber to complete and returns its exit value.
    *
-   * @example
+   * **Example** (Awaiting a fiber exit)
+   *
    * ```ts
    * import { Effect, Fiber } from "effect"
    *
@@ -204,8 +209,8 @@ export {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   await_ as await
 }
@@ -213,7 +218,8 @@ export {
  * Waits for all fibers in the provided iterable to complete and returns
  * an array of their exit values.
  *
- * @example
+ * **Example** (Awaiting multiple fiber exits)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -225,8 +231,8 @@ export {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const awaitAll: <A extends Fiber<any, any>>(
   self: Iterable<A>
@@ -243,7 +249,8 @@ export const awaitAll: <A extends Fiber<any, any>>(
  * Joins a fiber, blocking until it completes. If the fiber succeeds,
  * returns its value. If it fails, the error is propagated.
  *
- * @example
+ * **Example** (Joining a fiber)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -254,14 +261,20 @@ export const awaitAll: <A extends Fiber<any, any>>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const join: <A, E>(self: Fiber<A, E>) => Effect<A, E> = effect.fiberJoin
 
 /**
- * @since 2.0.0
+ * Waits for all fibers to succeed and returns their values in input order.
+ *
+ * If any fiber fails, the returned `Effect` fails with that fiber's cause and
+ * stops waiting for additional results. This does not interrupt the remaining
+ * fibers.
+ *
  * @category combinators
+ * @since 2.0.0
  */
 export const joinAll: <A extends Iterable<Fiber<any, any>>>(
   self: A
@@ -277,7 +290,8 @@ export const joinAll: <A extends Iterable<Fiber<any, any>>>(
  * Interrupts a fiber, causing it to stop executing and clean up any
  * acquired resources.
  *
- * @example
+ * **Example** (Interrupting a fiber)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -290,8 +304,8 @@ export const joinAll: <A extends Iterable<Fiber<any, any>>>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category interruption
+ * @since 2.0.0
  */
 export const interrupt: <A, E>(self: Fiber<A, E>) => Effect<void> = effect.fiberInterrupt
 
@@ -299,7 +313,8 @@ export const interrupt: <A, E>(self: Fiber<A, E>) => Effect<void> = effect.fiber
  * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
  * tracking which fiber initiated the interruption.
  *
- * @example
+ * **Example** (Interrupting a fiber as another fiber)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -314,15 +329,16 @@ export const interrupt: <A, E>(self: Fiber<A, E>) => Effect<void> = effect.fiber
  * })
  * ```
  *
- * @since 2.0.0
  * @category interruption
+ * @since 2.0.0
  */
 export const interruptAs: {
   /**
    * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
    * tracking which fiber initiated the interruption.
    *
-   * @example
+   * **Example** (Interrupting a fiber as another fiber)
+   *
    * ```ts
    * import { Effect, Fiber } from "effect"
    *
@@ -337,8 +353,8 @@ export const interruptAs: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category interruption
+   * @since 2.0.0
    */
   (
     fiberId: number | undefined,
@@ -348,7 +364,8 @@ export const interruptAs: {
    * Interrupts a fiber with a specific fiber ID as the interruptor. This allows
    * tracking which fiber initiated the interruption.
    *
-   * @example
+   * **Example** (Interrupting a fiber as another fiber)
+   *
    * ```ts
    * import { Effect, Fiber } from "effect"
    *
@@ -363,8 +380,8 @@ export const interruptAs: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category interruption
+   * @since 2.0.0
    */
   <A, E>(
     self: Fiber<A, E>,
@@ -377,7 +394,8 @@ export const interruptAs: {
  * Interrupts all fibers in the provided iterable, causing them to stop executing
  * and clean up any acquired resources.
  *
- * @example
+ * **Example** (Interrupting multiple fibers)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -415,8 +433,8 @@ export const interruptAs: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category interruption
+ * @since 2.0.0
  */
 export const interruptAll: <A extends Iterable<Fiber<any, any>>>(
   fibers: A
@@ -427,7 +445,8 @@ export const interruptAll: <A extends Iterable<Fiber<any, any>>>(
  * interrupting fiber. This allows you to control which fiber is considered the source
  * of the interruption, which can be useful for debugging and tracing.
  *
- * @example
+ * **Example** (Interrupting multiple fibers as another fiber)
+ *
  * ```ts
  * import { Console, Effect, Fiber } from "effect"
  *
@@ -460,8 +479,8 @@ export const interruptAll: <A extends Iterable<Fiber<any, any>>>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category interruption
+ * @since 2.0.0
  */
 export const interruptAllAs: {
   /**
@@ -469,7 +488,8 @@ export const interruptAllAs: {
    * interrupting fiber. This allows you to control which fiber is considered the source
    * of the interruption, which can be useful for debugging and tracing.
    *
-   * @example
+   * **Example** (Interrupting multiple fibers as another fiber)
+   *
    * ```ts
    * import { Console, Effect, Fiber } from "effect"
    *
@@ -502,8 +522,8 @@ export const interruptAllAs: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category interruption
+   * @since 2.0.0
    */
   (fiberId: number): <A extends Iterable<Fiber<any, any>>>(fibers: A) => Effect<void>
   /**
@@ -511,7 +531,8 @@ export const interruptAllAs: {
    * interrupting fiber. This allows you to control which fiber is considered the source
    * of the interruption, which can be useful for debugging and tracing.
    *
-   * @example
+   * **Example** (Interrupting multiple fibers as another fiber)
+   *
    * ```ts
    * import { Console, Effect, Fiber } from "effect"
    *
@@ -544,8 +565,8 @@ export const interruptAllAs: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category interruption
+   * @since 2.0.0
    */
   <A extends Iterable<Fiber<any, any>>>(fibers: A, fiberId: number): Effect<void>
 } = effect.fiberInterruptAllAs
@@ -554,7 +575,8 @@ export const interruptAllAs: {
  * Tests if a value is a Fiber. This is a type guard that can be used to
  * determine if an unknown value is a Fiber instance.
  *
- * @example
+ * **Example** (Checking for fibers)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -577,8 +599,8 @@ export const interruptAllAs: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isFiber = (
   u: unknown
@@ -588,7 +610,8 @@ export const isFiber = (
  * Returns the current fiber if called from within a fiber context,
  * otherwise returns `undefined`.
  *
- * @example
+ * **Example** (Getting the current fiber)
+ *
  * ```ts
  * import { Effect, Fiber } from "effect"
  *
@@ -600,30 +623,39 @@ export const isFiber = (
  * })
  * ```
  *
- * @since 2.0.0
  * @category accessors
+ * @since 2.0.0
  */
 export const getCurrent: () => Fiber<any, any> | undefined = effect.getCurrentFiber
 
 /**
- * Links the lifetime of a fiber to the provided scope.
+ * Links a fiber to a `Scope` and returns the same fiber.
+ *
+ * When the scope is closed, the fiber is interrupted. If the scope is already
+ * closed, the fiber is interrupted immediately.
  *
- * @since 4.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export const runIn: {
   /**
-   * Links the lifetime of a fiber to the provided scope.
+   * Links a fiber to a `Scope` and returns the same fiber.
+   *
+   * When the scope is closed, the fiber is interrupted. If the scope is already
+   * closed, the fiber is interrupted immediately.
    *
-   * @since 4.0.0
    * @category Scope
+   * @since 4.0.0
    */
   (scope: Scope): <A, E>(self: Fiber<A, E>) => Fiber<A, E>
   /**
-   * Links the lifetime of a fiber to the provided scope.
+   * Links a fiber to a `Scope` and returns the same fiber.
+   *
+   * When the scope is closed, the fiber is interrupted. If the scope is already
+   * closed, the fiber is interrupted immediately.
    *
-   * @since 4.0.0
    * @category Scope
+   * @since 4.0.0
    */
   <A, E>(self: Fiber<A, E>, scope: Scope): Fiber<A, E>
 } = effect.fiberRunIn