effect 4.0.0-beta.101 → 4.0.0-beta.103

package/dist/Schedule.js

@@ -22,7 +22,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 services
  * @since 4.0.0
  */
 export const CurrentMetadata = /*#__PURE__*/Context.Reference("effect/Schedule/CurrentMetadata", {
@@ -52,16 +52,16 @@ const ScheduleProto = {
  *
  * **Example** (Checking for schedules)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schedule } from "effect"
  *
  * const schedule = Schedule.exponential("100 millis")
  * const notSchedule = { foo: "bar" }
  *
- * console.log(Schedule.isSchedule(schedule)) // true
- * console.log(Schedule.isSchedule(notSchedule)) // false
- * console.log(Schedule.isSchedule(null)) // false
- * console.log(Schedule.isSchedule(undefined)) // false
+ * Schedule.isSchedule(schedule) // => true
+ * Schedule.isSchedule(notSchedule) // => false
+ * Schedule.isSchedule(null) // => false
+ * Schedule.isSchedule(undefined) // => false
  * ```
  *
  * @category guards
@@ -73,7 +73,7 @@ export const isSchedule = u => hasProperty(u, TypeId);
  *
  * **Example** (Creating a custom schedule from a step function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Duration, Effect, Schedule } from "effect"
  *
  * const schedule = Schedule.fromStep(Effect.sync(() => {
@@ -86,6 +86,14 @@ export const isSchedule = u => hasProperty(u, TypeId);
  *     return Effect.succeed([count++, Duration.millis(100)] as [number, Duration.Duration])
  *   }
  * }))
+ *
+ * const program = Effect.gen(function*() {
+ *   const step = yield* Schedule.toStep(schedule)
+ *   const [output] = yield* step(0, "input")
+ *   return output
+ * })
+ *
+ * await Effect.runPromise(program) // => 0
  * ```
  *
  * @category constructors
@@ -120,7 +128,7 @@ const metadataFn = () => {
  *
  * **Example** (Creating a metadata-aware schedule)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cause, Duration, Effect, Schedule } from "effect"
  *
  * const firstThreeInputs = Schedule.fromStepWithMetadata(Effect.succeed((metadata: Schedule.InputMetadata<string>) => {
@@ -133,6 +141,14 @@ const metadataFn = () => {
  *     Duration.millis(250)
  *   ] as [string, Duration.Duration])
  * }))
+ *
+ * const program = Effect.gen(function*() {
+ *   const step = yield* Schedule.toStep(firstThreeInputs)
+ *   const [output] = yield* step(0, "input")
+ *   return output
+ * })
+ *
+ * await Effect.runPromise(program) // => "attempt 1: input"
  * ```
  *
  * @category constructors
@@ -147,8 +163,8 @@ export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
  *
  * **Example** (Extracting a schedule step function)
  *
- * ```ts
- * import { Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
  * // Extract step function from an existing schedule
  * const schedule = Schedule.exponential("100 millis").pipe(Schedule.upTo({ times: 3 }))
@@ -159,10 +175,10 @@ export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
  *   // Use the step function directly for custom logic. The timestamp is
  *   // supplied by the caller, so tests can pass a deterministic value.
  *   const now = 0
- *   const result = yield* stepFn(now, "input")
- *
- *   console.log(`Step result: ${result}`)
+ *   return yield* stepFn(now, "input")
  * })
+ *
+ * await Effect.runPromise(program) // => [Duration.millis(100), Duration.millis(100)]
  * ```
  *
  * @category destructors
@@ -207,26 +223,19 @@ export const toStepWithMetadata = schedule => effect.clockWith(clock => effect.m
  *
  * **Example** (Extracting a sleeping step function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Schedule } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * // Convert schedule to step function with automatic sleeping
- * const schedule = Schedule.spaced("1 second").pipe(Schedule.upTo({ times: 3 }))
+ * const schedule = Schedule.recurs(3)
  *
  * const program = Effect.gen(function*() {
  *   const stepWithSleep = yield* Schedule.toStepWithSleep(schedule)
  *
- *   // Each call will automatically sleep for the scheduled delay
- *   console.log("Starting...")
- *   const result1 = yield* stepWithSleep("first")
- *   console.log(`First result: ${result1}`)
- *
- *   const result2 = yield* stepWithSleep("second")
- *   console.log(`Second result: ${result2}`)
- *
- *   const result3 = yield* stepWithSleep("third")
- *   console.log(`Third result: ${result3}`)
+ *   return [yield* stepWithSleep("first"), yield* stepWithSleep("second")]
  * })
+ *
+ * await Effect.runPromise(Effect.provide(program, TestClock.layer())) // => [0, 1]
  * ```
  *
  * @category destructors
@@ -239,94 +248,19 @@ export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedul
  *
  * **Example** (Adding extra delay to a schedule)
  *
- * ```ts
- * import { Console, Data, Duration, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * // Add a deterministic extra delay based on the schedule metadata
- * const delayedSchedule = Schedule.addDelay(
- *   Schedule.exponential("100 millis").pipe(Schedule.upTo({ times: 5 })),
- *   ({ output }) =>
- *     Effect.succeed(Duration.millis(Duration.toMillis(output) * 0.25))
+ * const schedule = Schedule.recurs(1).pipe(
+ *   Schedule.addDelay(() => Effect.succeed("25 millis"))
  * )
- *
- * const repeatProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.succeed("delayed task"),
- *     delayedSchedule.pipe(
- *       Schedule.tap(({ output: delay }) =>
- *         Console.log(`Base delay: ${delay}`)
- *       )
- *     )
- *   )
- * })
- *
- * // Add adaptive delay based on execution count
- * const adaptiveSchedule = Schedule.addDelay(
- *   Schedule.recurs(6),
- *   ({ output: executionCount }) =>
- *     // Increase delay as execution count grows
- *     Effect.succeed(Duration.millis(executionCount * 200))
- * )
- *
- * const adaptiveProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Adaptive delay task")
- *       return "adaptive"
- *     }),
- *     adaptiveSchedule.pipe(
- *       Schedule.tap(({ output: count }) =>
- *         Console.log(`Execution ${count + 1} with adaptive delay`)
- *       )
- *     )
- *   )
- * })
- *
- * // Add effectful delay computation from deterministic service data
- * const loadByExecution = [1, 3, 2, 4] as const
- *
- * const dynamicSchedule = Schedule.addDelay(
- *   Schedule.spaced("1 second").pipe(Schedule.upTo({ times: 4 })),
- *   ({ output: executionNumber }) => {
- *     const load = loadByExecution[executionNumber] ?? 1
- *     return Effect.succeed(Duration.millis(load * 100))
- *   }
- * )
- *
- * const dynamicProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Dynamic delay task")
- *       return "dynamic"
- *     }),
- *     dynamicSchedule
- *   )
+ * const program = Effect.gen(function*() {
+ *   const step = yield* Schedule.toStep(schedule)
+ *   const [, delay] = yield* step(0, undefined)
+ *   return delay
  * })
  *
- * // Combine with retry for progressive backoff
- * const progressiveRetrySchedule = Schedule.addDelay(
- *   Schedule.exponential("50 millis").pipe(Schedule.upTo({ times: 4 })),
- *   () => Effect.succeed(Duration.millis(100)) // Fixed additional delay
- * )
- *
- * const retryProgram = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       if (attempt < 5) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *       return `Success on attempt ${attempt}`
- *     }),
- *     progressiveRetrySchedule
- *   )
- *
- *   yield* Console.log(`Final result: ${result}`)
- * })
+ * await Effect.runPromise(program) // => Duration.millis(25)
  * ```
  *
  * @category delays & timeouts
@@ -339,35 +273,11 @@ export const addDelay = /*#__PURE__*/dual(2, (self, f) => modifyDelay(self, meta
  *
  * **Example** (Sequencing quick and slow retries)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * // First retry 3 times quickly, then switch to slower retries
- * const quickRetries = Schedule.exponential("100 millis").pipe(
- *   Schedule.upTo({ times: 3 })
- * )
- * const slowRetries = Schedule.exponential("1 second").pipe(
- *   Schedule.upTo({ times: 2 })
- * )
- *
- * const combinedRetries = Schedule.andThen(quickRetries, slowRetries)
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   let attempt = 0
- *   yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Attempt ${attempt}`)
- *       if (attempt < 6) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Failure ${attempt}` }))
- *       }
- *       return `Success on attempt ${attempt}`
- *     }),
- *     combinedRetries
- *   )
- * })
+ * const schedule = Schedule.andThen(Schedule.recurs(1), Schedule.recurs(2))
+ * Schedule.isSchedule(schedule) // => true
  * ```
  *
  * @category sequencing
@@ -388,31 +298,11 @@ export const andThen = /*#__PURE__*/dual(2, (self, other) => map(andThenResult(s
  *
  * **Example** (Tracking sequential schedule phases)
  *
- * ```ts
- * import { Console, Effect, Result, Schedule } from "effect"
- *
- * // Track which phase of the schedule we're in
- * const phaseTracker = Schedule.andThenResult(
- *   Schedule.exponential("100 millis").pipe(Schedule.upTo({ times: 2 })),
- *   Schedule.spaced("500 millis").pipe(Schedule.upTo({ times: 2 }))
- * )
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Task executed")
- *       return "task-result"
- *     }),
- *     phaseTracker.pipe(
- *       Schedule.tap(({ output: result }) =>
- *         Result.match(result, {
- *           onFailure: (phase1Output) => Console.log(`Phase 1: ${phase1Output}`),
- *           onSuccess: (phase2Output) => Console.log(`Phase 2: ${phase2Output}`)
- *         })
- *       )
- *     )
- *   )
- * })
+ * const schedule = Schedule.andThenResult(Schedule.recurs(1), Schedule.recurs(2))
+ * Schedule.isSchedule(schedule) // => true
  * ```
  *
  * @category sequencing
@@ -454,36 +344,11 @@ export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effe
  *
  * **Example** (Combining retry schedules by their maximum delay)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * const retrySchedule = Schedule.max([
- *   Schedule.fixed("5 seconds"),
- *   Schedule.exponential("5 seconds"),
- *   Schedule.spaced("10 seconds")
- * ])
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Retry attempt ${attempt}`)
- *       if (attempt < 3) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *       return "success"
- *     }),
- *     retrySchedule.pipe(
- *       Schedule.tap(({ output: duration }) =>
- *         Console.log(`Waiting for the slowest schedule: ${duration}`)
- *       )
- *     )
- *   )
- * })
+ * const schedule = Schedule.max([Schedule.fixed("5 seconds"), Schedule.spaced("10 seconds")])
+ * Schedule.isSchedule(schedule) // => true
  * ```
  *
  * @category combining
@@ -514,126 +379,11 @@ const maxDuration = results => {
  *
  * **Example** (Scheduling work with cron expressions)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class ScheduledTaskError extends Data.TaggedError("ScheduledTaskError")<{ readonly message: string }> {}
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * // Run every minute
  * const everyMinute = Schedule.cron("* * * * *")
- *
- * const minutelyProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Running minutely task")
- *       return "minute"
- *     }),
- *     everyMinute.pipe(
- *       Schedule.upTo({ times: 3 }), // Run only 3 times for demo
- *       Schedule.tap(({ output: duration }) =>
- *         Console.log(`Next execution in: ${duration}`)
- *       )
- *     )
- *   )
- * })
- *
- * // Run every day at 2:30 AM
- * const dailyBackup = Schedule.cron("30 2 * * *")
- *
- * const backupProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Running daily backup...")
- *       // Simulate backup process
- *       yield* Effect.sleep("2 seconds")
- *       yield* Console.log("Backup completed")
- *       return "backup-done"
- *     }),
- *     dailyBackup.pipe(
- *       Schedule.upTo({ times: 2 }) // Run 2 times for demo
- *     )
- *   )
- * })
- *
- * // Run every Monday at 9:00 AM with timezone
- * const weeklyReport = Schedule.cron("0 9 * * 1", "America/New_York")
- *
- * const reportProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Generating weekly report...")
- *       const report = {
- *         week: 42,
- *         status: "ready" as const
- *       }
- *       yield* Console.log(`Report generated: ${JSON.stringify(report)}`)
- *       return report
- *     }),
- *     weeklyReport.pipe(Schedule.upTo({ times: 1 }))
- *   )
- * })
- *
- * // Run every 15 minutes during business hours (9 AM - 5 PM)
- * const businessHoursCheck = Schedule.cron("0,15,30,45 9-17 * * 1-5")
- *
- * const businessProgram = Effect.gen(function*() {
- *   const statuses = ["healthy", "healthy", "degraded", "healthy"] as const
- *   let index = 0
- *
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Business hours health check...")
- *       const status = statuses[index++]
- *       yield* Console.log(`System status: ${status}`)
- *       return status
- *     }),
- *     businessHoursCheck.pipe(
- *       Schedule.upTo({ times: 4 }) // Demo with 4 checks
- *     )
- *   )
- * })
- *
- * // Run on specific days of the month
- * const monthlyInvoice = Schedule.cron("0 10 1,15 * *") // 1st and 15th at 10 AM
- *
- * const invoiceProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Processing monthly invoices...")
- *       const invoiceCount = 72
- *       yield* Console.log(`Processed ${invoiceCount} invoices`)
- *       return { count: invoiceCount, batch: "2024-01-a" }
- *     }),
- *     monthlyInvoice.pipe(Schedule.upTo({ times: 1 }))
- *   )
- * })
- *
- * // Complex cron with error handling
- * const complexCron = Schedule.cron("0 2,4,6 * * *").pipe(
- *   Schedule.tap(({ output: duration }) =>
- *     Console.log(`Scheduled to run again in ${duration}`)
- *   )
- * )
- *
- * const robustProgram = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log("Complex scheduled task...")
- *       if (attempt === 1) {
- *         return yield* Effect.fail(new ScheduledTaskError({ message: "Scheduled task failed" }))
- *       }
- *       return "success"
- *     }),
- *     complexCron.pipe(Schedule.upTo({ times: 3 }))
- *   ).pipe(
- *     Effect.catch((error: unknown) =>
- *       Console.log(`Cron task error: ${String(error)}`)
- *     )
- *   )
- * })
+ * Schedule.isSchedule(everyMinute) // => true
  * ```
  *
  * @category constructors
@@ -666,13 +416,10 @@ export const cron = (expression, tz) => {
  *
  * **Example** (Recurring once after a duration)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * const program = Effect.repeat(
- *   Console.log("runs again after one second"),
- *   Schedule.duration("1 second")
- * )
+ * Schedule.isSchedule(Schedule.duration("1 second")) // => true
  * ```
  *
  * @see {@link during} for recurring until a duration has elapsed
@@ -694,82 +441,10 @@ export const duration = durationInput => {
  *
  * **Example** (Repeating work during a duration)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * // Run a task for exactly 5 seconds, regardless of how many iterations
- * const fiveSecondSchedule = Schedule.during("5 seconds")
- *
- * const timedProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Task executed inside the time window")
- *       yield* Effect.sleep("500 millis") // Each task takes 500ms
- *       return "task done"
- *     }),
- *     fiveSecondSchedule.pipe(
- *       Schedule.tap(({ output: elapsedDuration }) =>
- *         Console.log(`Total elapsed: ${elapsedDuration}`)
- *       )
- *     )
- *   )
- *
- *   yield* Console.log("Time limit reached!")
- * })
- *
- * // Combine with other schedules for time-bounded execution
- * const timeAndCountLimited = Schedule.max([
- *   Schedule.spaced("1 second"),
- *   Schedule.during("10 seconds"), // Stop after 10 seconds OR
- *   Schedule.recurs(15) // 15 attempts, whichever comes first
- * ])
- *
- * // Burst execution within time window
- * const burstWindow = Schedule.during("3 seconds")
- *
- * const burstProgram = Effect.gen(function*() {
- *   yield* Console.log("Starting burst execution...")
- *
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Burst task")
- *       return "burst"
- *     }),
- *     burstWindow
- *   )
- *
- *   yield* Console.log("Burst window completed")
- * })
- *
- * // Timed retry window - retry for up to 30 seconds
- * const timedRetry = Schedule.max([
- *   Schedule.exponential("200 millis"),
- *   Schedule.during("30 seconds")
- * ])
- *
- * const retryProgram = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Retry attempt ${attempt}`)
- *
- *       if (attempt < 4) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *
- *       return `Success on attempt ${attempt}`
- *     }),
- *     timedRetry
- *   )
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- *   yield* Console.log(`Result: ${result}`)
- * }).pipe(
- *   Effect.catch((error: unknown) => Console.log(`Timed out: ${String(error)}`))
- * )
+ * Schedule.isSchedule(Schedule.during("5 seconds")) // => true
  * ```
  *
  * @see {@link duration} for one delayed recurrence
@@ -781,7 +456,7 @@ export const during = duration => {
   const durationMillis = Duration.toMillis(duration);
   return fromStepWithMetadata(effect.succeed(meta => {
     const elapsed = Duration.millis(meta.elapsed);
-    return meta.elapsed > durationMillis ? effect.succeed([elapsed, Duration.zero]) : Cause.done(elapsed);
+    return meta.elapsed > durationMillis ? Cause.done(elapsed) : effect.succeed([elapsed, Duration.zero]);
   }));
 };
 /**
@@ -795,36 +470,11 @@ export const during = duration => {
  *
  * **Example** (Combining retry schedules by their minimum delay)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * const retrySchedule = Schedule.min([
- *   Schedule.fixed("5 seconds"),
- *   Schedule.exponential("5 seconds"),
- *   Schedule.spaced("10 seconds")
- * ])
+ * ```ts import.meta.vitest
+ * import { Schedule } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Retry attempt ${attempt}`)
- *       if (attempt < 3) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *       return "success"
- *     }),
- *     retrySchedule.pipe(
- *       Schedule.tap(({ output: duration }) =>
- *         Console.log(`Waiting for the fastest schedule: ${duration}`)
- *       )
- *     )
- *   )
- * })
+ * const schedule = Schedule.min([Schedule.fixed("5 seconds"), Schedule.spaced("10 seconds")])
+ * Schedule.isSchedule(schedule) // => true
  * ```
  *
  * @category combining
@@ -858,44 +508,15 @@ const minDuration = results => {
  *
  * **Example** (Retrying with exponential backoff)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryFailure extends Data.TaggedError("RetryFailure")<{ readonly message: string }> {}
- *
- * // Basic exponential backoff with default factor of 2
- * const basicExponential = Schedule.exponential("100 millis")
- * // Delays: 100ms, 200ms, 400ms, 800ms, 1600ms, ...
- *
- * // Custom exponential backoff with factor 1.5
- * const gentleExponential = Schedule.exponential("200 millis", 1.5)
- * // Delays: 200ms, 300ms, 450ms, 675ms, 1012ms, ...
- *
- * // Retry with exponential backoff (limited to 5 attempts)
- * const retryPolicy = Schedule.max([
- *   Schedule.exponential("50 millis"),
- *   Schedule.recurs(5)
- * ])
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       if (attempt < 4) {
- *         yield* Console.log(`Attempt ${attempt} failed, retrying...`)
- *         return yield* Effect.fail(new RetryFailure({ message: `Failure ${attempt}` }))
- *       }
- *       return `Success on attempt ${attempt}`
- *     }),
- *     retryPolicy
- *   )
- *
- *   yield* Console.log(`Final result: ${result}`)
+ *   const step = yield* Schedule.toStep(Schedule.exponential("100 millis"))
+ *   return yield* step(0, undefined)
  * })
  *
- * // Will retry with delays: 50ms, 100ms, 200ms before success
+ * await Effect.runPromise(program) // => [Duration.millis(100), Duration.millis(100)]
  * ```
  *
  * @category constructors
@@ -915,63 +536,15 @@ export const exponential = (base, factor = 2) => {
  *
  * **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
- * const fibSchedule = Schedule.fibonacci("100 millis")
- * // Delays: 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, 1300ms, ...
- *
- * // Retry with Fibonacci backoff for gradual increase
- * const retryWithFib = Effect.gen(function*() {
- *   let attempt = 0
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Attempt ${attempt}`)
- *
- *       if (attempt < 5) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *
- *       return `Success on attempt ${attempt}`
- *     }),
- *     Schedule.max([
- *       Schedule.fibonacci("50 millis"),
- *       Schedule.recurs(6) // Maximum 6 retries
- *     ]).pipe(
- *       Schedule.tap(({ output: delay }) => Console.log(`Next retry in ${delay}`))
- *     )
- *   )
- *
- *   yield* Console.log(`Final result: ${result}`)
+ * const program = Effect.gen(function*() {
+ *   const step = yield* Schedule.toStep(Schedule.fibonacci("100 millis"))
+ *   return yield* step(0, undefined)
  * })
  *
- * // Heartbeat with Fibonacci intervals (starts fast, gets slower)
- * const adaptiveHeartbeat = Effect.gen(function*() {
- *   yield* Console.log("Heartbeat")
- *   return "pulse"
- * }).pipe(
- *   Effect.repeat(
- *     Schedule.fibonacci("200 millis").pipe(
- *       Schedule.upTo({ times: 8 }) // First 8 heartbeats
- *     )
- *   )
- * )
- *
- * // Fibonacci vs exponential comparison
- * const compareSchedules = Effect.gen(function*() {
- *   yield* Console.log("=== Fibonacci Delays ===")
- *   // 100ms, 100ms, 200ms, 300ms, 500ms, 800ms
- *
- *   yield* Console.log("=== Exponential Delays ===")
- *   // 100ms, 200ms, 400ms, 800ms, 1600ms, 3200ms
- *
- *   // Fibonacci grows more slowly than exponential
- * })
+ * await Effect.runPromise(program) // => [Duration.millis(100), Duration.millis(100)]
  * ```
  *
  * @category constructors
@@ -1011,50 +584,15 @@ export const fibonacci = one => {
  *
  * **Example** (Repeating on fixed intervals)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
- *
- * // Fixed interval schedule - recurs on a one-second cadence
- * const everySecond = Schedule.fixed("1 second")
- *
- * // Health check that runs at fixed intervals
- * const healthCheck = Effect.gen(function*() {
- *   yield* Console.log("Health check")
- *   yield* Effect.sleep("200 millis") // simulate health check work
- *   return "healthy"
- * }).pipe(
- *   Effect.repeat(Schedule.fixed("2 seconds").pipe(Schedule.upTo({ times: 5 })))
- * )
- *
- * // Difference between fixed and spaced:
- * // - fixed: maintains constant rate regardless of action duration
- * // - spaced: waits for the duration AFTER each action completes
- *
- * const longRunningTask = Effect.gen(function*() {
- *   yield* Console.log("Task started")
- *   yield* Effect.sleep("1.5 seconds") // Longer than interval
- *   yield* Console.log("Task completed")
- *   return "done"
- * })
- *
- * // Fixed schedule: if task takes 1.5s but interval is 1s,
- * // next execution happens immediately (no pile-up)
- * const fixedSchedule = longRunningTask.pipe(
- *   Effect.repeat(Schedule.fixed("1 second").pipe(Schedule.upTo({ times: 3 })))
- * )
- *
- * // Comparing with spaced (waits 1s AFTER each task)
- * const spacedSchedule = longRunningTask.pipe(
- *   Effect.repeat(Schedule.spaced("1 second").pipe(Schedule.upTo({ times: 3 })))
- * )
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   yield* Console.log("=== Fixed Schedule Demo ===")
- *   yield* fixedSchedule
- *
- *   yield* Console.log("=== Spaced Schedule Demo ===")
- *   yield* spacedSchedule
+ *   const step = yield* Schedule.toStep(Schedule.fixed("1 second"))
+ *   return yield* step(0, undefined)
  * })
+ *
+ * await Effect.runPromise(program) // => [0, Duration.seconds(1)]
  * ```
  *
  * @see {@link spaced} for delaying after each action completes
@@ -1096,59 +634,19 @@ export const fixed = interval => {
  *
  * **Example** (Mapping schedule outputs)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
  *
- * // Transform schedule output from number to string
  * const countSchedule = Schedule.recurs(5).pipe(
  *   Schedule.map(({ output: count }) => Effect.succeed(`Execution #${count + 1}`))
  * )
- *
- * // Map schedule delays to human-readable format
- * const readableDelays = Schedule.exponential("100 millis").pipe(
- *   Schedule.map(({ output: delay }) => Effect.succeed(`Next retry in ${delay}`))
- * )
- *
- * // Transform numeric output to structured data
- * const structuredSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.map(({ output: recurrence }) => Effect.succeed({
- *     iteration: recurrence + 1,
- *     phase: recurrence < 5 ? "warmup" as const : "steady" as const
- *   }))
- * )
- *
  * const program = Effect.gen(function*() {
- *   const results = yield* Effect.repeat(
- *     Effect.succeed("task completed"),
- *     structuredSchedule.pipe(
- *       Schedule.upTo({ times: 8 }),
- *       Schedule.tap(({ output: info }) =>
- *         Console.log(
- *           `${info.phase} phase - iteration ${info.iteration}`
- *         )
- *       )
- *     )
- *   )
- *
- *   yield* Console.log(`Completed iterations`)
+ *   const step = yield* Schedule.toStep(countSchedule)
+ *   const [output] = yield* step(0, undefined)
+ *   return output
  * })
  *
- * // Map with effectful transformation
- * const effectfulMap = Schedule.fixed("2 seconds").pipe(
- *   Schedule.map(({ output: count }) =>
- *     Effect.gen(function*() {
- *       yield* Console.log(`Processing count: ${count}`)
- *       return count * 10
- *     })
- *   )
- * )
- *
- * // Use timing metadata in the mapped output
- * const complexSchedule = Schedule.fibonacci("100 millis").pipe(
- *   Schedule.map(({ output: delay, attempt }) =>
- *     Effect.succeed(`Attempt ${attempt} delay: ${delay}`)
- *   )
- * )
+ * await Effect.runPromise(program) // => "Execution #1"
  * ```
  *
  * @category mapping
@@ -1184,28 +682,19 @@ export const map = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(
  *
  * **Example** (Modifying delays from schedule metadata)
  *
- * ```ts
- * import { Console, Duration, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
- * // Modify delays based on output - increase delay on high iteration counts
- * const adaptiveDelay = Schedule.recurs(10).pipe(
- *   Schedule.modifyDelay(({ output, duration }) => {
- *     // Double the delay if we're seeing high iteration counts
- *     return Effect.succeed(output > 5 ? Duration.times(duration, 2) : duration)
- *   })
+ * const schedule = Schedule.spaced("10 millis").pipe(
+ *   Schedule.modifyDelay(({ duration }) => Effect.succeed(Duration.times(duration, 2)))
  * )
- *
  * const program = Effect.gen(function*() {
- *   let counter = 0
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       counter++
- *       yield* Console.log(`Attempt ${counter}`)
- *       return counter
- *     }),
- *     adaptiveDelay.pipe(Schedule.upTo({ times: 8 }))
- *   )
+ *   const step = yield* Schedule.toStep(schedule)
+ *   const [, delay] = yield* step(0, undefined)
+ *   return delay
  * })
+ *
+ * await Effect.runPromise(program) // => Duration.millis(20)
  * ```
  *
  * @category delays & timeouts
@@ -1247,25 +736,19 @@ export const jittered = self => modifyDelay(self, ({
  *
  * **Example** (Passing inputs through as outputs)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
  *
- * // Create a schedule that outputs the inputs instead of original outputs
  * const inputSchedule = Schedule.passthrough(
  *   Schedule.exponential("100 millis").pipe(Schedule.upTo({ times: 3 }))
  * )
- *
  * const program = Effect.gen(function*() {
- *   let counter = 0
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       counter++
- *       yield* Console.log(`Task ${counter} executed`)
- *       return `result-${counter}`
- *     }),
- *     inputSchedule
- *   )
+ *   const step = yield* Schedule.toStep(inputSchedule)
+ *   const [output] = yield* step(0, "input")
+ *   return output
  * })
+ *
+ * await Effect.runPromise(program) // => "input"
  * ```
  *
  * @category mapping
@@ -1292,53 +775,17 @@ export const passthrough = self => fromStep(effect.map(toStep(self), step => (no
  *
  * **Example** (Limiting recurrences)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * // Basic recurs - retry at most 3 times
- * const maxThreeAttempts = Schedule.recurs(3)
- *
- * // Retry a failing operation at most 5 times
- * const program = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Attempt ${attempt}`)
- *
- *       if (attempt < 4) {
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *
- *       return `Success on attempt ${attempt}`
- *     }),
- *     Schedule.recurs(5) // Will retry up to 5 times
- *   )
- *
- *   yield* Console.log(`Final result: ${result}`)
- * })
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * // Combining recurs with other schedules for sophisticated retry logic
- * const complexRetry = Schedule.max([
- *   Schedule.exponential("100 millis"),
- *   Schedule.recurs(3) // At most 3 retries
- * ])
- *
- * // Allow ten recurrences after the initial run
- * const tenRecurrences = Effect.gen(function*() {
- *   yield* Console.log("Executing task...")
- *   return "completed"
- * }).pipe(
- *   Effect.repeat(Schedule.recurs(10))
+ * const executions: Array<number> = []
+ * const program = Effect.sync(() => executions.push(executions.length + 1)).pipe(
+ *   Effect.repeat(Schedule.recurs(3)),
+ *   Effect.as(executions)
  * )
  *
- * // The schedule outputs the current recurrence count (0-based)
- * const countingSchedule = Schedule.recurs(3).pipe(
- *   Schedule.tap(({ output: count }) => Console.log(`Execution #${count + 1}`))
- * )
+ * await Effect.runPromise(Effect.provide(program, TestClock.layer())) // => [1, 2, 3, 4]
  * ```
  *
  * @see {@link upTo} for limiting an existing schedule
@@ -1359,46 +806,15 @@ export const recurs = times => while_(forever, ({
  *
  * **Example** (Repeating with fixed spacing)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
- *
- * // Basic spaced schedule - runs every 2 seconds
- * const everyTwoSeconds = Schedule.spaced("2 seconds")
- *
- * // Heartbeat that runs indefinitely with fixed spacing
- * const heartbeat = Effect.gen(function*() {
- *   yield* Console.log("Heartbeat")
- * }).pipe(
- *   Effect.repeat(everyTwoSeconds)
- * )
- *
- * // Limited repeat - run only 5 times with 1-second spacing
- * const limitedTask = Effect.gen(function*() {
- *   yield* Console.log("Executing scheduled task...")
- *   yield* Effect.sleep("500 millis") // simulate work
- *   return "Task completed"
- * }).pipe(
- *   Effect.repeat(
- *     Schedule.spaced("1 second").pipe(Schedule.upTo({ times: 5 }))
- *   )
- * )
- *
- * // Simple spaced schedule with limited repetitions
- * const limitedSpaced = Schedule.max([
- *   Schedule.spaced("100 millis"),
- *   Schedule.recurs(5) // at most 5 times
- * ])
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   yield* Console.log("Starting spaced execution...")
- *
- *   yield* Effect.repeat(
- *     Effect.succeed("work item"),
- *     limitedSpaced
- *   )
- *
- *   yield* Console.log("Completed executions")
+ *   const step = yield* Schedule.toStep(Schedule.spaced("2 seconds"))
+ *   return yield* step(0, undefined)
  * })
+ *
+ * await Effect.runPromise(program) // => [0, Duration.seconds(2)]
  * ```
  *
  * @see {@link fixed} for recurrence aligned to a regular cadence
@@ -1422,23 +838,20 @@ export const spaced = duration => {
  *
  * **Example** (Tapping schedule metadata)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
- *
- * const monitoredSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.upTo({ times: 5 }),
- *   Schedule.tap((metadata) =>
- *     Console.log(
- *       `Attempt ${metadata.attempt} produced ${metadata.output} ` +
- *         `after ${metadata.elapsed}ms; next delay is ${metadata.duration}`
- *     )
- *   )
- * )
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
  *
- * const program = Effect.retry(
- *   Effect.fail("transient error"),
- *   monitoredSchedule
+ * const attempts: Array<number> = []
+ * const monitoredSchedule = Schedule.recurs(2).pipe(
+ *   Schedule.tap((metadata) => Effect.sync(() => attempts.push(metadata.attempt)))
  * )
+ * const program = Effect.gen(function*() {
+ *   const step = yield* Schedule.toStep(monitoredSchedule)
+ *   const [output] = yield* step(0, undefined)
+ *   return { attempts, output }
+ * })
+ *
+ * await Effect.runPromise(program) // => { attempts: [1], output: 0 }
  * ```
  *
  * @category sequencing
@@ -1475,64 +888,18 @@ export const tap = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(
  *
  * **Example** (Limiting by duration and recurrence count)
  *
- * ```ts
- * import { Console, Data, Effect, Schedule } from "effect"
- *
- * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
- *
- * // Limit an infinite schedule to five recurrences
- * const limitedHeartbeat = Schedule.spaced("1 second").pipe(
- *   Schedule.upTo({ times: 5 })
- * )
- *
- * const heartbeatProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Heartbeat")
- *       return "pulse"
- *     }),
- *     limitedHeartbeat
- *   )
- *
- *   yield* Console.log("Heartbeat sequence completed")
- * })
- *
- * // Limit retry attempts by both count and elapsed time
- * const limitedRetry = Schedule.exponential("100 millis").pipe(
- *   Schedule.upTo({
- *     duration: "5 seconds",
- *     times: 3
- *   })
- * )
- *
- * const retryProgram = Effect.gen(function*() {
- *   let attempt = 0
- *
- *   const result = yield* Effect.retry(
- *     Effect.gen(function*() {
- *       attempt++
- *       yield* Console.log(`Attempt ${attempt}`)
- *
- *       if (attempt < 5) { // Will fail more than 3 times
- *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
- *       }
- *
- *       return `Success on attempt ${attempt}`
- *     }),
- *     limitedRetry
- *   )
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- *   yield* Console.log(`Result: ${result}`)
- * }).pipe(
- *   Effect.catch((error: unknown) =>
- *     Console.log(`Failed after limited retries: ${String(error)}`)
- *   )
+ * const executions: Array<number> = []
+ * const schedule = Schedule.forever.pipe(Schedule.upTo({ times: 2 }))
+ * const program = Effect.sync(() => executions.push(executions.length + 1)).pipe(
+ *   Effect.repeat(schedule),
+ *   Effect.as(executions)
  * )
  *
- * // Empty options leave the schedule unchanged
- * const unchanged = Schedule.fixed("500 millis").pipe(
- *   Schedule.upTo({})
- * )
+ * await Effect.runPromise(Effect.provide(program, TestClock.layer())) // => [1, 2, 3]
  * ```
  *
  * @category filtering
@@ -1595,21 +962,15 @@ while_ as while };
  *
  * **Example** (Repeating on aligned windows)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
- *
- * // Execute tasks at regular intervals aligned to window boundaries
- * const windowSchedule = Schedule.windowed("5 seconds")
+ * ```ts import.meta.vitest
+ * import { Duration, Effect, Schedule } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Window task executed")
- *       return "window-task"
- *     }),
- *     windowSchedule.pipe(Schedule.upTo({ times: 4 }))
- *   )
+ *   const step = yield* Schedule.toStep(Schedule.windowed("5 seconds"))
+ *   return yield* step(0, undefined)
  * })
+ *
+ * await Effect.runPromise(program) // => [0, Duration.seconds(5)]
  * ```
  *
  * @category constructors
@@ -1629,21 +990,18 @@ export const windowed = interval => {
  *
  * **Example** (Repeating forever)
  *
- * ```ts
- * import { Console, Effect, Schedule } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Schedule } from "effect"
+ * import { TestClock } from "effect/testing"
  *
- * // A schedule that runs forever with no delay
- * const infiniteSchedule = Schedule.forever
+ * const executions: Array<number> = []
+ * const schedule = Schedule.forever.pipe(Schedule.upTo({ times: 2 }))
+ * const program = Effect.sync(() => executions.push(executions.length + 1)).pipe(
+ *   Effect.repeat(schedule),
+ *   Effect.as(executions)
+ * )
  *
- * const program = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Running forever...")
- *       return "continuous-task"
- *     }),
- *     infiniteSchedule.pipe(Schedule.upTo({ times: 5 })) // Limit for demo
- *   )
- * })
+ * await Effect.runPromise(Effect.provide(program, TestClock.layer())) // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -1686,12 +1044,13 @@ identity_ as identity };
  *
  * **Example** (Setting a schedule input type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schedule } from "effect"
  *
  * const schedule = Schedule.recurs(3).pipe(
  *   Schedule.setInputType<string>()
  * )
+ * Schedule.isSchedule(schedule) // => true
  * ```
  *
  * @category utility types