awaitly 1.35.0 → 2.0.0

package/dist/retry.d.cts

@@ -1,388 +0,0 @@
-import { Duration } from './duration.cjs';
-export { days, hours, isDuration, millis, minutes, seconds, toDays, toHours, toMillis, toMinutes, toSeconds } from './duration.cjs';
-
-/**
- * awaitly/schedule
- *
- * Composable scheduling primitives inspired by Effect's Schedule module.
- * Build complex retry and polling strategies by composing simple building blocks.
- *
- * @example
- * ```typescript
- * // "Exponential backoff with jitter, max 5 attempts, then poll every minute"
- * const schedule = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.jittered(0.2))
- *   .pipe(Schedule.upTo(5))
- *   .pipe(Schedule.andThen(Schedule.spaced(Duration.minutes(1))))
- *
- * // Use with workflows
- * const result = await step('fetchData', () => fetchData(), { schedule })
- * ```
- */
-
-/**
- * The state maintained by a schedule during execution.
- */
-interface ScheduleState {
-    /** Number of iterations completed */
-    readonly iterations: number;
-    /** Total elapsed time since schedule started */
-    readonly elapsed: Duration;
-    /** The last input received (if any) */
-    readonly lastInput?: unknown;
-    /** The last output produced (if any) */
-    readonly lastOutput?: unknown;
-    /** Combinator-specific metadata (used by andThen, union, intersect, etc.) */
-    readonly meta?: unknown;
-}
-/**
- * Decision returned by a schedule step.
- * Combinators can optionally provide `nextState` to thread custom state through execution.
- */
-type ScheduleDecision<Out> = {
-    readonly _tag: "Continue";
-    readonly delay: Duration;
-    readonly output: Out;
-    readonly nextState?: ScheduleState;
-} | {
-    readonly _tag: "Done";
-};
-/**
- * A schedule that repeats forever with no delay.
- */
-declare function forever<In = unknown>(): Schedule<In, number>;
-/**
- * A schedule that repeats exactly n times.
- *
- * @example
- * ```typescript
- * const thrice = Schedule.recurs(3)
- * ```
- */
-declare function recurs<In = unknown>(n: number): Schedule<In, number>;
-/**
- * A schedule that repeats once.
- */
-declare function once<In = unknown>(): Schedule<In, void>;
-/**
- * A schedule that always stops immediately.
- */
-declare function stop<In = unknown>(): Schedule<In, never>;
-/**
- * A schedule that waits a fixed duration between each iteration.
- *
- * @example
- * ```typescript
- * const pollEvery5s = Schedule.spaced(Duration.seconds(5))
- * ```
- */
-declare function spaced<In = unknown>(delay: Duration): Schedule<In, number>;
-/**
- * Alias for spaced - a fixed interval schedule.
- */
-declare const fixed: typeof spaced;
-/**
- * A schedule with exponentially increasing delays.
- * delay(n) = base * factor^n
- *
- * @example
- * ```typescript
- * // 100ms, 200ms, 400ms, 800ms, ...
- * const exponential = Schedule.exponential(Duration.millis(100))
- *
- * // With custom factor: 100ms, 300ms, 900ms, ...
- * const triple = Schedule.exponential(Duration.millis(100), 3)
- * ```
- */
-declare function exponential<In = unknown>(base: Duration, factor?: number): Schedule<In, Duration>;
-/**
- * A schedule with linearly increasing delays.
- * delay(n) = base * (n + 1)
- *
- * @example
- * ```typescript
- * // 100ms, 200ms, 300ms, 400ms, ...
- * const linear = Schedule.linear(Duration.millis(100))
- * ```
- */
-declare function linear<In = unknown>(base: Duration): Schedule<In, Duration>;
-/**
- * A schedule with fibonacci-sequence delays.
- * delay(n) follows fibonacci: base, base, 2*base, 3*base, 5*base, ...
- *
- * @example
- * ```typescript
- * // 100ms, 100ms, 200ms, 300ms, 500ms, 800ms, ...
- * const fib = Schedule.fibonacci(Duration.millis(100))
- * ```
- */
-declare function fibonacci<In = unknown>(base: Duration): Schedule<In, Duration>;
-/**
- * Limit a schedule to at most n iterations.
- *
- * @example
- * ```typescript
- * // Exponential backoff, max 5 attempts
- * const limited = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.upTo(5))
- * ```
- */
-declare function upTo<In, Out>(n: number): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Limit a schedule by total elapsed time.
- *
- * @example
- * ```typescript
- * // Retry for at most 30 seconds
- * const timeLimited = Schedule.spaced(Duration.seconds(1))
- *   .pipe(Schedule.upToElapsed(Duration.seconds(30)))
- * ```
- */
-declare function upToElapsed<In, Out>(maxElapsed: Duration): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Cap the maximum delay of a schedule.
- *
- * @example
- * ```typescript
- * // Exponential, but never more than 30 seconds
- * const capped = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.maxDelay(Duration.seconds(30)))
- * ```
- */
-declare function maxDelay<In, Out>(max: Duration): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Set a minimum delay for a schedule.
- *
- * @example
- * ```typescript
- * const atLeast1s = schedule.pipe(Schedule.minDelay(Duration.seconds(1)))
- * ```
- */
-declare function minDelay<In, Out>(min: Duration): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Continue while a predicate on the input returns true.
- *
- * @example
- * ```typescript
- * // Retry while the error is transient
- * const retryTransient = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.whileInput((err: Error) => err.message.includes("ECONNRESET")))
- * ```
- */
-declare function whileInput<In, Out>(predicate: (input: In) => boolean): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Continue while a predicate on the output returns true.
- *
- * @example
- * ```typescript
- * // Poll until status is "ready"
- * const untilReady = Schedule.spaced(Duration.seconds(1))
- *   .pipe(Schedule.whileOutput((status: string) => status !== "ready"))
- * ```
- */
-declare function whileOutput<In, Out>(predicate: (output: Out) => boolean): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Continue until a predicate on the input returns true.
- * Opposite of whileInput.
- */
-declare function untilInput<In, Out>(predicate: (input: In) => boolean): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Continue until a predicate on the output returns true.
- * Opposite of whileOutput.
- */
-declare function untilOutput<In, Out>(predicate: (output: Out) => boolean): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Add random jitter to delays to prevent thundering herd.
- *
- * @param factor - Jitter factor (0.0 to 1.0). Delay will be multiplied by (1 - factor) to (1 + factor).
- *
- * @example
- * ```typescript
- * // ±20% jitter
- * const jittered = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.jittered(0.2))
- * ```
- */
-declare function jittered<In, Out>(factor?: number): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Add a fixed random delay to each iteration.
- *
- * @example
- * ```typescript
- * // Add 0-500ms random delay
- * const randomized = schedule.pipe(Schedule.addDelay(Duration.millis(500)))
- * ```
- */
-declare function addDelay<In, Out>(maxExtra: Duration): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Chain two schedules: run the first until done, then run the second.
- * The second schedule starts with fresh state when it begins.
- *
- * @example
- * ```typescript
- * // 5 exponential retries, then poll every minute
- * const strategy = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.upTo(5))
- *   .pipe(Schedule.andThen(Schedule.spaced(Duration.minutes(1))))
- * ```
- */
-declare function andThen<In, Out1, Out2>(second: Schedule<In, Out2>): (first: Schedule<In, Out1>) => Schedule<In, Out1 | Out2>;
-/**
- * Run two schedules in parallel, using the shorter delay.
- * Both schedules advance their state independently.
- *
- * @example
- * ```typescript
- * // Use whichever delay is shorter
- * const union = Schedule.union(
- *   Schedule.exponential(Duration.millis(100)),
- *   Schedule.spaced(Duration.seconds(1))
- * )
- * ```
- */
-declare function union<In, Out1, Out2>(first: Schedule<In, Out1>, second: Schedule<In, Out2>): Schedule<In, [Out1, Out2]>;
-/**
- * Run two schedules in parallel, using the longer delay.
- * Both schedules advance their state independently. Stops when either schedule stops.
- *
- * @example
- * ```typescript
- * // Use whichever delay is longer
- * const intersect = Schedule.intersect(
- *   Schedule.exponential(Duration.millis(100)),
- *   Schedule.spaced(Duration.seconds(1))
- * )
- * ```
- */
-declare function intersect<In, Out1, Out2>(first: Schedule<In, Out1>, second: Schedule<In, Out2>): Schedule<In, [Out1, Out2]>;
-/**
- * Transform the output of a schedule.
- *
- * @example
- * ```typescript
- * const withIteration = Schedule.spaced(Duration.seconds(1))
- *   .pipe(Schedule.map((n) => ({ attempt: n + 1 })))
- * ```
- */
-declare function map<In, Out, NewOut>(fn: (output: Out) => NewOut): (schedule: Schedule<In, Out>) => Schedule<In, NewOut>;
-/**
- * Perform a side effect on each iteration.
- *
- * @example
- * ```typescript
- * const logged = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.tap((delay) => console.log(`Waiting ${delay}ms`)))
- * ```
- */
-declare function tap<In, Out>(fn: (output: Out, state: ScheduleState) => void): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Modify the delay of a schedule.
- *
- * @example
- * ```typescript
- * const doubled = schedule.pipe(Schedule.modifyDelay(d => Duration.multiply(d, 2)))
- * ```
- */
-declare function modifyDelay<In, Out>(fn: (delay: Duration, output: Out) => Duration): (schedule: Schedule<In, Out>) => Schedule<In, Out>;
-/**
- * Create an iterator for running a schedule step-by-step.
- *
- * @example
- * ```typescript
- * const runner = Schedule.run(mySchedule)
- *
- * while (true) {
- *   const next = runner.next(lastResult)
- *   if (next.done) break
- *   await sleep(next.value.delay)
- * }
- * ```
- */
-declare function run<In, Out>(schedule: Schedule<In, Out>): {
-    next: (input: In) => {
-        done: false;
-        value: {
-            delay: Duration;
-            output: Out;
-        };
-    } | {
-        done: true;
-    };
-};
-/**
- * Get all delays from a schedule (for testing/visualization).
- * Runs the schedule with undefined input until it completes or reaches maxIterations.
- */
-declare function delays<Out>(schedule: Schedule<undefined, Out>, maxIterations?: number): Duration[];
-/**
- * A schedule with pipe support for method chaining.
- */
-type PipedSchedule<In, Out> = Schedule<In, Out> & {
-    pipe: <NewOut>(fn: (s: Schedule<In, Out>) => Schedule<In, NewOut>) => PipedSchedule<In, NewOut>;
-} & {
-    pipe: <R>(fn: (s: Schedule<In, Out>) => R) => R;
-};
-/**
- * A Schedule defines a recurring pattern with delays and outputs.
- *
- * @typeParam In - The input type (from retry attempts, etc.)
- * @typeParam Out - The output type (often the delay or iteration count)
- */
-interface Schedule<In = unknown, Out = unknown> {
-    readonly _tag: "Schedule";
-    /** Compute the next step given input and current state */
-    readonly step: (input: In, state: ScheduleState) => ScheduleDecision<Out>;
-    /** Initial state for this schedule */
-    readonly initial: ScheduleState;
-}
-/**
- * Schedule namespace for composable scheduling.
- *
- * @example
- * ```typescript
- * import { Schedule, Duration } from "awaitly";
- *
- * // Exponential backoff with jitter, max 5 attempts
- * const retry = Schedule.exponential(Duration.millis(100))
- *   .pipe(Schedule.jittered(0.2))
- *   .pipe(Schedule.upTo(5))
- *   .pipe(Schedule.maxDelay(Duration.seconds(30)))
- *
- * // Then poll every minute forever
- * const poll = Schedule.spaced(Duration.minutes(1))
- *
- * // Chain them
- * const strategy = retry.pipe(Schedule.andThen(poll))
- * ```
- */
-declare const Schedule: {
-    readonly forever: <In = unknown>() => PipedSchedule<In, number>;
-    readonly once: <In = unknown>() => PipedSchedule<In, void>;
-    readonly recurs: <In = unknown>(n: number) => PipedSchedule<In, number>;
-    readonly stop: typeof stop;
-    readonly spaced: <In = unknown>(delay: Duration) => PipedSchedule<In, number>;
-    readonly fixed: <In = unknown>(delay: Duration) => PipedSchedule<In, number>;
-    readonly exponential: <In = unknown>(base: Duration, factor?: number) => PipedSchedule<In, Duration>;
-    readonly linear: <In = unknown>(base: Duration) => PipedSchedule<In, Duration>;
-    readonly fibonacci: <In = unknown>(base: Duration) => PipedSchedule<In, Duration>;
-    readonly upTo: typeof upTo;
-    readonly upToElapsed: typeof upToElapsed;
-    readonly maxDelay: typeof maxDelay;
-    readonly minDelay: typeof minDelay;
-    readonly whileInput: typeof whileInput;
-    readonly whileOutput: typeof whileOutput;
-    readonly untilInput: typeof untilInput;
-    readonly untilOutput: typeof untilOutput;
-    readonly jittered: typeof jittered;
-    readonly addDelay: typeof addDelay;
-    readonly andThen: typeof andThen;
-    readonly union: <In, Out1, Out2>(first: Schedule<In, Out1>, second: Schedule<In, Out2>) => PipedSchedule<In, [Out1, Out2]>;
-    readonly intersect: <In, Out1, Out2>(first: Schedule<In, Out1>, second: Schedule<In, Out2>) => PipedSchedule<In, [Out1, Out2]>;
-    readonly map: typeof map;
-    readonly tap: typeof tap;
-    readonly modifyDelay: typeof modifyDelay;
-    readonly run: typeof run;
-    readonly delays: typeof delays;
-};
-
-export { Duration, Duration as DurationType, Schedule, type ScheduleDecision, type ScheduleState, Schedule as ScheduleType, addDelay, andThen, delays, exponential, fibonacci, fixed, forever, intersect, jittered, linear, map, maxDelay, minDelay, modifyDelay, once, recurs, run, spaced, stop, tap, union, untilInput, untilOutput, upTo, upToElapsed, whileInput, whileOutput };