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

package/src/Channel.ts

@@ -109,7 +109,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"
@@ -118,13 +118,13 @@ 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 const TypeId: TypeId = "~effect/Channel"
 
 /**
- * Tests if a value is a `Channel`.
+ * Checks whether a value is a `Channel`.
  *
  * **Example** (Checking for channels)
  *
@@ -972,7 +972,7 @@ export const endSync = <A>(evaluate: LazyArg<A>): Channel<never, never, A> =>
 export const sync = <A>(evaluate: LazyArg<A>): Channel<A> => fromEffect(Effect.sync(evaluate))
 
 /**
- * Represents an Channel that emits no elements
+ * Represents a `Channel` that emits no elements.
  *
  * **Example** (Using empty channels)
  *
@@ -997,7 +997,7 @@ export const sync = <A>(evaluate: LazyArg<A>): Channel<A> => fromEffect(Effect.s
 export const empty: Channel<never> = fromPull(Effect.succeed(Cause.done()))
 
 /**
- * Represents an Channel that never completes
+ * Represents a `Channel` that never completes.
  *
  * **Example** (Using non-terminating channels)
  *
@@ -1172,7 +1172,7 @@ export const failCauseSync = <E>(
 export const die = (defect: unknown): Channel<never, never, never> => failCause(Cause.die(defect))
 
 /**
- * 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)
  *
@@ -1239,7 +1239,7 @@ export const fromEffectDone = <A, E, R>(
   fromPull(Effect.succeed(Effect.flatMap(effect, Cause.done)))
 
 /**
- * Use an effect and discard its result.
+ * Uses an effect and discards its result.
  *
  * @category constructors
  * @since 4.0.0
@@ -1266,7 +1266,7 @@ export const fromEffectTake = <A, E, Done, E2, R>(
   fromPull(Effect.succeed(Effect.flatMap(effect, Take.toPull)))
 
 /**
- * Create a channel from a queue
+ * Creates a channel from a queue.
  *
  * **Example** (Creating channels from queues)
  *
@@ -1309,7 +1309,7 @@ export const fromQueue = <A, E>(
 ): Channel<A, Exclude<E, Cause.Done>> => fromPull(Effect.succeed(Queue.take(queue)))
 
 /**
- * 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)
  *
@@ -1366,7 +1366,7 @@ export const identity = <Elem, Err, Done>(): Channel<Elem, Err, Done, Elem, Err,
   fromTransform((upstream, _scope) => Effect.succeed(upstream))
 
 /**
- * Create a channel from a PubSub subscription
+ * Creates a channel from a PubSub subscription.
  *
  * **Example** (Creating channels from subscriptions)
  *
@@ -1414,7 +1414,7 @@ export const fromSubscription = <A>(
 ): Channel<A> => fromPull(Effect.succeed(Effect.onInterrupt(PubSub.take(subscription), () => Cause.done())))
 
 /**
- * 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**
  *
@@ -1521,7 +1521,7 @@ export const fromSubscriptionArray = <A>(
   fromPull(Effect.succeed(Effect.onInterrupt(PubSub.takeAll(subscription), () => Cause.done())))
 
 /**
- * Create a channel from a PubSub that outputs individual values.
+ * Creates a channel from a PubSub that outputs individual values.
  *
  * **Details**
  *
@@ -1618,7 +1618,7 @@ export const fromPubSub = <A>(
 ): Channel<A> => unwrap(Effect.map(PubSub.subscribe(pubsub), fromSubscription))
 
 /**
- * Create a channel from a PubSub that outputs arrays of values.
+ * Creates a channel from a PubSub that outputs arrays of values.
  *
  * **Details**
  *
@@ -3152,22 +3152,36 @@ export const concat: {
 > => concatWith(self, (_) => that))
 
 /**
- * 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 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
@@ -3190,11 +3204,18 @@ export const combine: {
     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
@@ -3421,7 +3442,7 @@ export const orElseIfEmpty: {
   ))
 
 /**
- * Flatten a channel of channels.
+ * Flattens a channel of channels.
  *
  * **Example** (Flattening nested channels)
  *
@@ -4591,7 +4612,7 @@ export const filterMapArrayEffect: {
     ))))
 
 /**
- * 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)
  *
@@ -4630,7 +4651,7 @@ export const filterMapArrayEffect: {
  */
 export 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)
    *
@@ -4695,7 +4716,7 @@ export const mapAccum: {
     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)
    *
@@ -4808,7 +4829,7 @@ export const mapAccum: {
 )
 
 /**
- * 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)
@@ -4839,7 +4860,7 @@ export const mapAccum: {
  */
 export 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)
@@ -4885,7 +4906,7 @@ export const scan: {
     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)
@@ -4927,7 +4948,7 @@ export const scan: {
   scanEffect(self, initial, (s, a) => Effect.succeed(f(s, a))))
 
 /**
- * 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)
@@ -4973,7 +4994,7 @@ export const scan: {
  */
 export 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)
@@ -5034,7 +5055,7 @@ export const scanEffect: {
     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)
@@ -8992,8 +9013,8 @@ export const embedInput: {
 )
 
 /**
- * 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**
  *
@@ -9013,8 +9034,8 @@ export const embedInput: {
  */
 export 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**
    *
@@ -9041,8 +9062,8 @@ export const buffer: {
     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**
    *
@@ -9077,8 +9098,8 @@ export const buffer: {
   fromTransform(Effect.fnUntraced(function*(upstream, scope) {
     const pull = yield* toTransform(self)(upstream, scope)
     const queue = yield* Queue.make</**
-     * 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**
      *
@@ -9097,8 +9118,8 @@ export const buffer: {
      * @since 2.0.0
      */
     OutElem, /**
-     * 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**
      *
@@ -9131,8 +9152,8 @@ export const buffer: {
   })))
 
 /**
- * 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**
  *
@@ -9154,8 +9175,8 @@ export const buffer: {
  */
 export 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**
    *
@@ -9184,8 +9205,8 @@ export const bufferArray: {
     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**
    *
@@ -9222,8 +9243,8 @@ export const bufferArray: {
   fromTransform(Effect.fnUntraced(function*(upstream, scope) {
     const pull = yield* toTransform(self)(upstream, scope)
     const queue = yield* Queue.make</**
-     * 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**
      *
@@ -9244,8 +9265,8 @@ export const bufferArray: {
      * @since 4.0.0
      */
     OutElem, /**
-     * 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**
      *
@@ -9280,26 +9301,36 @@ export const bufferArray: {
   })))
 
 /**
- * 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 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
@@ -9308,13 +9339,18 @@ export const interruptWhen: {
     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
@@ -9334,7 +9370,7 @@ export const interruptWhen: {
   ))
 
 /**
- * Halts a channel when the specified effect completes or fails.
+ * Stops a channel when the specified effect completes or fails.
  *
  * **Details**
  *
@@ -9348,7 +9384,7 @@ export const interruptWhen: {
  */
 export const haltWhen: {
   /**
-   * Halts a channel when the specified effect completes or fails.
+   * Stops a channel when the specified effect completes or fails.
    *
    * **Details**
    *
@@ -9364,7 +9400,7 @@ export const haltWhen: {
     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**
    *
@@ -9449,9 +9485,8 @@ export const onError: {
   onExit(self, (exit) => Exit.isFailure(exit) ? finalizer(exit.cause) : Effect.void))
 
 /**
- * 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)
  *
@@ -9480,9 +9515,8 @@ export const onError: {
  */
 export 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)
    *
@@ -9515,9 +9549,8 @@ export const onExit: {
     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)
    *
@@ -9717,9 +9750,8 @@ export const onEnd: {
     ))))
 
 /**
- * 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)
  *
@@ -9745,9 +9777,8 @@ export const onEnd: {
  */
 export 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)
    *
@@ -9775,9 +9806,8 @@ export const ensuring: {
     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)
    *
@@ -9834,7 +9864,7 @@ const runWith = <
   })
 
 /**
- * Create a channel from the specified services.
+ * Creates a channel from the specified services.
  *
  * @category services
  * @since 2.0.0
@@ -9929,8 +9959,12 @@ export const provideService: {
   ))
 
 /**
- * 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**
  *
@@ -9942,8 +9976,12 @@ export const provideService: {
  */
 export 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**
    *
@@ -9957,8 +9995,12 @@ export const provideServiceEffect: {
     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**
    *

package/src/ChannelSchema.ts

@@ -370,7 +370,7 @@ export const duplex: {
   ))
 
 /**
- * Like `duplex`, but for channels whose encoded side is not statically typed.
+ * Wraps a bidirectional channel whose encoded chunks are typed as `unknown`.
  *
  * **When to use**
  *
@@ -391,7 +391,7 @@ export const duplex: {
  */
 export const duplexUnknown: {
   /**
-   * Like `duplex`, but for channels whose encoded side is not statically typed.
+   * Wraps a bidirectional channel whose encoded chunks are typed as `unknown`.
    *
    * **When to use**
    *
@@ -435,7 +435,7 @@ export const duplexUnknown: {
     R | In["EncodingServices"] | Out["DecodingServices"]
   >
   /**
-   * Like `duplex`, but for channels whose encoded side is not statically typed.
+   * Wraps a bidirectional channel whose encoded chunks are typed as `unknown`.
    *
    * **When to use**
    *