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

package/src/Schedule.ts

@@ -665,7 +665,7 @@ export const toStepWithSleep = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @category utils
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const addDelay: {
@@ -765,7 +765,7 @@ export const addDelay: {
    * })
    * ```
    *
-   * @category utils
+   * @category delays & timeouts
    * @since 2.0.0
    */
   <Output, Error2 = never, Env2 = never>(f: (output: Output) => Effect<Duration.Input, Error2, Env2>): <Input, Error, Env>(
@@ -867,7 +867,7 @@ export const addDelay: {
    * })
    * ```
    *
-   * @category utils
+   * @category delays & timeouts
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Error2 = never, Env2 = never>(
@@ -1376,9 +1376,7 @@ export const andThenResult: {
  *
  * **When to use**
  *
- * Use when the combined schedule should continue only while both
- * schedules still recur. Use `either` when either schedule should be enough to
- * continue.
+ * Use when the combined schedule should continue only while both schedules still recur.
  *
  * **Example** (Combining time and attempt limits)
  *
@@ -1444,7 +1442,7 @@ export const andThenResult: {
  *
  * @see {@link either} for continuing while either schedule still recurs
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const both: {
@@ -1455,9 +1453,7 @@ export const both: {
    *
    * **When to use**
    *
-   * Use when the combined schedule should continue only while both
-   * schedules still recur. Use `either` when either schedule should be enough to
-   * continue.
+   * Use when the combined schedule should continue only while both schedules still recur.
    *
    * **Example** (Combining time and attempt limits)
    *
@@ -1523,7 +1519,7 @@ export const both: {
    *
    * @see {@link either} for continuing while either schedule still recurs
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2, Output>(other: Schedule<Output2, Input2, Error2, Env2>): <Input, Error, Env>(
@@ -1536,9 +1532,7 @@ export const both: {
    *
    * **When to use**
    *
-   * Use when the combined schedule should continue only while both
-   * schedules still recur. Use `either` when either schedule should be enough to
-   * continue.
+   * Use when the combined schedule should continue only while both schedules still recur.
    *
    * **Example** (Combining time and attempt limits)
    *
@@ -1604,7 +1598,7 @@ export const both: {
    *
    * @see {@link either} for continuing while either schedule still recurs
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -1622,6 +1616,11 @@ export const both: {
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
+ * **When to use**
+ *
+ * Use when two schedules must both allow recurrence and only the left schedule's
+ * output is needed.
+ *
  * **Example** (Combining schedules and keeping the left output)
  *
  * ```ts
@@ -1646,7 +1645,7 @@ export const both: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const bothLeft: {
@@ -1655,6 +1654,11 @@ export const bothLeft: {
    * to recur, using the maximum of the two durations between recurrences and
    * outputting the result of the left schedule (i.e. `self`).
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and only the left schedule's
+   * output is needed.
+   *
    * **Example** (Combining schedules and keeping the left output)
    *
    * ```ts
@@ -1679,7 +1683,7 @@ export const bothLeft: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(
@@ -1690,6 +1694,11 @@ export const bothLeft: {
    * to recur, using the maximum of the two durations between recurrences and
    * outputting the result of the left schedule (i.e. `self`).
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and only the left schedule's
+   * output is needed.
+   *
    * **Example** (Combining schedules and keeping the left output)
    *
    * ```ts
@@ -1714,7 +1723,7 @@ export const bothLeft: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -1731,6 +1740,11 @@ export const bothLeft: {
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
+ * **When to use**
+ *
+ * Use when two schedules must both allow recurrence and only the right
+ * schedule's output is needed.
+ *
  * **Example** (Combining schedules and keeping the right output)
  *
  * ```ts
@@ -1757,7 +1771,7 @@ export const bothLeft: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const bothRight: {
@@ -1766,6 +1780,11 @@ export const bothRight: {
    * to recur, using the maximum of the two durations between recurrences and
    * outputting the result of the right schedule (i.e. `other`).
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and only the right
+   * schedule's output is needed.
+   *
    * **Example** (Combining schedules and keeping the right output)
    *
    * ```ts
@@ -1792,7 +1811,7 @@ export const bothRight: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(
@@ -1803,6 +1822,11 @@ export const bothRight: {
    * to recur, using the maximum of the two durations between recurrences and
    * outputting the result of the right schedule (i.e. `other`).
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and only the right
+   * schedule's output is needed.
+   *
    * **Example** (Combining schedules and keeping the right output)
    *
    * ```ts
@@ -1829,7 +1853,7 @@ export const bothRight: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -1847,6 +1871,11 @@ export const bothRight: {
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
+ * **When to use**
+ *
+ * Use when two schedules must both allow recurrence and their outputs should be
+ * combined into a custom value.
+ *
  * **Example** (Combining schedule outputs)
  *
  * ```ts
@@ -1877,7 +1906,7 @@ export const bothRight: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const bothWith: {
@@ -1887,6 +1916,11 @@ export const bothWith: {
    * outputting the result of the combination of both schedule outputs using the
    * specified `combine` function.
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and their outputs should be
+   * combined into a custom value.
+   *
    * **Example** (Combining schedule outputs)
    *
    * ```ts
@@ -1917,7 +1951,7 @@ export const bothWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2, Output, Output3>(
@@ -1932,6 +1966,11 @@ export const bothWith: {
    * outputting the result of the combination of both schedule outputs using the
    * specified `combine` function.
    *
+   * **When to use**
+   *
+   * Use when two schedules must both allow recurrence and their outputs should be
+   * combined into a custom value.
+   *
    * **Example** (Combining schedule outputs)
    *
    * ```ts
@@ -1962,7 +2001,7 @@ export const bothWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2, Output3>(
@@ -2030,7 +2069,7 @@ export const bothWith: {
  * })
  * ```
  *
- * @category utils
+ * @category collecting
  * @since 4.0.0
  */
 export const collectInputs = <Output, Input, Error, Env>(
@@ -2067,7 +2106,7 @@ export const collectInputs = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @category utils
+ * @category collecting
  * @since 4.0.0
  */
 export const collectOutputs = <Output, Input, Error, Env>(
@@ -2154,7 +2193,7 @@ export const collectOutputs = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @category utils
+ * @category collecting
  * @since 2.0.0
  */
 export const collectWhile: {
@@ -2238,7 +2277,7 @@ export const collectWhile: {
    * })
    * ```
    *
-   * @category utils
+   * @category collecting
    * @since 2.0.0
    */
   <Input, Output, Error2 = never, Env2 = never>(
@@ -2328,7 +2367,7 @@ export const collectWhile: {
    * })
    * ```
    *
-   * @category utils
+   * @category collecting
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Error2 = never, Env2 = never>(
@@ -2855,8 +2894,7 @@ export const delays = <Out, In, E, R>(self: Schedule<Out, In, E, R>): Schedule<D
  *
  * **When to use**
  *
- * Use when you need one delayed recurrence. Use `during` to keep
- * recurring until a duration has elapsed.
+ * Use when you need a schedule that recurs once after a fixed delay.
  *
  * **Details**
  *
@@ -2894,8 +2932,7 @@ export const duration = (durationInput: Duration.Input): Schedule<Duration.Durat
  *
  * **When to use**
  *
- * Use to bound a repeating or retrying schedule by elapsed time. Use
- * `duration` when you need one delayed recurrence.
+ * Use to bound a repeating or retrying schedule by elapsed time.
  *
  * **Example** (Repeating work during a duration)
  *
@@ -2993,8 +3030,7 @@ export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
  *
  * **When to use**
  *
- * Use when the combined schedule should continue while at least one
- * schedule still recurs. Use `both` when both schedules must continue.
+ * Use when the combined schedule should continue while at least one schedule still recurs.
  *
  * **Example** (Combining schedules with either semantics)
  *
@@ -3062,7 +3098,7 @@ export const during = (duration: Duration.Input): Schedule<Duration.Duration> =>
  *
  * @see {@link both} for continuing only while both schedules still recur
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const either: {
@@ -3073,8 +3109,7 @@ export const either: {
    *
    * **When to use**
    *
-   * Use when the combined schedule should continue while at least one
-   * schedule still recurs. Use `both` when both schedules must continue.
+   * Use when the combined schedule should continue while at least one schedule still recurs.
    *
    * **Example** (Combining schedules with either semantics)
    *
@@ -3142,7 +3177,7 @@ export const either: {
    *
    * @see {@link both} for continuing only while both schedules still recur
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(
@@ -3155,8 +3190,7 @@ export const either: {
    *
    * **When to use**
    *
-   * Use when the combined schedule should continue while at least one
-   * schedule still recurs. Use `both` when both schedules must continue.
+   * Use when the combined schedule should continue while at least one schedule still recurs.
    *
    * **Example** (Combining schedules with either semantics)
    *
@@ -3224,7 +3258,7 @@ export const either: {
    *
    * @see {@link both} for continuing only while both schedules still recur
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -3242,6 +3276,11 @@ export const either: {
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
+ * **When to use**
+ *
+ * Use when either schedule may keep recurrence going and only the left
+ * schedule's output is needed.
+ *
  * **Example** (Combining either schedules and keeping the left output)
  *
  * ```ts
@@ -3269,7 +3308,7 @@ export const either: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export const eitherLeft: {
@@ -3278,6 +3317,11 @@ export const eitherLeft: {
    * to recur, using the minimum of the two durations between recurrences and
    * outputting the result of the left schedule (i.e. `self`).
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and only the left
+   * schedule's output is needed.
+   *
    * **Example** (Combining either schedules and keeping the left output)
    *
    * ```ts
@@ -3305,7 +3349,7 @@ export const eitherLeft: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 4.0.0
    */
   <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(
@@ -3316,6 +3360,11 @@ export const eitherLeft: {
    * to recur, using the minimum of the two durations between recurrences and
    * outputting the result of the left schedule (i.e. `self`).
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and only the left
+   * schedule's output is needed.
+   *
    * **Example** (Combining either schedules and keeping the left output)
    *
    * ```ts
@@ -3343,7 +3392,7 @@ export const eitherLeft: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 4.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -3360,6 +3409,11 @@ export const eitherLeft: {
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
+ * **When to use**
+ *
+ * Use when either schedule may keep recurrence going and only the right
+ * schedule's output is needed.
+ *
  * **Example** (Combining either schedules and keeping the right output)
  *
  * ```ts
@@ -3387,7 +3441,7 @@ export const eitherLeft: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 4.0.0
  */
 export const eitherRight: {
@@ -3396,6 +3450,11 @@ export const eitherRight: {
    * to recur, using the minimum of the two durations between recurrences and
    * outputting the result of the right schedule (i.e. `other`).
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and only the right
+   * schedule's output is needed.
+   *
    * **Example** (Combining either schedules and keeping the right output)
    *
    * ```ts
@@ -3423,7 +3482,7 @@ export const eitherRight: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 4.0.0
    */
   <Output2, Input2, Error2, Env2>(other: Schedule<Output2, Input2, Error2, Env2>): <Output, Input, Error, Env>(
@@ -3434,6 +3493,11 @@ export const eitherRight: {
    * to recur, using the minimum of the two durations between recurrences and
    * outputting the result of the right schedule (i.e. `other`).
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and only the right
+   * schedule's output is needed.
+   *
    * **Example** (Combining either schedules and keeping the right output)
    *
    * ```ts
@@ -3461,7 +3525,7 @@ export const eitherRight: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 4.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
@@ -3479,6 +3543,11 @@ export const eitherRight: {
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
+ * **When to use**
+ *
+ * Use when either schedule may keep recurrence going and their outputs should be
+ * combined into a custom value.
+ *
  * **Example** (Combining either schedule outputs)
  *
  * ```ts
@@ -3510,7 +3579,7 @@ export const eitherRight: {
  * })
  * ```
  *
- * @category utils
+ * @category combining
  * @since 2.0.0
  */
 export const eitherWith: {
@@ -3520,6 +3589,11 @@ export const eitherWith: {
    * outputting the result of the combination of both schedule outputs using the
    * specified `combine` function.
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and their outputs should be
+   * combined into a custom value.
+   *
    * **Example** (Combining either schedule outputs)
    *
    * ```ts
@@ -3551,7 +3625,7 @@ export const eitherWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output2, Input2, Error2, Env2, Output, Output3>(
@@ -3566,6 +3640,11 @@ export const eitherWith: {
    * outputting the result of the combination of both schedule outputs using the
    * specified `combine` function.
    *
+   * **When to use**
+   *
+   * Use when either schedule may keep recurrence going and their outputs should be
+   * combined into a custom value.
+   *
    * **Example** (Combining either schedule outputs)
    *
    * ```ts
@@ -3597,7 +3676,7 @@ export const eitherWith: {
    * })
    * ```
    *
-   * @category utils
+   * @category combining
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Output2, Input2, Error2, Env2, Output3>(
@@ -3629,6 +3708,11 @@ export const eitherWith: {
                * outputting the result of the combination of both schedule outputs using the
                * specified `combine` function.
                *
+               * **When to use**
+               *
+               * Use when either schedule may keep recurrence going and their outputs should be
+               * combined into a custom value.
+               *
                * **Example** (Combining either schedule outputs)
                *
                * ```ts
@@ -3660,7 +3744,7 @@ export const eitherWith: {
                * })
                * ```
                *
-               * @category utils
+               * @category combining
                * @since 2.0.0
                */
               [Output3, Duration.Duration]>([
@@ -3866,8 +3950,7 @@ export const fibonacci = (one: Duration.Input): Schedule<Duration.Duration> => {
  *
  * **When to use**
  *
- * Use when recurrences should stay aligned to a regular cadence. Use
- * `spaced` when each delay should start after the previous action completes.
+ * Use when recurrences should stay aligned to a regular cadence.
  *
  * **Gotchas**
  *
@@ -4200,7 +4283,7 @@ export const map: {
  * })
  * ```
  *
- * @category utils
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const modifyDelay: {
@@ -4234,7 +4317,7 @@ export const modifyDelay: {
    * })
    * ```
    *
-   * @category utils
+   * @category delays & timeouts
    * @since 2.0.0
    */
   <Output, Error2 = never, Env2 = never>(
@@ -4275,7 +4358,7 @@ export const modifyDelay: {
    * })
    * ```
    *
-   * @category utils
+   * @category delays & timeouts
    * @since 2.0.0
    */
   <Output, Input, Error, Env, Error2 = never, Env2 = never>(
@@ -4312,7 +4395,7 @@ export const modifyDelay: {
  *
  * @see {@link modifyDelay} for replacing recurrence delays with a custom effectful transformation
  *
- * @category utils
+ * @category delays & timeouts
  * @since 2.0.0
  */
 export const jittered = <Output, Input, Error, Env>(
@@ -4350,7 +4433,7 @@ export const jittered = <Output, Input, Error, Env>(
  * })
  * ```
  *
- * @category utils
+ * @category mapping
  * @since 2.0.0
  */
 export const passthrough = <Output, Input, Error, Env>(
@@ -4369,9 +4452,7 @@ export const passthrough = <Output, Input, Error, Env>(
  *
  * **When to use**
  *
- * Use when you need a counter schedule with no additional delay. Use `take`
- * to limit an existing schedule while preserving its output and delay
- * behavior.
+ * Use when you need a counter schedule with no additional delay.
  *
  * **Gotchas**
  *
@@ -4546,7 +4627,7 @@ export const recurs = (times: number): Schedule<number> =>
  * })
  * ```
  *
- * @category utils
+ * @category folding
  * @since 2.0.0
  */
 export const reduce: {
@@ -4659,7 +4740,7 @@ export const reduce: {
    * })
    * ```
    *
-   * @category utils
+   * @category folding
    * @since 2.0.0
    */
   <State, Output, Error2 = never, Env2 = never>(
@@ -4777,7 +4858,7 @@ export const reduce: {
    * })
    * ```
    *
-   * @category utils
+   * @category folding
    * @since 2.0.0
    */
   <Output, Input, Error, Env, State, Error2 = never, Env2 = never>(
@@ -4819,9 +4900,7 @@ export const reduce: {
  *
  * **When to use**
  *
- * Use when each delay should start after the previous action
- * completes. Use `fixed` when recurrences should stay aligned to a regular
- * cadence.
+ * Use when each delay should start after the previous action completes.
  *
  * **Example** (Repeating with fixed spacing)
  *
@@ -5673,9 +5752,7 @@ export const tapOutput: {
  *
  * **When to use**
  *
- * Use to limit an existing schedule while preserving its output and
- * delay behavior. Use `recurs` when you only need an immediate counter
- * schedule.
+ * Use to limit an existing schedule while preserving its output and delay behavior.
  *
  * **Gotchas**
  *
@@ -5758,7 +5835,7 @@ export const tapOutput: {
  *
  * @see {@link recurs} for creating a count-limited schedule
  *
- * @category utils
+ * @category taking
  * @since 4.0.0
  */
 export const take: {
@@ -5769,9 +5846,7 @@ export const take: {
    *
    * **When to use**
    *
-   * Use to limit an existing schedule while preserving its output and
-   * delay behavior. Use `recurs` when you only need an immediate counter
-   * schedule.
+   * Use to limit an existing schedule while preserving its output and delay behavior.
    *
    * **Gotchas**
    *
@@ -5854,7 +5929,7 @@ export const take: {
    *
    * @see {@link recurs} for creating a count-limited schedule
    *
-   * @category utils
+   * @category taking
    * @since 4.0.0
    */
   (n: number): <Output, Input, Error, Env>(
@@ -5867,9 +5942,7 @@ export const take: {
    *
    * **When to use**
    *
-   * Use to limit an existing schedule while preserving its output and
-   * delay behavior. Use `recurs` when you only need an immediate counter
-   * schedule.
+   * Use to limit an existing schedule while preserving its output and delay behavior.
    *
    * **Gotchas**
    *
@@ -5952,7 +6025,7 @@ export const take: {
    *
    * @see {@link recurs} for creating a count-limited schedule
    *
-   * @category utils
+   * @category taking
    * @since 4.0.0
    */
   <Output, Input, Error, Env>(self: Schedule<Output, Input, Error, Env>, n: number): Schedule<Output, Input, Error, Env>
@@ -6124,7 +6197,7 @@ export {
    * @see {@link collectWhile} for collecting outputs while using the same predicate
    * @see {@link take} for stopping after a fixed number of schedule outputs
    *
-   * @category utils
+   * @category filtering
    * @since 4.0.0
    */
   while_ as while
@@ -6242,13 +6315,8 @@ export {
  *
  * **When to use**
  *
- * Use to check an existing schedule input type. Use
- * `setInputType` to adapt a schedule that does not depend on its input values.
- *
- * **Details**
- *
- * This helper is checked at compile time and does not change the schedule's
- * runtime behavior.
+ * Use when you need a generic helper to prove that an existing schedule can
+ * consume a required input type without changing runtime behavior.
  *
  * **Example** (Constraining schedule input types)
  *
@@ -6282,8 +6350,7 @@ export const satisfiesInputType = <T>() =>
  *
  * **When to use**
  *
- * Use to adapt a schedule that does not depend on its input
- * values. Use `satisfiesInputType` to check an existing schedule input type.
+ * Use to adapt a schedule that does not depend on its input values.
  *
  * **Details**
  *