Effect TS · Reference

Typed errors — cheatsheet

The compressed lesson: every way failure enters, flows, and leaves an Effect. Effect 3.22.1 (v4 note at bottom).

The shape

Effect<Success, Error>

// "runs this and either returns Success
//  or fails with one of Error"
// Error is a plain union of tagged objects.

Creating failure & the boundary

APIUse whenNotes
Effect.fail(err)Domain failure you'd model as a union memberGoes 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, unmappedFailure becomes UnknownException — original error at .error
Effect.die(err) / Effect.orDieBugs, impossible statesNot in E; lands in the Cause as Die

Recovering

APICatchesTrade-off
effect.pipe(Effect.catchTag('Tag', handler))One tag; handler gets the typed payloadUnmatched tags stay in E — compiler still holds you to them
Effect.catchAll(handler)Everything in EYou lose the specific failure's type; caller now sees handler's E
Effect.catchTags({ Tag: h, … })Several tags at onceSame as stacked catchTags, one pipe

The TaggedError pattern

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.

Meridian → Effect translation

You wrote (plain TS)Effect equivalent
type OrderError = NotFound | AlreadyPaidThe E union, assembled automatically from fails
Result<Order, OrderError> returnsEffect<Order, OrderError> — threading is automatic
switch (e._tag) at the call sitecatchTag / catchTags in the pipe
try { … } catch { … } around IOEffect.tryPromise({ try, catch })
throw new Error('impossible')Effect.die — a defect, not a domain failure

Rules of thumb

v4 note

Error model is stable across v4. Data.TaggedError, catchTag, tryPromise carry over; UnknownException semantics unchanged. Watch the migration map for surrounding renames.

← Back to Lesson 2