effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Channel.ts

@@ -1059,6 +1059,11 @@ export const fail = <E>(error: E): Channel<never, E, never> => fromPull(Effect.s
  * Constructs a channel that fails immediately with the specified lazily
  * evaluated error.
  *
+ * **When to use**
+ *
+ * Use when the error value should be computed each time the channel runs instead
+ * of when the channel is constructed.
+ *
  * **Example** (Failing with a lazy error)
  *
  * ```ts
@@ -1092,6 +1097,11 @@ export const failSync = <E>(evaluate: LazyArg<E>): Channel<never, E, never> => f
 /**
  * Constructs a channel that fails immediately with the specified `Cause`.
  *
+ * **When to use**
+ *
+ * Use when the channel failure must preserve a full `Cause`, such as defects,
+ * interruptions, or combined failures.
+ *
  * **Example** (Failing with causes)
  *
  * ```ts
@@ -1992,6 +2002,11 @@ export const mapDone: {
 /**
  * Maps the done value of this channel using the specified effectful function.
  *
+ * **When to use**
+ *
+ * Use when the terminal done value transformation needs services or can fail,
+ * while emitted elements should pass through unchanged.
+ *
  * @category sequencing
  * @since 4.0.0
  */
@@ -1999,6 +2014,11 @@ export const mapDoneEffect: {
   /**
    * Maps the done value of this channel using the specified effectful function.
    *
+   * **When to use**
+   *
+   * Use when the terminal done value transformation needs services or can fail,
+   * while emitted elements should pass through unchanged.
+   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -2008,6 +2028,11 @@ export const mapDoneEffect: {
   /**
    * Maps the done value of this channel using the specified effectful function.
    *
+   * **When to use**
+   *
+   * Use when the terminal done value transformation needs services or can fail,
+   * while emitted elements should pass through unchanged.
+   *
    * @category sequencing
    * @since 4.0.0
    */
@@ -2036,6 +2061,11 @@ const concurrencyIsSequential = (
  * Maps each output element with an effectful function, preserving the source
  * channel's done value.
  *
+ * **When to use**
+ *
+ * Use when transforming each channel output needs an Effect, service
+ * dependency, failure channel, or configured concurrency.
+ *
  * **Details**
  *
  * The mapping function receives the output element and its zero-based index.
@@ -2089,6 +2119,11 @@ export const mapEffect: {
    * Maps each output element with an effectful function, preserving the source
    * channel's done value.
    *
+   * **When to use**
+   *
+   * Use when transforming each channel output needs an Effect, service
+   * dependency, failure channel, or configured concurrency.
+   *
    * **Details**
    *
    * The mapping function receives the output element and its zero-based index.
@@ -2150,6 +2185,11 @@ export const mapEffect: {
    * Maps each output element with an effectful function, preserving the source
    * channel's done value.
    *
+   * **When to use**
+   *
+   * Use when transforming each channel output needs an Effect, service
+   * dependency, failure channel, or configured concurrency.
+   *
    * **Details**
    *
    * The mapping function receives the output element and its zero-based index.
@@ -4048,6 +4088,11 @@ export const filterMap: {
 /**
  * Filters output elements with an effectful predicate.
  *
+ * **When to use**
+ *
+ * Use when the keep/discard decision depends on an Effect or service and
+ * predicate failures should fail the returned channel.
+ *
  * **Details**
  *
  * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -4061,6 +4106,11 @@ export const filterEffect: {
   /**
    * Filters output elements with an effectful predicate.
    *
+   * **When to use**
+   *
+   * Use when the keep/discard decision depends on an Effect or service and
+   * predicate failures should fail the returned channel.
+   *
    * **Details**
    *
    * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -4076,6 +4126,11 @@ export const filterEffect: {
   /**
    * Filters output elements with an effectful predicate.
    *
+   * **When to use**
+   *
+   * Use when the keep/discard decision depends on an Effect or service and
+   * predicate failures should fail the returned channel.
+   *
    * **Details**
    *
    * Elements for which the predicate succeeds with `true` are emitted. Elements
@@ -4487,6 +4542,11 @@ export const filterMapArray: {
  * Filters each element inside emitted non-empty arrays with an effectful
  * predicate.
  *
+ * **When to use**
+ *
+ * Use when filtering array-valued channel outputs requires Effects or services,
+ * and arrays that become empty should be skipped.
+ *
  * **Details**
  *
  * The predicate receives the element and its index within the array. Elements
@@ -4501,6 +4561,11 @@ export const filterArrayEffect: {
    * Filters each element inside emitted non-empty arrays with an effectful
    * predicate.
    *
+   * **When to use**
+   *
+   * Use when filtering array-valued channel outputs requires Effects or services,
+   * and arrays that become empty should be skipped.
+   *
    * **Details**
    *
    * The predicate receives the element and its index within the array. Elements
@@ -4519,6 +4584,11 @@ export const filterArrayEffect: {
    * Filters each element inside emitted non-empty arrays with an effectful
    * predicate.
    *
+   * **When to use**
+   *
+   * Use when filtering array-valued channel outputs requires Effects or services,
+   * and arrays that become empty should be skipped.
+   *
    * **Details**
    *
    * The predicate receives the element and its index within the array. Elements
@@ -4550,6 +4620,11 @@ export const filterArrayEffect: {
  * Filters and maps each element inside emitted non-empty arrays using an
  * effectful `Filter`.
  *
+ * **When to use**
+ *
+ * Use when array-valued channel outputs need an effectful filter-map that can
+ * fail and can discard arrays that become empty.
+ *
  * **Details**
  *
  * Successful filter results are kept as mapped values. Failed filter results
@@ -4564,6 +4639,11 @@ export const filterMapArrayEffect: {
    * Filters and maps each element inside emitted non-empty arrays using an
    * effectful `Filter`.
    *
+   * **When to use**
+   *
+   * Use when array-valued channel outputs need an effectful filter-map that can
+   * fail and can discard arrays that become empty.
+   *
    * **Details**
    *
    * Successful filter results are kept as mapped values. Failed filter results
@@ -4580,6 +4660,11 @@ export const filterMapArrayEffect: {
    * Filters and maps each element inside emitted non-empty arrays using an
    * effectful `Filter`.
    *
+   * **When to use**
+   *
+   * Use when array-valued channel outputs need an effectful filter-map that can
+   * fail and can discard arrays that become empty.
+   *
    * **Details**
    *
    * Successful filter results are kept as mapped values. Failed filter results
@@ -4951,6 +5036,11 @@ export const scan: {
  * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
  * Emits the intermediate results of the scan operation.
  *
+ * **When to use**
+ *
+ * Use when maintaining accumulated state over channel output requires Effects
+ * or can fail, while still emitting each intermediate state.
+ *
  * **Example** (Scanning channel output with effects)
  *
  * ```ts
@@ -4997,6 +5087,11 @@ export const scanEffect: {
    * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
    * Emits the intermediate results of the scan operation.
    *
+   * **When to use**
+   *
+   * Use when maintaining accumulated state over channel output requires Effects
+   * or can fail, while still emitting each intermediate state.
+   *
    * **Example** (Scanning channel output with effects)
    *
    * ```ts
@@ -5058,6 +5153,11 @@ export const scanEffect: {
    * Transforms a channel statefully by scanning over its output with an effectful accumulator function.
    * Emits the intermediate results of the scan operation.
    *
+   * **When to use**
+   *
+   * Use when maintaining accumulated state over channel output requires Effects
+   * or can fail, while still emitting each intermediate state.
+   *
    * **Example** (Scanning channel output with effects)
    *
    * ```ts
@@ -5337,6 +5437,11 @@ export const catchCause: {
  * Runs an effect with the full failure `Cause` when the channel fails, then
  * fails the returned channel with the original cause.
  *
+ * **When to use**
+ *
+ * Use when observing the full channel failure `Cause` is needed without
+ * changing successful output or replacing the original cause.
+ *
  * **Details**
  *
  * Use this for observing failures, such as logging or metrics. If the observer
@@ -5350,6 +5455,11 @@ export const tapCause: {
    * Runs an effect with the full failure `Cause` when the channel fails, then
    * fails the returned channel with the original cause.
    *
+   * **When to use**
+   *
+   * Use when observing the full channel failure `Cause` is needed without
+   * changing successful output or replacing the original cause.
+   *
    * **Details**
    *
    * Use this for observing failures, such as logging or metrics. If the observer
@@ -5378,6 +5488,11 @@ export const tapCause: {
    * Runs an effect with the full failure `Cause` when the channel fails, then
    * fails the returned channel with the original cause.
    *
+   * **When to use**
+   *
+   * Use when observing the full channel failure `Cause` is needed without
+   * changing successful output or replacing the original cause.
+   *
    * **Details**
    *
    * Use this for observing failures, such as logging or metrics. If the observer
@@ -5609,7 +5724,7 @@ export const catchCauseIf: {
  * **When to use**
  *
  * Use when you need to recover a channel only from causes selected by a
- * `Filter`, and the recovery needs both the selected value and the original
+ * `Filter`, while giving the recovery both the selected value and the original
  * `Cause`.
  *
  * **Details**
@@ -5632,7 +5747,7 @@ export const catchCauseFilter: {
    * **When to use**
    *
    * Use when you need to recover a channel only from causes selected by a
-   * `Filter`, and the recovery needs both the selected value and the original
+   * `Filter`, while giving the recovery both the selected value and the original
    * `Cause`.
    *
    * **Details**
@@ -5687,7 +5802,7 @@ export const catchCauseFilter: {
    * **When to use**
    *
    * Use when you need to recover a channel only from causes selected by a
-   * `Filter`, and the recovery needs both the selected value and the original
+   * `Filter`, while giving the recovery both the selected value and the original
    * `Cause`.
    *
    * **Details**
@@ -7456,6 +7571,11 @@ const ignoreCause_ = <
 /**
  * Ignores all errors in the channel including defects, converting them to an empty channel.
  *
+ * **When to use**
+ *
+ * Use when a channel should become best-effort and all failure causes, including
+ * defects and interruptions, can be converted to empty output.
+ *
  * **Details**
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
@@ -7773,6 +7893,11 @@ export const switchMap: {
 /**
  * Merges multiple channels with specified concurrency and buffering options.
  *
+ * **When to use**
+ *
+ * Use when channel outputs are themselves channels and multiple inner channels
+ * should run with configured concurrency and buffering.
+ *
  * **Example** (Merging nested channels)
  *
  * ```ts
@@ -7805,6 +7930,11 @@ export const mergeAll: {
   /**
    * Merges multiple channels with specified concurrency and buffering options.
    *
+   * **When to use**
+   *
+   * Use when channel outputs are themselves channels and multiple inner channels
+   * should run with configured concurrency and buffering.
+   *
    * **Example** (Merging nested channels)
    *
    * ```ts
@@ -7861,6 +7991,11 @@ export const mergeAll: {
   /**
    * Merges multiple channels with specified concurrency and buffering options.
    *
+   * **When to use**
+   *
+   * Use when channel outputs are themselves channels and multiple inner channels
+   * should run with configured concurrency and buffering.
+   *
    * **Example** (Merging nested channels)
    *
    * ```ts
@@ -7951,6 +8086,11 @@ export const mergeAll: {
         const queue = yield* Queue.bounded</**
          * Merges multiple channels with specified concurrency and buffering options.
          *
+         * **When to use**
+         *
+         * Use when channel outputs are themselves channels and multiple inner channels
+         * should run with configured concurrency and buffering.
+         *
          * **Example** (Merging nested channels)
          *
          * ```ts
@@ -7982,6 +8122,11 @@ export const mergeAll: {
         OutElem, /**
          * Merges multiple channels with specified concurrency and buffering options.
          *
+         * **When to use**
+         *
+         * Use when channel outputs are themselves channels and multiple inner channels
+         * should run with configured concurrency and buffering.
+         *
          * **Example** (Merging nested channels)
          *
          * ```ts
@@ -8369,6 +8514,11 @@ export const merge: {
  * Runs an effect concurrently with a channel while emitting only the channel's
  * output elements.
  *
+ * **When to use**
+ *
+ * Use when a side effect should run for the lifetime of a channel and only the
+ * channel's output elements should be emitted.
+ *
  * **Details**
  *
  * The effect's successful value is ignored. If the effect fails while the
@@ -8382,6 +8532,11 @@ export const mergeEffect: {
    * Runs an effect concurrently with a channel while emitting only the channel's
    * output elements.
    *
+   * **When to use**
+   *
+   * Use when a side effect should run for the lifetime of a channel and only the
+   * channel's output elements should be emitted.
+   *
    * **Details**
    *
    * The effect's successful value is ignored. If the effect fails while the
@@ -8397,6 +8552,11 @@ export const mergeEffect: {
    * Runs an effect concurrently with a channel while emitting only the channel's
    * output elements.
    *
+   * **When to use**
+   *
+   * Use when a side effect should run for the lifetime of a channel and only the
+   * channel's output elements should be emitted.
+   *
    * **Details**
    *
    * The effect's successful value is ignored. If the effect fails while the
@@ -9016,6 +9176,11 @@ export const embedInput: {
  * Buffers individual output elements in a queue with the configured `capacity`
  * so a faster producer can progress independently of a slower consumer.
  *
+ * **When to use**
+ *
+ * Use when output elements can be decoupled from downstream demand and the
+ * configured backpressure or loss strategy is acceptable.
+ *
  * **Details**
  *
  * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9037,6 +9202,11 @@ export const buffer: {
    * Buffers individual output elements in a queue with the configured `capacity`
    * so a faster producer can progress independently of a slower consumer.
    *
+   * **When to use**
+   *
+   * Use when output elements can be decoupled from downstream demand and the
+   * configured backpressure or loss strategy is acceptable.
+   *
    * **Details**
    *
    * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9065,6 +9235,11 @@ export const buffer: {
    * Buffers individual output elements in a queue with the configured `capacity`
    * so a faster producer can progress independently of a slower consumer.
    *
+   * **When to use**
+   *
+   * Use when output elements can be decoupled from downstream demand and the
+   * configured backpressure or loss strategy is acceptable.
+   *
    * **Details**
    *
    * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9101,6 +9276,11 @@ export const buffer: {
      * Buffers individual output elements in a queue with the configured `capacity`
      * so a faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when output elements can be decoupled from downstream demand and the
+     * configured backpressure or loss strategy is acceptable.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9121,6 +9301,11 @@ export const buffer: {
      * Buffers individual output elements in a queue with the configured `capacity`
      * so a faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when output elements can be decoupled from downstream demand and the
+     * configured backpressure or loss strategy is acceptable.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9155,6 +9340,11 @@ export const buffer: {
  * Buffers array output elements in a queue with the configured `capacity` so a
  * faster producer can progress independently of a slower consumer.
  *
+ * **When to use**
+ *
+ * Use when emitted arrays are batches of elements and it is acceptable for
+ * buffering to flatten and rebuild those batches.
+ *
  * **Details**
  *
  * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9178,6 +9368,11 @@ export const bufferArray: {
    * Buffers array output elements in a queue with the configured `capacity` so a
    * faster producer can progress independently of a slower consumer.
    *
+   * **When to use**
+   *
+   * Use when emitted arrays are batches of elements and it is acceptable for
+   * buffering to flatten and rebuild those batches.
+   *
    * **Details**
    *
    * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9208,6 +9403,11 @@ export const bufferArray: {
    * Buffers array output elements in a queue with the configured `capacity` so a
    * faster producer can progress independently of a slower consumer.
    *
+   * **When to use**
+   *
+   * Use when emitted arrays are batches of elements and it is acceptable for
+   * buffering to flatten and rebuild those batches.
+   *
    * **Details**
    *
    * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9246,6 +9446,11 @@ export const bufferArray: {
      * Buffers array output elements in a queue with the configured `capacity` so a
      * faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when emitted arrays are batches of elements and it is acceptable for
+     * buffering to flatten and rebuild those batches.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9268,6 +9473,11 @@ export const bufferArray: {
      * Buffers array output elements in a queue with the configured `capacity` so a
      * faster producer can progress independently of a slower consumer.
      *
+     * **When to use**
+     *
+     * Use when emitted arrays are batches of elements and it is acceptable for
+     * buffering to flatten and rebuild those batches.
+     *
      * **Details**
      *
      * Finite queues use the `strategy` option. The default `"suspend"` strategy
@@ -9640,6 +9850,11 @@ export const onStart: {
 /**
  * Runs an effect the first time the channel emits an output element.
  *
+ * **When to use**
+ *
+ * Use when initialization depends on the first output element rather than only
+ * on channel startup.
+ *
  * **Details**
  *
  * The effect receives the first emitted element. The first element is still
@@ -9653,6 +9868,11 @@ export const onFirst: {
   /**
    * Runs an effect the first time the channel emits an output element.
    *
+   * **When to use**
+   *
+   * Use when initialization depends on the first output element rather than only
+   * on channel startup.
+   *
    * **Details**
    *
    * The effect receives the first emitted element. The first element is still
@@ -9668,6 +9888,11 @@ export const onFirst: {
   /**
    * Runs an effect the first time the channel emits an output element.
    *
+   * **When to use**
+   *
+   * Use when initialization depends on the first output element rather than only
+   * on channel startup.
+   *
    * **Details**
    *
    * The effect receives the first emitted element. The first element is still
@@ -10478,8 +10703,8 @@ export const bind: {
  *
  * **When to use**
  *
- * Use when starting a Channel Do-notation chain from an existing output value
- * by assigning that value to a field name.
+ * Use when you need to start a Channel Do-notation chain from an existing
+ * output value by assigning that value to a field name.
  *
  * @see {@link Do} for starting Do notation from an empty object
  * @see {@link bind} for adding a field produced by another channel
@@ -10494,8 +10719,8 @@ export const bindTo: {
    *
    * **When to use**
    *
-   * Use when starting a Channel Do-notation chain from an existing output value
-   * by assigning that value to a field name.
+   * Use when you need to start a Channel Do-notation chain from an existing
+   * output value by assigning that value to a field name.
    *
    * @see {@link Do} for starting Do notation from an empty object
    * @see {@link bind} for adding a field produced by another channel
@@ -10520,8 +10745,8 @@ export const bindTo: {
    *
    * **When to use**
    *
-   * Use when starting a Channel Do-notation chain from an existing output value
-   * by assigning that value to a field name.
+   * Use when you need to start a Channel Do-notation chain from an existing
+   * output value by assigning that value to a field name.
    *
    * @see {@link Do} for starting Do notation from an empty object
    * @see {@link bind} for adding a field produced by another channel
@@ -10977,6 +11202,11 @@ export const runFold: {
 /**
  * Runs a channel and effectfully folds all output elements with an accumulator.
  *
+ * **When to use**
+ *
+ * Use when folding channel output needs effects, services, or an additional
+ * failure channel during accumulation.
+ *
  * **Details**
  *
  * The initial accumulator is evaluated lazily. Each output element is passed to
@@ -10990,6 +11220,11 @@ export const runFoldEffect: {
   /**
    * Runs a channel and effectfully folds all output elements with an accumulator.
    *
+   * **When to use**
+   *
+   * Use when folding channel output needs effects, services, or an additional
+   * failure channel during accumulation.
+   *
    * **Details**
    *
    * The initial accumulator is evaluated lazily. Each output element is passed to
@@ -11005,6 +11240,11 @@ export const runFoldEffect: {
   /**
    * Runs a channel and effectfully folds all output elements with an accumulator.
    *
+   * **When to use**
+   *
+   * Use when folding channel output needs effects, services, or an additional
+   * failure channel during accumulation.
+   *
    * **Details**
    *
    * The initial accumulator is evaluated lazily. Each output element is passed to

package/src/ChannelSchema.ts

@@ -152,8 +152,8 @@ export const decode = <S extends Schema.Top>(
  *
  * **When to use**
  *
- * Use when the encoded input type is intentionally unknown or untyped, so
- * that only the decoded output is statically typed according to the schema.
+ * Use when you need an intentionally unknown or untyped encoded input while
+ * keeping only the decoded output statically typed according to the schema.
  *
  * **Details**
  *
@@ -374,9 +374,9 @@ export const duplex: {
  *
  * **When to use**
  *
- * Use when a bidirectional channel crosses an encoded boundary whose chunk types
- * are intentionally erased, while callers should send and receive schema-typed
- * chunks.
+ * Use when you need a bidirectional channel to cross an encoded boundary whose
+ * chunk types are intentionally erased, while callers send and receive
+ * schema-typed chunks.
  *
  * **Details**
  *
@@ -395,9 +395,9 @@ export const duplexUnknown: {
    *
    * **When to use**
    *
-   * Use when a bidirectional channel crosses an encoded boundary whose chunk types
-   * are intentionally erased, while callers should send and receive schema-typed
-   * chunks.
+   * Use when you need a bidirectional channel to cross an encoded boundary whose
+   * chunk types are intentionally erased, while callers send and receive
+   * schema-typed chunks.
    *
    * **Details**
    *
@@ -439,9 +439,9 @@ export const duplexUnknown: {
    *
    * **When to use**
    *
-   * Use when a bidirectional channel crosses an encoded boundary whose chunk types
-   * are intentionally erased, while callers should send and receive schema-typed
-   * chunks.
+   * Use when you need a bidirectional channel to cross an encoded boundary whose
+   * chunk types are intentionally erased, while callers send and receive
+   * schema-typed chunks.
    *
    * **Details**
    *