effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Exit.ts

@@ -76,9 +76,9 @@ const TypeId = core.ExitTypeId
  *
  * **Details**
  *
- * An `Exit<A, E>` is either:
- * - `Success<A, E>` containing a value of type `A`
- * - `Failure<A, E>` containing a `Cause<E>` describing why the computation failed
+ * An `Exit<A, E>` is either `Success<A, E>` containing a value of type `A`, or
+ * `Failure<A, E>` containing a `Cause<E>` describing why the computation
+ * failed.
  *
  * Since `Exit` is also an `Effect`, you can yield it inside `Effect.gen`.
  *
@@ -179,7 +179,7 @@ export interface Success<out A, out E = never> extends Exit.Proto<A, E> {
  *
  * **Details**
  *
- * - The `Cause<E>` may contain typed errors, defects, or interruptions
+ * The `Cause<E>` may contain typed errors, defects, or interruptions.
  *
  * **Example** (Accessing the failure cause)
  *
@@ -210,8 +210,8 @@ export interface Failure<out A, out E> extends Exit.Proto<A, E> {
  *
  * **When to use**
  *
- * Use to validate unknown values at system boundaries
- * - Works as a type guard, narrowing to `Exit<unknown, unknown>`
+ * Use to validate unknown values at system boundaries and narrow them to
+ * `Exit<unknown, unknown>`.
  *
  * **Details**
  *
@@ -241,8 +241,7 @@ export const isExit: (u: unknown) => u is Exit<unknown, unknown> = core.isExit
  *
  * **When to use**
  *
- * Use to wrap a known success value into an Exit
- * - Use when constructing test data or returning explicit results
+ * Use when you need an Exit that contains a known success value.
  *
  * **Details**
  *
@@ -272,7 +271,8 @@ export const succeed: <A>(a: A) => Exit<A> = core.exitSucceed
  * **When to use**
  *
  * Use when you already have a `Cause<E>` and want to wrap it in an Exit
- * - Use for advanced error handling where you need full control over the Cause structure
+ * for advanced error handling where you need full control over the Cause
+ * structure.
  *
  * **Details**
  *
@@ -302,11 +302,11 @@ export const failCause: <E>(cause: Cause.Cause<E>) => Exit<never, E> = core.exit
  *
  * **When to use**
  *
- * Use when you need expected, recoverable failures
+ * Use when you need to represent an expected typed failure as an `Exit`.
  *
  * **Details**
  *
- * - The error is wrapped in a `Cause.Fail` internally
+ * The error is wrapped in a `Cause.Fail` internally.
  *
  * Returns a `Failure<never, E>`.
  *
@@ -333,11 +333,12 @@ export const fail: <E>(e: E) => Exit<never, E> = core.exitFail
  *
  * **When to use**
  *
- * Use when you need unexpected, unrecoverable errors that should not appear in the typed error channel
+ * Use when you need unexpected, unrecoverable errors that should not appear in
+ * the typed error channel.
  *
  * **Details**
  *
- * - The defect is wrapped in a `Cause.Die` internally
+ * The defect is wrapped in a `Cause.Die` internally.
  *
  * Returns a `Failure<never>` with `E = never`, since defects do not appear in
  * the typed error channel.
@@ -364,13 +365,12 @@ export const die: (defect: unknown) => Exit<never> = core.exitDie
  *
  * **When to use**
  *
- * Use to signal that a fiber was interrupted
+ * Use to signal that a fiber was interrupted.
  *
  * **Details**
  *
- * - Optionally pass a fiber ID to identify which fiber was interrupted
- *
- * Returns a `Failure<never>` with an `Interrupt` cause.
+ * Optionally pass a fiber ID to identify which fiber was interrupted. Returns
+ * a `Failure<never>` with an `Interrupt` cause.
  *
  * **Example** (Creating an interruption Exit)
  *
@@ -396,12 +396,12 @@ export {
    *
    * **When to use**
    *
-   * Use when you need a success Exit but do not care about the value
-   * - Avoids allocating a new Exit for a common case
+   * Use when you need a shared successful `Exit` with no meaningful value.
    *
    * **Details**
    *
-   * Equivalent to `Exit.succeed(undefined)` but shared as a single instance.
+   * Equivalent to `Exit.succeed(undefined)` but shared as a single instance,
+   * avoiding allocation for a common case.
    *
    * **Example** (Using the void Exit)
    *
@@ -426,8 +426,8 @@ export {
  *
  * **When to use**
  *
- * Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>`
- * - After narrowing, the `value` property becomes accessible
+ * Use as a type guard to narrow `Exit<A, E>` to `Success<A, E>` and access the
+ * `value` property.
  *
  * **Example** (Narrowing to Success)
  *
@@ -454,8 +454,8 @@ export const isSuccess: <A, E>(self: Exit<A, E>) => self is Success<A, E> = effe
  *
  * **When to use**
  *
- * Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>`
- * - After narrowing, the `cause` property becomes accessible
+ * Use as a type guard to narrow `Exit<A, E>` to `Failure<A, E>` and access the
+ * `cause` property.
  *
  * **Example** (Narrowing to Failure)
  *
@@ -482,14 +482,12 @@ export const isFailure: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effe
  *
  * **When to use**
  *
- * Use to distinguish typed failures from defects or interruptions
+ * Use to distinguish typed failures from defects or interruptions.
  *
  * **Details**
  *
- * - Returns `false` for successful exits
- *
- * Only checks for `Fail` reasons in the Cause. A Cause with only `Die` or
- * `Interrupt` reasons returns `false`.
+ * Returns `false` for successful exits. Only checks for `Fail` reasons in the
+ * Cause. A Cause with only `Die` or `Interrupt` reasons returns `false`.
  *
  * **Example** (Checking for typed errors)
  *
@@ -514,14 +512,12 @@ export const hasFails: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effec
  *
  * **When to use**
  *
- * Use to check for unexpected errors
+ * Use to check whether an `Exit` failure cause contains unexpected errors.
  *
  * **Details**
  *
- * - Returns `false` for successful exits
- *
- * Only checks for `Die` reasons in the Cause. A Cause with only `Fail` or
- * `Interrupt` reasons returns `false`.
+ * Returns `false` for successful exits. Only checks for `Die` reasons in the
+ * Cause. A Cause with only `Fail` or `Interrupt` reasons returns `false`.
  *
  * **Example** (Checking for defects)
  *
@@ -546,14 +542,12 @@ export const hasDies: <A, E>(self: Exit<A, E>) => self is Failure<A, E> = effect
  *
  * **When to use**
  *
- * Use to check if a fiber was interrupted
+ * Use to check whether an `Exit` contains fiber interruption.
  *
  * **Details**
  *
- * - Returns `false` for successful exits
- *
- * Only checks for `Interrupt` reasons in the Cause. A Cause with only `Fail`
- * or `Die` reasons returns `false`.
+ * Returns `false` for successful exits. Only checks for `Interrupt` reasons in
+ * the Cause. A Cause with only `Fail` or `Die` reasons returns `false`.
  *
  * **Example** (Checking for interruptions)
  *
@@ -730,8 +724,8 @@ export const filterCause: <A, E>(self: Exit<A, E>) => Result.Result<Cause.Cause<
  *
  * **When to use**
  *
- * Use when composing Exit checks with `Filter` or other `Result`-based
- * filtering APIs and you only need the first typed error in the Cause.
+ * Use when you need the first typed error from an `Exit` as a `Result` for
+ * `Filter` or other `Result`-based filtering APIs.
  *
  * **Details**
  *
@@ -770,8 +764,8 @@ export const findError: <A, E>(input: Exit<A, E>) => Result.Result<E, Exit<A, E>
  *
  * **When to use**
  *
- * Use when composing Exit checks with `Filter` or other `Result`-based
- * filtering APIs and you only need the first defect in the Cause.
+ * Use when you need the first defect from an `Exit` as a `Result` for
+ * `Filter` or other `Result`-based filtering APIs.
  *
  * **Details**
  *
@@ -810,14 +804,13 @@ export const findDefect: <A, E>(input: Exit<A, E>) => Result.Result<unknown, Exi
  *
  * **When to use**
  *
- * Use when you need exhaustive handling of both outcomes
+ * Use when you need exhaustive handling of both `Exit` success and failure
+ * outcomes.
  *
  * **Details**
  *
- * - Calls `onSuccess` with the value if the Exit is a Success
- * - Calls `onFailure` with the Cause if the Exit is a Failure
- *
- * Supports both curried and direct call styles (data-last and data-first).
+ * Calls `onSuccess` with the value if the Exit is a Success, and calls
+ * `onFailure` with the Cause if the Exit is a Failure.
  *
  * **Example** (Matching on an Exit)
  *
@@ -844,14 +837,13 @@ export const match: {
    *
    * **When to use**
    *
-   * Use when you need exhaustive handling of both outcomes
+   * Use when you need exhaustive handling of both `Exit` success and failure
+   * outcomes.
    *
    * **Details**
    *
-   * - Calls `onSuccess` with the value if the Exit is a Success
-   * - Calls `onFailure` with the Cause if the Exit is a Failure
-   *
-   * Supports both curried and direct call styles (data-last and data-first).
+   * Calls `onSuccess` with the value if the Exit is a Success, and calls
+   * `onFailure` with the Cause if the Exit is a Failure.
    *
    * **Example** (Matching on an Exit)
    *
@@ -883,14 +875,13 @@ export const match: {
    *
    * **When to use**
    *
-   * Use when you need exhaustive handling of both outcomes
+   * Use when you need exhaustive handling of both `Exit` success and failure
+   * outcomes.
    *
    * **Details**
    *
-   * - Calls `onSuccess` with the value if the Exit is a Success
-   * - Calls `onFailure` with the Cause if the Exit is a Failure
-   *
-   * Supports both curried and direct call styles (data-last and data-first).
+   * Calls `onSuccess` with the value if the Exit is a Success, and calls
+   * `onFailure` with the Cause if the Exit is a Failure.
    *
    * **Example** (Matching on an Exit)
    *
@@ -929,10 +920,9 @@ export const match: {
  *
  * **Details**
  *
- * - Has no effect on failures, which pass through unchanged
+ * Failures pass through unchanged.
  *
  * Allocates a new Exit if successful.
- * Supports both curried and direct call styles.
  *
  * **Example** (Mapping over a success)
  *
@@ -960,10 +950,9 @@ export const map: {
    *
    * **Details**
    *
-   * - Has no effect on failures, which pass through unchanged
+   * Failures pass through unchanged.
    *
    * Allocates a new Exit if successful.
-   * Supports both curried and direct call styles.
    *
    * **Example** (Mapping over a success)
    *
@@ -991,10 +980,9 @@ export const map: {
    *
    * **Details**
    *
-   * - Has no effect on failures, which pass through unchanged
+   * Failures pass through unchanged.
    *
    * Allocates a new Exit if successful.
-   * Supports both curried and direct call styles.
    *
    * **Example** (Mapping over a success)
    *
@@ -1024,10 +1012,9 @@ export const map: {
  *
  * **Details**
  *
- * - Has no effect on successes, which pass through unchanged
+ * Successes pass through unchanged.
  *
  * Allocates a new Exit if the error is transformed.
- * Supports both curried and direct call styles.
  *
  * **Gotchas**
  *
@@ -1062,10 +1049,9 @@ export const mapError: {
    *
    * **Details**
    *
-   * - Has no effect on successes, which pass through unchanged
+   * Successes pass through unchanged.
    *
    * Allocates a new Exit if the error is transformed.
-   * Supports both curried and direct call styles.
    *
    * **Gotchas**
    *
@@ -1100,10 +1086,9 @@ export const mapError: {
    *
    * **Details**
    *
-   * - Has no effect on successes, which pass through unchanged
+   * Successes pass through unchanged.
    *
    * Allocates a new Exit if the error is transformed.
-   * Supports both curried and direct call styles.
    *
    * **Gotchas**
    *
@@ -1136,15 +1121,13 @@ export const mapError: {
  *
  * **When to use**
  *
- * Use when you need to remap both channels in one step
+ * Use when you need to remap both channels in one step.
  *
  * **Details**
  *
- * - `onSuccess` transforms the value if the Exit is a Success
- * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
- *
+ * `onSuccess` transforms the value if the Exit is a Success. `onFailure`
+ * transforms the typed error if the Exit is a Failure with a Fail reason.
  * Allocates a new Exit.
- * Supports both curried and direct call styles.
  *
  * **Gotchas**
  *
@@ -1178,15 +1161,13 @@ export const mapBoth: {
    *
    * **When to use**
    *
-   * Use when you need to remap both channels in one step
+   * Use when you need to remap both channels in one step.
    *
    * **Details**
    *
-   * - `onSuccess` transforms the value if the Exit is a Success
-   * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
-   *
+   * `onSuccess` transforms the value if the Exit is a Success. `onFailure`
+   * transforms the typed error if the Exit is a Failure with a Fail reason.
    * Allocates a new Exit.
-   * Supports both curried and direct call styles.
    *
    * **Gotchas**
    *
@@ -1222,15 +1203,13 @@ export const mapBoth: {
    *
    * **When to use**
    *
-   * Use when you need to remap both channels in one step
+   * Use when you need to remap both channels in one step.
    *
    * **Details**
    *
-   * - `onSuccess` transforms the value if the Exit is a Success
-   * - `onFailure` transforms the typed error if the Exit is a Failure with a Fail reason
-   *
+   * `onSuccess` transforms the value if the Exit is a Success. `onFailure`
+   * transforms the typed error if the Exit is a Failure with a Fail reason.
    * Allocates a new Exit.
-   * Supports both curried and direct call styles.
    *
    * **Gotchas**
    *
@@ -1269,11 +1248,12 @@ export const mapBoth: {
  *
  * **When to use**
  *
- * Use when you only care about whether the computation succeeded or failed, not the value
+ * Use when you need to discard a successful `Exit` value while preserving
+ * whether the `Exit` succeeded or failed.
  *
  * **Details**
  *
- * - Failures pass through unchanged
+ * Failures pass through unchanged.
  *
  * Allocates a new Exit if successful.
  *
@@ -1304,8 +1284,8 @@ export const asVoid: <A, E>(self: Exit<A, E>) => Exit<void, E> = effect.exitAsVo
  *
  * **Details**
  *
- * - If all exits are successful, returns a void success
- * - If any exit is a failure, returns a single failure with all error causes combined
+ * If all exits are successful, this returns a void success. If any exit is a
+ * failure, this returns a single failure with all error causes combined.
  *
  * Iterates over the entire collection. Collects all failure causes, not just
  * the first.
@@ -1336,11 +1316,12 @@ export const asVoidAll: <I extends Iterable<Exit<any, any>>>(
  *
  * **When to use**
  *
- * Use when you want to optionally extract the value without pattern matching
+ * Use when you need the success value from an `Exit` as an `Option` instead of
+ * pattern matching.
  *
  * **Details**
  *
- * - Returns `Option.some(value)` for a Success, `Option.none()` for a Failure
+ * Returns `Option.some(value)` for a Success and `Option.none()` for a Failure.
  *
  * **Example** (Getting the success value)
  *
@@ -1364,11 +1345,12 @@ export const getSuccess: <A, E>(self: Exit<A, E>) => Option<A> = effect.exitGetS
  *
  * **When to use**
  *
- * Use when you want to optionally inspect the failure cause
+ * Use when you need the failure `Cause` from an `Exit` as an `Option` instead
+ * of pattern matching.
  *
  * **Details**
  *
- * - Returns `Option.some(cause)` for a Failure, `Option.none()` for a Success
+ * Returns `Option.some(cause)` for a Failure and `Option.none()` for a Success.
  *
  * **Example** (Getting the failure cause)
  *
@@ -1392,12 +1374,13 @@ export const getCause: <A, E>(self: Exit<A, E>) => Option<Cause.Cause<E>> = effe
  *
  * **When to use**
  *
- * Use when you want to optionally extract a typed error without dealing with the full Cause
+ * Use when you need the first typed error from an `Exit` as an `Option`,
+ * ignoring successes and non-typed failures.
  *
  * **Details**
  *
- * - Returns `Option.some(error)` if the Cause contains a Fail reason, `Option.none()` otherwise
- * - Returns `Option.none()` for successes, defect-only failures, and interrupt-only failures
+ * Returns `Option.some(error)` if the Cause contains a Fail reason. Successes,
+ * defect-only failures, and interrupt-only failures return `Option.none()`.
  *
  * **Gotchas**
  *

package/src/Fiber.ts

@@ -291,8 +291,8 @@ export const awaitAll: <A extends Fiber<any, any>>(
  *
  * **When to use**
  *
- * Use when the forked fiber is part of the current workflow and
- * its failure should fail the current Effect.
+ * Use when you need a forked fiber's failure to fail the current Effect because
+ * that fiber is part of the current workflow.
  *
  * **Gotchas**
  *
@@ -323,8 +323,8 @@ export const join: <A, E>(self: Fiber<A, E>) => Effect<A, E> = effect.fiberJoin
  *
  * **When to use**
  *
- * Use when every fiber must succeed and you want the successful values rather
- * than the `Exit` values.
+ * Use when you need every fiber to succeed and want the successful values
+ * rather than the `Exit` values.
  *
  * **Details**
  *
@@ -358,7 +358,8 @@ export const joinAll: <A extends Iterable<Fiber<any, any>>>(
  *
  * **When to use**
  *
- * Use when a forked fiber is no longer needed and should be cancelled.
+ * Use when you need to cancel a forked fiber and wait for its cleanup to
+ * complete.
  *
  * **Details**
  *
@@ -526,7 +527,8 @@ export const interruptAs: {
  *
  * **When to use**
  *
- * Use when a group of forked fibers is no longer needed.
+ * Use when you need to cancel several forked fibers and wait for their cleanup
+ * to complete.
  *
  * **Details**
  *

package/src/FiberHandle.ts

@@ -235,6 +235,11 @@ export const makeRuntime = <R, E = unknown, A = unknown>(): Effect.Effect<
  * Creates a scoped run function that forks effects into a new `FiberHandle`
  * and returns a `Promise` for each effect result.
  *
+ * **When to use**
+ *
+ * Use when integrating a scoped `FiberHandle` runner with Promise-based APIs
+ * and Promise rejection from squashed failures is the desired boundary.
+ *
  * **Details**
  *
  * Each call stores the fiber in the handle and interrupts the previous fiber
@@ -287,6 +292,11 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * Sets 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.
  *
+ * **When to use**
+ *
+ * Use when an existing forked fiber must be installed synchronously into a
+ * handle and immediate interruption of replaced or closed fibers is acceptable.
+ *
  * **Example** (Setting a fiber unsafely)
  *
  * ```ts
@@ -313,6 +323,11 @@ export const setUnsafe: {
    * Sets 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.
    *
+   * **When to use**
+   *
+   * Use when an existing forked fiber must be installed synchronously into a
+   * handle and immediate interruption of replaced or closed fibers is acceptable.
+   *
    * **Example** (Setting a fiber unsafely)
    *
    * ```ts
@@ -345,6 +360,11 @@ export const setUnsafe: {
    * Sets 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.
    *
+   * **When to use**
+   *
+   * Use when an existing forked fiber must be installed synchronously into a
+   * handle and immediate interruption of replaced or closed fibers is acceptable.
+   *
    * **Example** (Setting a fiber unsafely)
    *
    * ```ts
@@ -538,6 +558,11 @@ export const set: {
 /**
  * Retrieves the fiber from the FiberHandle synchronously.
  *
+ * **When to use**
+ *
+ * Use when synchronous inspection of the current fiber is needed and an
+ * `Option` result is enough outside the Effect workflow.
+ *
  * **Example** (Reading the current fiber unsafely)
  *
  * ```ts

package/src/FiberMap.ts

@@ -253,6 +253,11 @@ export const makeRuntime = <R, K, E = unknown, A = unknown>(): Effect.Effect<
  * Creates a scoped run function that forks effects into a new `FiberMap` and
  * returns a `Promise` for each effect result.
  *
+ * **When to use**
+ *
+ * Use when keyed fibers must be managed in a scoped map while exposing their
+ * results through Promise-based APIs.
+ *
  * **Details**
  *
  * Each call stores the fiber under the supplied key, interrupting any previous
@@ -311,6 +316,11 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
  * mutation.
  *
+ * **When to use**
+ *
+ * Use when an existing forked fiber must be installed under a key immediately
+ * and synchronous interruption of the replaced fiber is acceptable.
+ *
  * **Details**
  *
  * When the fiber completes, it is removed from the map. If the key already has
@@ -346,6 +356,11 @@ export const setUnsafe: {
    * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
    * mutation.
    *
+   * **When to use**
+   *
+   * Use when an existing forked fiber must be installed under a key immediately
+   * and synchronous interruption of the replaced fiber is acceptable.
+   *
    * **Details**
    *
    * When the fiber completes, it is removed from the map. If the key already has
@@ -388,6 +403,11 @@ export const setUnsafe: {
    * Adds a fiber to the `FiberMap` under a key using a synchronous, unsafe
    * mutation.
    *
+   * **When to use**
+   *
+   * Use when an existing forked fiber must be installed under a key immediately
+   * and synchronous interruption of the replaced fiber is acceptable.
+   *
    * **Details**
    *
    * When the fiber completes, it is removed from the map. If the key already has
@@ -610,6 +630,11 @@ export const set: {
 /**
  * Retrieves a fiber from the FiberMap synchronously.
  *
+ * **When to use**
+ *
+ * Use when synchronous keyed lookup of a fiber in a `FiberMap` is needed and an
+ * `Option` result is enough outside the Effect workflow.
+ *
  * **Example** (Retrieving a fiber unsafely)
  *
  * ```ts
@@ -641,6 +666,11 @@ export const getUnsafe: {
   /**
    * Retrieves a fiber from the FiberMap synchronously.
    *
+   * **When to use**
+   *
+   * Use when synchronous keyed lookup of a fiber in a `FiberMap` is needed and an
+   * `Option` result is enough outside the Effect workflow.
+   *
    * **Example** (Retrieving a fiber unsafely)
    *
    * ```ts
@@ -672,6 +702,11 @@ export const getUnsafe: {
   /**
    * Retrieves a fiber from the FiberMap synchronously.
    *
+   * **When to use**
+   *
+   * Use when synchronous keyed lookup of a fiber in a `FiberMap` is needed and an
+   * `Option` result is enough outside the Effect workflow.
+   *
    * **Example** (Retrieving a fiber unsafely)
    *
    * ```ts

package/src/FiberSet.ts

@@ -233,6 +233,11 @@ export const makeRuntime = <R = never, A = unknown, E = unknown>(): Effect.Effec
  * Creates a scoped run function that forks effects into a new `FiberSet` and
  * returns a `Promise` for each effect result.
  *
+ * **When to use**
+ *
+ * Use when many scoped fibers should be tracked as a set while exposing each
+ * result through Promise-based APIs.
+ *
  * **Details**
  *
  * Managed fibers are removed when they complete and are interrupted when the
@@ -284,6 +289,11 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * Adds an existing fiber to the `FiberSet` using a synchronous, unsafe
  * mutation.
  *
+ * **When to use**
+ *
+ * Use when an already forked fiber must be registered immediately and
+ * synchronous interruption on a closed set is acceptable.
+ *
  * **Details**
  *
  * When the fiber completes, it is removed from the set. If the set is already
@@ -315,6 +325,11 @@ export const addUnsafe: {
    * Adds an existing fiber to the `FiberSet` using a synchronous, unsafe
    * mutation.
    *
+   * **When to use**
+   *
+   * Use when an already forked fiber must be registered immediately and
+   * synchronous interruption on a closed set is acceptable.
+   *
    * **Details**
    *
    * When the fiber completes, it is removed from the set. If the set is already
@@ -351,6 +366,11 @@ export const addUnsafe: {
    * Adds an existing fiber to the `FiberSet` using a synchronous, unsafe
    * mutation.
    *
+   * **When to use**
+   *
+   * Use when an already forked fiber must be registered immediately and
+   * synchronous interruption on a closed set is acceptable.
+   *
    * **Details**
    *
    * When the fiber completes, it is removed from the set. If the set is already