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

package/dist/Channel.d.ts

@@ -801,6 +801,11 @@ export declare const fail: <E>(error: E) => Channel<never, E, never>;
  * 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
@@ -833,6 +838,11 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Channel<never, E, ne
 /**
  * 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
@@ -1626,6 +1636,11 @@ export declare 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
  */
@@ -1633,6 +1648,11 @@ export declare 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
      */
@@ -1640,6 +1660,11 @@ export declare 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
      */
@@ -1649,6 +1674,11 @@ export declare const mapDoneEffect: {
  * 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.
@@ -1702,6 +1732,11 @@ export declare 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.
@@ -1758,6 +1793,11 @@ export declare 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.
@@ -2739,6 +2779,11 @@ export declare 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
@@ -2752,6 +2797,11 @@ export declare 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
@@ -2765,6 +2815,11 @@ export declare 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
@@ -3076,6 +3131,11 @@ export declare 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
@@ -3090,6 +3150,11 @@ export declare 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
@@ -3104,6 +3169,11 @@ export declare 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
@@ -3119,6 +3189,11 @@ export declare 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
@@ -3133,6 +3208,11 @@ export declare 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
@@ -3147,6 +3227,11 @@ export declare 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
@@ -3378,6 +3463,11 @@ export declare 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
@@ -3424,6 +3514,11 @@ export declare 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
@@ -3470,6 +3565,11 @@ export declare 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
@@ -3629,6 +3729,11 @@ export declare 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
@@ -3642,6 +3747,11 @@ export declare 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
@@ -3655,6 +3765,11 @@ export declare 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
@@ -3741,7 +3856,7 @@ export declare 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**
@@ -3764,7 +3879,7 @@ export declare 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**
@@ -3787,7 +3902,7 @@ export declare 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**
@@ -4410,6 +4525,11 @@ export declare const ignore: <Arg extends Channel<any, any, any, any, any, any,
 /**
  * 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.
@@ -4566,6 +4686,11 @@ export declare 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
@@ -4598,6 +4723,11 @@ export declare 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
@@ -4634,6 +4764,11 @@ export declare 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
@@ -4786,6 +4921,11 @@ export declare 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
@@ -4799,6 +4939,11 @@ export declare 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
@@ -4812,6 +4957,11 @@ export declare 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
@@ -5195,6 +5345,11 @@ export declare 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
@@ -5216,6 +5371,11 @@ export declare 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
@@ -5242,6 +5402,11 @@ export declare 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
@@ -5269,6 +5434,11 @@ export declare 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
@@ -5292,6 +5462,11 @@ export declare 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
@@ -5320,6 +5495,11 @@ export declare 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
@@ -5611,6 +5791,11 @@ export declare 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
@@ -5624,6 +5809,11 @@ export declare 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
@@ -5637,6 +5827,11 @@ export declare 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
@@ -6121,8 +6316,8 @@ export declare 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
@@ -6137,8 +6332,8 @@ export declare 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
@@ -6155,8 +6350,8 @@ export declare 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
@@ -6485,6 +6680,11 @@ export declare 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
@@ -6498,6 +6698,11 @@ export declare 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
@@ -6511,6 +6716,11 @@ export declare 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