effect 4.0.0-beta.71 → 4.0.0-beta.73

package/dist/Channel.d.ts

@@ -95,7 +95,7 @@ import type * as Unify from "./Unify.ts";
 /**
  * String literal type used as the unique brand for `Channel` values.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/Channel";
@@ -103,12 +103,12 @@ export type TypeId = "~effect/Channel";
  * Runtime identifier stored on `Channel` values and used by `isChannel` to
  * recognize them.
  *
- * @category Type Identifiers
+ * @category type IDs
  * @since 4.0.0
  */
 export declare const TypeId: TypeId;
 /**
- * Tests if a value is a `Channel`.
+ * Checks whether a value is a `Channel`.
  *
  * **Example** (Checking for channels)
  *
@@ -717,7 +717,7 @@ export declare const endSync: <A>(evaluate: LazyArg<A>) => Channel<never, never,
  */
 export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
 /**
- * Represents an Channel that emits no elements
+ * Represents a `Channel` that emits no elements.
  *
  * **Example** (Using empty channels)
  *
@@ -741,7 +741,7 @@ export declare const sync: <A>(evaluate: LazyArg<A>) => Channel<A>;
  */
 export declare const empty: Channel<never>;
 /**
- * Represents an Channel that never completes
+ * Represents a `Channel` that never completes.
  *
  * **Example** (Using non-terminating channels)
  *
@@ -908,7 +908,7 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Ch
  */
 export declare const die: (defect: unknown) => Channel<never, never, never>;
 /**
- * Use an effect to write a single value to the channel.
+ * Uses an effect to write a single value to the channel.
  *
  * **Example** (Creating channels from effects)
  *
@@ -958,7 +958,7 @@ export declare const fromEffect: <A, E, R>(effect: Effect.Effect<A, E, R>) => Ch
  */
 export declare const fromEffectDone: <A, E, R>(effect: Effect.Effect<A, E, R>) => Channel<never, Pull.ExcludeDone<E>, A, unknown, unknown, unknown, R>;
 /**
- * Use an effect and discard its result.
+ * Uses an effect and discards its result.
  *
  * @category constructors
  * @since 4.0.0
@@ -978,7 +978,7 @@ export declare const fromEffectDrain: <A, E, R>(effect: Effect.Effect<A, E, R>)
  */
 export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<Take.Take<A, E, Done>, E2, R>) => Channel<Arr.NonEmptyReadonlyArray<A>, E | E2, Done, unknown, unknown, unknown, R>;
 /**
- * Create a channel from a queue
+ * Creates a channel from a queue.
  *
  * **Example** (Creating channels from queues)
  *
@@ -1018,7 +1018,7 @@ export declare const fromEffectTake: <A, E, Done, E2, R>(effect: Effect.Effect<T
  */
 export declare const fromQueue: <A, E>(queue: Queue.Dequeue<A, E>) => Channel<A, Exclude<E, Cause.Done>>;
 /**
- * Create a channel from a queue that emits arrays of elements
+ * Creates a channel from a queue that emits arrays of elements.
  *
  * **Example** (Creating batched channels from queues)
  *
@@ -1070,7 +1070,7 @@ export declare const fromQueueArray: <A, E>(queue: Queue.Dequeue<A, E>) => Chann
  */
 export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, Elem, Err, Done>;
 /**
- * Create a channel from a PubSub subscription
+ * Creates a channel from a PubSub subscription.
  *
  * **Example** (Creating channels from subscriptions)
  *
@@ -1115,7 +1115,7 @@ export declare const identity: <Elem, Err, Done>() => Channel<Elem, Err, Done, E
  */
 export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>) => Channel<A>;
 /**
- * Create a channel from a PubSub subscription that outputs arrays of values.
+ * Creates a channel from a PubSub subscription that outputs arrays of values.
  *
  * **Details**
  *
@@ -1218,7 +1218,7 @@ export declare const fromSubscription: <A>(subscription: PubSub.Subscription<A>)
  */
 export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscription<A>) => Channel<Arr.NonEmptyReadonlyArray<A>>;
 /**
- * Create a channel from a PubSub that outputs individual values.
+ * Creates a channel from a PubSub that outputs individual values.
  *
  * **Details**
  *
@@ -1312,7 +1312,7 @@ export declare const fromSubscriptionArray: <A>(subscription: PubSub.Subscriptio
  */
 export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Channel<A>;
 /**
- * Create a channel from a PubSub that outputs arrays of values.
+ * Creates a channel from a PubSub that outputs arrays of values.
  *
  * **Details**
  *
@@ -2257,33 +2257,54 @@ export declare const concat: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, that: Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
 /**
- * Combines the elements from this channel and the specified channel by
- * repeatedly applying the function `f` to extract an element using both sides
- * and conceptually "offer" it to the destination channel. `f` can maintain
- * some internal state to control the combining process, with the initial
- * state being specified by `s`.
+ * Combines two channels with a stateful pull function.
+ *
+ * **When to use**
+ *
+ * Use to coordinate pulling from two channels when each output element depends
+ * on both sides and local state.
+ *
+ * **Details**
+ *
+ * The combining function receives the current state and pull functions for the
+ * left and right channels. It returns the next output element together with the
+ * next state.
  *
  * @category sequencing
  * @since 4.0.0
  */
 export declare const combine: {
     /**
-     * Combines the elements from this channel and the specified channel by
-     * repeatedly applying the function `f` to extract an element using both sides
-     * and conceptually "offer" it to the destination channel. `f` can maintain
-     * some internal state to control the combining process, with the initial
-     * state being specified by `s`.
+     * Combines two channels with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling from two channels when each output element depends
+     * on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right channels. It returns the next output element together with the
+     * next state.
      *
      * @category sequencing
      * @since 4.0.0
      */
     <OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2, S, OutElem, OutErr, OutDone, A, E, R>(that: Channel<OutElem2, OutErr2, OutDone2, InElem2, InErr2, InDone2, Env2>, s: LazyArg<S>, f: (s: S, pullLeft: Pull.Pull<OutElem, OutErr, OutDone>, pullRight: Pull.Pull<OutElem2, OutErr2, OutDone2>) => Effect.Effect<readonly [A, S], E, R>): <InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<A, Pull.ExcludeDone<E>, Cause.Done.Extract<E>, InElem & InElem2, InErr & InErr2, InDone & InDone2, Env | Env2 | R>;
     /**
-     * Combines the elements from this channel and the specified channel by
-     * repeatedly applying the function `f` to extract an element using both sides
-     * and conceptually "offer" it to the destination channel. `f` can maintain
-     * some internal state to control the combining process, with the initial
-     * state being specified by `s`.
+     * Combines two channels with a stateful pull function.
+     *
+     * **When to use**
+     *
+     * Use to coordinate pulling from two channels when each output element depends
+     * on both sides and local state.
+     *
+     * **Details**
+     *
+     * The combining function receives the current state and pull functions for the
+     * left and right channels. It returns the next output element together with the
+     * next state.
      *
      * @category sequencing
      * @since 4.0.0
@@ -2334,7 +2355,7 @@ export declare const orElseIfEmpty: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, f: (leftover: Types.NoInfer<OutDone>) => Channel<OutElem1, OutErr1, OutDone1, InElem1, InErr1, InDone1, Env1>): Channel<OutElem | OutElem1, OutErr1 | OutErr, OutDone | OutDone1, InElem & InElem1, InErr & InErr1, InDone & InDone1, Env1 | Env>;
 };
 /**
- * Flatten a channel of channels.
+ * Flattens a channel of channels.
  *
  * **Example** (Flattening nested channels)
  *
@@ -3138,7 +3159,7 @@ export declare const filterMapArrayEffect: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, B, X, EX, RX>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>, filter: Filter.FilterEffect<OutElem, B, X, EX, RX>): Channel<Arr.NonEmptyReadonlyArray<B>, OutErr | EX, OutDone, InElem, InErr, InDone, Env | RX>;
 };
 /**
- * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+ * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
  *
  * **Example** (Mapping with accumulated state)
  *
@@ -3177,7 +3198,7 @@ export declare const filterMapArrayEffect: {
  */
 export declare const mapAccum: {
     /**
-     * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+     * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
      *
      * **Example** (Mapping with accumulated state)
      *
@@ -3218,7 +3239,7 @@ export declare const mapAccum: {
         readonly onHalt?: ((state: S) => Array<B>) | undefined;
     }): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<B, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * Statefully maps over a channel with an accumulator, where each element can produce multiple output values.
+     * Maps over a channel statefully with an accumulator, where each element can produce multiple output values.
      *
      * **Example** (Mapping with accumulated state)
      *
@@ -3260,7 +3281,7 @@ export declare const mapAccum: {
     }): Channel<B, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Statefully transforms a channel by scanning over its output with an accumulator function.
+ * Transforms a channel statefully by scanning over its output with an accumulator function.
  * Emits the intermediate results of the scan operation.
  *
  * **Example** (Scanning channel output)
@@ -3291,7 +3312,7 @@ export declare const mapAccum: {
  */
 export declare const scan: {
     /**
-     * Statefully transforms a channel by scanning over its output with an accumulator function.
+     * Transforms a channel statefully by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output)
@@ -3322,7 +3343,7 @@ export declare const scan: {
      */
     <S, OutElem>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Statefully transforms a channel by scanning over its output with an accumulator function.
+     * Transforms a channel statefully by scanning over its output with an accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output)
@@ -3354,7 +3375,7 @@ export declare const scan: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => S): Channel<S, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+ * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
  * **Example** (Scanning channel output with effects)
@@ -3400,7 +3421,7 @@ export declare const scan: {
  */
 export declare const scanEffect: {
     /**
-     * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+     * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output with effects)
@@ -3446,7 +3467,7 @@ export declare const scanEffect: {
      */
     <S, OutElem, E, R>(initial: S, f: (s: S, a: Types.NoInfer<OutElem>) => Effect.Effect<S, E, R>): <OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<S, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
     /**
-     * Statefully transforms a channel by scanning over its output with an effectful accumulator function.
+     * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
      * Emits the intermediate results of the scan operation.
      *
      * **Example** (Scanning channel output with effects)
@@ -5171,8 +5192,8 @@ export declare const embedInput: {
     <OutElem, OutErr, OutDone, Env, InErr, InElem, InDone, R>(self: Channel<OutElem, OutErr, OutDone, unknown, unknown, unknown, Env>, input: (upstream: Pull.Pull<InElem, InErr, InDone>) => Effect.Effect<void, never, R>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Allows a faster producer to progress independently of a slower consumer by
- * buffering up to `capacity` elements in a queue.
+ * Buffers individual output elements in a queue with the configured `capacity`
+ * so a faster producer can progress independently of a slower consumer.
  *
  * **Details**
  *
@@ -5192,8 +5213,8 @@ export declare const embedInput: {
  */
 export declare const buffer: {
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers individual output elements in a queue with the configured `capacity`
+     * so a faster producer can progress independently of a slower consumer.
      *
      * **Details**
      *
@@ -5218,8 +5239,8 @@ export declare const buffer: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers individual output elements in a queue with the configured `capacity`
+     * so a faster producer can progress independently of a slower consumer.
      *
      * **Details**
      *
@@ -5245,8 +5266,8 @@ export declare const buffer: {
     }): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Allows a faster producer to progress independently of a slower consumer by
- * buffering up to `capacity` elements in a queue.
+ * Buffers array output elements in a queue with the configured `capacity` so a
+ * faster producer can progress independently of a slower consumer.
  *
  * **Details**
  *
@@ -5268,8 +5289,8 @@ export declare const buffer: {
  */
 export declare const bufferArray: {
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers array output elements in a queue with the configured `capacity` so a
+     * faster producer can progress independently of a slower consumer.
      *
      * **Details**
      *
@@ -5296,8 +5317,8 @@ export declare const bufferArray: {
         readonly strategy?: "dropping" | "sliding" | "suspend" | undefined;
     }): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
     /**
-     * Allows a faster producer to progress independently of a slower consumer by
-     * buffering up to `capacity` elements in a queue.
+     * Buffers array output elements in a queue with the configured `capacity` so a
+     * faster producer can progress independently of a slower consumer.
      *
      * **Details**
      *
@@ -5325,39 +5346,54 @@ export declare const bufferArray: {
     }): Channel<Arr.NonEmptyReadonlyArray<OutElem>, OutErr, OutDone, InElem, InErr, InDone, Env>;
 };
 /**
- * Returns a new channel, which is the same as this one, except it will be
- * interrupted when the specified effect completes. If the effect completes
- * successfully before the underlying channel is done, then the returned
- * channel will yield the success value of the effect as its terminal value.
- * On the other hand, if the underlying channel finishes first, then the
- * returned channel will yield the success value of the underlying channel as
- * its terminal value.
+ * Interrupts a channel when another effect completes.
+ *
+ * **When to use**
+ *
+ * Use to race channel execution against an external effect whose success can
+ * become the channel's done value.
+ *
+ * **Details**
+ *
+ * If the effect completes first, its success value becomes the returned
+ * channel's done value. If the channel completes first, the original channel's
+ * done value is preserved.
  *
  * @category utils
  * @since 2.0.0
  */
 export declare const interruptWhen: {
     /**
-     * Returns a new channel, which is the same as this one, except it will be
-     * interrupted when the specified effect completes. If the effect completes
-     * successfully before the underlying channel is done, then the returned
-     * channel will yield the success value of the effect as its terminal value.
-     * On the other hand, if the underlying channel finishes first, then the
-     * returned channel will yield the success value of the underlying channel as
-     * its terminal value.
+     * Interrupts a channel when another effect completes.
+     *
+     * **When to use**
+     *
+     * Use to race channel execution against an external effect whose success can
+     * become the channel's done value.
+     *
+     * **Details**
+     *
+     * If the effect completes first, its success value becomes the returned
+     * channel's done value. If the channel completes first, the original channel's
+     * done value is preserved.
      *
      * @category utils
      * @since 2.0.0
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel, which is the same as this one, except it will be
-     * interrupted when the specified effect completes. If the effect completes
-     * successfully before the underlying channel is done, then the returned
-     * channel will yield the success value of the effect as its terminal value.
-     * On the other hand, if the underlying channel finishes first, then the
-     * returned channel will yield the success value of the underlying channel as
-     * its terminal value.
+     * Interrupts a channel when another effect completes.
+     *
+     * **When to use**
+     *
+     * Use to race channel execution against an external effect whose success can
+     * become the channel's done value.
+     *
+     * **Details**
+     *
+     * If the effect completes first, its success value becomes the returned
+     * channel's done value. If the channel completes first, the original channel's
+     * done value is preserved.
      *
      * @category utils
      * @since 2.0.0
@@ -5365,7 +5401,7 @@ export declare const interruptWhen: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, OutDone2, OutErr2, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, effect: Effect.Effect<OutDone2, OutErr2, Env2>): Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Halts a channel when the specified effect completes or fails.
+ * Stops a channel when the specified effect completes or fails.
  *
  * **Details**
  *
@@ -5379,7 +5415,7 @@ export declare const interruptWhen: {
  */
 export declare const haltWhen: {
     /**
-     * Halts a channel when the specified effect completes or fails.
+     * Stops a channel when the specified effect completes or fails.
      *
      * **Details**
      *
@@ -5393,7 +5429,7 @@ export declare const haltWhen: {
      */
     <OutDone2, OutErr2, Env2>(effect: Effect.Effect<OutDone2, OutErr2, Env2>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | OutErr2, OutDone | OutDone2, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Halts a channel when the specified effect completes or fails.
+     * Stops a channel when the specified effect completes or fails.
      *
      * **Details**
      *
@@ -5445,9 +5481,8 @@ export declare const onError: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: (cause: Cause.Cause<OutErr>) => Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Returns a new channel with an attached finalizer. The finalizer is
- * guaranteed to be executed so long as the channel begins execution (and
- * regardless of whether or not it completes).
+ * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+ * the channel begins execution, whether it succeeds or fails.
  *
  * **Example** (Running exit finalizers)
  *
@@ -5476,9 +5511,8 @@ export declare const onError: {
  */
 export declare const onExit: {
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+     * the channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Running exit finalizers)
      *
@@ -5507,9 +5541,8 @@ export declare const onExit: {
      */
     <OutDone, OutErr, Env2>(finalizer: (e: Exit.Exit<OutDone, OutErr>) => Effect.Effect<unknown, never, Env2>): <OutElem, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with an exit-aware finalizer that is guaranteed to run once
+     * the channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Running exit finalizers)
      *
@@ -5656,9 +5689,8 @@ export declare const onEnd: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, A, E, R>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, onEnd: Effect.Effect<A, E, R>): Channel<OutElem, OutErr | E, OutDone, InElem, InErr, InDone, Env | R>;
 };
 /**
- * Returns a new channel with an attached finalizer. The finalizer is
- * guaranteed to be executed so long as the channel begins execution (and
- * regardless of whether or not it completes).
+ * Returns a channel with a finalizer effect that is guaranteed to run once the
+ * channel begins execution, whether it succeeds or fails.
  *
  * **Example** (Ensuring cleanup runs)
  *
@@ -5684,9 +5716,8 @@ export declare const onEnd: {
  */
 export declare const ensuring: {
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with a finalizer effect that is guaranteed to run once the
+     * channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Ensuring cleanup runs)
      *
@@ -5712,9 +5743,8 @@ export declare const ensuring: {
      */
     <Env2>(finalizer: Effect.Effect<unknown, never, Env2>): <OutElem, OutDone, OutErr, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
     /**
-     * Returns a new channel with an attached finalizer. The finalizer is
-     * guaranteed to be executed so long as the channel begins execution (and
-     * regardless of whether or not it completes).
+     * Returns a channel with a finalizer effect that is guaranteed to run once the
+     * channel begins execution, whether it succeeds or fails.
      *
      * **Example** (Ensuring cleanup runs)
      *
@@ -5741,7 +5771,7 @@ export declare const ensuring: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, Env2>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, finalizer: Effect.Effect<unknown, never, Env2>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env2 | Env>;
 };
 /**
- * Create a channel from the specified services.
+ * Creates a channel from the specified services.
  *
  * @category services
  * @since 2.0.0
@@ -5798,8 +5828,12 @@ export declare const provideService: {
     <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env, I, S>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>, key: Context.Key<I, S>, service: NoInfer<S>): Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Exclude<Env, I>>;
 };
 /**
- * Evaluates an effect to obtain a service, then provides that service to the
- * channel.
+ * Provides a service to the channel after obtaining it from an effect.
+ *
+ * **When to use**
+ *
+ * Use to supply a channel dependency when constructing the service itself is
+ * effectful or can fail.
  *
  * **Details**
  *
@@ -5811,8 +5845,12 @@ export declare const provideService: {
  */
 export declare const provideServiceEffect: {
     /**
-     * Evaluates an effect to obtain a service, then provides that service to the
-     * channel.
+     * Provides a service to the channel after obtaining it from an effect.
+     *
+     * **When to use**
+     *
+     * Use to supply a channel dependency when constructing the service itself is
+     * effectful or can fail.
      *
      * **Details**
      *
@@ -5824,8 +5862,12 @@ export declare const provideServiceEffect: {
      */
     <I, S, ES, RS>(key: Context.Key<I, S>, service: Effect.Effect<NoInfer<S>, ES, RS>): <OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>(self: Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>) => Channel<OutElem, OutErr | ES, OutDone, InElem, InErr, InDone, Exclude<Env, I> | RS>;
     /**
-     * Evaluates an effect to obtain a service, then provides that service to the
-     * channel.
+     * Provides a service to the channel after obtaining it from an effect.
+     *
+     * **When to use**
+     *
+     * Use to supply a channel dependency when constructing the service itself is
+     * effectful or can fail.
      *
      * **Details**
      *