@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Schedule.js

@@ -0,0 +1,1199 @@
+/**
+ * Composable scheduling strategies.
+ *
+ * @module
+ */
+import { fibonacciAt, FibonacciIndex, increment } from "./Number.js";
+import { done, err, ok } from "./Result.js";
+import { durationToMillis, Millis, minMillis, } from "./Time.js";
+import { onePositiveInt, PositiveInt } from "./Type.js";
+/**
+ * Creates an internal per-step metrics tracker.
+ *
+ * Each call updates internal state and returns computed metrics.
+ */
+const createScheduleStepMetrics = (deps) => {
+    let attempt = onePositiveInt;
+    let start = null;
+    let previous = null;
+    return () => {
+        const now = deps.time.now();
+        const currentAttempt = attempt;
+        attempt = increment(attempt);
+        start ??= now;
+        const elapsed = (now - start);
+        const elapsedSincePrevious = previous === null ? 0 : (now - previous);
+        previous = now;
+        return { attempt: currentAttempt, elapsed, elapsedSincePrevious };
+    };
+};
+/**
+ * A schedule that never stops and has no delay.
+ *
+ * Outputs the attempt count (0, 1, 2, ...). Useful as a base for composition or
+ * for immediate retry without backoff.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Retry immediately, up to 5 times
+ * const immediate = take(5)(forever);
+ * ```
+ *
+ * @group Constructors
+ */
+export const forever = () => {
+    let attempt = 0;
+    return () => ok([attempt++, minMillis]);
+};
+/**
+ * A schedule that runs exactly once with no delay.
+ *
+ * Convenience for `take(1)(forever)`. Useful for one-shot operations.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Execute once, no retry
+ * const oneShot = once;
+ * ```
+ *
+ * @group Constructors
+ */
+export const once = () => {
+    let finished = false;
+    return () => {
+        if (finished)
+            return err(done());
+        finished = true;
+        return ok([0, minMillis]);
+    };
+};
+/**
+ * A schedule that recurs a fixed number of times.
+ *
+ * Convenience for `take(n)(forever)`. Outputs the current repetition count (0,
+ * 1, 2, ..., n-1).
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Retry up to 3 times (4 total attempts including initial)
+ * const retry = recurs(3);
+ * ```
+ *
+ * @group Constructors
+ */
+export const recurs = (n) => take(n)(forever);
+/**
+ * Constant delay schedule.
+ *
+ * Always waits the same duration after each execution completes. Never stops —
+ * combine with {@link take} or {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // 1s, 1s, 1s, ... (polling)
+ * const poll = spaced("1s");
+ *
+ * // Retry 3 times with 500ms between each
+ * const retry = take(3)(spaced("500ms"));
+ *
+ * // Heartbeat schedule
+ * const heartbeat = spaced("30s");
+ * ```
+ *
+ * @group Constructors
+ */
+export const spaced = (duration) => () => {
+    const ms = durationToMillis(duration);
+    return () => ok([ms, ms]);
+};
+/**
+ * Exponential backoff schedule.
+ *
+ * Computes delay as `base * factor^(attempt - 1)`:
+ *
+ * - Attempt 1: `base`
+ * - Attempt 2: `base * factor`
+ * - Attempt 3: `base * factor²`
+ * - ...
+ *
+ * Never stops — combine with {@link take} or {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // 100ms, 200ms, 400ms, 800ms, ...
+ * const exp = exponential("100ms");
+ *
+ * // 100ms, 150ms, 225ms, 338ms, ... (gentler growth)
+ * const gentle = exponential("100ms", 1.5);
+ * ```
+ *
+ * @group Constructors
+ */
+export const exponential = (base, factor = 2) => () => {
+    const baseMs = durationToMillis(base);
+    let attempt = 0;
+    return () => {
+        attempt++;
+        const rawDelay = baseMs * Math.pow(factor, attempt - 1);
+        const delay = Millis.orThrow(Math.max(0, Math.round(rawDelay)));
+        return ok([delay, delay]);
+    };
+};
+/**
+ * Linear backoff schedule.
+ *
+ * Delay increases linearly: `base * attempt`:
+ *
+ * - Attempt 1: `base`
+ * - Attempt 2: `base * 2`
+ * - Attempt 3: `base * 3`
+ * - ...
+ *
+ * Never stops — combine with {@link take} or {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // 100ms, 200ms, 300ms, 400ms, ...
+ * const lin = linear("100ms");
+ * ```
+ *
+ * @group Constructors
+ */
+export const linear = (base) => () => {
+    const ms = durationToMillis(base);
+    let attempt = 0;
+    return () => {
+        attempt++;
+        const delay = Millis.orThrow(ms * attempt);
+        return ok([delay, delay]);
+    };
+};
+/**
+ * Fibonacci backoff schedule.
+ *
+ * Delays follow the Fibonacci sequence, growing more slowly than exponential:
+ *
+ * - Attempt 1: `initial`
+ * - Attempt 2: `initial`
+ * - Attempt 3: `initial * 2`
+ * - Attempt 4: `initial * 3`
+ * - Attempt 5: `initial * 5`
+ * - ...
+ *
+ * Never stops — combine with {@link take} or {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, ...
+ * const fib = fibonacci("100ms");
+ * ```
+ *
+ * @group Constructors
+ */
+export const fibonacci = (initial) => () => {
+    const ms = durationToMillis(initial);
+    let index = 1;
+    return () => {
+        const delay = Millis.orThrow(ms * fibonacciAt(FibonacciIndex.orThrow(index)));
+        index++;
+        return ok([delay, delay]);
+    };
+};
+/**
+ * Fixed interval schedule aligned to time windows.
+ *
+ * Recurs on a fixed interval, outputting the repetition count (0, 1, 2, ...).
+ * Unlike {@link spaced}, which waits a duration _after_ each execution, `fixed`
+ * maintains a consistent cadence from when the schedule started.
+ *
+ * If execution takes longer than the interval, the next execution happens
+ * immediately but subsequent runs still align to the original window
+ * boundaries. This prevents "pile-up" while maintaining predictable timing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Health check every 5 seconds, aligned to windows
+ * const healthCheck = take(10)(fixed("5s"));
+ *
+ * // Cron-like behavior: run at consistent intervals
+ * const cronLike = fixed("1m");
+ * ```
+ *
+ * @group Constructors
+ */
+export const fixed = (interval) => (deps) => {
+    const intervalMs = durationToMillis(interval);
+    const metrics = createScheduleStepMetrics(deps);
+    let count = 0;
+    return () => {
+        const { elapsed } = metrics();
+        // Which window should we be in based on count?
+        const expectedWindowEnd = (count + 1) * intervalMs;
+        const runningBehind = intervalMs > 0 && elapsed >= expectedWindowEnd;
+        // Time until next window boundary
+        const remainder = intervalMs === 0 ? 0 : elapsed % intervalMs;
+        const boundary = intervalMs - remainder;
+        const delay = runningBehind ? 0 : boundary;
+        return ok([count++, delay]);
+    };
+};
+/**
+ * Divides the timeline into fixed windows and sleeps until the next boundary.
+ *
+ * Similar to {@link fixed}, but always sleeps until the next window boundary
+ * regardless of when the last execution started. Outputs the repetition count.
+ *
+ * Useful for aligning executions to regular intervals from the start time.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Execute at regular 5-second boundaries from start
+ * const aligned = windowed("5s");
+ * // If elapsed is 3s, waits 2s. If elapsed is 7s, waits 3s.
+ * ```
+ *
+ * @group Constructors
+ */
+export const windowed = (interval) => (deps) => {
+    const intervalMs = durationToMillis(interval);
+    const metrics = createScheduleStepMetrics(deps);
+    let count = 0;
+    return () => {
+        const { elapsed } = metrics();
+        const remainder = intervalMs === 0 ? 0 : elapsed % intervalMs;
+        const delay = intervalMs === 0 ? 0 : intervalMs - remainder;
+        return ok([count++, delay]);
+    };
+};
+/**
+ * A schedule that runs once with a single delay.
+ *
+ * Convenience for `take(1)(spaced(delay))`. Useful for simple one-shot delays.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Wait 1 second then stop
+ * const oneShot = fromDelay("1s");
+ * ```
+ *
+ * @group Constructors
+ */
+export const fromDelay = (delay) => take(1)(spaced(delay));
+/**
+ * A schedule that runs through a sequence of delays.
+ *
+ * Convenience for sequencing single-delay schedules. Useful for predefined
+ * retry patterns.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Custom retry sequence: 100ms, 500ms, 2s
+ * const custom = fromDelays("100ms", "500ms", "2s");
+ * ```
+ *
+ * @group Constructors
+ */
+export const fromDelays = (...delays) => sequenceSchedules(...delays.map((d) => fromDelay(d)));
+/**
+ * A schedule that outputs the total elapsed time since the schedule started.
+ *
+ * Never stops — combine with {@link take} or {@link maxElapsed} to limit. Useful
+ * for tracking how long a retry sequence has been running.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Track elapsed time alongside retries
+ * const withTiming = intersectSchedules(exponential("100ms"), elapsed);
+ * // Outputs: [[100, 0], [200, ~100], [400, ~300], ...]
+ *
+ * // Stop after 30 seconds of elapsed time
+ * const timeLimited = whileScheduleOutput((ms: Millis) => ms < 30000)(
+ *   elapsed,
+ * );
+ * ```
+ *
+ * @group Constructors
+ */
+export const elapsed = (deps) => {
+    const metrics = createScheduleStepMetrics(deps);
+    return () => ok([metrics().elapsed, minMillis]);
+};
+/**
+ * A schedule that runs for a specified duration then stops.
+ *
+ * Outputs the elapsed time. Useful for time-boxed operations or combining with
+ * other schedules to create time-limited variants.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Run for at most 30 seconds
+ * const timeLimited = during("30s");
+ *
+ * // Combine with exponential for time-boxed retry
+ * const timedRetry = intersectSchedules(
+ *   exponential("100ms"),
+ *   during("10s"),
+ * );
+ * ```
+ *
+ * @group Constructors
+ */
+export const during = (duration) => whileScheduleOutput((ms) => ms <= durationToMillis(duration))(elapsed);
+/**
+ * A schedule that always outputs a constant value.
+ *
+ * Never stops — combine with {@link take} or {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Always output "retry"
+ * const labeled = always("retry");
+ *
+ * // Combine with timing
+ * const withLabel = intersectSchedules(
+ *   exponential("100ms"),
+ *   always("backoff"),
+ * );
+ * ```
+ *
+ * @group Constructors
+ */
+export const always = (value) => mapSchedule(() => value)(forever);
+/**
+ * Creates a schedule by unfolding a state.
+ *
+ * Each step outputs the current state and computes the next state using the
+ * provided function. Never stops — combine with {@link take} or
+ * {@link maxElapsed} to limit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Counter: 0, 1, 2, 3, ...
+ * const counter = unfoldSchedule(0, (n) => n + 1);
+ *
+ * // Custom backoff: 100, 150, 225, 338, ... (×1.5 each time)
+ * const customBackoff = unfoldSchedule(100, (delay) =>
+ *   Math.round(delay * 1.5),
+ * );
+ *
+ * // State machine
+ * type Phase = "init" | "warmup" | "active";
+ * const phases = unfoldSchedule<Phase>("init", (phase) => {
+ *   switch (phase) {
+ *     case "init":
+ *       return "warmup";
+ *     case "warmup":
+ *       return "active";
+ *     case "active":
+ *       return "active";
+ *   }
+ * });
+ * ```
+ *
+ * @group Constructors
+ */
+export const unfoldSchedule = (initial, next) => () => {
+    let state = initial;
+    return () => {
+        const current = state;
+        state = next(state);
+        return ok([current, minMillis]);
+    };
+};
+/**
+ * Limits a schedule to a maximum number of attempts.
+ *
+ * After `n` attempts, returns `Err(Done<void>)` (stop).
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Exponential backoff, max 3 retries
+ * const limited = take(3)(exponential("100ms"));
+ * // Attempt 1: 100ms, Attempt 2: 200ms, Attempt 3: 400ms, Attempt 4: Err(Done<void>)
+ * ```
+ *
+ * @group Limiting
+ */
+export const take = (n) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    let attempt = 0;
+    return (input) => {
+        attempt++;
+        if (attempt > n)
+            return err(done());
+        return step(input);
+    };
+};
+/**
+ * Limits schedule execution to a maximum elapsed time.
+ *
+ * After `duration` has elapsed since the schedule started, returns
+ * `Err(Done<void>)`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Retry for at most 30 seconds
+ * const timeLimited = maxElapsed("30s")(exponential("1s"));
+ * ```
+ *
+ * @group Limiting
+ */
+export const maxElapsed = (duration) => {
+    const maxMs = durationToMillis(duration);
+    return (schedule) => (deps) => {
+        const step = schedule(deps);
+        const metrics = createScheduleStepMetrics(deps);
+        return (input) => {
+            const { elapsed } = metrics();
+            return elapsed >= maxMs ? err(done()) : step(input);
+        };
+    };
+};
+/**
+ * Caps the delay to a maximum value.
+ *
+ * If the schedule returns a delay greater than `max`, returns `max` instead.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Exponential capped at 10 seconds
+ * const capped = maxDelay("10s")(exponential("1s"));
+ * // 1s, 2s, 4s, 8s, 10s, 10s, 10s, ...
+ * ```
+ *
+ * @group Limiting
+ */
+export const maxDelay = (max) => {
+    const maxMs = durationToMillis(max);
+    return (schedule) => (deps) => {
+        const step = schedule(deps);
+        return (input) => {
+            const result = step(input);
+            if (!result.ok)
+                return result;
+            const [output, delay] = result.value;
+            return ok([output, Millis.orThrow(Math.min(delay, maxMs))]);
+        };
+    };
+};
+/**
+ * Adds randomized jitter to delays.
+ *
+ * Jitter helps prevent "thundering herd" when many clients retry simultaneously
+ * after a service recovers. The delay is randomized within a range:
+ *
+ * - `factor = 0` — no jitter (original delay)
+ * - `factor = 0.5` — delay varies ±50% (e.g., 1s becomes 500ms-1500ms)
+ * - `factor = 1` — full jitter, delay varies 0-200% (e.g., 1s becomes 0-2s)
+ *
+ * ### Example
+ *
+ * ```ts
+ * // AWS-style full jitter
+ * const awsStyle = jitter(1)(exponential("1s"));
+ *
+ * // Conservative jitter (±25%)
+ * const conservative = jitter(0.25)(exponential("1s"));
+ * ```
+ *
+ * @group Delay
+ */
+export const jitter = (factor = 0.5) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [output, delay] = result.value;
+        const jittered = delay * (1 - factor + deps.random.next() * 2 * factor);
+        return ok([output, Millis.orThrow(Math.max(0, Math.round(jittered)))]);
+    };
+};
+/**
+ * Adds an initial delay before the first attempt.
+ *
+ * Subsequent attempts use the schedule's normal delays.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Wait 1s before first attempt, then exponential backoff
+ * const withWarmup = delayed("1s")(exponential("100ms"));
+ * ```
+ *
+ * @group Delay
+ */
+export const delayed = (initialDelay) => {
+    const initialMs = durationToMillis(initialDelay);
+    return (schedule) => (deps) => {
+        const step = schedule(deps);
+        let first = true;
+        return (input) => {
+            const result = step(input);
+            if (!result.ok)
+                return result;
+            if (first) {
+                first = false;
+                return ok([result.value[0], initialMs]);
+            }
+            return result;
+        };
+    };
+};
+/**
+ * Adds a fixed delay to the schedule's existing delay.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Add 500ms to each delay
+ * const slower = addDelay("500ms")(exponential("100ms"));
+ * // Delays: 600ms, 700ms, 900ms, 1300ms, ...
+ * ```
+ *
+ * @group Delay
+ */
+export const addDelay = (extra) => {
+    const extraMs = durationToMillis(extra);
+    return modifyDelay((d) => d + extraMs);
+};
+/**
+ * Transforms the delay of a schedule.
+ *
+ * More flexible than {@link maxDelay} — can implement any delay transformation.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Double all delays
+ * const slower = modifyDelay((d) => d * 2)(exponential("100ms"));
+ *
+ * // Cap at 10s (equivalent to maxDelay)
+ * const capped = modifyDelay((d) => Math.min(d, 10000))(exponential("1s"));
+ * ```
+ *
+ * @group Delay
+ */
+export const modifyDelay = (f) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [output, delay] = result.value;
+        return ok([output, Millis.orThrow(Math.max(0, Math.round(f(delay))))]);
+    };
+};
+/**
+ * Adjusts delay by subtracting execution time.
+ *
+ * A simple combinator that subtracts the previous execution time from the
+ * schedule's delay. If execution took longer than the delay, returns 0.
+ *
+ * For window-aligned scheduling, use {@link fixed} instead.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Poll every 5s, accounting for execution time
+ * const polling = compensate(spaced("5s"));
+ * // If poll takes 1s → wait 4s. If poll takes 6s → wait 0s.
+ * ```
+ *
+ * @group Delay
+ */
+export const compensate = (schedule) => (deps) => {
+    const step = schedule(deps);
+    const metrics = createScheduleStepMetrics(deps);
+    return (input) => {
+        const { elapsedSincePrevious } = metrics();
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [output, delay] = result.value;
+        const adjusted = Math.max(0, delay - elapsedSincePrevious);
+        return ok([output, adjusted]);
+    };
+};
+/**
+ * Continues while the input satisfies a predicate.
+ *
+ * Stops (returns `Err(Done<void>)`) when {@link Predicate} returns `false`.
+ * Useful for input-aware retry strategies, e.g., only retry certain error
+ * types.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface MyError extends Typed<"Transient" | "Fatal"> {}
+ *
+ * // Only retry transient errors
+ * const retryTransient = whileScheduleInput(
+ *   (error: MyError) => error.type === "Transient",
+ * )(exponential("100ms"));
+ * ```
+ *
+ * @group Filtering
+ */
+export const whileScheduleInput = (predicate) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        if (!predicate(input))
+            return err(done());
+        return step(input);
+    };
+};
+/**
+ * Continues until the input satisfies a predicate.
+ *
+ * Stops (returns `Err(Done<void>)`) when {@link Predicate} returns `true`.
+ * Useful for stopping retry on specific error conditions.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface MyError extends Typed<"Transient" | "Fatal"> {}
+ *
+ * // Stop retrying on fatal errors
+ * const stopOnFatal = untilScheduleInput(
+ *   (error: MyError) => error.type === "Fatal",
+ * )(exponential("100ms"));
+ * ```
+ *
+ * @group Filtering
+ */
+export const untilScheduleInput = (predicate) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        if (predicate(input))
+            return err(done());
+        return step(input);
+    };
+};
+/**
+ * Continues while the output satisfies a predicate.
+ *
+ * Stops (returns `Err(Done<void>)`) when {@link Predicate} returns `false`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Continue while delay is under 5 seconds
+ * const capped = whileScheduleOutput((delay: Millis) => delay < 5000)(
+ *   exponential("1s"),
+ * );
+ * ```
+ *
+ * @group Filtering
+ */
+export const whileScheduleOutput = (predicate) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        if (!predicate(result.value[0]))
+            return err(done());
+        return result;
+    };
+};
+/**
+ * Continues until the output satisfies a predicate.
+ *
+ * Stops (returns `Err(Done<void>)`) when {@link Predicate} returns `true`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Stop when delay reaches 1 second
+ * const limited = untilScheduleOutput((delay: Millis) => delay >= 1000)(
+ *   exponential("100ms"),
+ * );
+ * ```
+ *
+ * @group Filtering
+ */
+export const untilScheduleOutput = (predicate) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        if (predicate(result.value[0]))
+            return err(done());
+        return result;
+    };
+};
+/**
+ * Resets the schedule after a period of inactivity.
+ *
+ * If `elapsedSincePrevious` is greater than or equal to `duration`, creates a
+ * fresh state. Useful for circuit breakers that should "forget" failures after
+ * idle time.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Reset retry count after 1 minute of success
+ * const circuitBreaker = resetScheduleAfter("1m")(
+ *   take(5)(exponential("1s")),
+ * );
+ * ```
+ *
+ * @group State
+ */
+export const resetScheduleAfter = (duration) => {
+    const resetMs = durationToMillis(duration);
+    return (schedule) => (deps) => {
+        let step = schedule(deps);
+        const metrics = createScheduleStepMetrics(deps);
+        return (input) => {
+            const { elapsedSincePrevious } = metrics();
+            if (elapsedSincePrevious >= resetMs) {
+                step = schedule(deps);
+            }
+            return step(input);
+        };
+    };
+};
+/**
+ * Transforms the output of a schedule.
+ *
+ * The delay (second tuple element) remains unchanged.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { exponential, mapSchedule } from "@evolu/common";
+ *
+ * const schedule = mapSchedule((delay) => ({
+ *   delay,
+ *   doubled: delay * 2,
+ * }))(exponential("100ms"));
+ * ```
+ *
+ * @group Transform
+ */
+export const mapSchedule = (f) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [output, delay] = result.value;
+        return ok([f(output), delay]);
+    };
+};
+export function passthrough(schedule) {
+    if (schedule === undefined) {
+        return () => (input) => ok([input, minMillis]);
+    }
+    return (deps) => {
+        const step = schedule(deps);
+        return (input) => {
+            const result = step(input);
+            if (!result.ok)
+                return result;
+            return ok([input, result.value[1]]);
+        };
+    };
+}
+/**
+ * Folds over the outputs of a schedule, accumulating state.
+ *
+ * Each step outputs the accumulated value. Useful for tracking totals,
+ * collecting outputs, or building up metadata across attempts.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Track total delay spent
+ * const withTotal = foldSchedule(
+ *   0,
+ *   (total: number, delay: Millis) => total + delay,
+ * )(exponential("100ms"));
+ * // Outputs: 100, 300, 700, 1500, ... (cumulative)
+ *
+ * // Collect all outputs
+ * const collected = foldSchedule([] as Millis[], (acc, delay: Millis) => [
+ *   ...acc,
+ *   delay,
+ * ])(take(3)(spaced("1s")));
+ * // Outputs: [1000], [1000, 1000], [1000, 1000, 1000]
+ *
+ * // Count attempts with custom output
+ * const counted = foldSchedule(
+ *   { attempts: 0, lastDelay: 0 as Millis },
+ *   (acc, delay: Millis) => ({
+ *     attempts: acc.attempts + 1,
+ *     lastDelay: delay,
+ *   }),
+ * )(exponential("100ms"));
+ * ```
+ *
+ * @group Transform
+ */
+export const foldSchedule = (initial, f) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    let acc = initial;
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [output, delay] = result.value;
+        acc = f(acc, output);
+        return ok([acc, delay]);
+    };
+};
+/**
+ * Wraps a schedule to output the number of repetitions instead of original
+ * output.
+ *
+ * Outputs 0, 1, 2, ... while preserving the underlying schedule's timing and
+ * termination behavior.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Track how many retries occurred
+ * const counted = repetitions(exponential("100ms"));
+ * // Outputs: 0, 1, 2, ... with exponential delays
+ * ```
+ *
+ * @group Transform
+ */
+export const repetitions = (schedule) => foldSchedule(-1, (n) => n + 1)(schedule);
+/**
+ * Outputs the delay between recurrences.
+ *
+ * Wraps a schedule to output its delay (in milliseconds) instead of the
+ * original output. Useful for monitoring or logging delay patterns.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Monitor exponential delays
+ * const monitorDelays = delays(exponential("100ms"));
+ * // Outputs: 100, 200, 400, 800, ... (the delays themselves)
+ *
+ * // Log delays for debugging
+ * const logged = tapScheduleOutput(console.log)(
+ *   delays(exponential("100ms")),
+ * );
+ * ```
+ *
+ * @group Transform
+ */
+export const delays = (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        const [, delay] = result.value;
+        return ok([delay, delay]);
+    };
+};
+/**
+ * Collects all outputs into an array.
+ *
+ * Each step outputs an array containing all outputs so far.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Collect all delays
+ * const collected = collectAllScheduleOutputs(take(3)(spaced("100ms")));
+ * // Outputs: [100], [100, 100], [100, 100, 100]
+ * ```
+ *
+ * @group Collection
+ */
+export const collectAllScheduleOutputs = (schedule) => foldSchedule([], (acc, out) => [...acc, out])(schedule);
+/**
+ * Collects all inputs into an array.
+ *
+ * Each step outputs an array containing all inputs received so far. Mirror of
+ * {@link collectAllScheduleOutputs} but for inputs.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Collect all errors during retry
+ * const errorHistory = collectScheduleInputs(
+ *   take(3)(exponential("100ms")),
+ * );
+ * // After 3 retries, outputs array of all error inputs
+ * ```
+ *
+ * @group Collection
+ */
+export const collectScheduleInputs = (schedule) => collectAllScheduleOutputs(passthrough(schedule));
+/**
+ * Collects outputs while a predicate is true.
+ *
+ * More flexible than {@link collectAllScheduleOutputs} — stops collecting when
+ * the predicate returns false.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Collect delays while under 1 second
+ * const smallDelays = collectWhileScheduleOutput(
+ *   (delay: Millis) => delay < 1000,
+ * )(exponential("100ms"));
+ * // Outputs: [100], [100, 200], [100, 200, 400], [100, 200, 400, 800], stops
+ * ```
+ *
+ * @group Collection
+ */
+export const collectWhileScheduleOutput = (predicate) => (schedule) => collectAllScheduleOutputs(whileScheduleOutput(predicate)(schedule));
+/**
+ * Collects outputs until a predicate becomes true.
+ *
+ * Mirror of {@link collectWhileScheduleOutput} — stops collecting when the
+ * predicate returns true (inclusive of the matching output).
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Collect delays until reaching 1 second
+ * const untilLarge = collectUntilScheduleOutput(
+ *   (delay: Millis) => delay >= 1000,
+ * )(exponential("100ms"));
+ * // Outputs: [100], [100, 200], [100, 200, 400], [100, 200, 400, 800], stops
+ * ```
+ *
+ * @group Collection
+ */
+export const collectUntilScheduleOutput = (predicate) => (schedule) => collectAllScheduleOutputs(untilScheduleOutput(predicate)(schedule));
+/**
+ * Sequences schedules: runs each until it stops, then continues with the next.
+ *
+ * Useful for adaptive strategies that start aggressive and become more
+ * conservative over time.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Fast retries first, then slower, then final fallback
+ * const adaptive = sequenceSchedules(
+ *   take(3)(exponential("100ms")),
+ *   take(5)(fixed("500ms")),
+ *   fixed("1s"),
+ * );
+ * // Runs: 100ms, 200ms, 400ms, then 500ms×5, then 1s forever
+ * ```
+ *
+ * @group Composition
+ */
+export const sequenceSchedules = (...schedules) => (deps) => {
+    let index = 0;
+    let currentStep = schedules.length > 0 ? schedules[0](deps) : null;
+    return (input) => {
+        while (currentStep !== null) {
+            const result = currentStep(input);
+            if (result.ok)
+                return result;
+            // Current exhausted, try next.
+            index++;
+            currentStep = index < schedules.length ? schedules[index](deps) : null;
+        }
+        return err(done());
+    };
+};
+/**
+ * Combines two schedules with AND semantics.
+ *
+ * Continues only while both schedules want to continue. Uses the maximum delay.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Retry up to 5 times AND within 30 seconds (both conditions must be met)
+ * const both = intersectSchedules(
+ *   take(5)(exponential("1s")),
+ *   maxElapsed("30s")(forever),
+ * );
+ * ```
+ *
+ * @group Composition
+ */
+export const intersectSchedules = (a, b) => (deps) => {
+    const stepA = a(deps);
+    const stepB = b(deps);
+    return (input) => {
+        const resultA = stepA(input);
+        const resultB = stepB(input);
+        if (!resultA.ok || !resultB.ok)
+            return err(done());
+        const [outputA, delayA] = resultA.value;
+        const [outputB, delayB] = resultB.value;
+        return ok([[outputA, outputB], Millis.orThrow(Math.max(delayA, delayB))]);
+    };
+};
+/**
+ * Combines two schedules with OR semantics.
+ *
+ * Continues while either schedule wants to continue. Uses the minimum delay.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Retry up to 5 times OR up to 30 seconds, whichever is longer
+ * const either = unionSchedules(
+ *   take(5)(exponential("1s")),
+ *   maxElapsed("30s")(forever),
+ * );
+ * ```
+ *
+ * @group Composition
+ */
+export const unionSchedules = (a, b) => (deps) => {
+    const stepA = a(deps);
+    const stepB = b(deps);
+    return (input) => {
+        const resultA = stepA(input);
+        const resultB = stepB(input);
+        if (!resultA.ok && !resultB.ok)
+            return err(done());
+        if (!resultA.ok)
+            return resultB;
+        if (!resultB.ok)
+            return resultA;
+        const [outputA, delayA] = resultA.value;
+        const [outputB, delayB] = resultB.value;
+        // Use minimum delay, output from the one with smaller delay
+        const minDelay = Math.min(delayA, delayB);
+        return delayA <= delayB
+            ? ok([outputA, minDelay])
+            : ok([outputB, minDelay]);
+    };
+};
+/**
+ * Selects between two schedules based on input.
+ *
+ * If {@link Predicate} returns `true`, uses `altSchedule`; otherwise uses the
+ * base schedule. Useful for implementing error-aware backoff where certain
+ * errors (e.g., throttling) use different delays.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface MyError extends Typed<"Throttled" | "NetworkError"> {}
+ *
+ * const awsWithThrottling = whenInput<MyError, Millis>(
+ *   (error) => error.type === "Throttled",
+ *   exponential("1s"), // throttled: 1s base
+ * )(exponential("100ms")); // normal: 100ms base
+ * ```
+ *
+ * @group Composition
+ */
+export const whenInput = (predicate, altSchedule) => (schedule) => (deps) => {
+    const normalStep = schedule(deps);
+    const altStep = altSchedule(deps);
+    return (input) => {
+        if (predicate(input))
+            return altStep(input);
+        return normalStep(input);
+    };
+};
+/**
+ * Executes a side effect for every output without altering the schedule.
+ *
+ * Useful for logging, monitoring, or debugging without changing schedule
+ * behavior.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Log each delay for debugging
+ * const logged = tapScheduleOutput((delay: Millis) => {
+ *   console.log(`Next delay: ${delay}ms`);
+ * })(exponential("100ms"));
+ *
+ * // Track metrics
+ * const recorded: Array<Millis> = [];
+ * const tracked = tapScheduleOutput((delay: Millis) => {
+ *   recorded.push(delay);
+ * })(retryStrategyAws);
+ * ```
+ *
+ * @group Side effects
+ */
+export const tapScheduleOutput = (f) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        const result = step(input);
+        if (!result.ok)
+            return result;
+        f(result.value[0]);
+        return result;
+    };
+};
+/**
+ * Executes a side effect for every input without altering the schedule.
+ *
+ * Useful for logging errors during retry or monitoring what values are being
+ * processed.
+ *
+ * ### Example
+ *
+ * ```ts
+ * interface MyError extends Typed<string> {}
+ *
+ * const retrySchedule: Schedule<Millis, MyError> = exponential("100ms");
+ *
+ * // Log each error during retry
+ * const logged = tapScheduleInput((error: MyError) => {
+ *   console.log(`Retrying after error: ${error.type}`);
+ * })(retrySchedule);
+ *
+ * // Track retry reasons
+ * const reasons: Array<string> = [];
+ * const tracked = tapScheduleInput((error: MyError) => {
+ *   reasons.push(error.type);
+ * })(retrySchedule);
+ * ```
+ *
+ * @group Side effects
+ */
+export const tapScheduleInput = (f) => (schedule) => (deps) => {
+    const step = schedule(deps);
+    return (input) => {
+        f(input);
+        return step(input);
+    };
+};
+/**
+ * AWS standard retry strategy.
+ *
+ * Exponential backoff (100ms base), max 2 retries (3 total attempts), 20s cap,
+ * full jitter.
+ *
+ * @group Retry Strategies
+ * @see https://github.com/aws/aws-sdk-java-v2/blob/master/core/retries/src/main/java/software/amazon/awssdk/retries/StandardRetryStrategy.java
+ * @see https://github.com/aws/aws-sdk-java-v2/blob/master/core/retries/src/main/java/software/amazon/awssdk/retries/DefaultRetryStrategy.java
+ */
+export const retryStrategyAws = /*#__PURE__*/ jitter(1)(
+/*#__PURE__*/ maxDelay("20s")(
+/*#__PURE__*/ take(2)(/*#__PURE__*/ exponential("100ms"))));