effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Channel.js

@@ -675,6 +675,11 @@ export const fail = error => fromPull(Effect.succeed(Effect.fail(error)));
  * 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
@@ -707,6 +712,11 @@ export const failSync = evaluate => fromPull(Effect.failSync(evaluate));
 /**
  * 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
@@ -1423,6 +1433,11 @@ export const mapDone = /*#__PURE__*/dual(2, (self, f) => mapDoneEffect(self, o =
 /**
  * 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
  */
@@ -1432,6 +1447,11 @@ const concurrencyIsSequential = concurrency => concurrency === undefined || conc
  * 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.
@@ -1827,7 +1847,7 @@ export const flatten = channels => flatMap(channels, identity_);
  * // Outputs: 1, 2, 3, 4, 5, 6, 7, 8, 9
  * ```
  *
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export const flattenArray = self => transformPull(self, pull => {
@@ -1867,7 +1887,7 @@ export const flattenArray = self => transformPull(self, pull => {
  * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
  * fail the returned channel. Done `Take` values complete the returned channel.
  *
- * @category utils
+ * @category transforming
  * @since 4.0.0
  */
 export const flattenTake = self => mapEffectSequential(self, Take.toPull);
@@ -1899,7 +1919,7 @@ export const drain = self => transformPull(self, pull => Effect.succeed(Effect.f
 /**
  * Repeats this channel according to the provided schedule.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export const repeat = /*#__PURE__*/dual(2, (self, schedule) => Schedule.toStepWithMetadata(typeof schedule === "function" ? schedule(identity_) : schedule).pipe(Effect.map(step => {
@@ -1913,7 +1933,7 @@ export const repeat = /*#__PURE__*/dual(2, (self, schedule) => Schedule.toStepWi
 /**
  * Repeats this channel forever.
  *
- * @category utils
+ * @category repetition
  * @since 4.0.0
  */
 export const forever = self => concatWith(self, () => forever(self));
@@ -1928,7 +1948,7 @@ export const forever = self => concatWith(self, () => forever(self));
  * fails. If the schedule finishes, the returned channel completes with the
  * schedule output.
  *
- * @category utils
+ * @category sequencing
  * @since 4.0.0
  */
 export const schedule = /*#__PURE__*/dual(2, (self, schedule) => transformPull(self, (pull, _scope) => Effect.map(Schedule.toStepWithSleep(schedule), step => {
@@ -1994,6 +2014,11 @@ export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromTransform((u
 /**
  * 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
@@ -2102,6 +2127,11 @@ export const filterMapArray = /*#__PURE__*/dual(2, (self, filter) => transformPu
  * 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
@@ -2121,6 +2151,11 @@ export const filterArrayEffect = /*#__PURE__*/dual(2, (self, predicate) => trans
  * 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
@@ -2245,6 +2280,11 @@ export const scan = /*#__PURE__*/dual(3, (self, initial, f) => scanEffect(self,
  * 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
@@ -2357,6 +2397,11 @@ export const catchCause = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  * 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
@@ -2397,7 +2442,7 @@ export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => catchCa
  * **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**
@@ -2656,6 +2701,11 @@ const ignoreCause_ = self => catchCause(self, () => empty);
 /**
  * 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.
@@ -2672,7 +2722,7 @@ export const ignoreCause = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
- * @category utils
+ * @category error handling
  * @since 4.0.0
  */
 export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
@@ -2735,6 +2785,11 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
 /**
  * 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
@@ -2760,7 +2815,7 @@ export const switchMap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f,
  * // Outputs: 1, 2, 3, 4, 5, 6 (order may vary due to concurrency)
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const mergeAll = /*#__PURE__*/dual(2, (channels, {
@@ -2831,7 +2886,7 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
  * // Order may vary: 1, "a", 2, "b", 3, "c"
  * ```
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export const merge = /*#__PURE__*/dual(args => isChannel(args[0]) && isChannel(args[1]), (left, right, options) => fromTransformBracket(Effect.fnUntraced(function* (upstream, _scope, forkedScope) {
@@ -2869,12 +2924,17 @@ export const merge = /*#__PURE__*/dual(args => isChannel(args[0]) && isChannel(a
  * 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
  * channel is running, the returned channel fails with that error.
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fromEffectDrain(effect), {
@@ -3052,7 +3112,7 @@ export const encodeText = () => fromTransform((upstream, _scope) => Effect.sync(
  * // Outputs: 2, 4, 6
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstream, scope) => Effect.flatMap(toTransform(self)(upstream, scope), upstream => toTransform(that)(upstream, scope))));
@@ -3080,7 +3140,7 @@ export const pipeTo = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstre
  * // Source errors are preserved and not sent to transform channel
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const pipeToOrFail = /*#__PURE__*/dual(2, (self, that) => fromTransform((upstream, scope) => Effect.flatMap(toTransform(self)(upstream, scope), upstream => {
@@ -3125,7 +3185,7 @@ export const unwrap = channel => fromTransform((upstream, scope) => {
  * Runs a channel with a scope provided for the duration of the channel
  * execution, removing the channel's `Scope` requirement.
  *
- * @category utils
+ * @category resource management
  * @since 2.0.0
  */
 export const scoped = self => fromTransformBracket((upstream, scope, forkedScope) => Effect.map(Scope.provide(toTransform(self)(upstream, scope), forkedScope), Scope.provide(forkedScope)));
@@ -3160,7 +3220,7 @@ export const scoped = self => fromTransformBracket((upstream, scope, forkedScope
  * )
  * ```
  *
- * @category utils
+ * @category sequencing
  * @since 2.0.0
  */
 export const embedInput = /*#__PURE__*/dual(2, (self, input) => fromTransformBracket((upstream, scope, forkedScope) => Effect.andThen(Effect.forkIn(input(upstream), forkedScope), toTransform(self)(Cause.done(), scope))));
@@ -3168,6 +3228,11 @@ export const embedInput = /*#__PURE__*/dual(2, (self, input) => fromTransformBra
  * 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
@@ -3200,6 +3265,11 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effe
  * 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
@@ -3244,7 +3314,7 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromTransform
  * channel's done value. If the channel completes first, the original channel's
  * done value is preserved.
  *
- * @category utils
+ * @category interruption
  * @since 2.0.0
  */
 export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => merge(self, fromPull(Effect.succeed(Effect.flatMap(effect, Cause.done))), {
@@ -3260,7 +3330,7 @@ export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => merge(self,
  * fails with that error. If the channel completes first, the channel's done
  * value is preserved.
  *
- * @category utils
+ * @category interruption
  * @since 4.0.0
  */
 export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBracket(Effect.fnUntraced(function* (upstream, scope, forkedScope) {
@@ -3280,7 +3350,7 @@ export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBrac
  * The finalizer receives the failure `Cause`. The original channel failure is
  * preserved. The finalizer itself must not fail.
  *
- * @category utils
+ * @category error handling
  * @since 4.0.0
  */
 export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, exit => Exit.isFailure(exit) ? finalizer(exit.cause) : Effect.void));
@@ -3310,7 +3380,7 @@ export const onError = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, ex
  * })
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 4.0.0
  */
 export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromTransformBracket((upstream, scope, forkedScope) => Scope.addFinalizerExit(forkedScope, finalizer).pipe(Effect.andThen(toTransform(self)(upstream, scope)))));
@@ -3322,20 +3392,25 @@ export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromTransformBra
  * The effect's successful value is ignored. If the effect fails, the returned
  * channel fails before running the source channel.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export const onStart = /*#__PURE__*/dual(2, (self, onStart) => unwrap(Effect.as(onStart, self)));
 /**
  * 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
  * emitted unchanged. The effect is not run if the channel completes without
  * emitting an element.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(self, pull => Effect.sync(() => {
@@ -3355,7 +3430,7 @@ export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(sel
  * not run when the channel fails. If the effect fails, the returned channel
  * fails with that error.
  *
- * @category utils
+ * @category hooks
  * @since 4.0.0
  */
 export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, pull => Effect.succeed(Pull.catchDone(pull, leftover => Effect.flatMap(onEnd, () => Cause.done(leftover))))));
@@ -3382,7 +3457,7 @@ export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, p
  * )
  * ```
  *
- * @category utils
+ * @category resource management
  * @since 2.0.0
  */
 export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => onExit(self, _ => finalizer));
@@ -3502,7 +3577,7 @@ const withSpanImpl = (self, name, options) => acquireUseRelease(Effect.makeSpan(
 /**
  * The starting channel for Do notation, emitting an empty object.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export const Do = /*#__PURE__*/succeed({});
@@ -3514,7 +3589,7 @@ export {
 /**
  * Adds a computed field to each object emitted by a channel.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 let_ as let };
@@ -3528,7 +3603,7 @@ let_ as let };
  * channel's output becomes the value of the new field. `options.concurrency`
  * and `options.bufferSize` control how derived channels are flattened.
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export const bind = /*#__PURE__*/dual(args => isChannel(args[0]), (self, name, f, options) => flatMap(self, elem => map(f(elem), b => ({
@@ -3540,14 +3615,14 @@ export const bind = /*#__PURE__*/dual(args => isChannel(args[0]), (self, name, f
  *
  * **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
  * @see {@link let_ let} for adding a computed field
  *
- * @category Do notation
+ * @category do notation
  * @since 4.0.0
  */
 export const bindTo = /*#__PURE__*/dual(2, (self, name) => map(self, elem => ({
@@ -3767,6 +3842,11 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend
 /**
  * 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