effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/Channel.js

@@ -300,6 +300,8 @@ export const suspend = evaluate => fromTransform((upstream, scope) => Effect.sus
  * `release` runs with the channel's `Exit` when the channel completes, fails,
  * or is interrupted.
  *
+ * **Details**
+ *
  * Acquisition is uninterruptible. If acquisition fails, `use` is not run and
  * `release` is not registered.
  *
@@ -329,6 +331,8 @@ export const acquireUseRelease = (acquire, use, release) => fromTransformBracket
  * Acquires a resource, emits the acquired value as a single channel element,
  * and registers `release` in the channel scope.
  *
+ * **Details**
+ *
  * The release action runs when the channel scope closes and receives the scope
  * exit. If acquisition fails, no element is emitted and `release` is not
  * registered.
@@ -807,6 +811,8 @@ export const fromEffect = effect => fromPull(Effect.sync(() => {
  * Creates a channel that evaluates an effect and uses its successful value as
  * the channel's done value without emitting any output elements.
  *
+ * **Details**
+ *
  * If the effect fails, the channel fails with the effect's error.
  *
  * @category constructors
@@ -823,6 +829,8 @@ export const fromEffectDrain = effect => fromPull(Effect.flatMap(effect, () => C
 /**
  * Creates a channel from an effect that produces a `Take`.
  *
+ * **Details**
+ *
  * A successful `Take` emits a non-empty array of output elements. A failed
  * `Take` fails the channel. A done `Take` completes the channel with its done
  * value.
@@ -971,6 +979,8 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
 /**
  * Create a channel from a PubSub subscription that outputs arrays of values.
  *
+ * **Details**
+ *
  * This constructor creates a channel that reads from a PubSub subscription and outputs
  * arrays of values in chunks. It's useful when you want to process multiple values at once
  * for better performance.
@@ -1072,6 +1082,8 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
 /**
  * Create a channel from a PubSub that outputs individual values.
  *
+ * **Details**
+ *
  * This constructor creates a channel that reads from a PubSub by automatically
  * subscribing to it. The channel outputs individual values as they are published
  * to the PubSub, making it ideal for real-time streaming scenarios.
@@ -1164,6 +1176,8 @@ export const fromPubSub = pubsub => unwrap(Effect.map(PubSub.subscribe(pubsub),
 /**
  * Create a channel from a PubSub that outputs arrays of values.
  *
+ * **Details**
+ *
  * This constructor creates a channel that reads from a PubSub by automatically
  * subscribing to it and collecting values into arrays. The channel outputs
  * arrays of values in chunks, making it ideal for batch processing scenarios.
@@ -1284,6 +1298,8 @@ export const fromPubSubArray = pubsub => unwrap(Effect.map(PubSub.subscribe(pubs
 /**
  * Subscribes to a `PubSub` of `Take` values and exposes them as a channel.
  *
+ * **Details**
+ *
  * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
  * fail the channel. Done `Take` values complete the channel.
  *
@@ -1301,6 +1317,8 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
 /**
  * Creates a channel that pulls values from an `AsyncIterable`.
  *
+ * **Details**
+ *
  * Each yielded value is emitted as an output element. The iterator's return
  * value becomes the channel's done value. Thrown or rejected iterator errors
  * are converted with `onError`. If the channel scope closes early and the
@@ -1323,6 +1341,8 @@ export const fromAsyncIterable = (iterable, onError) => fromTransform(Effect.fnU
  * Creates a channel from an `AsyncIterable`, emitting each yielded value as a
  * single-element non-empty array.
  *
+ * **Details**
+ *
  * The iterator's return value becomes the channel's done value. Thrown or
  * rejected iterator errors are converted with `onError`. If the channel scope
  * closes early and the iterator has a `return` method, that method is called.
@@ -1393,6 +1413,8 @@ const concurrencyIsSequential = concurrency => concurrency === undefined || conc
  * Maps each output element with an effectful function, preserving the source
  * channel's done value.
  *
+ * **Details**
+ *
  * The mapping function receives the output element and its zero-based index.
  * By default elements are mapped sequentially. Use `options.concurrency` to
  * map multiple elements concurrently, and `options.unordered` to allow
@@ -1515,6 +1537,8 @@ export const mapInputError = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
  * Applies a side effect function to each output element of the channel,
  * returning a new channel that emits the same elements.
  *
+ * **Details**
+ *
  * The `tap` function allows you to perform side effects (like logging or
  * debugging) on each element emitted by a channel without modifying the
  * elements themselves.
@@ -1549,6 +1573,8 @@ export const tap = /*#__PURE__*/dual(args => isChannel(args[0]), (self, f, optio
  * Maps each output element to a channel and flattens the child channel
  * outputs.
  *
+ * **Details**
+ *
  * The source channel's done value is preserved. Child channel done values are
  * used only for child-channel completion. By default child channels are run
  * sequentially. Use `options.concurrency` and `options.bufferSize` to run child
@@ -1696,6 +1722,8 @@ export const combine = /*#__PURE__*/dual(4, (self, that, s, f) => fromTransform(
  * Runs a fallback channel if this channel completes without emitting any
  * output elements.
  *
+ * **Details**
+ *
  * If the source emits at least one element, the source is used unchanged. If
  * the source completes before emitting an element, the fallback function
  * receives the source done value and returns the replacement channel.
@@ -1808,6 +1836,8 @@ export const flattenArray = self => transformPull(self, pull => {
  * Flattens a channel that emits `Take` values into a channel that emits the
  * `Take` outputs directly.
  *
+ * **Details**
+ *
  * Output `Take` values are emitted as non-empty arrays. Failed `Take` values
  * fail the returned channel. Done `Take` values complete the returned channel.
  *
@@ -1865,6 +1895,8 @@ export const forever = self => concatWith(self, () => forever(self));
  * Runs a schedule step for each output element while preserving the emitted
  * elements.
  *
+ * **Details**
+ *
  * The schedule receives each output element as input. Schedule delays are
  * applied between emitted elements. If the schedule fails, the returned channel
  * fails. If the schedule finishes, the returned channel completes with the
@@ -1911,6 +1943,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => fromTransform((u
 /**
  * Filters and maps output elements using a `Filter`.
  *
+ * **Details**
+ *
  * Successful filter results are emitted as mapped values. Failed filter
  * results are discarded. The source channel's errors and done value are
  * preserved.
@@ -1925,6 +1959,8 @@ export const filterMap = /*#__PURE__*/dual(2, (self, filter) => fromTransform((u
 /**
  * Filters output elements with an effectful predicate.
  *
+ * **Details**
+ *
  * Elements for which the predicate succeeds with `true` are emitted. Elements
  * for which the predicate succeeds with `false` are discarded. Predicate
  * failures fail the returned channel.
@@ -1938,6 +1974,8 @@ export const filterEffect = /*#__PURE__*/dual(2, (self, predicate) => fromTransf
 /**
  * Filters and maps output elements using an effectful `Filter`.
  *
+ * **Details**
+ *
  * Successful filter results are emitted as mapped values. Failed filter
  * results are discarded. Failures from the effectful filter fail the returned
  * channel.
@@ -1997,6 +2035,8 @@ export const filterArray = /*#__PURE__*/dual(2, (self, predicate) => transformPu
  * Filters and maps each element inside emitted non-empty arrays using a
  * `Filter`.
  *
+ * **Details**
+ *
  * Successful filter results are kept as mapped values. Failed filter results
  * are removed from the array. Arrays that become empty are discarded.
  *
@@ -2017,6 +2057,8 @@ export const filterMapArray = /*#__PURE__*/dual(2, (self, filter) => transformPu
  * Filters each element inside emitted non-empty arrays with an effectful
  * predicate.
  *
+ * **Details**
+ *
  * The predicate receives the element and its index within the array. Elements
  * for which the predicate succeeds with `true` are kept. Arrays that become
  * empty are discarded. Predicate failures fail the returned channel.
@@ -2034,6 +2076,8 @@ export const filterArrayEffect = /*#__PURE__*/dual(2, (self, predicate) => trans
  * Filters and maps each element inside emitted non-empty arrays using an
  * effectful `Filter`.
  *
+ * **Details**
+ *
  * Successful filter results are kept as mapped values. Failed filter results
  * are removed from the array. Arrays that become empty are discarded. Failures
  * from the effectful filter fail the returned channel.
@@ -2268,6 +2312,8 @@ 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.
  *
+ * **Details**
+ *
  * Use this for observing failures, such as logging or metrics. If the observer
  * effect fails, that failure can fail the returned channel.
  *
@@ -2288,6 +2334,8 @@ export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => catchCa
 /**
  * Recovers from channel failures whose full `Cause` is selected by a `Filter`.
  *
+ * **Details**
+ *
  * When the filter succeeds, the recovery function receives the selected value
  * and the original cause. When the filter fails, the returned channel fails
  * with the residual cause produced by the filter.
@@ -2302,6 +2350,8 @@ export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => catchC
 const catch_ = /*#__PURE__*/dual(2, (self, f) => catchCauseFilter(self, Cause.findError, e => f(e)));
 export {
 /**
+ * Recovers from typed channel errors by running a fallback channel.
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2310,6 +2360,8 @@ catch_ as catch };
  * Runs an effect when the channel fails with a typed error, then preserves the
  * original channel failure.
  *
+ * **Details**
+ *
  * The effect is not run for normal channel completion. If the observer effect
  * fails, that failure can fail the returned channel.
  *
@@ -2320,6 +2372,8 @@ export const tapError = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pu
 /**
  * Recovers from typed channel errors that match a predicate or refinement.
  *
+ * **Details**
+ *
  * Matching errors are handled by the recovery function. Non-matching errors
  * are handled by `orElse` when provided. Without `orElse`, non-matching errors
  * are re-failed.
@@ -2333,6 +2387,8 @@ export const catchIf = /*#__PURE__*/dual(args => isChannel(args[0]), (self, pred
 /**
  * Recovers from typed channel errors selected by a `Filter`.
  *
+ * **Details**
+ *
  * Successful filter results are handled by the recovery function. Failed
  * filter results are handled by `orElse` when provided. Without `orElse`,
  * failed filter results are re-failed.
@@ -2347,6 +2403,8 @@ export const catchFilter = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
 /**
  * Recovers from tagged channel errors whose `_tag` matches one or more tags.
  *
+ * **Details**
+ *
  * Matching tagged errors are handled by the recovery function. Non-matching
  * errors are handled by `orElse` when provided. Without `orElse`,
  * non-matching errors are re-failed.
@@ -2491,6 +2549,8 @@ export const orDie = self => catch_(self, die);
 /**
  * Ignores all errors in the channel, converting them to an empty channel.
  *
+ * **Details**
+ *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
  * @category error handling
@@ -2507,6 +2567,8 @@ const ignoreCause_ = self => catchCause(self, () => empty);
 /**
  * Ignores all errors in the channel including defects, converting them to an empty channel.
  *
+ * **Details**
+ *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
  * @category error handling
@@ -2546,6 +2608,8 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
  * Maps each output element to a channel and emits values from the most recent
  * active child channels.
  *
+ * **Details**
+ *
  * With the default concurrency of `1`, starting a new child channel interrupts
  * the previous child channel. Use `options.concurrency` to allow more active
  * child channels. The source channel's done value is preserved.
@@ -2716,6 +2780,8 @@ 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.
  *
+ * **Details**
+ *
  * The effect's successful value is ignored. If the effect fails while the
  * channel is running, the returned channel fails with that error.
  *
@@ -2730,6 +2796,8 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => merge(self, fr
  * standalone `\r` as line terminators. The behavior matches
  * `String.linesIterator` regardless of how the input is chunked.
  *
+ * **Details**
+ *
  * A line terminator at the very end of the stream does **not** produce a
  * trailing empty line (consistent with `String.linesIterator`). Conversely,
  * if the stream ends without a terminator the final partial line is still
@@ -2840,6 +2908,8 @@ export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(
 /**
  * Decodes incoming `Uint8Array` chunks into strings using `TextDecoder`.
  *
+ * **Details**
+ *
  * Input chunks are decoded with streaming enabled so multi-byte characters may
  * span `Uint8Array` boundaries. The optional `encoding` and `options` are
  * passed to `TextDecoder`.
@@ -2857,6 +2927,8 @@ export const decodeText = (encoding, options) => fromTransform((upstream, _scope
 /**
  * Encodes incoming string chunks into `Uint8Array` values using `TextEncoder`.
  *
+ * **Details**
+ *
  * Each string inside an emitted array is encoded independently.
  *
  * @category String manipulation
@@ -2972,6 +3044,8 @@ export const scoped = self => fromTransformBracket((upstream, scope, forkedScope
  * Runs an input handler against the upstream pull while the wrapped channel
  * runs without receiving upstream input directly.
  *
+ * **Details**
+ *
  * The input handler is forked in the channel scope. The wrapped channel is run
  * with an already-completed input.
  *
@@ -3057,6 +3131,8 @@ export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => merge(self,
 /**
  * Halts a channel when the specified effect completes or fails.
  *
+ * **Details**
+ *
  * If the effect completes before the channel is done, its success value becomes
  * the returned channel's done value. If the effect fails, the returned channel
  * fails with that error. If the channel completes first, the channel's done
@@ -3077,6 +3153,8 @@ export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBrac
 /**
  * Attaches a finalizer that runs only when the channel exits with failure.
  *
+ * **Details**
+ *
  * The finalizer receives the failure `Cause`. The original channel failure is
  * preserved. The finalizer itself must not fail.
  *
@@ -3118,6 +3196,8 @@ export const onExit = /*#__PURE__*/dual(2, (self, finalizer) => fromTransformBra
 /**
  * Runs an effect before the channel starts.
  *
+ * **Details**
+ *
  * The effect's successful value is ignored. If the effect fails, the returned
  * channel fails before running the source channel.
  *
@@ -3128,6 +3208,8 @@ export const onStart = /*#__PURE__*/dual(2, (self, onStart) => unwrap(Effect.as(
 /**
  * Runs an effect the first time the channel emits an output element.
  *
+ * **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.
@@ -3146,6 +3228,8 @@ export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(sel
 /**
  * Runs an effect when the channel completes successfully.
  *
+ * **Details**
+ *
  * The effect runs before the original done value is propagated. The effect is
  * not run when the channel fails. If the effect fails, the returned channel
  * fails with that error.
@@ -3214,6 +3298,8 @@ export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromT
  * Evaluates an effect to obtain a service, then provides that service to the
  * channel.
  *
+ * **Details**
+ *
  * If the service effect fails, the returned channel fails. The provided service
  * removes the corresponding service requirement from the returned channel.
  *
@@ -3225,6 +3311,8 @@ export const provideServiceEffect = /*#__PURE__*/dual(3, (self, key, service) =>
  * Provides a `Layer` or `Context` to the channel, removing the corresponding
  * service requirements.
  *
+ * **Details**
+ *
  * Providing a `Context` delegates to `provideContext`. Providing a `Layer`
  * builds the layer in the channel scope. Use `options.local` to build a fresh
  * layer instance for this provision.
@@ -3236,6 +3324,8 @@ export const provide = /*#__PURE__*/dual(args => isChannel(args[0]), (self, laye
 /**
  * Transforms the current context before running the channel.
  *
+ * **Details**
+ *
  * The function receives the surrounding context and returns the context to
  * provide to the channel. The returned channel requires the services needed to
  * build that context.
@@ -3250,6 +3340,8 @@ export const updateContext = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
 /**
  * Updates a service in the current context before running the channel.
  *
+ * **Details**
+ *
  * The existing service is read from the context. The updated service is
  * provided to the channel under the same key.
  *
@@ -3260,6 +3352,8 @@ export const updateService = /*#__PURE__*/dual(3, (self, service, f) => updateCo
 /**
  * Runs the channel inside a tracing span with the specified name and options.
  *
+ * **Details**
+ *
  * The created span is provided as the current parent span while the channel
  * runs. The span is ended with the channel's exit value.
  *
@@ -3294,6 +3388,8 @@ const let_ = /*#__PURE__*/dual(3, (self, name, f) => map(self, elem => ({
 })));
 export {
 /**
+ * Adds a computed field to each object emitted by a channel.
+ *
  * @category Do notation
  * @since 4.0.0
  */
@@ -3302,6 +3398,8 @@ let_ as let };
  * Adds a field to each object emitted by a channel by running another channel
  * derived from that object.
  *
+ * **Details**
+ *
  * The field name must not already exist on the emitted object. The derived
  * channel's output becomes the value of the new field. `options.concurrency`
  * and `options.bufferSize` control how derived channels are flattened.
@@ -3412,6 +3510,8 @@ export const runForEach = /*#__PURE__*/dual(2, (self, f) => runWith(self, pull =
  * Runs a channel and applies an effectful predicate to each output element
  * until the predicate returns `false`.
  *
+ * **Details**
+ *
  * Returning `true` continues consuming the channel. Returning `false` stops
  * consumption early. The returned effect completes with `void`.
  *
@@ -3460,6 +3560,8 @@ export const runDone = self => runWith(self, identity_, Effect.succeed);
  * Runs a channel until the first output element is available, returning it in
  * an `Option`.
  *
+ * **Details**
+ *
  * Returns `Option.some` with the first output element, or `Option.none` if the
  * channel completes without emitting output.
  *
@@ -3477,6 +3579,8 @@ export const runHead = self => Effect.suspend(() => {
  * Runs a channel to completion and returns the last output element in an
  * `Option`.
  *
+ * **Details**
+ *
  * Returns `Option.some` with the last emitted element, or `Option.none` if the
  * channel completes without emitting output.
  *
@@ -3530,6 +3634,8 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Effect.suspend
 /**
  * Runs a channel and effectfully folds all output elements with an accumulator.
  *
+ * **Details**
+ *
  * The initial accumulator is evaluated lazily. Each output element is passed to
  * the effectful accumulator function. The returned effect succeeds with the
  * final accumulator value.
@@ -3550,6 +3656,8 @@ export const runFoldEffect = /*#__PURE__*/dual(3, (self, initial, f) => Effect.s
 /**
  * Converts a channel to a scoped `Pull` for low-level consumption.
  *
+ * **Details**
+ *
  * The effect requires a `Scope`. The returned pull should be consumed only
  * while that scope remains open. Pulls are serialized so only one pull is
  * evaluated at a time.
@@ -3617,6 +3725,8 @@ export const toPullScoped = (self, scope) => toTransform(self)(Cause.done(), sco
 /**
  * Runs a channel and offers each output element into a queue.
  *
+ * **Details**
+ *
  * When the channel completes, the queue is ended. When the channel fails, the
  * queue is failed with the channel's cause. The returned effect itself
  * completes with `void`.
@@ -3636,6 +3746,8 @@ export const runIntoQueue = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * Runs a channel that emits non-empty arrays and offers each array element into
  * a queue.
  *
+ * **Details**
+ *
  * When the channel completes, the queue is ended. When the channel fails, the
  * queue is failed with the channel's cause. The returned effect itself
  * completes with `void`.
@@ -3655,6 +3767,8 @@ export const runIntoQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), (
  * Creates a scoped queue and forks the channel to feed it for concurrent
  * consumption.
  *
+ * **Details**
+ *
  * Output elements are offered to the queue. Channel completion and failure are
  * signaled through the queue. The queue is shut down when the surrounding scope
  * closes.
@@ -3694,6 +3808,8 @@ export const toQueue = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__PURE__
 /**
  * Creates a scoped queue and forks an array-emitting channel to feed it.
  *
+ * **Details**
+ *
  * Each element inside emitted non-empty arrays is offered to the queue. Channel
  * completion and failure are signaled through the queue. The queue is shut down
  * when the surrounding scope closes.
@@ -3714,6 +3830,8 @@ export const toQueueArray = /*#__PURE__*/dual(args => isChannel(args[0]), /*#__P
 /**
  * Converts a channel to a PubSub for concurrent consumption.
  *
+ * **Details**
+ *
  * `shutdownOnEnd` indicates whether the PubSub should be shut down when the
  * channel ends. By default this is `true`.
  *
@@ -3730,6 +3848,8 @@ export const toPubSub = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(func
 /**
  * Runs a channel and publishes each output element to a `PubSub`.
  *
+ * **Details**
+ *
  * The channel's output values are published as individual PubSub messages. Use
  * `options.shutdownOnEnd` to shut down the PubSub when channel execution ends.
  *
@@ -3742,6 +3862,8 @@ const makePubSub = options => Effect.acquireRelease(options.capacity === "unboun
  * Converts an array-emitting channel to a scoped `PubSub` for concurrent
  * consumption.
  *
+ * **Details**
+ *
  * Each element inside emitted non-empty arrays is published as an individual
  * PubSub message. `shutdownOnEnd` indicates whether the PubSub should be shut
  * down when the channel ends. By default this is `true`.
@@ -3760,6 +3882,8 @@ export const toPubSubArray = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced
  * Runs an array-emitting channel and publishes each array element to a
  * `PubSub`.
  *
+ * **Details**
+ *
  * Each element inside emitted non-empty arrays is published as an individual
  * PubSub message. Use `options.shutdownOnEnd` to shut down the PubSub when
  * channel execution ends.
@@ -3771,6 +3895,8 @@ export const runIntoPubSubArray = /*#__PURE__*/dual(args => isChannel(args[0]),
 /**
  * Converts a channel to a scoped `PubSub` of `Take` values.
  *
+ * **Details**
+ *
  * Emitted non-empty arrays are published as output `Take` values. When the
  * channel ends, its final `Exit` is published so subscribers can observe
  * completion or failure.