Add catchTagOrDie and catchTagsOrDie

[kyrregjerstad]

Summary

• Add catchTagOrDie — catches specific tagged errors by _tag, converting unmatched errors into defects (die). Unlike catchTag, unhandled errors are removed from the error channel entirely.
• Add catchTagsOrDie — same semantics but accepts an object of handlers (like catchTags).
• Both support dual (data-first and data-last) calling conventions and variadic tag arguments (for catchTagOrDie).

Motivation

A common pattern is catching one specific tagged error and re-mapping it, while treating all other errors as unexpected defects. The natural approach doesn't work:

declare const findUser: Effect<User, DbNotFound | DbUnknown>

findUser.pipe(
  Effect.catchTag("DbNotFound", () => new MyError({ message: "not found" })),
  Effect.orDie // also turns MyError into a defect!
)

orDie kills all errors — including the MyError that was just introduced by the handler. The only workaround today is a manual catchAll branch:

findUser.pipe(
  Effect.catchAll((e) =>
    e._tag === "DbNotFound"
      ? Effect.fail(new MyError({ message: "not found" }))
      : Effect.die(e)
  )
)

catchTagOrDie makes this a one-liner:

findUser.pipe(
  Effect.catchTagOrDie("DbNotFound", () =>
    Effect.fail(new MyError({ message: "not found" }))
  )
)
// Effect<User, MyError>

[changeset-bot]

🦋 Changeset detected

Latest commit: 312907e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 36 packages

Name	Type
effect	Minor
@effect/cli	Major
@effect/cluster	Major
@effect/experimental	Major
@effect/opentelemetry	Major
@effect/platform-browser	Major
@effect/platform-bun	Major
@effect/platform-node-shared	Major
@effect/platform-node	Major
@effect/platform	Major
@effect/printer-ansi	Major
@effect/printer	Major
@effect/rpc	Major
@effect/sql-clickhouse	Major
@effect/sql-d1	Major
@effect/sql-drizzle	Major
@effect/sql-kysely	Major
@effect/sql-libsql	Major
@effect/sql-mssql	Major
@effect/sql-mysql2	Major
@effect/sql-pg	Major
@effect/sql-sqlite-bun	Major
@effect/sql-sqlite-do	Major
@effect/sql-sqlite-node	Major
@effect/sql-sqlite-react-native	Major
@effect/sql-sqlite-wasm	Major
@effect/sql	Major
@effect/typeclass	Major
@effect/vitest	Major
@effect/workflow	Major
@effect/ai	Major
@effect/ai-amazon-bedrock	Major
@effect/ai-anthropic	Major
@effect/ai-google	Major
@effect/ai-openai	Major
@effect/ai-openrouter	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tim-smart]

effect 3 is mostly under a feature freeze now, but feel free to move this PR to the v4 repo: https://github.com/Effect-TS/effect-smol