effect 4.0.0-beta.71 → 4.0.0-beta.72

package/dist/Channel.js

@@ -102,12 +102,12 @@ import { ParentSpan } from "./Tracer.js";
  * 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 = "~effect/Channel";
 /**
- * Tests if a value is a `Channel`.
+ * Checks whether a value is a `Channel`.
  *
  * **Example** (Checking for channels)
  *
@@ -591,7 +591,7 @@ export const endSync = evaluate => fromPull(Effect.sync(() => Cause.done(evaluat
  */
 export const sync = evaluate => fromEffect(Effect.sync(evaluate));
 /**
- * Represents an Channel that emits no elements
+ * Represents a `Channel` that emits no elements.
  *
  * **Example** (Using empty channels)
  *
@@ -615,7 +615,7 @@ export const sync = evaluate => fromEffect(Effect.sync(evaluate));
  */
 export const empty = /*#__PURE__*/fromPull(/*#__PURE__*/Effect.succeed(/*#__PURE__*/Cause.done()));
 /**
- * Represents an Channel that never completes
+ * Represents a `Channel` that never completes.
  *
  * **Example** (Using non-terminating channels)
  *
@@ -782,7 +782,7 @@ export const failCauseSync = evaluate => fromPull(Effect.failCauseSync(evaluate)
  */
 export const die = defect => 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)
  *
@@ -839,7 +839,7 @@ export const fromEffect = effect => fromPull(Effect.sync(() => {
  */
 export const fromEffectDone = effect => 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
@@ -859,7 +859,7 @@ export const fromEffectDrain = effect => fromPull(Effect.flatMap(effect, () => C
  */
 export const fromEffectTake = effect => 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)
  *
@@ -899,7 +899,7 @@ export const fromEffectTake = effect => fromPull(Effect.succeed(Effect.flatMap(e
  */
 export const fromQueue = queue => 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)
  *
@@ -951,7 +951,7 @@ export const fromQueueArray = queue => fromPull(Effect.succeed(Queue.takeAll(que
  */
 export const identity = () => 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)
  *
@@ -996,7 +996,7 @@ export const identity = () => fromTransform((upstream, _scope) => Effect.succeed
  */
 export const fromSubscription = subscription => 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**
  *
@@ -1099,7 +1099,7 @@ export const fromSubscription = subscription => fromPull(Effect.succeed(Effect.o
  */
 export const fromSubscriptionArray = subscription => 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**
  *
@@ -1193,7 +1193,7 @@ export const fromSubscriptionArray = subscription => fromPull(Effect.succeed(Eff
  */
 export const fromPubSub = pubsub => 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**
  *
@@ -1716,11 +1716,18 @@ export const concatWith = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  */
 export const concat = /*#__PURE__*/dual(2, (self, that) => 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
@@ -1767,7 +1774,7 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, f) => fromTransform((up
   return Effect.suspend(() => currentPull ?? makePull);
 })));
 /**
- * Flatten a channel of channels.
+ * Flattens a channel of channels.
  *
  * **Example** (Flattening nested channels)
  *
@@ -2127,7 +2134,7 @@ export const filterMapArrayEffect = /*#__PURE__*/dual(2, (self, filter) => trans
   return Effect.flatMap(Effect.filterMapEffect(arr, filter), passes => Arr.isReadonlyArrayNonEmpty(passes) ? Effect.succeed(passes) : Effect.flatMap(pull, loop));
 }))));
 /**
- * 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)
  *
@@ -2204,7 +2211,7 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
   return pump;
 })));
 /**
- * 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)
@@ -2235,7 +2242,7 @@ export const mapAccum = /*#__PURE__*/dual(args => isChannel(args[0]), (self, ini
  */
 export const scan = /*#__PURE__*/dual(3, (self, initial, f) => 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)
@@ -3158,8 +3165,8 @@ export const scoped = self => fromTransformBracket((upstream, scope, forkedScope
  */
 export const embedInput = /*#__PURE__*/dual(2, (self, input) => fromTransformBracket((upstream, scope, forkedScope) => Effect.andThen(Effect.forkIn(input(upstream), forkedScope), toTransform(self)(Cause.done(), scope))));
 /**
- * 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**
  *
@@ -3190,8 +3197,8 @@ export const buffer = /*#__PURE__*/dual(2, (self, options) => fromTransform(Effe
   return Queue.take(queue);
 })));
 /**
- * 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**
  *
@@ -3224,13 +3231,18 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromTransform
   return Queue.takeAll(queue);
 })));
 /**
- * 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
@@ -3239,7 +3251,7 @@ export const interruptWhen = /*#__PURE__*/dual(2, (self, effect) => merge(self,
   haltStrategy: "either"
 }));
 /**
- * Halts a channel when the specified effect completes or fails.
+ * Stops a channel when the specified effect completes or fails.
  *
  * **Details**
  *
@@ -3273,9 +3285,8 @@ export const haltWhen = /*#__PURE__*/dual(2, (self, effect) => fromTransformBrac
  */
 export const onError = /*#__PURE__*/dual(2, (self, finalizer) => 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)
  *
@@ -3349,9 +3360,8 @@ export const onFirst = /*#__PURE__*/dual(2, (self, onFirst) => transformPull(sel
  */
 export const onEnd = /*#__PURE__*/dual(2, (self, onEnd) => transformPull(self, pull => Effect.succeed(Pull.catchDone(pull, leftover => Effect.flatMap(onEnd, () => Cause.done(leftover))))));
 /**
- * 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)
  *
@@ -3382,7 +3392,7 @@ const runWith = (self, f, onHalt) => Effect.suspend(() => {
   return Pull.catchDone(Effect.flatMap(makePull, f), onHalt ? onHalt : Effect.succeed).pipe(Effect.onExit(exit => Scope.close(scope, exit)));
 });
 /**
- * Create a channel from the specified services.
+ * Creates a channel from the specified services.
  *
  * @category services
  * @since 2.0.0
@@ -3405,8 +3415,12 @@ export const provideContext = /*#__PURE__*/dual(2, (self, context) => fromTransf
  */
 export const provideService = /*#__PURE__*/dual(3, (self, key, service) => fromTransform((upstream, scope) => Effect.map(Effect.provideService(toTransform(self)(upstream, scope), key, service), Effect.provideService(key, service))));
 /**
- * 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**
  *