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

package/dist/Sink.d.ts

@@ -172,7 +172,7 @@ export declare namespace Sink {
     }
 }
 /**
- * Checks if a value is a Sink.
+ * Checks whether a value is a Sink.
  *
  * **Example** (Checking for a sink)
  *
@@ -193,6 +193,12 @@ export declare const isSink: (u: unknown) => u is Sink<unknown, never, 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
  */
@@ -278,7 +284,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
@@ -493,7 +499,15 @@ export declare const never: Sink<unknown>;
  */
 export declare const ignoreLeftover: <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, never, E, R>;
 /**
- * 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
@@ -503,6 +517,21 @@ export declare const drain: Sink<void, unknown>;
  * 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
  */
@@ -510,12 +539,20 @@ export declare const fold: <S, In, E = never, R = never>(s: LazyArg<S>, contFn:
 /**
  * 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
  */
@@ -536,6 +573,13 @@ export declare const foldUntil: <S, In, E = never, R = never>(s: LazyArg<S>, max
 /**
  * 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
  */
@@ -543,6 +587,13 @@ export declare const every: <In>(predicate: Predicate<In>) => Sink<boolean, 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
  */
@@ -550,6 +601,20 @@ export declare const some: <In>(predicate: Predicate<In>) => Sink<boolean, In, I
 /**
  * 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
  */
@@ -557,6 +622,20 @@ export declare 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
      */
@@ -564,27 +643,62 @@ export declare 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
      */
     <A, In, L, E, R, A2>(self: Sink<A, In, L, E, R>, f: (a: A) => A2): 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
  */
 export declare 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
@@ -614,21 +728,21 @@ export declare const mapInput: {
     <A, In, L, E, R, In0>(self: Sink<A, In, L, E, R>, f: (input: In0) => In): Sink<A, In0, L, E, R>;
 };
 /**
- * Effectfully transforms this sink's input elements.
+ * Transforms this sink's input elements effectfully.
  *
  * @category mapping
  * @since 2.0.0
  */
 export declare 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
@@ -661,7 +775,7 @@ export declare const mapInputArray: {
     <A, In, L, E, R, In0>(self: Sink<A, In, L, E, R>, f: (input: Arr.NonEmptyReadonlyArray<In0>) => Arr.NonEmptyReadonlyArray<In>): Sink<A, In0, L, E, 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
@@ -669,7 +783,7 @@ export declare const mapInputArray: {
  */
 export declare 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
@@ -677,7 +791,7 @@ export declare const mapInputArrayEffect: {
      */
     <In0, In, E2, R2>(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
@@ -720,7 +834,7 @@ export declare const mapEnd: {
     <A, In, L, E, R, A2, L2 = never>(self: Sink<A, In, L, E, R>, f: (a: End<A, L>) => End<A2, L2>): Sink<A2, In, L2, E, R>;
 };
 /**
- * Effectfully transforms the full `End` produced by this sink.
+ * Transforms the full `End` produced by this sink effectfully.
  *
  * **Details**
  *
@@ -732,7 +846,7 @@ export declare const mapEnd: {
  */
 export declare const mapEffectEnd: {
     /**
-     * Effectfully transforms the full `End` produced by this sink.
+     * Transforms the full `End` produced by this sink effectfully.
      *
      * **Details**
      *
@@ -744,7 +858,7 @@ export declare 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**
      *
@@ -757,21 +871,63 @@ export declare const mapEffectEnd: {
     <A, In, L, E, R, A2, E2, R2, L2 = never>(self: Sink<A, In, L, E, R>, f: (end: End<A, L>) => Effect.Effect<End<A2, L2>, E2, R2>): Sink<A2, In, L2, E | E2, R | R2>;
 };
 /**
- * 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 declare 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
@@ -840,9 +996,18 @@ export declare 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
@@ -853,9 +1018,18 @@ export declare 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
@@ -866,9 +1040,18 @@ export declare 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
@@ -876,34 +1059,32 @@ export declare const flatMap: {
     <A, In, L, E, R, A1, In1 extends L, L1, E1, R1>(self: Sink<A, In, L, E, R>, f: (a: A) => Sink<A1, In1, L1, E1, R1>): Sink<A1, In & In1, L | L1, E | E1, R | R1>;
 };
 /**
- * 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
  */
 export declare const reduceWhile: <S, In>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: In) => S) => Sink<S, In, 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
  */
 export declare const reduceWhileEffect: <S, In, E, R>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, 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
  */
 export declare const reduceWhileArray: <S, In>(initial: LazyArg<S>, contFn: Predicate<S>, f: (s: S, input: NonEmptyReadonlyArray<In>) => S) => Sink<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
@@ -936,6 +1117,12 @@ export declare const reduceEffect: <S, In, E, R>(initial: LazyArg<S>, f: (s: S,
 /**
  * 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
  */
@@ -943,26 +1130,84 @@ export declare const head: <In>() => Sink<Option.Option<In>, In, In>;
 /**
  * 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 declare const last: <In>() => Sink<Option.Option<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
  */
 export declare 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
@@ -970,7 +1215,20 @@ export declare const find: {
     <In>(predicate: Predicate<In>): Sink<Option.Option<In>, In, In>;
 };
 /**
- * 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
@@ -986,6 +1244,10 @@ export declare const sum: Sink<number, number>;
 /**
  * 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
  */
@@ -993,6 +1255,13 @@ export declare const count: Sink<number, unknown>;
 /**
  * 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
  */
@@ -1052,7 +1321,7 @@ export declare const takeWhile: {
  */
 export declare const takeWhileFilter: <In, Out, X>(filter: Filter.Filter<In, Out, X>) => Sink<Array<Out>, In, In>;
 /**
- * Effectfully collects input elements while the predicate succeeds.
+ * Collects input elements effectfully while the predicate succeeds.
  *
  * **Details**
  *
@@ -1065,7 +1334,7 @@ export declare const takeWhileFilter: <In, Out, X>(filter: Filter.Filter<In, Out
  */
 export declare const takeWhileEffect: {
     /**
-     * Effectfully collects input elements while the predicate succeeds.
+     * Collects input elements effectfully while the predicate succeeds.
      *
      * **Details**
      *
@@ -1079,7 +1348,7 @@ export declare const takeWhileEffect: {
     <In, E, R>(predicate: (input: In) => Effect.Effect<boolean, E, R>): Sink<Array<In>, In, In, E, R>;
 };
 /**
- * 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**
@@ -1101,7 +1370,7 @@ export declare const takeWhileFilterEffect: <In, Out, X, E, R>(filter: Filter.Fi
  */
 export declare 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**
@@ -1222,24 +1491,21 @@ export declare const forEachWhileArray: <In, E, R>(f: (input: NonEmptyReadonlyAr
  */
 export declare const unwrap: <A, In, L, E, R, R2>(effect: Effect.Effect<Sink<A, In, L, E, R2>, E, R>) => Sink<A, In, L, E, Exclude<R, Scope.Scope> | R2>;
 /**
- * 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 declare 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
@@ -1377,12 +1643,20 @@ export declare 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
  */
@@ -1390,12 +1664,20 @@ export declare 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
      */
@@ -1403,12 +1685,20 @@ export declare 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
      */
@@ -1422,6 +1712,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
  */