effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Sink.ts

@@ -213,7 +213,7 @@ const SinkProto = {
 }
 
 /**
- * Checks if a value is a Sink.
+ * Checks whether a value is a Sink.
  *
  * **Example** (Checking for a sink)
  *
@@ -235,6 +235,12 @@ export const isSink = (u: unknown): u is Sink<unknown, never, unknown, unknown,
 /**
  * Creates a sink from a `Channel`.
  *
+ * **When to use**
+ *
+ * Use to create a `Sink` from a `Channel` that processes non-empty arrays of
+ * input values.
+ *
+ * @see {@link toChannel} for converting a `Sink` back to a `Channel`
  * @category constructors
  * @since 2.0.0
  */
@@ -442,7 +448,7 @@ export declare namespace make {
  *
  * **When to use**
  *
- * Use this when the effect needs to provide both the result value and optional
+ * Use when the effect needs to provide both the result value and optional
  * leftovers.
  *
  * @category constructors
@@ -695,7 +701,15 @@ export const ignoreLeftover = <A, In, L, E, R>(self: Sink<A, In, L, E, R>): Sink
   mapEnd(self, ([a]) => [a])
 
 /**
- * Drains elements from the stream by ignoring all inputs.
+ * Consumes and ignores all stream inputs.
+ *
+ * **When to use**
+ *
+ * Use to consume all upstream input and complete with void when the input
+ * values and any aggregate result are not needed.
+ *
+ * @see {@link count} for consuming all input while returning the number of elements
+ * @see {@link forEach} for consuming all input while running an effect for each element
  *
  * @category constructors
  * @since 2.0.0
@@ -711,6 +725,21 @@ export const drain: Sink<void, unknown> = fromTransform((upstream) =>
  * A sink that folds its inputs with the provided function, termination
  * predicate and initial state.
  *
+ * **When to use**
+ *
+ * Use to accumulate stream input element by element with an effectful step and
+ * stop based on the accumulated state.
+ *
+ * **Details**
+ *
+ * The initial state is evaluated lazily. Each input element is folded with the
+ * effectful function, and the sink continues while `contFn` returns `true`. If
+ * the sink stops in the middle of a pulled array, the remaining elements from
+ * that array are returned as leftovers.
+ *
+ * @see {@link foldArray} for folding each pulled non-empty input array at once
+ * @see {@link foldUntil} for folding until a fixed maximum number of elements is consumed
+ *
  * @category folding
  * @since 2.0.0
  */
@@ -741,12 +770,20 @@ export const fold = <S, In, E = never, R = never>(
 /**
  * Folds non-empty input arrays into state with an effectful function.
  *
+ * **When to use**
+ *
+ * Use to update state with an effectful function once per pulled non-empty
+ * input array when batch-level processing is the natural unit.
+ *
  * **Details**
  *
  * The initial state is evaluated lazily. After each pulled array is folded,
  * the sink continues while `contFn` returns `true`; otherwise it completes
  * with the current state.
  *
+ * @see {@link fold} for folding element by element and returning leftovers when stopping mid-array
+ * @see {@link reduceWhileArrayEffect} for array-level effectful reducing that checks the predicate before consuming input
+ *
  * @category folding
  * @since 4.0.0
  */
@@ -797,6 +834,13 @@ export const foldUntil = <S, In, E = never, R = never>(
 /**
  * A sink that returns whether all elements satisfy the specified predicate.
  *
+ * **When to use**
+ *
+ * Use to reduce a stream to a boolean that is true only when every input
+ * satisfies a pure predicate.
+ *
+ * @see {@link some} for the dual any-match check
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -810,6 +854,13 @@ export const every = <In>(predicate: Predicate<In>): Sink<boolean, In, In> =>
 /**
  * A sink that returns whether an element satisfies the specified predicate.
  *
+ * **When to use**
+ *
+ * Use to reduce a stream to a boolean that is true when any input satisfies a
+ * pure predicate.
+ *
+ * @see {@link every} for the all-match check
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -823,6 +874,20 @@ export const some = <In>(predicate: Predicate<In>): Sink<boolean, In, In> =>
 /**
  * Transforms this sink's result.
  *
+ * **When to use**
+ *
+ * Use to compute a new result from the original sink result while preserving
+ * the sink's input consumption behavior.
+ *
+ * **Details**
+ *
+ * The transformed sink preserves the original sink's input type, leftovers,
+ * errors, and requirements.
+ *
+ * @see {@link mapEffect} for effectful result transformations
+ * @see {@link as} for replacing the result with a constant value
+ * @see {@link mapEnd} for transforming both the result and leftovers
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -830,6 +895,20 @@ export const map: {
   /**
    * Transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use to compute a new result from the original sink result while preserving
+   * the sink's input consumption behavior.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input type, leftovers,
+   * errors, and requirements.
+   *
+   * @see {@link mapEffect} for effectful result transformations
+   * @see {@link as} for replacing the result with a constant value
+   * @see {@link mapEnd} for transforming both the result and leftovers
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -837,6 +916,20 @@ export const map: {
   /**
    * Transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use to compute a new result from the original sink result while preserving
+   * the sink's input consumption behavior.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input type, leftovers,
+   * errors, and requirements.
+   *
+   * @see {@link mapEffect} for effectful result transformations
+   * @see {@link as} for replacing the result with a constant value
+   * @see {@link mapEnd} for transforming both the result and leftovers
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -848,21 +941,42 @@ export const map: {
 )
 
 /**
- * Set the sink's result to a constant value.
+ * Sets the sink's result to a constant value.
+ *
+ * **When to use**
+ *
+ * Use to keep a sink's input consumption, errors, requirements, and leftovers
+ * while replacing only its result with a known value.
+ *
+ * @see {@link map} for computing the replacement from the original result
  *
  * @category mapping
  * @since 2.0.0
  */
 export const as: {
   /**
-   * Set the sink's result to a constant value.
+   * Sets the sink's result to a constant value.
+   *
+   * **When to use**
+   *
+   * Use to keep a sink's input consumption, errors, requirements, and leftovers
+   * while replacing only its result with a known value.
+   *
+   * @see {@link map} for computing the replacement from the original result
    *
    * @category mapping
    * @since 2.0.0
    */
   <A2>(a2: A2): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A2, In, L, E, R>
   /**
-   * Set the sink's result to a constant value.
+   * Sets the sink's result to a constant value.
+   *
+   * **When to use**
+   *
+   * Use to keep a sink's input consumption, errors, requirements, and leftovers
+   * while replacing only its result with a known value.
+   *
+   * @see {@link map} for computing the replacement from the original result
    *
    * @category mapping
    * @since 2.0.0
@@ -901,21 +1015,21 @@ export const mapInput: {
 )
 
 /**
- * Effectfully transforms this sink's input elements.
+ * Transforms this sink's input elements effectfully.
  *
  * @category mapping
  * @since 2.0.0
  */
 export const mapInputEffect: {
   /**
-   * Effectfully transforms this sink's input elements.
+   * Transforms this sink's input elements effectfully.
    *
    * @category mapping
    * @since 2.0.0
    */
   <In0, In, E2, R2>(f: (input: In0) => Effect.Effect<In, E2, R2>): <A, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In0, L, E2 | E, R2 | R>
   /**
-   * Effectfully transforms this sink's input elements.
+   * Transforms this sink's input elements effectfully.
    *
    * @category mapping
    * @since 2.0.0
@@ -967,7 +1081,7 @@ export const mapInputArray: {
 )
 
 /**
- * Effectfully transforms each non-empty array of upstream input before it is
+ * Transforms each non-empty array of upstream input effectfully before it is
  * fed to this sink.
  *
  * @category mapping
@@ -975,7 +1089,7 @@ export const mapInputArray: {
  */
 export const mapInputArrayEffect: {
   /**
-   * Effectfully transforms each non-empty array of upstream input before it is
+   * Transforms each non-empty array of upstream input effectfully before it is
    * fed to this sink.
    *
    * @category mapping
@@ -985,7 +1099,7 @@ export const mapInputArrayEffect: {
     f: (input: Arr.NonEmptyReadonlyArray<In0>) => Effect.Effect<Arr.NonEmptyReadonlyArray<In>, E2, R2>
   ): <A, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In0, L, E2 | E, R2 | R>
   /**
-   * Effectfully transforms each non-empty array of upstream input before it is
+   * Transforms each non-empty array of upstream input effectfully before it is
    * fed to this sink.
    *
    * @category mapping
@@ -1062,7 +1176,7 @@ const transformEffect = <A, In, L, E, R, A2, E2, R2, L2 = never>(
 ): Sink<A2, In, L2, E2, R2> => fromTransform((upstream, scope) => f(self.transform(upstream, scope)))
 
 /**
- * Effectfully transforms the full `End` produced by this sink.
+ * Transforms the full `End` produced by this sink effectfully.
  *
  * **Details**
  *
@@ -1074,7 +1188,7 @@ const transformEffect = <A, In, L, E, R, A2, E2, R2, L2 = never>(
  */
 export const mapEffectEnd: {
   /**
-   * Effectfully transforms the full `End` produced by this sink.
+   * Transforms the full `End` produced by this sink effectfully.
    *
    * **Details**
    *
@@ -1086,7 +1200,7 @@ export const mapEffectEnd: {
    */
   <A, L, A2, E2, R2, L2 = never>(f: (end: End<A, L>) => Effect.Effect<End<A2, L2>, E2, R2>): <In, E, R>(self: Sink<A, In, L, E, R>) => Sink<A2, In, L2, E2 | E, R2 | R>
   /**
-   * Effectfully transforms the full `End` produced by this sink.
+   * Transforms the full `End` produced by this sink effectfully.
    *
    * **Details**
    *
@@ -1106,21 +1220,63 @@ export const mapEffectEnd: {
 ): Sink<A2, In, L2, E | E2, R | R2> => transformEffect(self, Effect.flatMap(f)))
 
 /**
- * Effectfully transforms this sink's result.
+ * Transforms this sink's result effectfully.
+ *
+ * **When to use**
+ *
+ * Use when transforming a sink result itself is effectful, can fail, or needs
+ * services.
+ *
+ * **Details**
+ *
+ * The transformed sink preserves the original sink's input consumption and
+ * leftovers while adding the errors and requirements of the transformation.
+ *
+ * @see {@link map} for pure result transformations
+ * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+ * @see {@link flatMap} for continuing with another sink based on the result
  *
  * @category mapping
  * @since 2.0.0
  */
 export const mapEffect: {
   /**
-   * Effectfully transforms this sink's result.
+   * Transforms this sink's result effectfully.
+   *
+   * **When to use**
+   *
+   * Use when transforming a sink result itself is effectful, can fail, or needs
+   * services.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input consumption and
+   * leftovers while adding the errors and requirements of the transformation.
+   *
+   * @see {@link map} for pure result transformations
+   * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+   * @see {@link flatMap} for continuing with another sink based on the result
    *
    * @category mapping
    * @since 2.0.0
    */
   <A, A2, E2, R2>(f: (a: A) => Effect.Effect<A2, E2, R2>): <In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A2, In, L, E2 | E, R2 | R>
   /**
-   * Effectfully transforms this sink's result.
+   * Transforms this sink's result effectfully.
+   *
+   * **When to use**
+   *
+   * Use when transforming a sink result itself is effectful, can fail, or needs
+   * services.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input consumption and
+   * leftovers while adding the errors and requirements of the transformation.
+   *
+   * @see {@link map} for pure result transformations
+   * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+   * @see {@link flatMap} for continuing with another sink based on the result
    *
    * @category mapping
    * @since 2.0.0
@@ -1232,9 +1388,18 @@ export const take = <In>(n: number): Sink<Array<In>, In, In> =>
  * another sink from the provided function which will continue to run until it
  * yields a result.
  *
+ * **When to use**
+ *
+ * Use to compose sinks when the next sink depends on the result produced by the
+ * previous sink.
+ *
  * **Details**
  *
- * This function essentially runs sinks in sequence.
+ * Leftovers from the first sink are fed to the sink returned by `f` before more
+ * upstream input is pulled.
+ *
+ * @see {@link map} for transforming the result without switching sinks
+ * @see {@link mapEffect} for effectfully transforming the result without switching sinks
  *
  * @category sequencing
  * @since 2.0.0
@@ -1245,9 +1410,18 @@ export const flatMap: {
    * another sink from the provided function which will continue to run until it
    * yields a result.
    *
+   * **When to use**
+   *
+   * Use to compose sinks when the next sink depends on the result produced by the
+   * previous sink.
+   *
    * **Details**
    *
-   * This function essentially runs sinks in sequence.
+   * Leftovers from the first sink are fed to the sink returned by `f` before more
+   * upstream input is pulled.
+   *
+   * @see {@link map} for transforming the result without switching sinks
+   * @see {@link mapEffect} for effectfully transforming the result without switching sinks
    *
    * @category sequencing
    * @since 2.0.0
@@ -1258,9 +1432,18 @@ export const flatMap: {
    * another sink from the provided function which will continue to run until it
    * yields a result.
    *
+   * **When to use**
+   *
+   * Use to compose sinks when the next sink depends on the result produced by the
+   * previous sink.
+   *
    * **Details**
    *
-   * This function essentially runs sinks in sequence.
+   * Leftovers from the first sink are fed to the sink returned by `f` before more
+   * upstream input is pulled.
+   *
+   * @see {@link map} for transforming the result without switching sinks
+   * @see {@link mapEffect} for effectfully transforming the result without switching sinks
    *
    * @category sequencing
    * @since 2.0.0
@@ -1296,8 +1479,8 @@ export const flatMap: {
   }))
 
 /**
- * A sink that reduces its inputs using the provided function `f` starting from
- * the provided `initial` state while the specified `predicate` returns `true`.
+ * A sink that reduces input elements from the provided `initial` state with
+ * `f` while the specified `predicate` returns `true`.
  *
  * @category reducing
  * @since 4.0.0
@@ -1332,9 +1515,8 @@ export const reduceWhile = <S, In>(
   })
 
 /**
- * A sink that reduces its inputs using the provided effectful function `f`
- * starting from the provided `initial` state while the specified `predicate`
- * returns `true`.
+ * A sink that effectfully reduces input elements from the provided `initial`
+ * state with `f` while the specified `predicate` returns `true`.
  *
  * @category reducing
  * @since 4.0.0
@@ -1374,8 +1556,8 @@ export const reduceWhileEffect = <S, In, E, R>(
   })
 
 /**
- * A sink that reduces its inputs using the provided function `f` starting from
- * the provided `initial` state while the specified `predicate` returns `true`.
+ * A sink that reduces non-empty input arrays from the provided `initial` state
+ * with `f` while the specified `predicate` returns `true`.
  *
  * @category reducing
  * @since 4.0.0
@@ -1406,9 +1588,8 @@ export const reduceWhileArray = <S, In>(
   })
 
 /**
- * A sink that reduces its inputs using the provided effectful function `f`
- * starting from the provided `initial` state while the specified `predicate`
- * returns `true`.
+ * A sink that effectfully reduces non-empty input arrays from the provided
+ * `initial` state with `f` while the specified `predicate` returns `true`.
  *
  * @category reducing
  * @since 4.0.0
@@ -1492,6 +1673,12 @@ const head_ = reduceWhile(Option.none<unknown>, Option.isNone, (_, in_) => Optio
 /**
  * Creates a sink containing the first value.
  *
+ * **Details**
+ *
+ * Returns `Option.some(first)` for non-empty input, or `Option.none` when the
+ * upstream ends without input. The first element is consumed; later elements
+ * from the same pulled array are emitted as leftovers.
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1502,27 +1689,85 @@ const last_ = reduceArray(Option.none<unknown>, (_, arr) => Arr.last(arr))
 /**
  * Creates a sink containing the last value.
  *
+ * **When to use**
+ *
+ * Use when consuming all upstream input and only the final element is needed.
+ *
+ * **Details**
+ *
+ * Returns `Option.some(last)` with the final input value, or `Option.none` when
+ * the upstream ends without input.
+ *
+ * **Gotchas**
+ *
+ * This sink produces a result only when the upstream ends, so it does not
+ * complete for a stream that does not end.
+ *
+ * @see {@link head} for taking the first input value instead
+ *
  * @category constructors
  * @since 2.0.0
  */
 export const last = <In>(): Sink<Option.Option<In>, In> => last_ as any
 
 /**
- * Creates a sink containing the first matching value.
+ * Creates a sink containing the first value matched by a synchronous predicate.
+ *
+ * **When to use**
+ *
+ * Use to scan stream input until the first matching element is found and return
+ * that element as an `Option`.
+ *
+ * **Details**
+ *
+ * Returns `Option.none` if the upstream stream ends before a match is found.
+ * Refinement predicates narrow the returned value type. The matching input is
+ * consumed; any later elements from the same pulled array are returned as
+ * leftovers.
+ *
+ * @see {@link findEffect} for an effectful predicate that can fail or require services
  *
  * @category constructors
  * @since 4.0.0
  */
 export const find: {
   /**
-   * Creates a sink containing the first matching value.
+   * Creates a sink containing the first value matched by a synchronous predicate.
+   *
+   * **When to use**
+   *
+   * Use to scan stream input until the first matching element is found and return
+   * that element as an `Option`.
+   *
+   * **Details**
+   *
+   * Returns `Option.none` if the upstream stream ends before a match is found.
+   * Refinement predicates narrow the returned value type. The matching input is
+   * consumed; any later elements from the same pulled array are returned as
+   * leftovers.
+   *
+   * @see {@link findEffect} for an effectful predicate that can fail or require services
    *
    * @category constructors
    * @since 4.0.0
    */
   <In, Out extends In>(refinement: Refinement<In, Out>): Sink<Option.Option<Out>, In, In>
   /**
-   * Creates a sink containing the first matching value.
+   * Creates a sink containing the first value matched by a synchronous predicate.
+   *
+   * **When to use**
+   *
+   * Use to scan stream input until the first matching element is found and return
+   * that element as an `Option`.
+   *
+   * **Details**
+   *
+   * Returns `Option.none` if the upstream stream ends before a match is found.
+   * Refinement predicates narrow the returned value type. The matching input is
+   * consumed; any later elements from the same pulled array are returned as
+   * leftovers.
+   *
+   * @see {@link findEffect} for an effectful predicate that can fail or require services
    *
    * @category constructors
    * @since 4.0.0
@@ -1536,7 +1781,20 @@ export const find: {
   )
 
 /**
- * Creates a sink containing the first matching value.
+ * Creates a sink containing the first value matched by an effectful predicate.
+ *
+ * **When to use**
+ *
+ * Use when deciding whether an input matches requires an effect, can fail, or
+ * needs services.
+ *
+ * **Details**
+ *
+ * Returns `Option.some` with the first input whose predicate result is `true`,
+ * or `Option.none` if the upstream stream ends first. If the predicate effect
+ * fails, the sink fails with the same error.
+ *
+ * @see {@link find} for the synchronous predicate variant
  *
  * @category constructors
  * @since 2.0.0
@@ -1566,6 +1824,10 @@ export const sum: Sink<number, number> = reduceArray(() => 0, (s, arr) => {
 /**
  * A sink that counts the number of elements fed to it.
  *
+ * **When to use**
+ *
+ * Use to consume input and return only the number of elements received.
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1574,6 +1836,13 @@ export const count: Sink<number, unknown> = reduceArray(() => 0, (s, arr) => s +
 /**
  * Accumulates incoming elements into an array.
  *
+ * **When to use**
+ *
+ * Use to collect all upstream input elements into a single array when you need
+ * a sink result containing the complete input.
+ *
+ * @see {@link take} for collecting only a fixed number of input elements
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1681,7 +1950,7 @@ export const takeWhileFilter = <In, Out, X>(
   })
 
 /**
- * Effectfully collects input elements while the predicate succeeds.
+ * Collects input elements effectfully while the predicate succeeds.
  *
  * **Details**
  *
@@ -1694,7 +1963,7 @@ export const takeWhileFilter = <In, Out, X>(
  */
 export const takeWhileEffect: {
   /**
-   * Effectfully collects input elements while the predicate succeeds.
+   * Collects input elements effectfully while the predicate succeeds.
    *
    * **Details**
    *
@@ -1742,7 +2011,7 @@ export const takeWhileEffect: {
   })
 
 /**
- * Effectfully applies a `FilterEffect` to input elements while it succeeds,
+ * Applies a `FilterEffect` to input elements effectfully while it succeeds,
  * collecting each successful output.
  *
  * **Details**
@@ -1801,7 +2070,7 @@ export const takeUntil = <In>(predicate: Predicate<In>): Sink<Array<In>, In, In>
   })
 
 /**
- * Effectfully collects input elements until the predicate returns `true`,
+ * Collects input elements effectfully until the predicate returns `true`,
  * including the matching element in the result.
  *
  * **Details**
@@ -1974,24 +2243,21 @@ export const unwrap = <A, In, L, E, R, R2>(
 ): Sink<A, In, L, E, Exclude<R, Scope.Scope> | R2> => fromChannel(Channel.unwrap(Effect.map(effect, toChannel)))
 
 /**
- * Summarize a sink by running an effect when the sink starts and again when
- * it completes.
+ * Runs a summary effect when the sink starts and again when it completes.
  *
  * @category utils
  * @since 2.0.0
  */
 export const summarized: {
   /**
-   * Summarize a sink by running an effect when the sink starts and again when
-   * it completes.
+   * Runs a summary effect when the sink starts and again when it completes.
    *
    * @category utils
    * @since 2.0.0
    */
   <A2, E2, R2, A3>(summary: Effect.Effect<A2, E2, R2>, f: (start: A2, end: A2) => A3): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<[A, A3], In, L, E2 | E, R2 | R>
   /**
-   * Summarize a sink by running an effect when the sink starts and again when
-   * it completes.
+   * Runs a summary effect when the sink starts and again when it completes.
    *
    * @category utils
    * @since 2.0.0
@@ -2196,12 +2462,20 @@ export const orElse: {
 /**
  * Handles failures from this sink by inspecting the full `Cause`.
  *
+ * **When to use**
+ *
+ * Use to recover from a sink failure based on the full `Cause` instead of only
+ * the typed error value.
+ *
  * **Details**
  *
  * When this sink fails, the handler effect is run and its success value
  * becomes the sink result. If the handler fails, the returned sink fails with
  * that error.
  *
+ * @see {@link catch_ catch} for recovering from typed errors only
+ * @see {@link orElse} for recovering by switching to another sink
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2209,12 +2483,20 @@ export const catchCause: {
   /**
    * Handles failures from this sink by inspecting the full `Cause`.
    *
+   * **When to use**
+   *
+   * Use to recover from a sink failure based on the full `Cause` instead of only
+   * the typed error value.
+   *
    * **Details**
    *
    * When this sink fails, the handler effect is run and its success value
    * becomes the sink result. If the handler fails, the returned sink fails with
    * that error.
    *
+   * @see {@link catch_ catch} for recovering from typed errors only
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -2222,12 +2504,20 @@ export const catchCause: {
   /**
    * Handles failures from this sink by inspecting the full `Cause`.
    *
+   * **When to use**
+   *
+   * Use to recover from a sink failure based on the full `Cause` instead of only
+   * the typed error value.
+   *
    * **Details**
    *
    * When this sink fails, the handler effect is run and its success value
    * becomes the sink result. If the handler fails, the returned sink fails with
    * that error.
    *
+   * @see {@link catch_ catch} for recovering from typed errors only
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -2265,6 +2555,14 @@ export {
   /**
    * Handles typed errors from this sink with an effectful fallback value.
    *
+   * **When to use**
+   *
+   * Use to recover from a typed sink failure by producing the replacement
+   * result with an `Effect`.
+   *
+   * @see {@link catchCause} for recovering from the full failure cause
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */