effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Sink.d.ts

@@ -1,4 +1,35 @@
 /**
+ * The `Sink` module provides composable consumers for `Stream` values. A
+ * `Sink<A, In, L, E, R>` pulls input elements of type `In`, may require
+ * services `R`, may fail with `E`, and eventually produces a result `A` plus
+ * any leftover input `L` that was read but not consumed.
+ *
+ * **Mental model**
+ *
+ * - A sink is the terminal consumer used by `Stream.run`
+ * - Sinks can consume zero, one, many, or all input elements before finishing
+ * - Leftovers allow one sink to stop early without losing already-pulled input
+ * - Sink composition preserves typed errors and service requirements
+ * - Most sinks are built from `Channel` internally, but users compose them with
+ *   the higher-level APIs in this module
+ *
+ * **Common tasks**
+ *
+ * - Create simple sinks: {@link succeed}, {@link fail}, {@link fromEffect}
+ * - Fold input: {@link fold}
+ * - Collect values: {@link collect}
+ * - Count or drain input: {@link count}, {@link drain}
+ * - Transform results: {@link map}, {@link mapEffect}, {@link as}
+ * - Adapt input before consumption: {@link mapInput}, {@link mapInputEffect}
+ *
+ * **Gotchas**
+ *
+ * - A sink can finish before the stream is exhausted; check leftover-aware
+ *   combinators when composing parsers or protocol decoders
+ * - `In` is contravariant, so a sink that accepts broader input can be used
+ *   where narrower input is expected
+ * - Resource and service requirements are tracked in the `R` type parameter
+ *
  * @since 2.0.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts";
@@ -29,11 +60,10 @@ declare const TypeId = "~effect/Sink";
  * and will eventually yield a value of type `A` together with a remainder of
  * type `L` (i.e. any leftovers).
  *
- * @example
+ * **Example** (Running a sink with a stream)
+ *
  * ```ts
- * import { Effect } from "effect"
- * import * as Sink from "effect/Sink"
- * import * as Stream from "effect/Stream"
+ * import { Effect, Sink, Stream } from "effect"
  *
  * // Create a simple sink that always succeeds with a value
  * const sink: Sink.Sink<number> = Sink.succeed(42)
@@ -46,8 +76,8 @@ declare const TypeId = "~effect/Sink";
  * // Output: 42
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Sink<out A, in In = unknown, out L = never, out E = never, out R = never> extends Sink.Variance<A, In, L, E, R>, Pipeable {
     readonly transform: (upstream: Pull.Pull<NonEmptyReadonlyArray<In>, never, void>, scope: Scope.Scope) => Effect.Effect<End<A, L>, E, R>;
@@ -56,30 +86,25 @@ export interface Sink<out A, in In = unknown, out L = never, out E = never, out
     [Unify.ignoreSymbol]?: SinkUnifyIgnore;
 }
 /**
- * @since 2.0.0
+ * Tuple returned when a `Sink` finishes.
+ *
+ * The first element is the sink result. The optional second element contains a
+ * non-empty array of leftover input that was pulled but not consumed.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type End<A, L = never> = readonly [value: A, leftover?: NonEmptyReadonlyArray<L> | undefined];
 /**
- * Interface for Sink unification, used internally by the Effect type system
- * to provide proper type inference when using Sink with other Effect types.
+ * Type-level unification support for `Sink` values.
  *
- * @example
- * ```ts
- * import type { Effect } from "effect"
- * import type * as Sink from "effect/Sink"
- * import type * as Unify from "effect/Unify"
- *
- * // SinkUnify helps unify Sink and Effect types
- * declare const sink: Sink.Sink<number>
- * declare const effect: Effect.Effect<string>
+ * This preserves the result, input, leftover, error, and service type
+ * parameters when Effect's `Unify` machinery normalizes generic values that
+ * include sinks. Users normally do not need to reference this interface
+ * directly.
  *
- * // The unification system handles mixed operations
- * type Combined = Sink.SinkUnify<{ [Unify.typeSymbol]?: any }>
- * ```
- *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface SinkUnify<A extends {
     [Unify.typeSymbol]?: any;
@@ -87,16 +112,11 @@ export interface SinkUnify<A extends {
     Sink?: () => A[Unify.typeSymbol] extends Sink<infer A, infer In, infer L, infer E, infer R> | infer _ ? Sink<A, In, L, E, R> : never;
 }
 /**
- * Interface used to ignore certain types during Sink unification.
- * Part of the internal type system machinery.
+ * Marker used by Effect's `Unify` machinery for `Sink` values.
  *
- * @example
- * ```ts
- * import type * as Sink from "effect/Sink"
- *
- * // Used internally by the type system
- * type IgnoreConfig = Sink.SinkUnifyIgnore
- * ```
+ * It prevents the inherited `Effect` unifier from being selected when
+ * sink-specific unification should preserve the `Sink` type parameters. Users
+ * normally do not need to reference this interface directly.
  *
  * @category models
  * @since 2.0.0
@@ -107,53 +127,31 @@ export interface SinkUnifyIgnore {
 /**
  * Namespace containing types and interfaces for Sink variance and type relationships.
  *
- * @example
- * ```ts
- * import type * as Sink from "effect/Sink"
- *
- * // The Sink namespace contains internal type definitions
- * // These are used internally for type safety and variance
- * type SinkType<A, In, L, E, R> = Sink.Sink<A, In, L, E, R>
- * ```
- *
  * @since 2.0.0
- * @category models
  */
 export declare namespace Sink {
     /**
-     * Represents the variance annotations for a Sink type.
-     * Used internally to track how type parameters flow through the Sink.
+     * Type-level variance marker for `Sink`.
      *
-     * @example
-     * ```ts
-     * import type * as Sink from "effect/Sink"
+     * The result `A`, leftovers `L`, errors `E`, and services `R` are
+     * covariant. The input type `In` is contravariant because values flow into
+     * the sink.
      *
-     * // The variance interface is used internally
-     * // It defines how type parameters behave in Sink
-     * type SinkWithVariance = Sink.Sink<string> & { variance: "internal" }
-     * ```
-     *
-     * @since 2.0.0
      * @category models
+     * @since 2.0.0
      */
     interface Variance<out A, in In, out L, out E, out R> {
         readonly [TypeId]: VarianceStruct<A, In, L, E, R>;
     }
     /**
-     * The internal structure representing Sink variance annotations.
-     * Contains the actual variance markers for each type parameter.
+     * Structural encoding used by `Sink.Variance` to record each `Sink` type
+     * parameter's variance.
      *
-     * @example
-     * ```ts
-     * import type * as Sink from "effect/Sink"
+     * `_A`, `_L`, `_E`, and `_R` are covariant markers. `_In` is a
+     * contravariant marker.
      *
-     * // The variance structure is used internally by the type system
-     * // It ensures proper type safety for Sink operations
-     * type SinkInstance = Sink.Sink<number, string>
-     * ```
-     *
-     * @since 2.0.0
      * @category models
+     * @since 2.0.0
      */
     interface VarianceStruct<out A, in In, out L, out E, out R> {
         _A: Types.Covariant<A>;
@@ -166,7 +164,8 @@ export declare namespace Sink {
 /**
  * Checks if a value is a Sink.
  *
- * @example
+ * **Example** (Checking for a sink)
+ *
  * ```ts
  * import { Sink } from "effect"
  *
@@ -177,26 +176,33 @@ export declare namespace Sink {
  * console.log(Sink.isSink(notStream)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export declare const isSink: (u: unknown) => u is Sink<unknown, never, unknown, unknown, unknown>;
 /**
  * Creates a sink from a `Channel`.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromChannel: <L, In, E, A, R>(channel: Channel.Channel<never, E, End<A, L>, NonEmptyReadonlyArray<In>, never, void, R>) => Sink<A, In, L, E, R>;
 /**
- * @since 4.0.0
+ * Creates a `Sink` from a low-level transform function.
+ *
+ * The transform receives the upstream pull of non-empty input arrays and the
+ * active scope, and returns an effect that completes with the sink's `End`
+ * value.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromTransform: <In, A, E, R, L = never>(transform: (upstream: Pull.Pull<NonEmptyReadonlyArray<In>, never, void>, scope: Scope.Scope) => Effect.Effect<End<A, L>, E, R>) => Sink<A, In, L, E, R>;
 /**
  * Creates a `Channel` from a Sink.
  *
- * @example
+ * **Example** (Converting a sink to a channel)
+ *
  * ```ts
  * import { Sink } from "effect"
  *
@@ -205,20 +211,36 @@ export declare const fromTransform: <In, A, E, R, L = never>(transform: (upstrea
  * const channel = Sink.toChannel(sink)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const toChannel: <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Channel.Channel<never, E, End<A, L>, NonEmptyReadonlyArray<In>, never, void, R>;
 /**
- * @since 4.0.0
+ * Creates a pipe-style constructor for sinks over input type `In`.
+ *
+ * The returned function exposes the sink input as a `Stream<In>`, applies the
+ * provided pipeline, and uses the final effect's success value as the sink
+ * result.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <In>() => make.Constructor<In>;
 /**
+ * Companion namespace containing overload types for the pipe-style sink
+ * constructor returned by `Sink.make`.
+ *
  * @since 4.0.0
  */
 export declare namespace make {
     /**
+     * Overloaded function type returned by `Sink.make`.
+     *
+     * The first pipeline function receives the sink input as a `Stream<In>`. The
+     * final pipeline step must return an `Effect`, whose success value becomes
+     * the sink result.
+     *
+     * @category models
      * @since 4.0.0
      */
     interface Constructor<In> {
@@ -235,29 +257,50 @@ export declare namespace make {
     }
 }
 /**
- * @since 4.0.0
+ * Creates a sink that ignores upstream input and completes from an effect that
+ * already returns an `End`.
+ *
+ * Use this when the effect needs to provide both the result value and optional
+ * leftovers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const fromEffectEnd: <A, E, R, L = never>(effect: Effect.Effect<End<A, L>, E, R>) => Sink<A, unknown, L, E, R>;
 /**
- * @since 4.0.0
+ * Creates a sink that ignores upstream input and completes with the success
+ * value of the provided effect.
+ *
+ * If the effect fails, the sink fails with the same error.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => Sink<A, unknown, never, E, R>;
 /**
- * @since 2.0.0
+ * Creates a sink that offers every consumed input element to a queue.
+ *
+ * When the upstream stream ends, the sink ends the queue and completes with
+ * `void`.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromQueue: <A>(queue: Queue.Queue<A, Cause.Done>) => Sink<void, A>;
 /**
- * @since 2.0.0
+ * Creates a sink that publishes every consumed input element to a `PubSub`.
+ *
+ * The sink completes with `void` when the upstream stream ends.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Sink<void, A>;
 /**
  * A sink that immediately ends with the specified value.
  *
- * @example
+ * **Example** (Succeeding with a value)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -272,28 +315,29 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Sink<void, A>;
  * // Output: 42
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const succeed: <A, L = never>(a: A, leftovers?: NonEmptyReadonlyArray<L> | undefined) => Sink<A, unknown, L>;
 /**
  * A sink that immediately ends with the specified lazily evaluated value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const sync: <A>(a: LazyArg<A>) => Sink<A>;
 /**
  * A sink that is created from a lazily evaluated sink.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const suspend: <A, In, L, E, R>(evaluate: LazyArg<Sink<A, In, L, E, R>>) => Sink<A, In, L, E, R>;
 /**
  * A sink that always fails with the specified error.
  *
- * @example
+ * **Example** (Failing with an error)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -308,14 +352,15 @@ export declare const suspend: <A, In, L, E, R>(evaluate: LazyArg<Sink<A, In, L,
  * // Output: Error: Sink failed
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fail: <E>(e: E) => Sink<never, unknown, never, E>;
 /**
  * A sink that always fails with the specified lazily evaluated error.
  *
- * @example
+ * **Example** (Failing with a lazy error)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -330,14 +375,15 @@ export declare const fail: <E>(e: E) => Sink<never, unknown, never, E>;
  * // Output: Error: Lazy error
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failSync: <E>(evaluate: LazyArg<E>) => Sink<never, unknown, never, E>;
 /**
  * Creates a sink halting with a specified `Cause`.
  *
- * @example
+ * **Example** (Failing with a cause)
+ *
  * ```ts
  * import { Cause, Effect, Sink, Stream } from "effect"
  *
@@ -352,14 +398,15 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Sink<never, unknown,
  * // Output: Error: Custom cause
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failCause: <E>(cause: Cause.Cause<E>) => Sink<never, unknown, never, E>;
 /**
  * Creates a sink halting with a specified lazily evaluated `Cause`.
  *
- * @example
+ * **Example** (Failing with a lazy cause)
+ *
  * ```ts
  * import { Cause, Effect, Sink, Stream } from "effect"
  *
@@ -374,14 +421,15 @@ export declare const failCause: <E>(cause: Cause.Cause<E>) => Sink<never, unknow
  * // Output: Error: Lazy cause
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Sink<never, unknown, never, E>;
 /**
  * Creates a sink halting with a specified defect.
  *
- * @example
+ * **Example** (Dying with a defect)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -396,308 +444,351 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Si
  * // Output: Error: Defect error
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const die: (defect: unknown) => Sink<never>;
 /**
  * A sink that never completes.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const never: Sink<unknown>;
 /**
- * Drains the remaining elements from the stream after the sink finishes
+ * Drops leftovers produced by a sink.
+ *
+ * The sink result is preserved, but any leftover elements are discarded
+ * instead of being returned to downstream sink composition. This does not
+ * continue pulling additional elements from the upstream stream.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const drain: Sink<void, unknown>;
 /**
  * A sink that folds its inputs with the provided function, termination
  * predicate and initial state.
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export declare const fold: <S, In, E = never, R = never>(s: LazyArg<S>, contFn: Predicate<S>, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, In, E, R>;
 /**
- * @since 2.0.0
+ * Folds non-empty input arrays into state with an effectful function.
+ *
+ * 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.
+ *
  * @category folding
+ * @since 4.0.0
  */
 export declare const foldArray: <S, In, E = never, R = never>(s: LazyArg<S>, contFn: Predicate<S>, f: (s: S, input: Arr.NonEmptyReadonlyArray<In>) => Effect.Effect<S, E, R>) => Sink<S, In, never, E, R>;
 /**
- * @since 2.0.0
+ * Folds input elements into state until the specified maximum number of
+ * elements has been consumed or the upstream stream ends.
+ *
+ * If the sink stops in the middle of a pulled array, the remaining elements
+ * from that array are returned as leftovers.
+ *
  * @category folding
+ * @since 2.0.0
  */
 export declare const foldUntil: <S, In, E = never, R = never>(s: LazyArg<S>, max: number, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, In, E, R>;
 /**
  * A sink that returns whether all elements satisfy the specified predicate.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const every: <In>(predicate: Predicate<In>) => Sink<boolean, In, In>;
 /**
  * A sink that returns whether an element satisfies the specified predicate.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const some: <In>(predicate: Predicate<In>) => Sink<boolean, In, In>;
 /**
  * Transforms this sink's result.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const map: {
     /**
      * Transforms this sink's result.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, A2>(f: (a: A) => A2): <In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A2, In, L, E, R>;
     /**
      * Transforms this sink's result.
      *
-     * @since 2.0.0
      * @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.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const as: {
     /**
      * Set the sink's result to a constant value.
      *
-     * @since 2.0.0
      * @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.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, In, L, E, R, A2>(self: Sink<A, In, L, E, R>, a2: A2): Sink<A2, In, L, E, R>;
 };
 /**
  * Transforms this sink's input elements.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const mapInput: {
     /**
      * Transforms this sink's input elements.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <In0, In>(f: (input: In0) => In): <A, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In0, L, E, R>;
     /**
      * Transforms this sink's input elements.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <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.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const mapInputEffect: {
     /**
      * Effectfully transforms this sink's input elements.
      *
-     * @since 2.0.0
      * @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.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, In, L, E, R, In0, E2, R2>(self: Sink<A, In, L, E, R>, f: (input: In0) => Effect.Effect<In, E2, R2>): Sink<A, In0, L, E | E2, R | R2>;
 };
 /**
- * Transforms this sink's input elements.
+ * Transforms each non-empty array of upstream input before it is fed to this
+ * sink.
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapInputArray: {
     /**
-     * Transforms this sink's input elements.
+     * Transforms each non-empty array of upstream input before it is fed to this
+     * sink.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <In0, In>(f: (input: Arr.NonEmptyReadonlyArray<In0>) => Arr.NonEmptyReadonlyArray<In>): <A, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In0, L, E, R>;
     /**
-     * Transforms this sink's input elements.
+     * Transforms each non-empty array of upstream input before it is fed to this
+     * sink.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <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 this sink's input elements.
+ * Effectfully transforms each non-empty array of upstream input before it is
+ * fed to this sink.
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapInputArrayEffect: {
     /**
-     * Effectfully transforms this sink's input elements.
+     * Effectfully transforms each non-empty array of upstream input before it is
+     * fed to this sink.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <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 this sink's input elements.
+     * Effectfully transforms each non-empty array of upstream input before it is
+     * fed to this sink.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, In, L, E, R, In0, E2, R2>(self: Sink<A, In, L, E, R>, f: (input: Arr.NonEmptyReadonlyArray<In0>) => Effect.Effect<Arr.NonEmptyReadonlyArray<In>, E2, R2>): Sink<A, In0, L, E | E2, R | R2>;
 };
 /**
- * Transforms this sink's result.
+ * Transforms the full `End` produced by this sink.
+ *
+ * This can change both the result value and the optional leftovers.
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapEnd: {
     /**
-     * Transforms this sink's result.
+     * Transforms the full `End` produced by this sink.
+     *
+     * This can change both the result value and the optional leftovers.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <A, L, A2, L2 = never>(f: (a: End<A, L>) => End<A2, L2>): <In, E, R>(self: Sink<A, In, L, E, R>) => Sink<A2, In, L2, E, R>;
     /**
-     * Transforms this sink's result.
+     * Transforms the full `End` produced by this sink.
+     *
+     * This can change both the result value and the optional leftovers.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <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 this sink's result.
+ * Effectfully transforms the full `End` produced by this sink.
+ *
+ * This can change both the result value and the optional leftovers, and the
+ * transformation can fail or require services.
  *
- * @since 4.0.0
  * @category mapping
+ * @since 4.0.0
  */
 export declare const mapEffectEnd: {
     /**
-     * Effectfully transforms this sink's result.
+     * Effectfully transforms the full `End` produced by this sink.
+     *
+     * This can change both the result value and the optional leftovers, and the
+     * transformation can fail or require services.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <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 this sink's result.
+     * Effectfully transforms the full `End` produced by this sink.
+     *
+     * This can change both the result value and the optional leftovers, and the
+     * transformation can fail or require services.
      *
-     * @since 4.0.0
      * @category mapping
+     * @since 4.0.0
      */
     <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.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const mapEffect: {
     /**
      * Effectfully transforms this sink's result.
      *
-     * @since 2.0.0
      * @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.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, In, L, E, R, A2, E2, R2>(self: Sink<A, In, L, E, R>, f: (a: A) => Effect.Effect<A2, E2, R2>): Sink<A2, In, L, E | E2, R | R2>;
 };
 /**
  * Transforms the errors emitted by this sink using `f`.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const mapError: {
     /**
      * Transforms the errors emitted by this sink using `f`.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <E, E2>(f: (error: E) => E2): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E2, R>;
     /**
      * Transforms the errors emitted by this sink using `f`.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, In, L, E, R, E2>(self: Sink<A, In, L, E, R>, f: (error: E) => E2): Sink<A, In, L, E2, R>;
 };
 /**
  * Transforms the leftovers emitted by this sink using `f`.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export declare const mapLeftover: {
     /**
      * Transforms the leftovers emitted by this sink using `f`.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <L, L2>(f: (leftover: L) => L2): <A, In, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L2, E, R>;
     /**
      * Transforms the leftovers emitted by this sink using `f`.
      *
-     * @since 2.0.0
      * @category mapping
+     * @since 2.0.0
      */
     <A, In, L, E, R, L2>(self: Sink<A, In, L, E, R>, f: (leftover: L) => L2): Sink<A, In, L2, E, R>;
 };
 /**
- * @since 2.0.0
+ * Collects up to `n` input elements into an array.
+ *
+ * If `n` is less than or equal to zero, the sink completes with an empty array.
+ * If more elements are pulled than needed, the remaining elements from the same
+ * array are returned as leftovers.
+ *
  * @category collecting
+ * @since 2.0.0
  */
 export declare const take: <In>(n: number) => Sink<Array<In>, In, In>;
 /**
@@ -707,8 +798,8 @@ export declare const take: <In>(n: number) => Sink<Array<In>, In, In>;
  *
  * This function essentially runs sinks in sequence.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export declare const flatMap: {
     /**
@@ -718,8 +809,8 @@ export declare const flatMap: {
      *
      * This function essentially runs sinks in sequence.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <A, A1, L, In1 extends L, L1, E1, R1>(f: (a: A) => Sink<A1, In1, L1, E1, R1>): <In, E, R>(self: Sink<A, In, L, E, R>) => Sink<A1, In & In1, L1 | L, E1 | E, R1 | R>;
     /**
@@ -729,8 +820,8 @@ export declare const flatMap: {
      *
      * This function essentially runs sinks in sequence.
      *
-     * @since 2.0.0
      * @category sequencing
+     * @since 2.0.0
      */
     <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>;
 };
@@ -738,8 +829,8 @@ export declare 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`.
  *
- * @since 2.0.0
  * @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>;
 /**
@@ -747,16 +838,16 @@ export declare const reduceWhile: <S, In>(initial: LazyArg<S>, predicate: Predic
  * starting from the provided `initial` state while the specified `predicate`
  * returns `true`.
  *
- * @since 2.0.0
  * @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`.
  *
- * @since 4.0.0
  * @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>;
 /**
@@ -764,150 +855,203 @@ export declare const reduceWhileArray: <S, In>(initial: LazyArg<S>, contFn: Pred
  * starting from the provided `initial` state while the specified `predicate`
  * returns `true`.
  *
- * @since 4.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export declare const reduceWhileArrayEffect: <S, In, E, R>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: NonEmptyReadonlyArray<In>) => Effect.Effect<S, E, R>) => Sink<S, In, never, E, R>;
 /**
  * A sink that reduces its inputs using the provided function `f` starting from
  * the provided `initial` state.
  *
- * @since 2.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export declare const reduce: <S, In>(initial: LazyArg<S>, f: (s: S, input: In) => S) => Sink<S, In>;
 /**
  * A sink that reduces its inputs using the provided function `f` starting from
  * the specified `initial` state.
  *
- * @since 2.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export declare const reduceArray: <S, In>(initial: LazyArg<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 specified `initial` state.
  *
- * @since 2.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export declare const reduceEffect: <S, In, E, R>(initial: LazyArg<S>, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, never, E, R>;
 /**
  * Creates a sink containing the first value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const head: <In>() => Sink<Option.Option<In>, In, In>;
 /**
  * Creates a sink containing the last value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const last: <In>() => Sink<Option.Option<In>, In>;
 /**
  * Creates a sink containing the first matching value.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const find: {
     /**
      * Creates a sink containing the first matching value.
      *
-     * @since 4.0.0
      * @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.
      *
-     * @since 4.0.0
      * @category constructors
+     * @since 4.0.0
      */
     <In>(predicate: Predicate<In>): Sink<Option.Option<In>, In, In>;
 };
 /**
  * Creates a sink containing the first matching value.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const findEffect: <In, E, R>(predicate: (input: In) => Effect.Effect<boolean, E, R>) => Sink<Option.Option<In>, In, In, E, R>;
 /**
  * Creates a sink which sums up its inputs.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const sum: Sink<number, number>;
 /**
  * A sink that counts the number of elements fed to it.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const count: Sink<number, unknown>;
 /**
  * Accumulates incoming elements into an array.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const collect: <In>() => Sink<Array<In>, In>;
 /**
- * @since 4.0.0
+ * Collects the longest input prefix whose elements satisfy the predicate or
+ * refinement.
+ *
+ * The first failing input is consumed and excluded from the result. Any later
+ * elements from the same pulled array are returned as leftovers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeWhile: {
     /**
-     * @since 4.0.0
+     * Collects the longest input prefix whose elements satisfy the predicate or
+     * refinement.
+     *
+     * The first failing input is consumed and excluded from the result. Any later
+     * elements from the same pulled array are returned as leftovers.
+     *
      * @category constructors
+     * @since 4.0.0
      */
     <In, Out extends In>(refinement: Refinement<In, Out>): Sink<Array<Out>, In, In>;
     /**
-     * @since 4.0.0
+     * Collects the longest input prefix whose elements satisfy the predicate or
+     * refinement.
+     *
+     * The first failing input is consumed and excluded from the result. Any later
+     * elements from the same pulled array are returned as leftovers.
+     *
      * @category constructors
+     * @since 4.0.0
      */
     <In>(predicate: Predicate<In>): Sink<Array<In>, In, In>;
 };
 /**
- * @since 4.0.0
+ * Applies a `Filter` to input elements while it succeeds, collecting each
+ * successful output.
+ *
+ * The first input for which the filter fails is consumed and excluded from the
+ * result. Any later elements from the same pulled array are returned as
+ * leftovers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeWhileFilter: <In, Out, X>(filter: Filter.Filter<In, Out, X>) => Sink<Array<Out>, In, In>;
 /**
- * @since 4.0.0
+ * Effectfully collects input elements while the predicate succeeds.
+ *
+ * The first input for which the predicate returns `false` is consumed and
+ * excluded from the result. Any later elements from the same pulled array are
+ * returned as leftovers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeWhileEffect: {
     /**
-     * @since 4.0.0
+     * Effectfully collects input elements while the predicate succeeds.
+     *
+     * The first input for which the predicate returns `false` is consumed and
+     * excluded from the result. Any later elements from the same pulled array are
+     * returned as leftovers.
+     *
      * @category constructors
+     * @since 4.0.0
      */
     <In, E, R>(predicate: (input: In) => Effect.Effect<boolean, E, R>): Sink<Array<In>, In, In, E, R>;
 };
 /**
- * @since 4.0.0
+ * Effectfully applies a `FilterEffect` to input elements while it succeeds,
+ * collecting each successful output.
+ *
+ * The first input for which the filter fails is consumed and excluded from the
+ * result. Any later elements from the same pulled array are returned as
+ * leftovers.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeWhileFilterEffect: <In, Out, X, E, R>(filter: Filter.FilterEffect<In, Out, X, E, R>) => Sink<Array<Out>, In, In, E, R>;
 /**
- * @since 4.0.0
+ * Collects input elements until the predicate returns `true`, including the
+ * matching element in the result.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeUntil: <In>(predicate: Predicate<In>) => Sink<Array<In>, In, In>;
 /**
- * @since 4.0.0
+ * Effectfully collects input elements until the predicate returns `true`,
+ * including the matching element in the result.
+ *
+ * If the predicate effect fails, the sink fails with the same error.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const takeUntilEffect: <In, E, R>(predicate: (input: In) => Effect.Effect<boolean, E, R>) => Sink<Array<In>, In, In, E, R>;
 /**
  * A sink that executes the provided effectful function for every item fed
  * to it.
  *
- * @example
+ * **Example** (Running effects for each item)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -925,15 +1069,16 @@ export declare const takeUntilEffect: <In, E, R>(predicate: (input: In) => Effec
  * // Processing: 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const forEach: <In, X, E, R>(f: (input: In) => Effect.Effect<X, E, R>) => Sink<void, In, never, E, R>;
 /**
  * A sink that executes the provided effectful function for every Chunk fed
  * to it.
  *
- * @example
+ * **Example** (Running effects for each chunk)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -952,24 +1097,36 @@ export declare const forEach: <In, X, E, R>(f: (input: In) => Effect.Effect<X, E
  * // Output: Processing chunk of 5 items: [1, 2, 3, 4, 5]
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const forEachArray: <In, X, E, R>(f: (input: NonEmptyReadonlyArray<In>) => Effect.Effect<X, E, R>) => Sink<void, In, never, E, R>;
 /**
- * @since 2.0.0
+ * Runs an effectful function for each input element while it returns `true`.
+ *
+ * The sink stops consuming input when the function returns `false` or when the
+ * upstream stream ends, and completes with `void`.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const forEachWhile: <In, E, R>(f: (input: In) => Effect.Effect<boolean, E, R>) => Sink<void, In, never, E, R>;
 /**
- * @since 2.0.0
+ * Runs an effectful function for each non-empty input array while it returns
+ * `true`.
+ *
+ * The sink stops consuming input when the function returns `false` or when the
+ * upstream stream ends, and completes with `void`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export declare const forEachWhileArray: <In, E, R>(f: (input: NonEmptyReadonlyArray<In>) => Effect.Effect<boolean, E, R>) => Sink<void, In, never, E, R>;
 /**
  * Creates a sink produced from a scoped effect.
  *
- * @example
+ * **Example** (Unwrapping a sink effect)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -990,108 +1147,176 @@ export declare const forEachWhileArray: <In, E, R>(f: (input: NonEmptyReadonlyAr
  * // Item: 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 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.
  *
- * @since 2.0.0
  * @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.
      *
-     * @since 2.0.0
      * @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.
      *
-     * @since 2.0.0
      * @category utils
+     * @since 2.0.0
      */
     <A, In, L, E, R, A2, E2, R2, A3>(self: Sink<A, In, L, E, R>, summary: Effect.Effect<A2, E2, R2>, f: (start: A2, end: A2) => A3): Sink<[A, A3], In, L, E | E2, R | R2>;
 };
 /**
  * Returns the sink that executes this one and times its execution.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export declare const withDuration: <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<[A, Duration.Duration], In, L, E, R>;
 /**
- * @since 2.0.0
+ * A sink that drains all input and returns the elapsed duration.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const timed: Sink<Duration.Duration, unknown>;
 /**
- * @since 4.0.0
- * @category Services
+ * Provides a `Context` to this sink.
+ *
+ * Services contained in the provided context are removed from the sink's
+ * service requirements.
+ *
+ * @category services
+ * @since 2.0.0
  */
 export declare const provideContext: {
     /**
-     * @since 4.0.0
-     * @category Services
+     * Provides a `Context` to this sink.
+     *
+     * Services contained in the provided context are removed from the sink's
+     * service requirements.
+     *
+     * @category services
+     * @since 2.0.0
      */
     <Provided>(context: Context.Context<Provided>): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E, Exclude<R, Provided>>;
     /**
-     * @since 4.0.0
-     * @category Services
+     * Provides a `Context` to this sink.
+     *
+     * Services contained in the provided context are removed from the sink's
+     * service requirements.
+     *
+     * @category services
+     * @since 2.0.0
      */
     <A, In, L, E, R, Provided>(self: Sink<A, In, L, E, R>, context: Context.Context<Provided>): Sink<A, In, L, E, Exclude<R, Provided>>;
 };
 /**
+ * Provides a single service implementation to this sink.
+ *
+ * The service identified by `key` is removed from the sink's service
+ * requirements.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export declare const provideService: {
     /**
+     * Provides a single service implementation to this sink.
+     *
+     * The service identified by `key` is removed from the sink's service
+     * requirements.
+     *
+     * @category services
      * @since 4.0.0
-     * @category Services
      */
     <I, S>(key: Context.Key<I, S>, value: Types.NoInfer<S>): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E, Exclude<R, I>>;
     /**
+     * Provides a single service implementation to this sink.
+     *
+     * The service identified by `key` is removed from the sink's service
+     * requirements.
+     *
+     * @category services
      * @since 4.0.0
-     * @category Services
      */
     <A, In, L, E, R, I, S>(self: Sink<A, In, L, E, R>, key: Context.Key<I, S>, value: Types.NoInfer<S>): Sink<A, In, L, E, Exclude<R, I>>;
 };
 /**
+ * Runs a fallback sink if this sink fails with a typed error.
+ *
+ * The fallback is built from the error and continues consuming from the same
+ * upstream stream. If the upstream stream had already ended, the fallback sees
+ * the upstream end instead.
+ *
+ * @category error handling
  * @since 2.0.0
- * @category Error handling
  */
 export declare const orElse: {
     /**
+     * Runs a fallback sink if this sink fails with a typed error.
+     *
+     * The fallback is built from the error and continues consuming from the same
+     * upstream stream. If the upstream stream had already ended, the fallback sees
+     * the upstream end instead.
+     *
+     * @category error handling
      * @since 2.0.0
-     * @category Error handling
      */
     <E, A2, In2, L2, E2, R2>(f: (error: Types.NoInfer<E>) => Sink<A2, In2, L2, E2, R2>): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In & In2, L2 | L, E2 | E, R2 | R>;
     /**
+     * Runs a fallback sink if this sink fails with a typed error.
+     *
+     * The fallback is built from the error and continues consuming from the same
+     * upstream stream. If the upstream stream had already ended, the fallback sees
+     * the upstream end instead.
+     *
+     * @category error handling
      * @since 2.0.0
-     * @category Error handling
      */
     <A, In, L, E, R, A2, In2, L2, E2, R2>(self: Sink<A, In, L, E, R>, f: (error: E) => Sink<A2, In2, L2, E2, R2>): Sink<A | A2, In & In2, L | L2, E | E2, R | R2>;
 };
 /**
+ * Handles failures from this sink by inspecting the full `Cause`.
+ *
+ * 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.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export declare const catchCause: {
     /**
+     * Handles failures from this sink by inspecting the full `Cause`.
+     *
+     * 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.
+     *
+     * @category error handling
      * @since 4.0.0
-     * @category Error handling
      */
     <E, A2, E2, R2>(f: (error: Cause.Cause<Types.NoInfer<E>>) => Effect.Effect<A2, E2, R2>): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In, L, E, R2 | R>;
     /**
+     * Handles failures from this sink by inspecting the full `Cause`.
+     *
+     * 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.
+     *
+     * @category error handling
      * @since 4.0.0
-     * @category Error handling
      */
     <A, In, L, E, R, A2, E2, R2>(self: Sink<A, In, L, E, R>, f: (error: Cause.Cause<E>) => Effect.Effect<A2, E2, R2>): Sink<A | A2, In, L, E2, R | R2>;
 };
@@ -1101,39 +1326,69 @@ declare const catch_: {
 };
 export { 
 /**
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 catch_ as catch };
 /**
- * @since 4.0.0
+ * Runs an effect after this sink completes, fails, or is interrupted.
+ *
+ * The effect receives the sink's `Exit` for the result value. The original
+ * sink result and leftovers are preserved unless the finalizer itself fails.
+ *
  * @category Finalization
+ * @since 4.0.0
  */
 export declare const onExit: {
     /**
-     * @since 4.0.0
+     * Runs an effect after this sink completes, fails, or is interrupted.
+     *
+     * The effect receives the sink's `Exit` for the result value. The original
+     * sink result and leftovers are preserved unless the finalizer itself fails.
+     *
      * @category Finalization
+     * @since 4.0.0
      */
     <A, E, X, E2, R2>(f: (exit: Exit.Exit<A, E>) => Effect.Effect<X, E2, R2>): <In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E | E2, R2 | R>;
     /**
-     * @since 4.0.0
+     * Runs an effect after this sink completes, fails, or is interrupted.
+     *
+     * The effect receives the sink's `Exit` for the result value. The original
+     * sink result and leftovers are preserved unless the finalizer itself fails.
+     *
      * @category Finalization
+     * @since 4.0.0
      */
     <A, In, L, E, R, X, E2, R2>(self: Sink<A, In, L, E, R>, f: (exit: Exit.Exit<A, E>) => Effect.Effect<X, E2, R2>): Sink<A, In, L, E | E2, R | R2>;
 };
 /**
- * @since 4.0.0
+ * Runs a finalizer effect after this sink completes, fails, or is interrupted.
+ *
+ * The original sink result and leftovers are preserved unless the finalizer
+ * itself fails.
+ *
  * @category Finalization
+ * @since 2.0.0
  */
 export declare const ensuring: {
     /**
-     * @since 4.0.0
+     * Runs a finalizer effect after this sink completes, fails, or is interrupted.
+     *
+     * The original sink result and leftovers are preserved unless the finalizer
+     * itself fails.
+     *
      * @category Finalization
+     * @since 2.0.0
      */
     <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E | E2, R2 | R>;
     /**
-     * @since 4.0.0
+     * Runs a finalizer effect after this sink completes, fails, or is interrupted.
+     *
+     * The original sink result and leftovers are preserved unless the finalizer
+     * itself fails.
+     *
      * @category Finalization
+     * @since 2.0.0
      */
     <A, In, L, E, R, X, E2, R2>(self: Sink<A, In, L, E, R>, effect: Effect.Effect<X, E2, R2>): Sink<A, In, L, E | E2, R | R2>;
 };