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

package/dist/Sink.js

@@ -33,7 +33,8 @@ const SinkProto = {
 /**
  * Checks if a value is a Sink.
  *
- * @example
+ * **Example** (Checking for a sink)
+ *
  * ```ts
  * import { Sink } from "effect"
  *
@@ -44,22 +45,28 @@ const SinkProto = {
  * console.log(Sink.isSink(notStream)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isSink = u => hasProperty(u, TypeId);
 /**
  * Creates a sink from a `Channel`.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromChannel = channel => fromTransform((upstream, scope) => Channel.toTransform(channel)(upstream, scope).pipe(Effect.flatMap(Effect.forever({
   disableYield: true
 })), Pull.catchDone(Effect.succeed)));
 /**
- * @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 const fromTransform = transform => {
   const self = Object.create(SinkProto);
@@ -69,7 +76,8 @@ export const fromTransform = transform => {
 /**
  * Creates a `Channel` from a Sink.
  *
- * @example
+ * **Example** (Converting a sink to a channel)
+ *
  * ```ts
  * import { Sink } from "effect"
  *
@@ -78,28 +86,50 @@ export const fromTransform = transform => {
  * const channel = Sink.toChannel(sink)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const toChannel = self => Channel.fromTransform((upstream, scope) => Effect.succeed(Effect.flatMap(self.transform(upstream, scope), Cause.done)));
 /**
- * @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 const make = () => (...fns) => fromTransform((upstream, scope) => pipe(internalStream.fromChannel(Channel.fromPull(Effect.succeed(upstream))), ...fns, Effect.flatMap(a => Cause.done([a])), Scope.provide(scope)));
 /**
- * @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 const fromEffectEnd = effect => fromTransform(() => effect);
 /**
- * @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 const fromEffect = effect => fromEffectEnd(Effect.map(effect, a => [a]));
 /**
- * @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 const fromQueue = queue => fromTransform(upstream => upstream.pipe(Effect.flatMap(arr => Queue.offerAll(queue, arr)), Effect.forever({
   disableYield: true
@@ -108,14 +138,19 @@ export const fromQueue = queue => fromTransform(upstream => upstream.pipe(Effect
   return endVoid;
 })));
 /**
- * @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 const fromPubSub = pubsub => forEachArray(arr => PubSub.publishAll(pubsub, arr));
 /**
  * A sink that immediately ends with the specified value.
  *
- * @example
+ * **Example** (Succeeding with a value)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -130,28 +165,29 @@ export const fromPubSub = pubsub => forEachArray(arr => PubSub.publishAll(pubsub
  * // Output: 42
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const succeed = (a, leftovers) => fromEffectEnd(Effect.succeed([a, leftovers]));
 /**
  * A sink that immediately ends with the specified lazily evaluated value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const sync = a => fromEffect(Effect.sync(a));
 /**
  * A sink that is created from a lazily evaluated sink.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const suspend = evaluate => fromTransform((upstream, scope) => evaluate().transform(upstream, scope));
 /**
  * A sink that always fails with the specified error.
  *
- * @example
+ * **Example** (Failing with an error)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -166,14 +202,15 @@ export const suspend = evaluate => fromTransform((upstream, scope) => evaluate()
  * // Output: Error: Sink failed
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fail = e => fromEffectEnd(Effect.fail(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"
  *
@@ -188,14 +225,15 @@ export const fail = e => fromEffectEnd(Effect.fail(e));
  * // Output: Error: Lazy error
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failSync = evaluate => fromEffectEnd(Effect.failSync(evaluate));
 /**
  * Creates a sink halting with a specified `Cause`.
  *
- * @example
+ * **Example** (Failing with a cause)
+ *
  * ```ts
  * import { Cause, Effect, Sink, Stream } from "effect"
  *
@@ -210,14 +248,15 @@ export const failSync = evaluate => fromEffectEnd(Effect.failSync(evaluate));
  * // Output: Error: Custom cause
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failCause = cause => fromEffectEnd(Effect.failCause(cause));
 /**
  * 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"
  *
@@ -232,14 +271,15 @@ export const failCause = cause => fromEffectEnd(Effect.failCause(cause));
  * // Output: Error: Lazy cause
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const failCauseSync = evaluate => fromEffectEnd(Effect.failCauseSync(evaluate));
 /**
  * Creates a sink halting with a specified defect.
  *
- * @example
+ * **Example** (Dying with a defect)
+ *
  * ```ts
  * import { Effect, Sink, Stream } from "effect"
  *
@@ -254,29 +294,33 @@ export const failCauseSync = evaluate => fromEffectEnd(Effect.failCauseSync(eval
  * // Output: Error: Defect error
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const die = defect => fromEffectEnd(Effect.die(defect));
 /**
  * A sink that never completes.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const never = /*#__PURE__*/fromEffectEnd(Effect.never);
 /**
- * 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 const ignoreLeftover = self => mapEnd(self, ([a]) => [a]);
 /**
  * Drains elements from the stream by ignoring all inputs.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const drain = /*#__PURE__*/fromTransform(upstream => Pull.catchDone(Effect.forever(upstream, {
   disableYield: true
@@ -285,8 +329,8 @@ export const drain = /*#__PURE__*/fromTransform(upstream => Pull.catchDone(Effec
  * 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 const fold = (s, contFn, f) => fromTransform(upstream => {
   let state = s();
@@ -302,8 +346,14 @@ export const fold = (s, contFn, f) => fromTransform(upstream => {
   }).pipe(Pull.catchDone(() => Effect.succeed([state])));
 });
 /**
- * @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 const foldArray = (s, contFn, f) => fromTransform(upstream => {
   let state = s();
@@ -317,105 +367,124 @@ export const foldArray = (s, contFn, f) => fromTransform(upstream => {
   }).pipe(Pull.catchDone(() => Effect.succeed([state])));
 });
 /**
- * @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 const foldUntil = (s, max, f) => fold(() => [s(), 0], tuple => tuple[1] < max, ([output, count], input) => Effect.map(f(output, input), s => [s, count + 1])).pipe(map(tuple => tuple[0]));
 /**
  * A sink that returns whether all elements satisfy the specified predicate.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const every = predicate => fold(constTrue, identity, (_, a) => Effect.succeed(predicate(a)));
 /**
  * A sink that returns whether an element satisfies the specified predicate.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const some = predicate => fold(constFalse, b => !b, (_, a) => Effect.succeed(predicate(a)));
 /**
  * Transforms this sink's result.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => mapEnd(self, ([a, l]) => [f(a), l]));
 /**
  * Set the sink's result to a constant value.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const as = /*#__PURE__*/dual(2, (self, a2) => map(self, () => a2));
 /**
  * Transforms this sink's input elements.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const mapInput = /*#__PURE__*/dual(2, (self, f) => mapInputArray(self, Arr.map(f)));
 /**
  * Effectfully transforms this sink's input elements.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const mapInputEffect = /*#__PURE__*/dual(2, (self, f) => mapInputArrayEffect(self, Effect.forEach(f)));
 /**
- * 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 const mapInputArray = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => self.transform(Effect.map(upstream, f), scope)));
 /**
- * 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 const mapInputArrayEffect = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => self.transform(Effect.flatMap(upstream, f), scope)));
 /**
- * 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 const mapEnd = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => Effect.map(self.transform(upstream, scope), f)));
 const transformEffect = (self, f) => fromTransform((upstream, scope) => f(self.transform(upstream, scope)));
 /**
- * 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 const mapEffectEnd = /*#__PURE__*/dual(2, (self, f) => transformEffect(self, Effect.flatMap(f)));
 /**
  * Effectfully transforms this sink's result.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const mapEffect = /*#__PURE__*/dual(2, (self, f) => mapEffectEnd(self, ([a, l]) => Effect.map(f(a), a2 => [a2, l])));
 /**
  * Transforms the errors emitted by this sink using `f`.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const mapError = /*#__PURE__*/dual(2, (self, f) => transformEffect(self, Effect.mapError(f)));
 /**
  * Transforms the leftovers emitted by this sink using `f`.
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const mapLeftover = /*#__PURE__*/dual(2, (self, f) => mapEnd(self, ([a, l]) => [a, l && Arr.map(l, f)]));
 /**
- * @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 const take = n => fromTransform(upstream => {
   const taken = [];
@@ -452,8 +521,8 @@ export const take = n => fromTransform(upstream => {
  *
  * This function essentially runs sinks in sequence.
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const flatMap = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => {
   let upstreamDone = false;
@@ -476,8 +545,8 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream
  * 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 const reduceWhile = (initial, predicate, f) => fromTransform(upstream => {
   let state = initial();
@@ -505,8 +574,8 @@ export const reduceWhile = (initial, predicate, f) => fromTransform(upstream =>
  * starting from the provided `initial` state while the specified `predicate`
  * returns `true`.
  *
- * @since 2.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export const reduceWhileEffect = (initial, predicate, f) => fromTransform(upstream => {
   let state = initial();
@@ -538,8 +607,8 @@ export const reduceWhileEffect = (initial, predicate, f) => fromTransform(upstre
  * 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 const reduceWhileArray = (initial, contFn, f) => fromTransform(upstream => {
   let state = initial();
@@ -563,8 +632,8 @@ export const reduceWhileArray = (initial, contFn, f) => fromTransform(upstream =
  * starting from the provided `initial` state while the specified `predicate`
  * returns `true`.
  *
- * @since 4.0.0
  * @category reducing
+ * @since 4.0.0
  */
 export const reduceWhileArrayEffect = (initial, predicate, f) => fromTransform(upstream => {
   let state = initial();
@@ -585,8 +654,8 @@ export const reduceWhileArrayEffect = (initial, predicate, f) => fromTransform(u
  * 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 const reduce = (initial, f) => reduceArray(initial, (s, arr) => {
   for (let i = 0; i < arr.length; i++) {
@@ -598,8 +667,8 @@ export const reduce = (initial, f) => reduceArray(initial, (s, arr) => {
  * 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 const reduceArray = (initial, f) => fromTransform(upstream => {
   let state = initial();
@@ -614,45 +683,45 @@ export const reduceArray = (initial, f) => fromTransform(upstream => {
  * 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 const reduceEffect = (initial, f) => reduceWhileEffect(initial, constTrue, f);
 const head_ = /*#__PURE__*/reduceWhile(Option.none, Option.isNone, (_, in_) => Option.some(in_));
 /**
  * Creates a sink containing the first value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const head = () => head_;
 const last_ = /*#__PURE__*/reduceArray(Option.none, (_, arr) => Arr.last(arr));
 /**
  * Creates a sink containing the last value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const last = () => last_;
 /**
  * Creates a sink containing the first matching value.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const find = predicate => reduceWhile(Option.none, Option.isNone, (acc, in_) => predicate(in_) ? Option.some(in_) : acc);
 /**
  * Creates a sink containing the first matching value.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const findEffect = predicate => reduceWhileEffect(Option.none, Option.isNone, (acc, in_) => Effect.map(predicate(in_), b => b ? Option.some(in_) : acc));
 /**
  * Creates a sink which sums up its inputs.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const sum = /*#__PURE__*/reduceArray(() => 0, (s, arr) => {
   for (let i = 0; i < arr.length; i++) {
@@ -663,23 +732,29 @@ export const sum = /*#__PURE__*/reduceArray(() => 0, (s, arr) => {
 /**
  * A sink that counts the number of elements fed to it.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const count = /*#__PURE__*/reduceArray(() => 0, (s, arr) => s + arr.length);
 /**
  * Accumulates incoming elements into an array.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const collect = () => reduceArray(Arr.empty, (s, arr) => {
   s.push(...arr);
   return s;
 });
 /**
- * @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 const takeWhile = predicate => fromTransform(upstream => {
   const out = Arr.empty();
@@ -697,8 +772,15 @@ export const takeWhile = predicate => fromTransform(upstream => {
   }), Pull.catchDone(end => Effect.succeed(end ?? [out])));
 });
 /**
- * @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 const takeWhileFilter = filter => fromTransform(upstream => {
   const out = Arr.empty();
@@ -717,8 +799,14 @@ export const takeWhileFilter = filter => fromTransform(upstream => {
   }), Pull.catchDone(end => Effect.succeed(end ?? [out])));
 });
 /**
- * @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 const takeWhileEffect = predicate => fromTransform(upstream => {
   const out = Arr.empty();
@@ -747,8 +835,15 @@ export const takeWhileEffect = predicate => fromTransform(upstream => {
   }), Pull.catchDone(() => Effect.succeed([out, leftover])));
 });
 /**
- * @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 const takeWhileFilterEffect = filter => fromTransform(upstream => {
   const out = Arr.empty();
@@ -774,8 +869,11 @@ export const takeWhileFilterEffect = filter => fromTransform(upstream => {
   }), Pull.catchDone(() => Effect.succeed([out, leftover])));
 });
 /**
- * @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 const takeUntil = predicate => suspend(() => {
   let done = false;
@@ -786,8 +884,13 @@ export const takeUntil = predicate => suspend(() => {
   });
 });
 /**
- * @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 const takeUntilEffect = predicate => suspend(() => {
   let done = false;
@@ -805,7 +908,8 @@ export const takeUntilEffect = predicate => suspend(() => {
  * 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"
  *
@@ -823,8 +927,8 @@ export const takeUntilEffect = predicate => suspend(() => {
  * // Processing: 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const forEach = f => forEachArray(Effect.forEach(_ => f(_), {
   discard: true
@@ -833,7 +937,8 @@ export const forEach = f => forEachArray(Effect.forEach(_ => f(_), {
  * 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"
  *
@@ -852,15 +957,20 @@ export const forEach = f => forEachArray(Effect.forEach(_ => f(_), {
  * // Output: Processing chunk of 5 items: [1, 2, 3, 4, 5]
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const forEachArray = f => fromTransform(upstream => upstream.pipe(Effect.flatMap(f), Effect.forever({
   disableYield: true
 }), Pull.catchDone(() => endVoid)));
 /**
- * @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 const forEachWhile = f => forEachWhileArray(Effect.fnUntraced(function* (input) {
   for (let i = 0; i < input.length; i++) {
@@ -870,8 +980,14 @@ export const forEachWhile = f => forEachWhileArray(Effect.fnUntraced(function* (
   return true;
 }));
 /**
- * @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 const forEachWhileArray = f => fromTransform(upstream => upstream.pipe(Effect.flatMap(f), Effect.flatMap(cont => cont ? Effect.void : Cause.done()), Effect.forever({
   disableYield: true
@@ -879,7 +995,8 @@ export const forEachWhileArray = f => fromTransform(upstream => upstream.pipe(Ef
 /**
  * Creates a sink produced from a scoped effect.
  *
- * @example
+ * **Example** (Unwrapping a sink effect)
+ *
  * ```ts
  * import { Console, Effect, Sink, Stream } from "effect"
  *
@@ -900,16 +1017,16 @@ export const forEachWhileArray = f => fromTransform(upstream => upstream.pipe(Ef
  * // Item: 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const unwrap = effect => fromChannel(Channel.unwrap(Effect.map(effect, toChannel)));
 /**
  * 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 const summarized = /*#__PURE__*/dual(3, (self, summary, f) => fromTransform(Effect.fnUntraced(function* (upstream, scope) {
   const start = yield* summary;
@@ -920,28 +1037,46 @@ export const summarized = /*#__PURE__*/dual(3, (self, summary, f) => fromTransfo
 /**
  * Returns the sink that executes this one and times its execution.
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const withDuration = self => summarized(self, Clock.currentTimeNanos, (start, end) => Duration.nanos(end - start));
 /**
- * @since 2.0.0
+ * A sink that drains all input and returns the elapsed duration.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export const timed = /*#__PURE__*/map(/*#__PURE__*/withDuration(drain), ([, duration]) => duration);
 /**
- * @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 const provideContext = /*#__PURE__*/dual(2, (self, context) => fromTransform((upstream, scope) => self.transform(upstream, scope).pipe(Effect.provideContext(context))));
 /**
+ * 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 const provideService = /*#__PURE__*/dual(3, (self, key, value) => fromTransform((upstream, scope) => self.transform(upstream, scope).pipe(Effect.provideService(key, value))));
 /**
+ * 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 const orElse = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream, scope) => {
   let upstreamDone = false;
@@ -957,25 +1092,41 @@ export const orElse = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstream,
   }), scope));
 }));
 /**
+ * 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 const catchCause = /*#__PURE__*/dual(2, (self, f) => transformEffect(self, Effect.catchCause(cause => Effect.map(f(cause), a2 => [a2]))));
 const catch_ = /*#__PURE__*/dual(2, (self, f) => transformEffect(self, Effect.catch(error => Effect.map(f(error), a2 => [a2]))));
 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 const onExit = /*#__PURE__*/dual(2, (self, f) => transformEffect(self, Effect.onExit(exit => f(Exit.map(exit, ([a]) => a)))));
 /**
- * @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 const ensuring = /*#__PURE__*/dual(2, (self, effect) => onExit(self, () => effect));
 //# sourceMappingURL=Sink.js.map