scheduling

Scheduling in Effect

Overview

Effect's Schedule type describes patterns for:

• Retrying failed operations
• Repeating successful operations
• Polling at intervals
• Backoff strategies for resilience

Schedule<Out, In, Requirements>;
//       ^^^  ^^ Output and input types

Built-In Schedules

Fixed Intervals

import { Schedule } from "effect";

const everySecond = Schedule.spaced("1 second");

const fixed = Schedule.fixed("500 millis");

Recurrence Limits

const fiveTimes = Schedule.recurs(5);

const once = Schedule.once;

const forever = Schedule.forever;

Exponential Backoff

const exponential = Schedule.exponential("100 millis");

const capped = Schedule.exponential("100 millis").pipe(Schedule.upTo("30 seconds"));

const jittered = Schedule.exponential("100 millis").pipe(Schedule.jittered);

Time-Based Limits

const forOneMinute = Schedule.spaced("1 second").pipe(Schedule.upTo("1 minute"));

const untilSuccess = Schedule.recurWhile((result) => result.status === "pending");

Using Schedules

Effect.retry - Retry on Failure

const resilientFetch = fetchData().pipe(
  Effect.retry(Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5)))),
);

Effect.repeat - Repeat on Success

const polling = checkStatus().pipe(Effect.repeat(Schedule.spaced("5 seconds")));

Effect.schedule - Full Control

const scheduled = effect.pipe(Effect.schedule(mySchedule));

Schedule Combinators

Composing Schedules

const exponentialWithLimit = Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(10)));

const eitherSchedule = Schedule.union(Schedule.spaced("1 second"), Schedule.recurs(5));

Adding Jitter

const jittered = Schedule.exponential("1 second").pipe(Schedule.jittered);

const customJitter = Schedule.exponential("1 second").pipe(Schedule.jittered({ min: 0.8, max: 1.2 }));

Delaying First Execution

const delayed = Schedule.spaced("1 second").pipe(Schedule.delayed(() => "5 seconds"));

Resetting Schedule

const resetting = Schedule.exponential("1 second").pipe(Schedule.resetAfter("1 minute"));

Conditional Retrying

Retry While Condition

// Use Match.tag for error type checking in predicates
const retryTransient = effect.pipe(
  Effect.retry({
    schedule: Schedule.exponential("1 second"),
    while: (error) =>
      Match.value(error).pipe(
        Match.tag("TransientError", () => true),
        Match.orElse(() => false),
      ),
  }),
);

Retry Until Condition

const retryUntilFatal = effect.pipe(
  Effect.retry({
    schedule: Schedule.recurs(10),
    until: (error) =>
      Match.value(error).pipe(
        Match.tag("FatalError", () => true),
        Match.orElse(() => false),
      ),
  }),
);

Cron Scheduling

import { Cron } from "effect";

const daily = Cron.parse("0 0 * * *");

const hourly = Cron.parse("0 * * * *");

const cronSchedule = Schedule.cron(daily);

Schedule Outputs

Schedules can produce values:

const withElapsed = Schedule.elapsed;

const withCount = Schedule.count;

const collecting = Schedule.collectAll<number>();

Using Schedule Output

const [result, elapsed] =
  yield * effect.pipe(Effect.retry(Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.elapsed))));
console.log(`Took ${elapsed}ms after retries`);

Common Patterns

API Retry with Backoff

const apiCall = fetchFromApi().pipe(
  Effect.retry(
    Schedule.exponential("500 millis").pipe(
      Schedule.jittered,
      Schedule.compose(Schedule.recurs(5)),
      Schedule.upTo("30 seconds"),
    ),
  ),
);

Polling with Timeout

const poll = checkJobStatus(jobId).pipe(
  Effect.repeat(Schedule.spaced("2 seconds").pipe(Schedule.upTo("5 minutes"))),
  Effect.timeout("5 minutes"),
);

Circuit Breaker Pattern

const circuitBreaker = (effect: Effect.Effect<A, E>) => {
  let failures = 0;
  const maxFailures = 5;
  const resetTimeout = "30 seconds";

  return effect.pipe(
    Effect.retry(
      Schedule.exponential("1 second").pipe(
        Schedule.compose(Schedule.recurs(3)),
        Schedule.tapOutput(() =>
          Effect.sync(() => {
            failures++;
          }),
        ),
      ),
    ),
  );
};

Retry with Logging

const retryWithLogs = effect.pipe(
  Effect.retry(
    Schedule.exponential("1 second").pipe(
      Schedule.compose(Schedule.recurs(5)),
      Schedule.tapInput((error) => Effect.log(`Retrying after error: ${error}`)),
    ),
  ),
);

Schedule Reference

Schedule	Pattern
Schedule.forever	Never stops
Schedule.once	Single execution
Schedule.recurs(n)	Exactly n times
Schedule.spaced(d)	Fixed delay d
Schedule.fixed(d)	Fixed interval from start
Schedule.exponential(d)	d, 2d, 4d, 8d...
Schedule.fibonacci(d)	d, d, 2d, 3d, 5d...
Schedule.linear(d)	d, 2d, 3d, 4d...

Best Practices

1. Always add recurs limit - Avoid infinite retries
2. Use jitter for distributed systems - Prevents thundering herd
3. Cap exponential backoff - Use upTo() for max delay
4. Log retry attempts - Use tapInput for visibility
5. Different schedules for different errors - Transient vs permanent

Additional Resources

For comprehensive scheduling documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Built-In Schedules" for schedule types
• "Schedule Combinators" for composition
• "Repetition" for repeat patterns
• "Retrying" for retry patterns
• "Cron" for cron expressions