effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Schedule.js

@@ -1,33 +1,67 @@
 /**
- * This module provides utilities for creating and composing schedules for retrying operations,
- * repeating effects, and implementing various timing strategies.
+ * Declarative policies for retrying, repeating, and pacing Effect programs.
  *
- * A Schedule is a function that takes an input and returns a decision whether to continue or halt,
- * along with a delay duration. Schedules can be combined, transformed, and used to implement
- * sophisticated retry and repetition logic.
+ * A `Schedule<Output, Input, Error, Env>` is a stateful policy that is stepped
+ * with an input value. Each step either stops the recurrence or emits an output
+ * together with the delay before the next step. Schedules are values: they can
+ * be transformed, combined, and passed to retry, repeat, stream, and channel
+ * APIs without running anything until the surrounding Effect program runs.
  *
- * **Example** (Retrying and repeating effects)
+ * **Mental model**
+ *
+ * - Constructors such as {@link recurs}, {@link spaced}, {@link fixed},
+ *   {@link exponential}, and {@link fibonacci} define the base cadence or
+ *   stopping rule.
+ * - Combinators such as {@link both}, {@link either}, and {@link andThen}
+ *   combine schedules and determine both stopping behavior and output shape.
+ * - Delay helpers such as {@link addDelay}, {@link modifyDelay}, and
+ *   {@link jittered} adjust pacing while preserving the schedule's control
+ *   flow.
+ * - Metadata-aware constructors and {@link CurrentMetadata} expose attempts,
+ *   elapsed time, input, output, and duration for advanced policies.
+ *
+ * **Common tasks**
+ *
+ * - Retry a failing effect with exponential backoff and a maximum retry count.
+ * - Repeat a successful effect on a fixed or spaced interval.
+ * - Add jitter so concurrent clients do not retry at the same instant.
+ * - Transform or retain schedule outputs with {@link map},
+ *   {@link collectOutputs}, and {@link take}.
+ *
+ * **Example** (Retrying with bounded exponential backoff)
  *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
- * // Retry with exponential backoff
- * const retryPolicy = Schedule.exponential("100 millis", 2.0)
- *   .pipe(Schedule.both(Schedule.recurs(3)))
+ * let attempts = 0
  *
- * const program = Effect.gen(function*() {
- *   // This will retry up to 3 times with exponential backoff
- *   const result = yield* Effect.retry(
- *     Effect.fail("Network error"),
- *     retryPolicy
+ * const request = Effect.sync(() => {
+ *   attempts += 1
+ *   return attempts
+ * }).pipe(
+ *   Effect.flatMap((attempt) =>
+ *     attempt < 3 ? Effect.fail("temporary failure") : Effect.succeed("ok")
  *   )
- * })
+ * )
  *
- * // Repeat on a fixed schedule
- * const heartbeat = Effect.log("heartbeat")
- *   .pipe(Effect.repeat(Schedule.spaced("30 seconds")))
+ * const policy = Schedule.exponential("100 millis").pipe(
+ *   Schedule.jittered,
+ *   Schedule.both(Schedule.recurs(5))
+ * )
+ *
+ * const program = Effect.retry(request, policy)
  * ```
  *
+ * **Gotchas**
+ *
+ * - A schedule is a description; delays happen only when an operation such as
+ *   `Effect.retry` or `Effect.repeat` runs it.
+ * - `Schedule.recurs(3)` allows three recurrences in addition to the first run
+ *   performed by retry or repeat.
+ * - Combining schedules changes the output type as well as the stopping rule,
+ *   so check the resulting type when using {@link both}, {@link either}, or
+ *   {@link andThen}.
+ *
  * @since 2.0.0
  */
 import * as Cause from "./Cause.js";
@@ -54,7 +88,7 @@ const randomNext = /*#__PURE__*/random.Random.useSync(random => random.nextDoubl
  * input and output values, zero duration, and zeroed timing fields before any
  * schedule step has produced metadata.
  *
- * @category Metadata
+ * @category metadata
  * @since 4.0.0
  */
 export const CurrentMetadata = /*#__PURE__*/Context.Reference("effect/Schedule/CurrentMetadata", {
@@ -202,8 +236,22 @@ export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
  */
 export const toStep = schedule => effect.catchCause(schedule.step, cause => effect.succeed(() => effect.failCause(cause)));
 /**
- * Extracts a step function from a Schedule that provides metadata about each
- * execution. It will also handle sleeping for the computed delay.
+ * Extracts a step function from a `Schedule` that sleeps for each computed
+ * delay and returns metadata for the completed step.
+ *
+ * **When to use**
+ *
+ * Use to drive a schedule manually while preserving the computed output,
+ * delay, input, attempt, and elapsed timing metadata for each step.
+ *
+ * **Details**
+ *
+ * The returned step reads the current time from `Clock` when invoked, calls the
+ * schedule step with that timestamp and input, sleeps for the returned
+ * duration, and then yields `Metadata`.
+ *
+ * @see {@link toStep} for manually supplying the timestamp and handling the returned delay yourself
+ * @see {@link toStepWithSleep} for the same automatic sleeping behavior when only the schedule output is needed
  *
  * @category destructors
  * @since 4.0.0
@@ -253,7 +301,7 @@ export const toStepWithMetadata = schedule => effect.clockWith(clock => effect.m
 export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedule), step => input => effect.map(step(input), meta => meta.output));
 /**
  * Returns a new `Schedule` that adds the delay computed by the specified
- * effectful function to the the next recurrence of the schedule.
+ * effectful function to the next recurrence of the schedule.
  *
  * **Example** (Adding extra delay to a schedule)
  *
@@ -352,9 +400,8 @@ export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedul
  */
 export const addDelay = /*#__PURE__*/dual(2, (self, f) => modifyDelay(self, (output, delay) => effect.map(f(output), d => Duration.sum(Duration.fromInputUnsafe(d), Duration.fromInputUnsafe(delay)))));
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * merges their outputs.
  *
  * **Example** (Sequencing quick and slow retries)
  *
@@ -394,9 +441,8 @@ export const addDelay = /*#__PURE__*/dual(2, (self, f) => modifyDelay(self, (out
  */
 export const andThen = /*#__PURE__*/dual(2, (self, other) => map(andThenResult(self, other), result => effect.succeed(Result.merge(result))));
 /**
- * Returns a new `Schedule` that will first execute the left (i.e. `self`)
- * schedule to completion. Once the left schedule is complete, the right (i.e.
- * `other`) schedule will be executed to completion.
+ * Returns a schedule that runs `self` to completion, then runs `other`, and
+ * preserves which schedule produced each output.
  *
  * **Details**
  *
@@ -462,6 +508,12 @@ export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effe
  * to recur, using the maximum of the two durations between recurrences and
  * outputting a tuple of the outputs of both schedules.
  *
+ * **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.
+ *
  * **Example** (Combining time and attempt limits)
  *
  * ```ts
@@ -524,6 +576,8 @@ export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effe
  * // Compare with either which provides union semantics (OR logic)
  * ```
  *
+ * @see {@link either} for continuing while either schedule still recurs
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -937,7 +991,7 @@ export const cron = (expression, tz) => {
   })));
 };
 /**
- * Returns a new schedule that outputs the delay between each occurence.
+ * Returns a new schedule that outputs the delay between each occurrence.
  *
  * **Example** (Extracting schedule delays)
  *
@@ -963,7 +1017,7 @@ export const cron = (expression, tz) => {
  *   )
  * })
  *
- * // Monitor delays from a fibonacci schedule
+ * // Monitor delays from a Fibonacci schedule
  * const fibonacciDelays = Schedule.delays(
  *   Schedule.fibonacci("200 millis").pipe(Schedule.take(8))
  * )
@@ -1024,11 +1078,29 @@ export const delays = self => fromStep(effect.map(toStep(self), step => (now, in
 /**
  * Returns a schedule that recurs once after the specified duration.
  *
+ * **When to use**
+ *
+ * Use when you need one delayed recurrence. Use `during` to keep
+ * recurring until a duration has elapsed.
+ *
  * **Details**
  *
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
+ * **Example** (Recurring once after a duration)
+ *
+ * ```ts
+ * import { Console, Effect, Schedule } from "effect"
+ *
+ * const program = Effect.repeat(
+ *   Console.log("runs again after one second"),
+ *   Schedule.duration("1 second")
+ * )
+ * ```
+ *
+ * @see {@link during} for recurring until a duration has elapsed
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1040,6 +1112,11 @@ export const duration = durationInput => {
  * Returns a new `Schedule` that will always recur, but only during the
  * specified `duration` of time.
  *
+ * **When to use**
+ *
+ * Use to bound a repeating or retrying schedule by elapsed time. Use
+ * `duration` when you need one delayed recurrence.
+ *
  * **Example** (Repeating work during a duration)
  *
  * ```ts
@@ -1118,6 +1195,8 @@ export const duration = durationInput => {
  * )
  * ```
  *
+ * @see {@link duration} for one delayed recurrence
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1129,6 +1208,11 @@ export const during = duration => while_(elapsed, ({
  * to recur, using the minimum of the two durations between recurrences and
  * outputting a tuple of the outputs of both schedules.
  *
+ * **When to use**
+ *
+ * Use when the combined schedule should continue while at least one
+ * schedule still recurs. Use `both` when both schedules must continue.
+ *
  * **Example** (Combining schedules with either semantics)
  *
  * ```ts
@@ -1190,9 +1274,11 @@ export const during = duration => while_(elapsed, ({
  * })
  *
  * // Either provides union semantics (OR logic)
- * // Compare with intersect which provides intersection semantics (AND logic)
+ * // Compare with both, which provides intersection semantics (AND logic)
  * ```
  *
+ * @see {@link both} for continuing only while both schedules still recur
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -1315,7 +1401,8 @@ export const eitherWith = /*#__PURE__*/dual(3, (self, other, combine) => fromSte
   onDone: leftDone => stepRight(now, input).pipe(effect.map(rightResult => [combine(leftDone, rightResult[0]), rightResult[1]]), Pull.catchDone(rightDone => Cause.done(combine(leftDone, rightDone))))
 }))));
 /**
- * A schedule that always recurs and returns the total elapsed duration since the first recurrence.
+ * Schedule that always recurs and returns the total elapsed duration since the
+ * first recurrence.
  *
  * **Details**
  *
@@ -1346,7 +1433,7 @@ export const eitherWith = /*#__PURE__*/dual(3, (self, other, combine) => fromSte
  */
 export const elapsed = /*#__PURE__*/fromStepWithMetadata(/*#__PURE__*/effect.succeed(meta => effect.succeed([Duration.millis(meta.elapsed), Duration.zero])));
 /**
- * A schedule that always recurs, but will wait a certain amount between
+ * Schedule that always recurs, but will wait a certain amount between
  * repetitions, given by `base * factor.pow(n)`, where `n` is the number of
  * repetitions so far. Returns the current duration between recurrences.
  *
@@ -1402,22 +1489,22 @@ export const exponential = (base, factor = 2) => {
   }));
 };
 /**
- * A schedule that always recurs, increasing delays by summing the preceding
- * two delays (similar to the fibonacci sequence). Returns the current
+ * Schedule that always recurs, increasing delays by summing the preceding
+ * two delays (similar to the Fibonacci sequence). Returns the current
  * duration between recurrences.
  *
- * **Example** (Retrying with fibonacci backoff)
+ * **Example** (Retrying with Fibonacci backoff)
  *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Basic fibonacci schedule starting with 100ms
+ * // Basic Fibonacci schedule starting with 100ms
  * const fibSchedule = Schedule.fibonacci("100 millis")
  * // Delays: 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, 1300ms, ...
  *
- * // Retry with fibonacci backoff for gradual increase
+ * // Retry with Fibonacci backoff for gradual increase
  * const retryWithFib = Effect.gen(function*() {
  *   let attempt = 0
  *
@@ -1441,7 +1528,7 @@ export const exponential = (base, factor = 2) => {
  *   yield* Console.log(`Final result: ${result}`)
  * })
  *
- * // Heartbeat with fibonacci intervals (starts fast, gets slower)
+ * // Heartbeat with Fibonacci intervals (starts fast, gets slower)
  * const adaptiveHeartbeat = Effect.gen(function*() {
  *   yield* Console.log("Heartbeat")
  *   return "pulse"
@@ -1486,10 +1573,15 @@ export const fibonacci = one => {
  * Returns a `Schedule` that recurs on the specified fixed `interval` and
  * outputs the number of repetitions of the schedule so far.
  *
- * **Details**
+ * **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.
  *
- * If the action run between updates takes longer than the interval, then the
- * action will be run immediately, but re-runs will not "pile up".
+ * **Gotchas**
+ *
+ * If the action run between recurrences takes longer than the interval, the
+ * next recurrence happens immediately, but missed intervals are not replayed.
  *
  * ```text
  * |-----interval-----|-----interval-----|-----interval-----|
@@ -1501,7 +1593,7 @@ export const fibonacci = one => {
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
- * // Fixed interval schedule - runs exactly every 1 second
+ * // Fixed interval schedule - recurs on a one-second cadence
  * const everySecond = Schedule.fixed("1 second")
  *
  * // Health check that runs at fixed intervals
@@ -1544,6 +1636,8 @@ export const fibonacci = one => {
  * })
  * ```
  *
+ * @see {@link spaced} for delaying after each action completes
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1649,7 +1743,7 @@ export const map = /*#__PURE__*/dual(2, (self, f) => {
 });
 /**
  * Returns a new `Schedule` that modifies the delay of the next recurrence
- * of the schedule using the specified effectual function.
+ * of the schedule using the specified effectful function.
  *
  * **Example** (Modifying delays from schedule output)
  *
@@ -1684,9 +1778,16 @@ export const modifyDelay = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map
 /**
  * Returns a new `Schedule` that randomly adjusts each recurrence delay.
  *
+ * **When to use**
+ *
+ * Use to add random variation to an existing schedule's recurrence delays while
+ * preserving its output and completion behavior.
+ *
  * **Details**
  *
- * Delays are jittered between `80%` and `120%` of the original delay.
+ * Each recurrence delay is scaled by a random factor between `0.8` and `1.2`.
+ *
+ * @see {@link modifyDelay} for replacing recurrence delays with a custom effectful transformation
  *
  * @category utils
  * @since 2.0.0
@@ -1733,6 +1834,18 @@ export const passthrough = self => fromStep(effect.map(toStep(self), step => (no
  * Returns a `Schedule` which can only be stepped the specified number of
  * `times` before it terminates.
  *
+ * **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.
+ *
+ * **Gotchas**
+ *
+ * `recurs(n)` counts schedule recurrences, not the first evaluation of the
+ * effect being repeated or retried. For retrying, this means one initial
+ * attempt plus at most `n` retries.
+ *
  * **Example** (Limiting recurrences)
  *
  * ```ts
@@ -1766,11 +1879,11 @@ export const passthrough = self => fromStep(effect.map(toStep(self), step => (no
  *
  * // Combining recurs with other schedules for sophisticated retry logic
  * const complexRetry = Schedule.exponential("100 millis").pipe(
- *   Schedule.both(Schedule.recurs(3)) // At most 3 attempts
+ *   Schedule.both(Schedule.recurs(3)) // At most 3 retries
  * )
  *
- * // Repeat an effect exactly 10 times
- * const exactlyTenTimes = Effect.gen(function*() {
+ * // Allow ten recurrences after the initial run
+ * const tenRecurrences = Effect.gen(function*() {
  *   yield* Console.log("Executing task...")
  *   return "completed"
  * }).pipe(
@@ -1783,6 +1896,8 @@ export const passthrough = self => fromStep(effect.map(toStep(self), step => (no
  * )
  * ```
  *
+ * @see {@link take} for limiting an existing schedule
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1926,6 +2041,12 @@ export const reduce = /*#__PURE__*/dual(3, (self, initial, combine) => fromStep(
  * Returns a schedule that recurs continuously, each repetition spaced the
  * specified duration from the last run.
  *
+ * **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.
+ *
  * **Example** (Repeating with fixed spacing)
  *
  * ```ts
@@ -1969,6 +2090,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, initial, combine) => fromStep(
  * })
  * ```
  *
+ * @see {@link fixed} for recurrence aligned to a regular cadence
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1976,6 +2099,48 @@ export const spaced = duration => {
   const decoded = Duration.fromInputUnsafe(duration);
   return fromStepWithMetadata(effect.succeed(meta => effect.succeed([meta.attempt - 1, decoded])));
 };
+/**
+ * Returns a new `Schedule` that allows execution of an effectful function for
+ * every decision of the schedule, but does not alter the inputs and outputs of
+ * the schedule.
+ *
+ * **Details**
+ *
+ * The callback receives the full schedule metadata, including the input, output,
+ * computed delay duration, current attempt, and elapsed timing information.
+ *
+ * **Example** (Tapping schedule metadata)
+ *
+ * ```ts
+ * import { Console, Effect, Schedule } from "effect"
+ *
+ * const monitoredSchedule = Schedule.exponential("100 millis").pipe(
+ *   Schedule.take(5),
+ *   Schedule.tap((metadata) =>
+ *     Console.log(
+ *       `Attempt ${metadata.attempt} produced ${metadata.output} ` +
+ *         `after ${metadata.elapsed}ms; next delay is ${metadata.duration}`
+ *     )
+ *   )
+ * )
+ *
+ * const program = Effect.retry(
+ *   Effect.fail("transient error"),
+ *   monitoredSchedule
+ * )
+ * ```
+ *
+ * @category sequencing
+ * @since 4.0.0
+ */
+export const tap = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(self), step => {
+  const meta = metadataFn();
+  return (now, input) => effect.tap(step(now, input), ([output, duration]) => f({
+    ...meta(now, input),
+    output,
+    duration
+  }));
+})));
 /**
  * Returns a new `Schedule` that allows execution of an effectful function for
  * every input to the schedule, but does not alter the inputs and outputs of
@@ -2195,6 +2360,18 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  * from the schedule. Once the specified number of outputs is reached, the
  * schedule will stop.
  *
+ * **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.
+ *
+ * **Gotchas**
+ *
+ * `take(n)` limits schedule outputs. When used with repeat or retry, the
+ * effect is evaluated once before the schedule is stepped, so the total number
+ * of evaluations can be one greater than the number of outputs taken.
+ *
  * **Example** (Taking a limited number of recurrences)
  *
  * ```ts
@@ -2202,9 +2379,9 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Limit an infinite schedule to run only 5 times
+ * // Limit an infinite schedule to five recurrences
  * const limitedHeartbeat = Schedule.spaced("1 second").pipe(
- *   Schedule.take(5) // Will stop after 5 executions
+ *   Schedule.take(5) // Will stop after 5 schedule outputs
  * )
  *
  * const heartbeatProgram = Effect.gen(function*() {
@@ -2250,7 +2427,7 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  *
  * // Combine take with other schedule operations
  * const samplingSchedule = Schedule.fixed("500 millis").pipe(
- *   Schedule.take(10), // Sample exactly 10 times
+ *   Schedule.take(10), // Take at most 10 schedule outputs
  *   Schedule.map((count) => Effect.succeed(`Sample #${count + 1}`))
  * )
  *
@@ -2268,6 +2445,8 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  * })
  * ```
  *
+ * @see {@link recurs} for creating a count-limited schedule
+ *
  * @category utils
  * @since 4.0.0
  */
@@ -2392,20 +2571,28 @@ const while_ = /*#__PURE__*/dual(2, (self, predicate) => fromStep(effect.map(toS
 })));
 export {
 /**
- * Returns a new schedule that passes each input and output of the specified
- * schedule to the provided `predicate`.
+ * Returns a new schedule that continues while the predicate returns `true`.
+ *
+ * **When to use**
+ *
+ * Use to stop an existing schedule based on its full metadata, such as the
+ * current input, output, attempt, delay, or elapsed time.
  *
  * **Details**
  *
- * If the `predicate` returns `true`, the schedule will continue, otherwise
- * the schedule will stop.
+ * The predicate receives `Metadata`, may return `boolean` or an
+ * `Effect<boolean, ...>`, preserves the output and delay when it returns
+ * `true`, and stops the schedule when it returns `false`.
+ *
+ * @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
  * @since 4.0.0
  */
 while_ as while };
 /**
- * A schedule that divides the timeline to `interval`-long windows, and sleeps
+ * Schedule that divides the timeline to `interval`-long windows, and sleeps
  * until the nearest window boundary every time it recurs.
  *
  * **Details**
@@ -2482,75 +2669,123 @@ export {
 /**
  * Creates a schedule that always recurs, passing inputs directly as outputs.
  *
+ * **When to use**
+ *
+ * Use when you need an infinite schedule that preserves input values as
+ * outputs.
+ *
  * **Details**
  *
  * This schedule runs indefinitely, returning each input value as its output
  * without modification. It effectively acts as a pass-through that simply
  * echoes its input values at each step.
  *
+ * @see {@link forever} for an infinite schedule that returns incrementing step counts
  * @category constructors
  * @since 2.0.0
  */
 identity_ as identity };
 /**
- * Ensures that the provided schedule respects a specified input type.
+ * Ensures that a schedule's input type extends a given type `T`.
+ *
+ * **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.
  *
  * **Example** (Constraining schedule input types)
  *
  * ```ts
  * import { Schedule } from "effect"
  *
- * // Ensure schedule accepts string inputs
- * const stringSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesInputType<string>()
- * )
+ * declare const StringInputSchedule: Schedule.Schedule<number, string>
+ * declare const NumberInputSchedule: Schedule.Schedule<number, number>
  *
- * // Ensure schedule accepts number inputs
- * const numberSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesInputType<number>()
- * )
+ * const satisfiesStringInput = Schedule.satisfiesInputType<string>()
+ *
+ * // This works because the schedule input type is string.
+ * const validSchedule = satisfiesStringInput(StringInputSchedule)
  *
- * // Type-level constraint - this would be a compile error:
- * // Schedule.recurs(3).pipe(Schedule.satisfiesInputType<CustomType>())
- * // where CustomType doesn't match the schedule's input type
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesStringInput(NumberInputSchedule)
  * ```
  *
- * @category ensuring types
+ * @see {@link setInputType} for adapting an input-agnostic schedule
+ *
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesInputType = () => self => self;
 /**
- * Sets the input type of the provided schedule to a specified type, without
- * altering the schedule's behavior.
+ * Sets the input type of the provided schedule without altering its behavior.
+ *
+ * **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.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
+ *
+ * **Example** (Setting a schedule input type)
+ *
+ * ```ts
+ * import { Schedule } from "effect"
+ *
+ * const schedule = Schedule.recurs(3).pipe(
+ *   Schedule.setInputType<string>()
+ * )
+ * ```
  *
- * @category ensuring types
+ * @see {@link satisfiesInputType} for checking an existing input type
+ *
+ * @category utility types
  * @since 4.0.0
  */
 export const setInputType = () => self => self;
 /**
- * Ensures that the provided schedule respects a specified output type.
+ * Ensures that a schedule's output type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule output types)
  *
  * ```ts
- * import { Effect, Schedule } from "effect"
+ * import { Schedule } from "effect"
  *
- * // satisfiesOutputType is a type-level function for compile-time constraints
- * // It ensures that a schedule's output type matches the specified type
+ * declare const StringOutputSchedule: Schedule.Schedule<string>
+ * declare const NumberOutputSchedule: Schedule.Schedule<number>
  *
- * // Example with string output
- * const stringSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.map(() => Effect.succeed("hello")),
- *   Schedule.satisfiesOutputType<string>()
- * )
+ * const satisfiesStringOutput = Schedule.satisfiesOutputType<string>()
+ *
+ * // This works because the schedule output type is string.
+ * const validSchedule = satisfiesStringOutput(StringOutputSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesStringOutput(NumberOutputSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesOutputType = () => self => self;
 /**
- * Ensures that the provided schedule respects a specified error type.
+ * Ensures that a schedule's error type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule error types)
  *
@@ -2562,50 +2797,52 @@ export const satisfiesOutputType = () => self => self;
  *   message: string
  * }> {}
  *
- * // Ensure schedule handles CustomError types
- * const errorSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesErrorType<CustomError>()
- * )
+ * declare const CustomErrorSchedule: Schedule.Schedule<number, unknown, CustomError>
+ * declare const StringErrorSchedule: Schedule.Schedule<number, unknown, string>
  *
- * // Ensure schedule handles never errors (no errors)
- * const safeSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesErrorType<never>()
- * )
+ * const satisfiesCustomError = Schedule.satisfiesErrorType<CustomError>()
+ *
+ * // This works because the schedule error type is CustomError.
+ * const validSchedule = satisfiesCustomError(CustomErrorSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesCustomError(StringErrorSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesErrorType = () => self => self;
 /**
- * Ensures that the provided schedule respects a specified context type.
+ * Ensures that a schedule's context type extends a given type `T`.
+ *
+ * **Details**
+ *
+ * This helper is checked at compile time and does not change the schedule's
+ * runtime behavior.
  *
  * **Example** (Constraining schedule service types)
  *
  * ```ts
- * import { Effect, Schedule } from "effect"
+ * import { Schedule } from "effect"
  *
- * // Define service interfaces (type-level only)
  * interface Logger {
  *   readonly log: (message: string) => void
  * }
  *
- * interface Database {
- *   readonly query: (sql: string) => Effect.Effect<ReadonlyArray<unknown>>
- * }
+ * declare const LoggerSchedule: Schedule.Schedule<number, unknown, never, Logger>
+ * declare const NumberSchedule: Schedule.Schedule<number, unknown, never, number>
  *
- * // Ensure schedule requires Logger service
- * const loggerSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.satisfiesServicesType<Logger>()
- * )
+ * const satisfiesLogger = Schedule.satisfiesServicesType<Logger>()
  *
- * // Ensure schedule requires both Logger and Database services
- * const multiServiceSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.satisfiesServicesType<Logger | Database>()
- * )
+ * // This works because the schedule context type is Logger.
+ * const validSchedule = satisfiesLogger(LoggerSchedule)
+ *
+ * // This would cause a TypeScript compilation error:
+ * // const invalidSchedule = satisfiesLogger(NumberSchedule)
  * ```
  *
- * @category ensuring types
+ * @category utility types
  * @since 4.0.0
  */
 export const satisfiesServicesType = () => self => self;