Effect TS · Reference
The compressed lesson: every way failure enters, flows, and leaves an Effect. Effect 3.22.1 (v4 note at bottom).
Effect<Success, Error>
// "runs this and either returns Success
// or fails with one of Error"
// Error is a plain union of tagged objects.
| API | Use when | Notes |
|---|---|---|
Effect.fail(err) | Domain failure you'd model as a union member | Goes in the E channel; short-circuits gen bodies |
Effect.tryPromise({ try, catch }) | Any throwing/rejecting promise API (the imperative shell) | catch: (cause) => domainError. Object form only — in 3.22.1 the positional second arg is silently ignored |
Effect.tryPromise(() => p) | Quick wrap, unmapped | Failure becomes UnknownException — original error at .error |
Effect.die(err) / Effect.orDie | Bugs, impossible states | Not in E; lands in the Cause as Die |
| API | Catches | Trade-off |
|---|---|---|
effect.pipe(Effect.catchTag('Tag', handler)) | One tag; handler gets the typed payload | Unmatched tags stay in E — compiler still holds you to them |
Effect.catchAll(handler) | Everything in E | You lose the specific failure's type; caller now sees handler's E |
Effect.catchTags({ Tag: h, … }) | Several tags at once | Same as stacked catchTags, one pipe |
import { Data } from 'effect';
class PaymentDeclined extends Data.TaggedError('PaymentDeclined')<{ reason: string }> {}
// value is a plain tagged object:
// { _tag: 'PaymentDeclined', reason: 'over limit' }
const charge = (cents: number) =>
cents > 5000
? Effect.fail(new PaymentDeclined({ reason: 'over limit' }))
: Effect.succeed(`charged ${cents}c`);
The class is a stamp factory; instances are the discriminated-union members you already wrote in Meridian — now with a compiler-checked channel.
| You wrote (plain TS) | Effect equivalent |
|---|---|
type OrderError = NotFound | AlreadyPaid | The E union, assembled automatically from fails |
Result<Order, OrderError> returns | Effect<Order, OrderError> — threading is automatic |
switch (e._tag) at the call site | catchTag / catchTags in the pipe |
try { … } catch { … } around IO | Effect.tryPromise({ try, catch }) |
throw new Error('impossible') | Effect.die — a defect, not a domain failure |
throw must cross a tryPromise before it touches functional-core code — that's the imperative-shell boundary.E; bugs die. Never catchAll to sweep defects.Error model is stable across v4. Data.TaggedError, catchTag, tryPromise carry over; UnknownException semantics unchanged. Watch the migration map for surrounding renames.