effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Schedule.js

@@ -6,7 +6,8 @@
  * along with a delay duration. Schedules can be combined, transformed, and used to implement
  * sophisticated retry and repetition logic.
  *
- * @example
+ * **Example** (Retrying and repeating effects)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -44,8 +45,16 @@ import * as Result from "./Result.js";
 const TypeId = "~effect/Schedule";
 const randomNext = /*#__PURE__*/random.Random.useSync(random => random.nextDoubleUnsafe());
 /**
- * @since 4.0.0
+ * Context reference containing metadata for the currently running schedule step.
+ *
+ * **Details**
+ * Repeat, retry, stream, and channel scheduling operations provide this service
+ * to effects run between schedule steps. The default value contains undefined
+ * input and output values, zero duration, and zeroed timing fields before any
+ * schedule step has produced metadata.
+ *
  * @category Metadata
+ * @since 4.0.0
  */
 export const CurrentMetadata = /*#__PURE__*/Context.Reference("effect/Schedule/CurrentMetadata", {
   defaultValue: /*#__PURE__*/constant({
@@ -72,7 +81,8 @@ const ScheduleProto = {
 /**
  * Type guard that checks if a value is a Schedule.
  *
- * @example
+ * **Example** (Checking for schedules)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -85,33 +95,32 @@ const ScheduleProto = {
  * console.log(Schedule.isSchedule(undefined)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isSchedule = u => hasProperty(u, TypeId);
 /**
  * Creates a Schedule from a step function that returns a Pull.
  *
- * @example
- * ```ts
- * import { Schedule } from "effect"
+ * **Example** (Creating a custom schedule from a step function)
  *
- * // fromStep is an advanced function for creating custom schedules
- * // It requires a step function that returns a Pull value
+ * ```ts
+ * import { Cause, Duration, Effect, Schedule } from "effect"
  *
- * // Most users should use simpler schedule constructors like:
- * const simpleSchedule = Schedule.exponential("100 millis")
- * const spacedSchedule = Schedule.spaced("1 second")
- * const recurringSchedule = Schedule.recurs(5)
+ * const schedule = Schedule.fromStep(Effect.sync(() => {
+ *   let count = 0
  *
- * // These can be combined and transformed as needed
- * const complexSchedule = simpleSchedule.pipe(
- *   Schedule.both(Schedule.recurs(3))
- * )
+ *   return (_now: number, _input: string) => {
+ *     if (count >= 3) {
+ *       return Cause.done(count)
+ *     }
+ *     return Effect.succeed([count++, Duration.millis(100)] as [number, Duration.Duration])
+ *   }
+ * }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromStep = step => {
   const self = Object.create(ScheduleProto);
@@ -140,26 +149,25 @@ const metadataFn = () => {
 /**
  * Creates a Schedule from a step function that receives metadata about the schedule's execution.
  *
- * @example
- * ```ts
- * import { Effect, Schedule } from "effect"
+ * **Example** (Creating a metadata-aware schedule)
  *
- * // fromStepWithMetadata is an advanced function for creating schedules
- * // that need access to execution metadata like timing and recurrence count
+ * ```ts
+ * import { Cause, Duration, Effect, Schedule } from "effect"
  *
- * // Most users should use simpler metadata-aware functions like:
- * const metadataSchedule = Schedule.spaced("1 second").pipe(
- *   Schedule.collectWhile((metadata) => Effect.succeed(metadata.attempt <= 5))
- * )
+ * const firstThreeInputs = Schedule.fromStepWithMetadata(Effect.succeed((metadata: Schedule.InputMetadata<string>) => {
+ *   if (metadata.attempt > 3) {
+ *     return Cause.done("finished")
+ *   }
  *
- * // Or use existing schedules with metadata transformations:
- * const conditionalSchedule = Schedule.exponential("100 millis").pipe(
- *   Schedule.tapOutput((output) => Effect.log(`Output: ${output}`))
- * )
+ *   return Effect.succeed([
+ *     `attempt ${metadata.attempt}: ${metadata.input}`,
+ *     Duration.millis(250)
+ *   ] as [string, Duration.Duration])
+ * }))
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
   const meta = metadataFn();
@@ -168,7 +176,8 @@ export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
 /**
  * Extracts the step function from a Schedule.
  *
- * @example
+ * **Example** (Extracting a schedule step function)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -178,24 +187,25 @@ export const fromStepWithMetadata = step => fromStep(effect.map(step, f => {
  * const program = Effect.gen(function*() {
  *   const stepFn = yield* Schedule.toStep(schedule)
  *
- *   // Use the step function directly for custom logic
- *   const now = Date.now()
+ *   // 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}`)
  * })
  * ```
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 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.
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 export const toStepWithMetadata = schedule => effect.clockWith(clock => effect.map(toStep(schedule), step => {
   const metaFn = metadataFn();
@@ -212,7 +222,8 @@ export const toStepWithMetadata = schedule => effect.clockWith(clock => effect.m
 /**
  * Extracts a step function from a Schedule that automatically handles sleep delays.
  *
- * @example
+ * **Example** (Extracting a sleeping step function)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -235,37 +246,34 @@ export const toStepWithMetadata = schedule => effect.clockWith(clock => effect.m
  * })
  * ```
  *
- * @since 4.0.0
  * @category destructors
+ * @since 4.0.0
  */
 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.
  *
- * @example
+ * **Example** (Adding extra delay to a schedule)
+ *
  * ```ts
  * import { Console, Data, Duration, Effect, Schedule } from "effect"
  *
  * class RetryAttemptError extends Data.TaggedError("RetryAttemptError")<{ readonly message: string }> {}
  *
- * // Add random jitter to schedule delays
- * const jitteredSchedule = Schedule.addDelay(
+ * // Add a deterministic extra delay based on the schedule output
+ * const delayedSchedule = Schedule.addDelay(
  *   Schedule.exponential("100 millis").pipe(Schedule.take(5)),
  *   (output) =>
- *     // Add random jitter between 0-50ms
- *     Effect.succeed(Duration.millis(Math.random() * 50))
+ *     Effect.succeed(Duration.millis(Duration.toMillis(output) * 0.25))
  * )
  *
- * const jitterProgram = Effect.gen(function*() {
+ * const repeatProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
- *       return "jittered task"
- *     }),
- *     jitteredSchedule.pipe(
+ *     Effect.succeed("delayed task"),
+ *     delayedSchedule.pipe(
  *       Schedule.tapOutput((delay) =>
- *         Console.log(`Base delay with jitter applied`)
+ *         Console.log(`Base delay: ${delay}`)
  *       )
  *     )
  *   )
@@ -293,12 +301,15 @@ export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedul
  *   )
  * })
  *
- * // Add effectful delay computation
+ * // 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.take(4)),
- *   (executionNumber) =>
- *     // Simulate checking system load and return additional delay
- *     Effect.succeed(Duration.millis(Math.random() > 0.7 ? 2000 : 500))
+ *   (executionNumber) => {
+ *     const load = loadByExecution[executionNumber] ?? 1
+ *     return Effect.succeed(Duration.millis(load * 100))
+ *   }
  * )
  *
  * const dynamicProgram = Effect.gen(function*() {
@@ -311,25 +322,6 @@ export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedul
  *   )
  * })
  *
- * // Add delay based on previous execution results (30% extra)
- * const resultBasedSchedule = Schedule.addDelay(
- *   Schedule.fibonacci("200 millis").pipe(Schedule.take(5)),
- *   (fibonacciDelay) =>
- *     Effect.succeed(Duration.millis(Duration.toMillis(fibonacciDelay) * 0.3))
- * )
- *
- * const resultProgram = Effect.gen(function*() {
- *   yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       yield* Console.log("Result-based delay task")
- *       return Math.random()
- *     }),
- *     resultBasedSchedule.pipe(
- *       Schedule.tapOutput((delay) => Console.log(`Fibonacci delay: ${delay}`))
- *     )
- *   )
- * })
- *
  * // Combine with retry for progressive backoff
  * const progressiveRetrySchedule = Schedule.addDelay(
  *   Schedule.exponential("50 millis").pipe(Schedule.take(4)),
@@ -354,8 +346,8 @@ export const toStepWithSleep = schedule => effect.map(toStepWithMetadata(schedul
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 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)))));
 /**
@@ -363,7 +355,8 @@ export const addDelay = /*#__PURE__*/dual(2, (self, f) => modifyDelay(self, (out
  * schedule to completion. Once the left schedule is complete, the right (i.e.
  * `other`) schedule will be executed to completion.
  *
- * @example
+ * **Example** (Sequencing quick and slow retries)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -395,8 +388,8 @@ export const addDelay = /*#__PURE__*/dual(2, (self, f) => modifyDelay(self, (out
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const andThen = /*#__PURE__*/dual(2, (self, other) => map(andThenResult(self, other), result => effect.succeed(Result.merge(result))));
 /**
@@ -404,11 +397,12 @@ export const andThen = /*#__PURE__*/dual(2, (self, other) => map(andThenResult(s
  * schedule to completion. Once the left schedule is complete, the right (i.e.
  * `other`) schedule will be executed to completion.
  *
- * The output of the resulting schedule is a `Result` where outputs of the
- * left schedule are emitted as `Result.Err<Output>` and outputs of the right
- * schedule are emitted as `Result.Ok<Output>`.
+ * The resulting schedule emits a `Result` to indicate which phase produced
+ * each output: outputs from `self` are emitted as `Failure`, and outputs from
+ * `other` are emitted as `Success`.
+ *
+ * **Example** (Tracking sequential schedule phases)
  *
- * @example
  * ```ts
  * import { Console, Effect, Result, Schedule } from "effect"
  *
@@ -436,8 +430,8 @@ export const andThen = /*#__PURE__*/dual(2, (self, other) => map(andThenResult(s
  * })
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 4.0.0
  */
 export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effect.sync(() => {
   let currentSide = 0;
@@ -465,7 +459,8 @@ 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.
  *
- * @example
+ * **Example** (Combining time and attempt limits)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -482,7 +477,7 @@ export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effe
  * const program = Effect.gen(function*() {
  *   const results = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+ *       yield* Console.log("Task executed")
  *       return "task completed"
  *     }),
  *     bothSchedule.pipe(
@@ -526,8 +521,8 @@ export const andThenResult = /*#__PURE__*/dual(2, (self, other) => fromStep(effe
  * // Compare with either which provides union semantics (OR logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const both = /*#__PURE__*/dual(2, (self, other) => bothWith(self, other, (left, right) => [left, right]));
 /**
@@ -535,7 +530,8 @@ export const both = /*#__PURE__*/dual(2, (self, other) => bothWith(self, other,
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
- * @example
+ * **Example** (Combining schedules and keeping the left output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -558,8 +554,8 @@ export const both = /*#__PURE__*/dual(2, (self, other) => bothWith(self, other,
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothLeft = /*#__PURE__*/dual(2, (self, other) => bothWith(self, other, output => output));
 /**
@@ -567,7 +563,8 @@ export const bothLeft = /*#__PURE__*/dual(2, (self, other) => bothWith(self, oth
  * to recur, using the maximum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
- * @example
+ * **Example** (Combining schedules and keeping the right output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -592,8 +589,8 @@ export const bothLeft = /*#__PURE__*/dual(2, (self, other) => bothWith(self, oth
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothRight = /*#__PURE__*/dual(2, (self, other) => bothWith(self, other, (_, output) => output));
 /**
@@ -602,7 +599,8 @@ export const bothRight = /*#__PURE__*/dual(2, (self, other) => bothWith(self, ot
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
- * @example
+ * **Example** (Combining schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -631,8 +629,8 @@ export const bothRight = /*#__PURE__*/dual(2, (self, other) => bothWith(self, ot
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const bothWith = /*#__PURE__*/dual(3, (self, other, combine) => fromStep(effect.map(effect.zip(toStep(self), toStep(other)), ([stepLeft, stepRight]) => (now, input) => Pull.matchEffect(stepLeft(now, input), {
   onSuccess: leftResult => stepRight(now, input).pipe(effect.map(rightResult => [combine(leftResult[0], rightResult[0]), Duration.max(leftResult[1], rightResult[1])]), Pull.catchDone(rightDone => Cause.done(combine(leftResult[0], rightDone)))),
@@ -640,10 +638,15 @@ export const bothWith = /*#__PURE__*/dual(3, (self, other, combine) => fromStep(
   onFailure: effect.failCause
 }))));
 /**
- * Returns a new `Schedule` that always recurs, collecting all inputs of the
- * schedule into an array.
+ * Returns a new `Schedule` that follows `self` and outputs the inputs seen so
+ * far as an array.
+ *
+ * **Details**
+ * This does not make the schedule run forever. The collected schedule stops
+ * when `self` stops and fails when `self` fails.
+ *
+ * **Example** (Collecting schedule inputs)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -665,15 +668,20 @@ export const bothWith = /*#__PURE__*/dual(3, (self, other, combine) => fromStep(
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const collectInputs = self => collectWhile(passthrough(self), () => effect.succeed(true));
 /**
- * Returns a new `Schedule` that always recurs, collecting all outputs of the
- * schedule into an array.
+ * Returns a new `Schedule` that follows `self` and outputs the schedule outputs
+ * seen so far as an array.
+ *
+ * **Details**
+ * This does not make the schedule run forever. The collected schedule stops
+ * when `self` stops and fails when `self` fails.
+ *
+ * **Example** (Collecting schedule outputs)
  *
- * @example
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -693,39 +701,19 @@ export const collectInputs = self => collectWhile(passthrough(self), () => effec
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const collectOutputs = self => collectWhile(self, () => effect.succeed(true));
 /**
  * Returns a new `Schedule` that recurs as long as the specified `predicate`
  * returns `true`, collecting all outputs of the schedule into an array.
  *
- * @example
+ * **Example** (Collecting outputs while a condition holds)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
- * // Collect outputs while under time limit
- * const collectForTime = Schedule.collectWhile(
- *   Schedule.spaced("500 millis"),
- *   (metadata) => Effect.succeed(metadata.elapsed < 3000) // Stop after 3 seconds
- * )
- *
- * const timeBasedProgram = Effect.gen(function*() {
- *   const results = yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       const value = Math.floor(Math.random() * 100)
- *       yield* Console.log(`Generated value: ${value}`)
- *       return value
- *     }),
- *     collectForTime
- *   )
- *
- *   yield* Console.log(
- *     `Collected ${results.length} values: [${results.join(", ")}]`
- *   )
- * })
- *
  * // Collect outputs while condition is met
  * const collectWhileSmall = Schedule.collectWhile(
  *   Schedule.exponential("100 millis"),
@@ -736,16 +724,16 @@ export const collectOutputs = self => collectWhile(self, () => effect.succeed(tr
  * const conditionalProgram = Effect.gen(function*() {
  *   let attempt = 0
  *
- *   const delays = yield* Effect.repeat(
+ *   const attempts = yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       attempt++
  *       yield* Console.log(`Retry attempt ${attempt}`)
- *       return `${Date.now()}`
+ *       return `attempt-${attempt}`
  *     }),
  *     collectWhileSmall
  *   )
  *
- *   yield* Console.log(`Collected attempts: [${delays.join(", ")}]`)
+ *   yield* Console.log(`Collected attempts: [${attempts.join(", ")}]`)
  * })
  *
  * // Collect with effectful predicate
@@ -762,19 +750,17 @@ export const collectOutputs = self => collectWhile(self, () => effect.succeed(tr
  * )
  *
  * const effectfulProgram = Effect.gen(function*() {
- *   const timestamps = yield* Effect.repeat(
- *     Effect.gen(function*() {
- *       const now = new Date().toISOString()
- *       yield* Console.log(`Task at ${now}`)
- *       return now
- *     }),
+ *   const results = yield* Effect.repeat(
+ *     Effect.succeed("checked"),
  *     collectWithCheck
  *   )
  *
- *   yield* Console.log(`Final collection: ${timestamps.length} items`)
+ *   yield* Console.log(`Final collection: ${results.length} items`)
  * })
  *
  * // Collect samples with condition
+ * const samples = [12, 18, 24, 30, 36]
+ *
  * const collectSamples = Schedule.collectWhile(
  *   Schedule.spaced("200 millis"),
  *   (metadata) =>
@@ -782,24 +768,25 @@ export const collectOutputs = self => collectWhile(self, () => effect.succeed(tr
  * )
  *
  * const samplingProgram = Effect.gen(function*() {
- *   const samples = yield* Effect.repeat(
+ *   let index = 0
+ *   const collected = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const sample = Math.random() * 100
- *       yield* Console.log(`Sample: ${sample.toFixed(1)}`)
+ *       const sample = samples[index++]
+ *       yield* Console.log(`Sample: ${sample}`)
  *       return sample
  *     }),
  *     collectSamples
  *   )
  *
- *   const average = samples.reduce((sum, s) => sum + s, 0) / samples.length
+ *   const average = collected.reduce((sum, s) => sum + s, 0) / collected.length
  *   yield* Console.log(
- *     `Collected ${samples.length} samples, average: ${average.toFixed(1)}`
+ *     `Collected ${collected.length} samples, average: ${average.toFixed(1)}`
  *   )
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(while_(self, predicate), () => [], (outputs, output) => {
   outputs.push(output);
@@ -809,7 +796,8 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
  * outputs the duration between recurrences.
  *
- * @example
+ * **Example** (Scheduling work with cron expressions)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -821,7 +809,7 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  * const minutelyProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Minutely task at ${new Date().toISOString()}`)
+ *       yield* Console.log("Running minutely task")
  *       return "minute"
  *     }),
  *     everyMinute.pipe(
@@ -859,8 +847,8 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  *     Effect.gen(function*() {
  *       yield* Console.log("Generating weekly report...")
  *       const report = {
- *         week: Math.floor(Date.now() / (7 * 24 * 60 * 60 * 1000)),
- *         timestamp: new Date().toISOString()
+ *         week: 42,
+ *         status: "ready" as const
  *       }
  *       yield* Console.log(`Report generated: ${JSON.stringify(report)}`)
  *       return report
@@ -873,10 +861,13 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  * 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 = Math.random() > 0.1 ? "healthy" : "degraded"
+ *       const status = statuses[index++]
  *       yield* Console.log(`System status: ${status}`)
  *       return status
  *     }),
@@ -893,9 +884,9 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Processing monthly invoices...")
- *       const invoiceCount = Math.floor(Math.random() * 100) + 50
+ *       const invoiceCount = 72
  *       yield* Console.log(`Processed ${invoiceCount} invoices`)
- *       return { count: invoiceCount, date: new Date().toISOString() }
+ *       return { count: invoiceCount, batch: "2024-01-a" }
  *     }),
  *     monthlyInvoice.pipe(Schedule.take(1))
  *   )
@@ -909,11 +900,13 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  * )
  *
  * const robustProgram = Effect.gen(function*() {
+ *   let attempt = 0
+ *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
+ *       attempt++
  *       yield* Console.log("Complex scheduled task...")
- *       // Simulate occasional failures
- *       if (Math.random() < 0.3) {
+ *       if (attempt === 1) {
  *         return yield* Effect.fail(new ScheduledTaskError({ message: "Scheduled task failed" }))
  *       }
  *       return "success"
@@ -927,8 +920,8 @@ export const collectWhile = /*#__PURE__*/dual(2, (self, predicate) => reduce(whi
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const cron = (expression, tz) => {
   const parsed = Cron.isCron(expression) ? Result.succeed(expression) : Cron.parse(expression, tz);
@@ -941,7 +934,8 @@ export const cron = (expression, tz) => {
 /**
  * Returns a new schedule that outputs the delay between each occurence.
  *
- * @example
+ * **Example** (Extracting schedule delays)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1001,7 +995,7 @@ export const cron = (expression, tz) => {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Adaptive task execution")
- *       return Date.now()
+ *       return "completed"
  *     }),
  *     adaptiveDelays.pipe(
  *       Schedule.tapOutput((delay) => Console.log(`Adaptive delay: ${delay}`))
@@ -1018,8 +1012,8 @@ export const cron = (expression, tz) => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const delays = self => fromStep(effect.map(toStep(self), step => (now, input) => Pull.catchDone(effect.map(step(now, input), ([_, duration]) => [duration, duration]), _ => Cause.done(Duration.zero))));
 /**
@@ -1028,8 +1022,8 @@ export const delays = self => fromStep(effect.map(toStep(self), step => (now, in
  * The schedule outputs the configured duration for its first recurrence and
  * then completes.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const duration = durationInput => {
   const duration = Duration.fromInputUnsafe(durationInput);
@@ -1039,7 +1033,8 @@ export const duration = durationInput => {
  * Returns a new `Schedule` that will always recur, but only during the
  * specified `duration` of time.
  *
- * @example
+ * **Example** (Repeating work during a duration)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1049,12 +1044,9 @@ export const duration = durationInput => {
  * const fiveSecondSchedule = Schedule.during("5 seconds")
  *
  * const timedProgram = Effect.gen(function*() {
- *   const startTime = Date.now()
- *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const elapsed = Date.now() - startTime
- *       yield* Console.log(`Task executed after ${elapsed}ms`)
+ *       yield* Console.log("Task executed inside the time window")
  *       yield* Effect.sleep("500 millis") // Each task takes 500ms
  *       return "task done"
  *     }),
@@ -1082,8 +1074,8 @@ export const duration = durationInput => {
  *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Burst task at ${new Date().toISOString()}`)
- *       return Math.random()
+ *       yield* Console.log("Burst task")
+ *       return "burst"
  *     }),
  *     burstWindow
  *   )
@@ -1104,7 +1096,7 @@ export const duration = durationInput => {
  *       attempt++
  *       yield* Console.log(`Retry attempt ${attempt}`)
  *
- *       if (Math.random() < 0.8) { // 80% failure rate
+ *       if (attempt < 4) {
  *         return yield* Effect.fail(new RetryAttemptError({ message: `Attempt ${attempt} failed` }))
  *       }
  *
@@ -1119,8 +1111,8 @@ export const duration = durationInput => {
  * )
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const during = duration => while_(elapsed, ({
   output
@@ -1130,7 +1122,8 @@ 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.
  *
- * @example
+ * **Example** (Combining schedules with either semantics)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1147,7 +1140,7 @@ export const during = duration => while_(elapsed, ({
  * const program = Effect.gen(function*() {
  *   const results = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Task executed at ${new Date().toISOString()}`)
+ *       yield* Console.log("Task executed")
  *       return "task completed"
  *     }),
  *     eitherSchedule.pipe(
@@ -1193,8 +1186,8 @@ export const during = duration => while_(elapsed, ({
  * // Compare with intersect which provides intersection semantics (AND logic)
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const either = /*#__PURE__*/dual(2, (self, other) => eitherWith(self, other, (left, right) => [left, right]));
 /**
@@ -1202,7 +1195,8 @@ export const either = /*#__PURE__*/dual(2, (self, other) => eitherWith(self, oth
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the left schedule (i.e. `self`).
  *
- * @example
+ * **Example** (Combining either schedules and keeping the left output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1228,8 +1222,8 @@ export const either = /*#__PURE__*/dual(2, (self, other) => eitherWith(self, oth
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const eitherLeft = /*#__PURE__*/dual(2, (self, other) => eitherWith(self, other, output => output));
 /**
@@ -1237,7 +1231,8 @@ export const eitherLeft = /*#__PURE__*/dual(2, (self, other) => eitherWith(self,
  * to recur, using the minimum of the two durations between recurrences and
  * outputting the result of the right schedule (i.e. `other`).
  *
- * @example
+ * **Example** (Combining either schedules and keeping the right output)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1263,8 +1258,8 @@ export const eitherLeft = /*#__PURE__*/dual(2, (self, other) => eitherWith(self,
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const eitherRight = /*#__PURE__*/dual(2, (self, other) => eitherWith(self, other, (_, output) => output));
 /**
@@ -1273,7 +1268,8 @@ export const eitherRight = /*#__PURE__*/dual(2, (self, other) => eitherWith(self
  * outputting the result of the combination of both schedule outputs using the
  * specified `combine` function.
  *
- * @example
+ * **Example** (Combining either schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1303,8 +1299,8 @@ export const eitherRight = /*#__PURE__*/dual(2, (self, other) => eitherWith(self
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const eitherWith = /*#__PURE__*/dual(3, (self, other, combine) => fromStep(effect.map(effect.zip(toStep(self), toStep(other)), ([stepLeft, stepRight]) => (now, input) => Pull.matchEffect(stepLeft(now, input), {
   onSuccess: leftResult => stepRight(now, input).pipe(effect.map(rightResult => [combine(leftResult[0], rightResult[0]), Duration.min(leftResult[1], rightResult[1])]), Pull.catchDone(rightDone => effect.succeed([combine(leftResult[0], rightDone), leftResult[1]]))),
@@ -1317,9 +1313,8 @@ export const eitherWith = /*#__PURE__*/dual(3, (self, other, combine) => fromSte
  * This schedule never stops and outputs the cumulative time that has passed since the schedule
  * started executing. Useful for tracking execution time or implementing time-based logic.
  *
- * @returns A schedule that outputs the elapsed duration and never stops
+ * **Example** (Measuring elapsed schedule time)
  *
- * @example
  * ```ts
  * import { Console, Duration, Effect, Schedule } from "effect"
  *
@@ -1337,8 +1332,8 @@ export const eitherWith = /*#__PURE__*/dual(3, (self, other, combine) => fromSte
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const elapsed = /*#__PURE__*/fromStepWithMetadata(/*#__PURE__*/effect.succeed(meta => effect.succeed([Duration.millis(meta.elapsed), Duration.zero])));
 /**
@@ -1346,7 +1341,8 @@ export const elapsed = /*#__PURE__*/fromStepWithMetadata(/*#__PURE__*/effect.suc
  * repetitions, given by `base * factor.pow(n)`, where `n` is the number of
  * repetitions so far. Returns the current duration between recurrences.
  *
- * @example
+ * **Example** (Retrying with exponential backoff)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1386,8 +1382,8 @@ export const elapsed = /*#__PURE__*/fromStepWithMetadata(/*#__PURE__*/effect.suc
  * // Will retry with delays: 50ms, 100ms, 200ms before success
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const exponential = (base, factor = 2) => {
   const baseMillis = Duration.toMillis(Duration.fromInputUnsafe(base));
@@ -1401,7 +1397,8 @@ export const exponential = (base, factor = 2) => {
  * two delays (similar to the fibonacci sequence). Returns the current
  * duration between recurrences.
  *
- * @example
+ * **Example** (Retrying with fibonacci backoff)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1437,7 +1434,7 @@ export const exponential = (base, factor = 2) => {
  *
  * // Heartbeat with fibonacci intervals (starts fast, gets slower)
  * const adaptiveHeartbeat = Effect.gen(function*() {
- *   yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *   yield* Console.log("Heartbeat")
  *   return "pulse"
  * }).pipe(
  *   Effect.repeat(
@@ -1459,8 +1456,8 @@ export const exponential = (base, factor = 2) => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fibonacci = one => {
   const oneMillis = Duration.toMillis(Duration.fromInputUnsafe(one));
@@ -1488,7 +1485,8 @@ export const fibonacci = one => {
  * |---------action--------||action|-----|action|-----------|
  * ```
  *
- * @example
+ * **Example** (Repeating on fixed intervals)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1497,7 +1495,7 @@ export const fibonacci = one => {
  *
  * // Health check that runs at fixed intervals
  * const healthCheck = Effect.gen(function*() {
- *   yield* Console.log(`Health check at ${new Date().toISOString()}`)
+ *   yield* Console.log("Health check")
  *   yield* Effect.sleep("200 millis") // simulate health check work
  *   return "healthy"
  * }).pipe(
@@ -1535,8 +1533,8 @@ export const fibonacci = one => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fixed = interval => {
   const window = Duration.toMillis(Duration.fromInputUnsafe(interval));
@@ -1564,7 +1562,8 @@ export const fixed = interval => {
  * Returns a new `Schedule` that maps the output of this schedule using the
  * specified function.
  *
- * @example
+ * **Example** (Mapping schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1582,7 +1581,6 @@ export const fixed = interval => {
  * const structuredSchedule = Schedule.spaced("1 second").pipe(
  *   Schedule.map((recurrence) => Effect.succeed({
  *     iteration: recurrence + 1,
- *     timestamp: new Date().toISOString(),
  *     phase: recurrence < 5 ? "warmup" as const : "steady" as const
  *   }))
  * )
@@ -1594,7 +1592,7 @@ export const fixed = interval => {
  *       Schedule.take(8),
  *       Schedule.tapOutput((info) =>
  *         Console.log(
- *           `${info.phase} phase - iteration ${info.iteration} at ${info.timestamp}`
+ *           `${info.phase} phase - iteration ${info.iteration}`
  *         )
  *       )
  *     )
@@ -1619,8 +1617,8 @@ export const fixed = interval => {
  * )
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => {
   const handle = Pull.matchEffect({
@@ -1642,7 +1640,8 @@ 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.
  *
- * @example
+ * **Example** (Modifying delays from schedule output)
+ *
  * ```ts
  * import { Console, Duration, Effect, Schedule } from "effect"
  *
@@ -1667,8 +1666,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const modifyDelay = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(self), step => (now, input) => effect.flatMap(step(now, input), ([output, delay]) => effect.map(f(output, delay), delay => [output, Duration.fromInputUnsafe(delay)])))));
 /**
@@ -1676,8 +1675,8 @@ export const modifyDelay = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map
  *
  * Delays are jittered between `80%` and `120%` of the original delay.
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const jittered = self => modifyDelay(self, (_, delay) => effect.map(randomNext, random => {
   const millis = Duration.toMillis(Duration.fromInputUnsafe(delay));
@@ -1686,7 +1685,8 @@ export const jittered = self => modifyDelay(self, (_, delay) => effect.map(rando
 /**
  * Returns a new `Schedule` that outputs the inputs of the specified schedule.
  *
- * @example
+ * **Example** (Passing inputs through as outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1708,8 +1708,8 @@ export const jittered = self => modifyDelay(self, (_, delay) => effect.map(rando
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const passthrough = self => fromStep(effect.map(toStep(self), step => (now, input) => Pull.matchEffect(step(now, input), {
   onSuccess: result => effect.succeed([input, result[1]]),
@@ -1720,7 +1720,8 @@ 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.
  *
- * @example
+ * **Example** (Limiting recurrences)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -1758,7 +1759,7 @@ export const passthrough = self => fromStep(effect.map(toStep(self), step => (no
  * // Repeat an effect exactly 10 times
  * const exactlyTenTimes = Effect.gen(function*() {
  *   yield* Console.log("Executing task...")
- *   return Math.random()
+ *   return "completed"
  * }).pipe(
  *   Effect.repeat(Schedule.recurs(10))
  * )
@@ -1780,7 +1781,8 @@ export const recurs = times => while_(forever, ({
  * using the specified effectful `combine` function and starting from the
  * specified `initial` state.
  *
- * @example
+ * **Example** (Reducing schedule outputs)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1805,24 +1807,24 @@ export const recurs = times => while_(forever, ({
  *   yield* Console.log(`Final sum: ${finalSum}`)
  * })
  *
- * // Build a history of execution times
+ * // Build a history of execution counts
  * const historySchedule = Schedule.reduce(
  *   Schedule.spaced("1 second").pipe(Schedule.take(4)),
  *   () => [] as Array<number>, // Initial empty array
- *   (history, executionNumber) => Effect.succeed([...history, Date.now()])
+ *   (history, executionNumber) => Effect.succeed([...history, executionNumber])
  * )
  *
  * const historyProgram = Effect.gen(function*() {
  *   const timeline = yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log("Recording timestamp...")
+ *       yield* Console.log("Recording execution...")
  *       return "recorded"
  *     }),
  *     historySchedule
  *   )
  *
  *   yield* Console.log(
- *     `Execution timeline: ${timeline.length} timestamps recorded`
+ *     `Execution timeline: ${timeline.join(", ")}`
  *   )
  * })
  *
@@ -1883,8 +1885,8 @@ export const recurs = times => while_(forever, ({
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const reduce = /*#__PURE__*/dual(3, (self, initial, combine) => fromStep(effect.map(toStep(self), step => {
   let state = initial();
@@ -1911,7 +1913,8 @@ 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.
  *
- * @example
+ * **Example** (Repeating with fixed spacing)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -1920,7 +1923,7 @@ export const reduce = /*#__PURE__*/dual(3, (self, initial, combine) => fromStep(
  *
  * // Heartbeat that runs indefinitely with fixed spacing
  * const heartbeat = Effect.gen(function*() {
- *   yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *   yield* Console.log("Heartbeat")
  * }).pipe(
  *   Effect.repeat(everyTwoSeconds)
  * )
@@ -1953,8 +1956,8 @@ export const reduce = /*#__PURE__*/dual(3, (self, initial, combine) => fromStep(
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const spaced = duration => {
   const decoded = Duration.fromInputUnsafe(duration);
@@ -1965,7 +1968,8 @@ export const spaced = duration => {
  * every input to the schedule, but does not alter the inputs and outputs of
  * the schedule.
  *
- * @example
+ * **Example** (Tapping retry inputs)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2001,7 +2005,6 @@ export const spaced = duration => {
  *   Schedule.take(5),
  *   Schedule.tapInput((input: unknown) =>
  *     Effect.gen(function*() {
- *       yield* Console.log(`Processing input at ${new Date().toISOString()}`)
  *       yield* Console.log(`Input type: ${typeof input}`)
  *       // In real applications, might send metrics to monitoring system
  *     })
@@ -2023,10 +2026,13 @@ export const spaced = duration => {
  * )
  *
  * const validationProgram = Effect.gen(function*() {
+ *   let count = 0
+ *
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
+ *       count++
  *       yield* Console.log("Task with validation")
- *       return { data: Math.random(), timestamp: Date.now() }
+ *       return { data: `sample-${count}` }
  *     }),
  *     validatingSchedule
  *   )
@@ -2038,10 +2044,10 @@ export const spaced = duration => {
  *   Schedule.tapInput((error: RetryError) =>
  *     Effect.gen(function*() {
  *       if (String(error).includes("critical")) {
- *         yield* Console.log(`🚨 CRITICAL ERROR: ${String(error)}`)
+ *         yield* Console.log(`Critical error: ${String(error)}`)
  *         // In real applications, might trigger alerts or notifications
  *       } else {
- *         yield* Console.log(`ℹ️ Regular error: ${String(error)}`)
+ *         yield* Console.log(`Regular error: ${String(error)}`)
  *       }
  *     })
  *   )
@@ -2075,14 +2081,14 @@ export const spaced = duration => {
  *   ),
  *   Schedule.tapInput((error: RetryError) =>
  *     String(error).length > 20
- *       ? Console.log("📝 Long error message detected")
+ *       ? Console.log("Long error message detected")
  *       : Effect.void
  *   )
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const tapInput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(self), step => (now, input) => effect.andThen(f(input), step(now, input)))));
 /**
@@ -2090,7 +2096,8 @@ export const tapInput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(to
  * every output of the schedule, but does not alter the inputs and outputs of
  * the schedule.
  *
- * @example
+ * **Example** (Tapping schedule outputs)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2138,7 +2145,7 @@ export const tapInput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(to
  *     Effect.gen(function*() {
  *       const delayMs = delay.toString()
  *       if (delayMs.includes("1000")) { // Alert on delays >= 1 second
- *         yield* Console.log(`🚨 High delay detected: ${delay}`)
+ *         yield* Console.log(`High delay detected: ${delay}`)
  *       }
  *     })
  *   )
@@ -2148,8 +2155,7 @@ export const tapInput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(to
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
  *       yield* Console.log("Performing health check...")
- *       // Simulate health check
- *       return Math.random() > 0.7 ? "healthy" : "degraded"
+ *       return "healthy"
  *     }),
  *     alertingSchedule
  *   )
@@ -2161,14 +2167,14 @@ export const tapInput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(to
  *   Schedule.tapOutput((count) => Console.log(`Execution ${count + 1}`)),
  *   Schedule.tapOutput((count) =>
  *     count % 3 === 0
- *       ? Console.log("🎯 Checkpoint reached!")
+ *       ? Console.log("Checkpoint reached")
  *       : Effect.void
  *   )
  * )
  * ```
  *
- * @since 2.0.0
  * @category sequencing
+ * @since 2.0.0
  */
 export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(toStep(self), step => (now, input) => effect.tap(step(now, input), ([output]) => f(output)))));
 /**
@@ -2176,7 +2182,8 @@ 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.
  *
- * @example
+ * **Example** (Taking a limited number of recurrences)
+ *
  * ```ts
  * import { Console, Data, Effect, Schedule } from "effect"
  *
@@ -2190,7 +2197,7 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  * const heartbeatProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       yield* Console.log(`Heartbeat at ${new Date().toISOString()}`)
+ *       yield* Console.log("Heartbeat")
  *       return "pulse"
  *     }),
  *     limitedHeartbeat
@@ -2237,8 +2244,8 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  * const samplingProgram = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const value = Math.random()
- *       yield* Console.log(`Sampled value: ${value.toFixed(3)}`)
+ *       const value = "sample"
+ *       yield* Console.log(`Sampled value: ${value}`)
  *       return value
  *     }),
  *     samplingSchedule.pipe(
@@ -2248,8 +2255,8 @@ export const tapOutput = /*#__PURE__*/dual(2, (self, f) => fromStep(effect.map(t
  * })
  * ```
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 export const take = /*#__PURE__*/dual(2, (self, n) => while_(self, ({
   attempt
@@ -2258,7 +2265,8 @@ export const take = /*#__PURE__*/dual(2, (self, n) => while_(self, ({
  * Creates a schedule that unfolds a state by repeatedly applying a function,
  * outputting the current state and computing the next state.
  *
- * @example
+ * **Example** (Unfolding schedule state)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2306,15 +2314,14 @@ export const take = /*#__PURE__*/dual(2, (self, n) => while_(self, ({
  *     })
  * )
  *
- * // Random jitter schedule
- * const jitteredSchedule = Schedule.unfold(
- *   1000,
- *   (baseDelay) =>
+ * // Deterministic delay adjustment schedule
+ * const adjustedDelaySchedule = Schedule.unfold(
+ *   { delay: 1000, adjustment: 100 },
+ *   ({ delay, adjustment }) =>
  *     Effect.gen(function*() {
- *       const jitter = Math.random() * 200 - 100 // ±100ms jitter
- *       const nextDelay = Math.max(100, baseDelay + jitter)
- *       yield* Console.log(`Jittered delay: ${nextDelay.toFixed(0)}ms`)
- *       return nextDelay
+ *       const nextDelay = Math.max(100, delay + adjustment)
+ *       yield* Console.log(`Adjusted delay: ${nextDelay}ms`)
+ *       return { delay: nextDelay, adjustment: adjustment * -1 }
  *     })
  * )
  *
@@ -2347,8 +2354,8 @@ export const take = /*#__PURE__*/dual(2, (self, n) => while_(self, ({
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const unfold = (initial, next) => fromStep(effect.sync(() => {
   let state = initial;
@@ -2378,8 +2385,8 @@ export {
  * If the `predicate` returns `true`, the schedule will continue, otherwise
  * the schedule will stop.
  *
- * @since 2.0.0
- * @category utilities
+ * @category utils
+ * @since 4.0.0
  */
 while_ as while };
 /**
@@ -2395,7 +2402,8 @@ while_ as while };
  * |action------|sleep---|act|-sleep|action----|
  * ```
  *
- * @example
+ * **Example** (Repeating on aligned windows)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2405,8 +2413,7 @@ while_ as while };
  * const program = Effect.gen(function*() {
  *   yield* Effect.repeat(
  *     Effect.gen(function*() {
- *       const now = new Date().toISOString()
- *       yield* Console.log(`Window task executed at: ${now}`)
+ *       yield* Console.log("Window task executed")
  *       return "window-task"
  *     }),
  *     windowSchedule.pipe(Schedule.take(4))
@@ -2414,8 +2421,8 @@ while_ as while };
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const windowed = interval => {
   const window = Duration.toMillis(Duration.fromInputUnsafe(interval));
@@ -2427,7 +2434,8 @@ export const windowed = interval => {
  * The output of the schedule is the current count of its repetitions thus far
  * (i.e. `0, 1, 2, ...`).
  *
- * @example
+ * **Example** (Repeating forever)
+ *
  * ```ts
  * import { Console, Effect, Schedule } from "effect"
  *
@@ -2445,8 +2453,8 @@ export const windowed = interval => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const forever = /*#__PURE__*/spaced(Duration.zero);
 const constIdentity = /*#__PURE__*/fromStep(/*#__PURE__*/effect.succeed((_now, input) => effect.succeed([input, Duration.zero])));
@@ -2461,14 +2469,15 @@ export {
  * without modification. It effectively acts as a pass-through that simply
  * echoes its input values at each step.
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 identity_ as identity };
 /**
  * Ensures that the provided schedule respects a specified input type.
  *
- * @example
+ * **Example** (Constraining schedule input types)
+ *
  * ```ts
  * import { Schedule } from "effect"
  *
@@ -2487,22 +2496,23 @@ identity_ as identity };
  * // where CustomType doesn't match the schedule's input type
  * ```
  *
- * @since 2.0.0
  * @category ensuring 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.
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const setInputType = () => self => self;
 /**
  * Ensures that the provided schedule respects a specified output type.
  *
- * @example
+ * **Example** (Constraining schedule output types)
+ *
  * ```ts
  * import { Effect, Schedule } from "effect"
  *
@@ -2516,14 +2526,15 @@ export const setInputType = () => self => self;
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesOutputType = () => self => self;
 /**
  * Ensures that the provided schedule respects a specified error type.
  *
- * @example
+ * **Example** (Constraining schedule error types)
+ *
  * ```ts
  * import { Data, Schedule } from "effect"
  *
@@ -2543,16 +2554,17 @@ export const satisfiesOutputType = () => self => self;
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesErrorType = () => self => self;
 /**
  * Ensures that the provided schedule respects a specified context type.
  *
- * @example
+ * **Example** (Constraining schedule service types)
+ *
  * ```ts
- * import { Schedule } from "effect"
+ * import { Effect, Schedule } from "effect"
  *
  * // Define service interfaces (type-level only)
  * interface Logger {
@@ -2560,7 +2572,7 @@ export const satisfiesErrorType = () => self => self;
  * }
  *
  * interface Database {
- *   readonly query: (sql: string) => Promise<unknown>
+ *   readonly query: (sql: string) => Effect.Effect<ReadonlyArray<unknown>>
  * }
  *
  * // Ensure schedule requires Logger service
@@ -2574,8 +2586,8 @@ export const satisfiesErrorType = () => self => self;
  * )
  * ```
  *
- * @since 2.0.0
  * @category ensuring types
+ * @since 4.0.0
  */
 export const satisfiesServicesType = () => self => self;
 //# sourceMappingURL=Schedule.js.map