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

package/dist/Stream.js

@@ -256,8 +256,8 @@ export const service = service => fromEffect(Effect.service(service));
  *
  * **When to use**
  *
- * Use to emit an optional dependency as a stream element without requiring that
- * dependency to be present.
+ * Use when you need a stream that emits an optional service from the context
+ * without requiring that service to be present.
  *
  * **Example** (Accessing an optional service as a stream)
  *
@@ -539,8 +539,8 @@ export const toChannel = stream => stream.channel;
  *
  * **When to use**
  *
- * Use when you can use the `Queue` with the apis from the `Queue` module to emit
- * values to the stream or to signal the stream ending.
+ * Use when you need callback-based code to emit stream values by offering to a
+ * `Queue`, or signal stream completion through the `Queue` module APIs.
  *
  * By default it uses an "unbounded" buffer size.
  * You can customize the buffer size and strategy by passing an object as the
@@ -882,6 +882,11 @@ export const fromIterable = (iterable, options) => Array.isArray(iterable) && op
 /**
  * Creates a stream from an effect producing an iterable of values.
  *
+ * **When to use**
+ *
+ * Use when the iterable must be acquired from an Effect before the stream emits,
+ * and acquisition services or failures should be part of the stream.
+ *
  * **Example** (Creating a stream from an iterable effect)
  *
  * ```ts
@@ -964,6 +969,11 @@ export const fromArray = array => Arr.isReadonlyArrayNonEmpty(array) ? fromChann
 /**
  * Creates a stream from an effect that produces an array of values.
  *
+ * **When to use**
+ *
+ * Use when the array must be acquired from an Effect before the stream emits,
+ * and acquisition services or failures should be part of the stream.
+ *
  * **Example** (Creating a stream from an effect that produces an array of values)
  *
  * ```ts
@@ -1216,8 +1226,9 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
  *
  * **When to use**
  *
- * Use to create the subscription and `Stream.take` or
- * cancellation to control how many values are consumed.
+ * Use when you already have a `PubSub.Subscription` and want to expose its
+ * messages as a `Stream`, with `Stream.take` or cancellation controlling how
+ * many values are consumed.
  *
  * **Example** (Creating a stream from a PubSub subscription)
  *
@@ -1594,6 +1605,11 @@ export const mapArray = /*#__PURE__*/dual(2, (self, f) => fromChannel(Channel.ma
 /**
  * Maps over elements of the stream with the specified effectful function.
  *
+ * **When to use**
+ *
+ * Use when each stream element transformation needs an Effect, service
+ * dependency, failure channel, or configured concurrency.
+ *
  * **Example** (Effectfully mapping stream values)
  *
  * ```ts
@@ -1630,6 +1646,11 @@ export const mapEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self, f,
 /**
  * Flattens a stream of `Effect` values into a stream of their results.
  *
+ * **When to use**
+ *
+ * Use when stream elements already are effects and their successes should become
+ * stream elements while their failures enter the stream error channel.
+ *
  * **Example** (Flattening a stream of Effect values into a stream of their results)
  *
  * ```ts
@@ -1653,6 +1674,11 @@ export const flattenEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self,
 /**
  * Maps over non-empty array chunks emitted by the stream effectfully.
  *
+ * **When to use**
+ *
+ * Use when transformation needs to see and replace each non-empty emitted chunk
+ * effectfully instead of mapping individual stream elements.
+ *
  * **Example** (Effectfully mapping stream chunks)
  *
  * ```ts
@@ -2348,6 +2374,11 @@ export const merge = /*#__PURE__*/dual(args => isStream(args[0]) && isStream(arg
 /**
  * Merges this stream with a background effect, keeping the stream's elements.
  *
+ * **When to use**
+ *
+ * Use when an effect should run concurrently for the lifetime of a stream while
+ * only the stream's elements remain in the output.
+ *
  * **Details**
  *
  * The effect runs concurrently, fails the stream if it fails, and is interrupted
@@ -2380,6 +2411,12 @@ export const mergeEffect = /*#__PURE__*/dual(2, (self, effect) => self.channel.p
  * Merges this stream and the specified stream together, tagging values from the
  * left stream as `Result.succeed` and values from the right stream as `Result.fail`.
  *
+ * **When to use**
+ *
+ * Use when values from both streams should be emitted and downstream code needs
+ * left values wrapped as successful `Result` values and right values wrapped as
+ * failed `Result` values.
+ *
  * **Example** (Merging streams into results)
  *
  * ```ts
@@ -2414,6 +2451,11 @@ export const mergeResult = /*#__PURE__*/dual(2, (self, that) => merge(map(self,
 /**
  * Merges two streams while emitting only the values from the left stream.
  *
+ * **When to use**
+ *
+ * Use when the right stream is needed for its effects or failures, but downstream
+ * consumers should only receive values from the left stream.
+ *
  * **Details**
  *
  * The right stream still runs for its effects, and any failures from the right
@@ -2444,6 +2486,11 @@ export const mergeLeft = /*#__PURE__*/dual(2, (left, right) => mergeEffect(left,
  * Merges this stream and the specified stream together, emitting only the
  * values from the right stream while the left stream runs for its effects.
  *
+ * **When to use**
+ *
+ * Use when the left stream is needed for its effects or failures, but downstream
+ * consumers should only receive values from the right stream.
+ *
  * **Details**
  *
  * The merged stream ends when the right stream completes, interrupting the
@@ -2958,6 +3005,11 @@ export const zipWithPreviousAndNext = self => mapAccumArray(self, () => ({
  * Zips multiple streams so that when a value is emitted by any stream, it is
  * combined with the latest values from the other streams to produce a result.
  *
+ * **When to use**
+ *
+ * Use when each stream should contribute its latest value after all streams have
+ * emitted at least once.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -3009,6 +3061,11 @@ export const zipLatestAll = (...streams) => fromChannel(Channel.suspend(() => {
 /**
  * Combines two streams by emitting each new element with the latest value from the other stream.
  *
+ * **When to use**
+ *
+ * Use when two streams should start emitting combined pairs after both have
+ * produced at least one value.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -3039,6 +3096,11 @@ export const zipLatest = /*#__PURE__*/dual(2, (left, right) => zipLatestAll(left
  * Combines the latest values from both streams whenever either emits, using
  * the provided function.
  *
+ * **When to use**
+ *
+ * Use when two streams should start emitting custom combined values after both
+ * have produced at least one value.
+ *
  * **Gotchas**
  *
  * Note: tracking the latest value is done on a per-array basis. That means
@@ -3323,8 +3385,8 @@ export const partitionQueue = /*#__PURE__*/dual(args => isStream(args[0]), /*#__
  *
  * **When to use**
  *
- * Use when each stream element must be classified by an effectful `Filter` and
- * both passing and failing mapped values need to be consumed as streams.
+ * Use when you need to classify each stream element with an effectful `Filter`
+ * and consume both passing and failing mapped values as streams.
  *
  * **Details**
  *
@@ -3688,8 +3750,8 @@ export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, f
  *
  * **When to use**
  *
- * Use when your error type is a tagged union with a readonly `_tag`
- * field and you want to handle a specific error case.
+ * Use when you need to handle a specific error case from a stream whose error
+ * type is a tagged union with a readonly `_tag` field.
  *
  * **Example** (Catching tagged failures)
  *
@@ -3770,7 +3832,11 @@ export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cas
  * **When to use**
  *
  * Use to handle nested error causes without removing the parent error
- * from the error channel. The handler receives the unwrapped reason.
+ * from the error channel.
+ *
+ * **Details**
+ *
+ * The handler receives the unwrapped reason.
  *
  * **Example** (Catching a tagged error reason)
  *
@@ -3923,7 +3989,7 @@ export const catchCauseIf = /*#__PURE__*/dual(3, (self, predicate, f) => fromCha
  * **When to use**
  *
  * Use when you need to recover a stream 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**
@@ -4020,8 +4086,12 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  * **When to use**
  *
  * Use when you want a failing stream to end gracefully rather than propagate
- * the error. The `log` option controls whether the failure is logged before
- * the stream terminates.
+ * the error.
+ *
+ * **Details**
+ *
+ * The `log` option controls whether the failure is logged before the stream
+ * terminates.
  *
  * **Example** (Ignoring stream failures)
  *
@@ -4068,9 +4138,8 @@ export const ignore = /*#__PURE__*/dual(args => isStream(args[0]), (self, option
  *
  * **When to use**
  *
- * Use when a stream may fail with defects and you want to silently suppress the
- * entire failure cause — including both typed errors and defects — rather than
- * propagate it downstream.
+ * Use when you need to silently suppress a stream's entire failure cause,
+ * including both typed errors and defects, rather than propagate it downstream.
  *
  * **Example** (Ignoring stream failure causes)
  *
@@ -4333,6 +4402,11 @@ export const takeUntil = /*#__PURE__*/dual(args => isStream(args[0]), (self, pre
 /**
  * Takes stream elements until an effectful predicate returns `true`.
  *
+ * **When to use**
+ *
+ * Use when the stopping condition needs an Effect or service and predicate
+ * failure should fail the stream.
+ *
  * **Example** (Taking until an effectful predicate matches)
  *
  * ```ts
@@ -4448,6 +4522,11 @@ export const takeWhileFilter = /*#__PURE__*/dual(2, (self, filter) => transformP
 /**
  * Takes elements from the stream while the effectful predicate is `true`.
  *
+ * **When to use**
+ *
+ * Use when the leading-prefix predicate needs an Effect or service and the
+ * stream should stop before the first false result.
+ *
  * **Example** (Effectfully taking while a predicate holds)
  *
  * ```ts
@@ -4530,9 +4609,10 @@ export const dropUntil = /*#__PURE__*/dual(2, (self, predicate) => drop(dropWhil
  * Drops all elements of the stream until the specified effectful predicate
  * evaluates to `true`.
  *
- * **Details**
+ * **When to use**
  *
- * The first element that satisfies the predicate is also dropped.
+ * Use when dropping the leading prefix requires an Effect or service and the
+ * first matching element should also be dropped.
  *
  * **Example** (Dropping until an effectful predicate matches)
  *
@@ -5084,6 +5164,11 @@ const emptyArr = /*#__PURE__*/Arr.empty();
  * Maps each element statefully and effectfully, emitting zero or more output
  * values per input.
  *
+ * **When to use**
+ *
+ * Use when stateful element mapping needs Effects or can fail while emitting
+ * zero or more values per input element.
+ *
  * **Details**
  *
  * The mapping effect receives the current state and element, then returns the
@@ -5123,6 +5208,11 @@ export const mapAccumEffect = /*#__PURE__*/dual(args => isStream(args[0]), (self
  * Maps each non-empty input chunk statefully and effectfully, emitting zero or
  * more output values per chunk.
  *
+ * **When to use**
+ *
+ * Use when stateful mapping should process each emitted non-empty chunk with an
+ * Effect instead of each element separately.
+ *
  * **Details**
  *
  * The mapping effect receives the current state and chunk, then returns the
@@ -5623,9 +5713,9 @@ const groupByImpl = (self, f, options) => transformPullBracket(self, Effect.fnUn
  *
  * **When to use**
  *
- * Use when a stream is already ordered by the grouping key and you want to emit
- * each consecutive run as a non-empty array while keeping later non-adjacent
- * runs separate.
+ * Use when you already have a stream ordered by the grouping key and want to
+ * emit each consecutive run as a non-empty array while keeping later
+ * non-adjacent runs separate.
  *
  * **Details**
  *
@@ -7210,6 +7300,11 @@ export const runFold = /*#__PURE__*/dual(3, (self, initial, f) => Channel.runFol
 /**
  * Runs the stream and folds elements using an effectful reducer.
  *
+ * **When to use**
+ *
+ * Use when reducing stream elements needs Effects, services, or failures in the
+ * reducer.
+ *
  * **Example** (Effectfully folding stream values)
  *
  * ```ts
@@ -7510,6 +7605,11 @@ export const mkUint8Array = self => Effect.map(Channel.runFold(self.channel, ()
 /**
  * Converts the stream to a `ReadableStream` using the provided services.
  *
+ * **When to use**
+ *
+ * Use when bridging to Web Streams and you already have the `Context` required
+ * to run the stream outside an `Effect`.
+ *
  * **Details**
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -7583,6 +7683,11 @@ export const toReadableStream = /*#__PURE__*/dual(args => isStream(args[0]), (se
 /**
  * Creates an Effect that builds a ReadableStream from the stream.
  *
+ * **When to use**
+ *
+ * Use when bridging to Web Streams from inside an `Effect` so the required
+ * services can be captured from the current context.
+ *
  * **Details**
  *
  * See https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream.
@@ -7609,6 +7714,11 @@ export const toReadableStreamEffect = /*#__PURE__*/dual(args => isStream(args[0]
 /**
  * Converts the stream to an `AsyncIterable` using the provided services.
  *
+ * **When to use**
+ *
+ * Use when converting outside an Effect and you already have the `Context`
+ * needed to run the stream.
+ *
  * **Example** (Converting to an AsyncIterable with services)
  *
  * ```ts
@@ -7671,6 +7781,11 @@ export const toAsyncIterableWith = /*#__PURE__*/dual(2, (self, context) => ({
 /**
  * Creates an effect that yields an `AsyncIterable` using the current services.
  *
+ * **When to use**
+ *
+ * Use when the `AsyncIterable` should be created inside Effect with the current
+ * context supplying the stream's services.
+ *
  * **Example** (Creating an AsyncIterable effect)
  *
  * ```ts