Errors vs defects — recoverable or a bug

Effect v3.12.0

Not every failure should be handled, and knowing which is which changes how you design. Some you plan for. A timeout on a network call is an expected error. It lives in the E channel, the compiler tracks it, and you recover from it like any other case by falling back to a cached value.

Other failures are not cases at all. They are bugs. A broken invariant, a branch that should be impossible. Effect calls these defects and keeps them out of the E channel on purpose. Effect.die raises one deliberately, a crash you meant. Because it is a bug and not a planned case, you do not catch it. You read it after the fact from the Cause of an Exit.

Where you draw that line is your call. Sometimes you decide that if a step fails, it is not a case to handle but a bug. orDie promotes an expected error into a defect and the E channel disappears from the type, so the failure can no longer be recovered. That is the whole chapter in one move. Every failure is a value, and you decide in the type which ones you answer for and which ones end the program.

import { Data, Effect } from "effect";

// An EXPECTED error is a case you planned for. It lives in the E channel,
// the compiler tracks it, and you recover from it like normal.
class Timeout extends Data.TaggedError("Timeout")<{}> {}

const fetchUser: Effect.Effect<string, Timeout> = Effect.fail(new Timeout());

const program = fetchUser.pipe(
  Effect.catchTag("Timeout", () => Effect.succeed("cached user")),
);

console.log(Effect.runSync(program)); // cached user

❚❚ beat