effect-patterns-scheduling

name	effect-patterns-scheduling
description	Effect-TS patterns for Scheduling. Use when working with scheduling in Effect-TS applications.

Effect-TS Patterns: Scheduling

This skill provides 3 curated Effect-TS patterns for scheduling. Use this skill when working on tasks related to:

• scheduling
• Best practices in Effect-TS applications
• Real-world patterns and solutions

---

🟢 Beginner Patterns

Retry Failed Operations

Rule: Use Effect.retry with a Schedule to handle transient failures gracefully.

Good Example:

import { Effect, Schedule, Data } from "effect"

// ============================================
// 1. Define error types
// ============================================

class NetworkError extends Data.TaggedError("NetworkError")<{
  readonly message: string
}> {}

class RateLimitError extends Data.TaggedError("RateLimitError")<{
  readonly retryAfter: number
}> {}

class NotFoundError extends Data.TaggedError("NotFoundError")<{
  readonly resource: string
}> {}

// ============================================
// 2. Simulate a flaky API call
// ============================================

let callCount = 0
const fetchData = Effect.gen(function* () {
  callCount++
  yield* Effect.log(`API call attempt ${callCount}`)

  // Simulate intermittent failures
  if (callCount < 3) {
    return yield* Effect.fail(new NetworkError({ message: "Connection timeout" }))
  }

  return { data: "Success!", attempts: callCount }
})

// ============================================
// 3. Basic retry - fixed attempts
// ============================================

const withBasicRetry = fetchData.pipe(
  Effect.retry(Schedule.recurs(5))  // Retry up to 5 times
)

// ============================================
// 4. Retry with delay
// ============================================

const withDelayedRetry = fetchData.pipe(
  Effect.retry(
    Schedule.spaced("500 millis").pipe(
      Schedule.intersect(Schedule.recurs(5))
    )
  )
)

// ============================================
// 5. Retry only specific errors
// ============================================

const fetchWithErrors = (shouldFail: boolean) =>
  Effect.gen(function* () {
    if (shouldFail) {
      // Randomly fail with different errors
      const random = Math.random()
      if (random < 0.5) {
        return yield* Effect.fail(new NetworkError({ message: "Timeout" }))
      } else if (random < 0.8) {
        return yield* Effect.fail(new RateLimitError({ retryAfter: 1000 }))
      } else {
        return yield* Effect.fail(new NotFoundError({ resource: "user:123" }))
      }
    }
    return "Data fetched!"
  })

// Only retry network and rate limit errors, not NotFoundError
const retryTransientOnly = fetchWithErrors(true).pipe(
  Effect.retry({
    schedule: Schedule.recurs(3),
    while: (error) =>
      error._tag === "NetworkError" || error._tag === "RateLimitError",
  })
)

// ============================================
// 6. Retry with exponential backoff
// ============================================

const withExponentialBackoff = fetchData.pipe(
  Effect.retry(
    Schedule.exponential("100 millis", 2).pipe(  // 100ms, 200ms, 400ms...
      Schedule.intersect(Schedule.recurs(5))      // Max 5 retries
    )
  )
)

// ============================================
// 7. Run and observe
// ============================================

const program = Effect.gen(function* () {
  yield* Effect.log("Starting retry demo...")
  
  // Reset counter
  callCount = 0
  
  const result = yield* withBasicRetry
  yield* Effect.log(`Final result: ${JSON.stringify(result)}`)
})

Effect.runPromise(program)

Rationale:

Use Effect.retry to automatically retry operations that fail due to transient errors like network timeouts.

---

Many failures are temporary:

1. Network issues - Connection drops, timeouts
2. Rate limits - Too many requests
3. Resource contention - Database locks
4. Service restarts - Brief unavailability

Automatic retries handle these without manual intervention.

---

---

Your First Schedule

Rule: Use Schedule to control when and how often effects run.

Good Example:

import { Effect, Schedule } from "effect"

// ============================================
// 1. Retry a failing operation
// ============================================

let attempts = 0
const flakyOperation = Effect.gen(function* () {
  attempts++
  if (attempts < 3) {
    yield* Effect.log(`Attempt ${attempts} failed`)
    return yield* Effect.fail(new Error("Temporary failure"))
  }
  return `Success on attempt ${attempts}`
})

// Retry up to 5 times
const withRetry = flakyOperation.pipe(
  Effect.retry(Schedule.recurs(5))
)

// ============================================
// 2. Repeat a successful operation
// ============================================

const logTime = Effect.gen(function* () {
  const now = new Date().()
  * .()
   now
})


 repeated = logTime.(
  .(.())
)






 polling = logTime.(
  .(
    .().(
      .(.())
    )
  )
)






 fixedDelay = .()


 exponentialBackoff = .()


 limitedAttempts = .()


 retryPolicy = .().(
  .(.())
)





 program = .(* () {
  * .()
   result = * withRetry
  * .()

  * .()
  * repeated
})

.(program)

Rationale:

Use Schedule to control timing in Effect programs - retrying failed operations, repeating successful ones, or adding delays.

---

Schedules solve common timing problems:

1. Retries - Try again after failures
2. Polling - Check for updates periodically
3. Rate limiting - Control how fast things run
4. Backoff - Increase delays between attempts

---

---

🟡 Intermediate Patterns

Scheduling Pattern 1: Repeat an Effect on a Fixed Interval

Rule: Repeat effects at fixed intervals using Schedule.fixed for steady-state operations and background tasks.

Good Example:

This example demonstrates a health check service that polls multiple service endpoints every 30 seconds and reports their status.

import { Effect, Schedule, Duration } from "effect";

interface ServiceStatus {
  readonly service: string;
  readonly url: string;
  readonly isHealthy: boolean;
  readonly responseTime: number;
  readonly lastChecked: number;
}

// Mock health check that calls an endpoint
const checkServiceHealth = (
  url: string,
  service: string
): Effect.Effect<ServiceStatus> =>
  Effect.gen(function* () {
    const startTime = Date.now();

    // Simulate HTTP call with occasional failures
    const isHealthy = Math.random() > 0.1; // 90% success rate
    const responseTime = Math.random() * 500; // 0-500ms

    yield* Effect.(.(.(responseTime)));

     (!isHealthy) {
      * .( ());
    }

     {
      service,
      url,
      : ,
      : .(.() - startTime),
      : .(),
    };
  });


  {
   : <{
     : ;
     : ;
  }>;
   : ;
}


 serviceStatuses =  <, >();


 checkAllServices = (
  : 
): .<> =>
  .(* () {
     ( service  config.) {
       status = * (service., service.).(
        .
      );

       (status. === ) {
        serviceStatuses.(service., status.);
        .(
          
        );
      }  {
        .();
        
      }
    }
  });


 createHealthCheckScheduler = (
  : 
): .<> =>
  (config).(
    
    .(
      .(.(config.))
    )
  );


 reportStatus = (): .<> =>
  .( {
     (serviceStatuses. === ) {
      .();
      ;
    }

    .();
     ( [service, status]  serviceStatuses) {
       ago = .((.() - status.) / );
      .(
        
      );
    }
  });


 program = .(* () {
   :  = {
    : [
      { : , :  },
      { : , :  },
      { : , :  },
    ],
    : , 
  };

  
   checker = * (config).(
    .
  );

  
  * ().(
    .(
      .(
        .(), 
         .()
      )
    )
  );

  
  * checker.();
});

.(program);

This pattern:

1. Defines service health checks that may fail
2. Uses Schedule.fixed to repeat every 5 seconds
3. Handles failures gracefully (keeps last known status)
4. Runs in background while main logic continues
5. Reports current status at intervals

---

Rationale:

When you need to run an effect repeatedly at regular intervals (e.g., every 5 seconds, every 30 minutes), use Schedule.fixed to specify the interval. This creates a schedule that repeats the effect indefinitely or until a condition stops it, with precise timing between executions.

---

Many production systems need periodic operations:

• Health checks: Poll service availability every 30 seconds
• Cache refresh: Update cache every 5 minutes
• Metrics collection: Gather system metrics every 10 seconds
• Data sync: Sync data with remote service periodically
• Cleanup tasks: Remove stale data nightly

Without proper scheduling:

• Manual polling with while loops wastes CPU (busy-waiting)
• Thread.sleep blocks threads, preventing other work
• No automatic restart on failure
• Difficult to test deterministically

With Schedule.fixed:

• Efficient, non-blocking repetition
• Automatic failure handling and retry
• Testable with TestClock
• Clean, declarative syntax

---

---