Effect TS · Reference
Schedules & retries — cheatsheet
The compressed lesson: every builder, combinator, and rule for "try again" and "don't wait forever". Effect 3.22.1, behaviours verified in the course sandbox.
The shape
Schedule = // a value describing when/how often to act again
Effect.retry(effect, policy) // loop on E-channel failures
Effect.retryOrElse(effect, policy, orElse) // fall back after exhaustion
Effect.timeout(effect, '200 millis') // cap the wait
Builders
| Builder | Plan it makes | Verified note |
Schedule.recurs(n) | Stop after n retries | Counts retries, not attempts: n retries = n+1 attempts |
Schedule.once | Retry once | Pre-built value — no parentheses |
Schedule.forever | Never stop | Pre-built value — pair it with a cap |
Schedule.spaced(d) | Wait d after each finish, then try again | Unbounded alone |
Schedule.fixed(d) | New try every d, regardless of attempt length | Steady cadence |
Schedule.exponential(base, factor) | base, base×factor, base×factor², … | Measured 10+20+40ms for 3 retries at ('10 millis', 2) |
Schedule.jittered(s) | s with randomised delays | Spreads load when many callers retry together |
Composing
| Combinator | Rule | Verified example |
Schedule.intersect(a, b) | The tighter plan wins (cap and delay both apply) | intersect(recurs(5), spaced('50ms')) — the production recipe |
Schedule.union(a, b) | Keep going while either allows — the longer wins | union(recurs(2), recurs(5)) → 5 retries |
Schedule.andThen(a, b) | Run plan a to exhaustion, then plan b | Useful for "fast retries, then slow ones" |
Shorthands & conditions
| Form | Use when | Notes |
Effect.retry(effect, { times: 5 }) | Quick cap, no waiting | Object shorthand for Effect.retry only |
Effect.retry(effect, { until: f }) | Stop retrying when f(error) is true | Also while; docs form 1 |
Effect.retryOrElse(effect, policy, orElse) | Plan B after exhaustion | Verified with a real Schedule; orElse receives the final error |
Effect.repeat(effect, policy) | Repeat on successes | Mirror of retry; stops at first failure 2 |
Effect.timeout(effect, d) | Cap the wait at d | Loss → TimeoutException failure; abandon the slow work |
BullMQ → Effect translation
| You wrote (BullMQ ops) | Effect equivalent |
withRetry loop, delay *= 2 | Effect.retry(e, Schedule.exponential('100 millis', 2)) |
attempts: 5 job option | Schedule.recurs(5) — or { times: 5 } — capped via intersect |
backoff: { type: 'fixed', delay } | Schedule.spaced(delay) (after each finish) / Schedule.fixed(delay) (steady cadence) |
| Per-site copies of the loop | One policy value, passed/attached per call site |
| Timeout guard around a worker | Effect.timeout + catchTag('TimeoutException', fallback) |
Rules of thumb
- Retry failures, never defects. Verified: a
throw in Effect.sync is a Die — one attempt, no retry. If retry seems to "not work", check what channel the failure is actually in.
- Always cap an unbounded plan.
spaced/forever/exponential never stop alone — intersect with recurs(n).
- Exhaustion is typed. The last failure resurfaces in
E; callers still handle the domain error, unaware of the retrying.
recurs(n) = n retries = n+1 attempts. Say "attempts" out loud when you set the number.
← Back to Lesson 3