The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | # Error Handling: `catch*` Renamings |
| 2 | |
| 3 | The `catch` combinators on `Effect` have been renamed in v4. The general |
| 4 | pattern: `catchAll*` is shortened to `catch*`, and the `catchSome*` family is |
| 5 | replaced by `catchFilter` / `catchCauseFilter`. |
| 6 | |
| 7 | ## Renamings |
| 8 | |
| 9 | | v3 | v4 | |
| 10 | | ------------------------ | ------------------------------ | |
| 11 | | `Effect.catchAll` | `Effect.catch` | |
| 12 | | `Effect.catchAllCause` | `Effect.catchCause` | |
| 13 | | `Effect.catchAllDefect` | `Effect.catchDefect` | |
| 14 | | `Effect.catchTag` | `Effect.catchTag` (unchanged) | |
| 15 | | `Effect.catchTags` | `Effect.catchTags` (unchanged) | |
| 16 | | `Effect.catchIf` | `Effect.catchIf` (unchanged) | |
| 17 | | `Effect.catchSome` | `Effect.catchFilter` | |
| 18 | | `Effect.catchSomeCause` | `Effect.catchCauseFilter` | |
| 19 | | `Effect.catchSomeDefect` | Removed | |
| 20 | |
| 21 | ## `Effect.catchAll` → `Effect.catch` |
| 22 | |
| 23 | **v3** |
| 24 | |
| 25 | ```ts |
| 26 | import { Effect } from "effect" |
| 27 | |
| 28 | const program = Effect.fail("error").pipe( |
| 29 | Effect.catchAll((error) => Effect.succeed(`recovered: ${error}`)) |
| 30 | ) |
| 31 | ``` |
| 32 | |
| 33 | **v4** |
| 34 | |
| 35 | ```ts |
| 36 | import { Effect } from "effect" |
| 37 | |
| 38 | const program = Effect.fail("error").pipe( |
| 39 | Effect.catch((error) => Effect.succeed(`recovered: ${error}`)) |
| 40 | ) |
| 41 | ``` |
| 42 | |
| 43 | ## `Effect.catchAllCause` → `Effect.catchCause` |
| 44 | |
| 45 | **v3** |
| 46 | |
| 47 | ```ts |
| 48 | import { Effect } from "effect" |
| 49 | |
| 50 | const program = Effect.die("defect").pipe( |
| 51 | Effect.catchAllCause((cause) => Effect.succeed("recovered")) |
| 52 | ) |
| 53 | ``` |
| 54 | |
| 55 | **v4** |
| 56 | |
| 57 | ```ts |
| 58 | import { Cause, Effect } from "effect" |
| 59 | |
| 60 | const program = Effect.die("defect").pipe( |
| 61 | Effect.catchCause((cause) => Effect.succeed("recovered")) |
| 62 | ) |
| 63 | ``` |
| 64 | |
| 65 | ## `Effect.catchSome` → `Effect.catchFilter` |
| 66 | |
| 67 | In v3, `catchSome` took a function returning `Option<Effect>`. In v4, |
| 68 | `catchFilter` uses the `Filter` module instead. |
| 69 | |
| 70 | **v3** |
| 71 | |
| 72 | ```ts |
| 73 | import { Effect, Option } from "effect" |
| 74 | |
| 75 | const program = Effect.fail(42).pipe( |
| 76 | Effect.catchSome((error) => |
| 77 | error === 42 |
| 78 | ? Option.some(Effect.succeed("caught")) |
| 79 | : Option.none() |
| 80 | ) |
| 81 | ) |
| 82 | ``` |
| 83 | |
| 84 | **v4** |
| 85 | |
| 86 | ```ts |
| 87 | import { Effect, Filter } from "effect" |
| 88 | |
| 89 | const program = Effect.fail(42).pipe( |
| 90 | Effect.catchFilter( |
| 91 | Filter.fromPredicate((error: number) => error === 42), |
| 92 | (error) => Effect.succeed("caught") |
| 93 | ) |
| 94 | ) |
| 95 | ``` |
| 96 | |
| 97 | ## Defects take precedence in mixed causes |
| 98 | |
| 99 | A failure cause can hold a typed error and a defect at the same time, for |
| 100 | example when a finalizer dies after the effect has already failed. In v4, |
| 101 | every operator that recovers from typed errors skips such causes. The handler |
| 102 | does not run, and the failure is propagated with each typed error converted to |
| 103 | a defect. |
| 104 | |
| 105 | In v3 only some operators behaved this way (`catchAll`, `matchEffect`, |
| 106 | `match`, `orElse`, `orElseSucceed`, `ignore`, `either`, `option` and |
| 107 | `Effect.retry`). `catchTag`, `catchTags`, `catchIf`, `catchSome` and the |
| 108 | `Stream` and `Channel` recovery operators ran the handler and dropped the |
| 109 | defect. In v4 the rule is the same for all of them: |
| 110 | |
| 111 | - `Effect`: `catch`, `catchTag`, `catchTags`, `catchIf`, `catchFilter`, |
| 112 | `catchReason`, `catchReasons`, `catchEager`, `matchEffect`, `match`, |
| 113 | `matchEager`, `orElseSucceed`, `ignore`, `option`, `result`, `orDie`, |
| 114 | `eventually`, `firstSuccessOf`, `retry`, `retryOrElse`, `repeat` and |
| 115 | `repeatOrElse` |
| 116 | - `Stream` and `Channel`: their typed recovery operators, including `catch`, |
| 117 | `catchTag`, `catchIf`, `catchFilter`, `catchReason`, `catchReasons`, |
| 118 | `ignore`, `orDie` and `retry` |
| 119 | |
| 120 | An interruption alongside a typed error does not prevent recovery. The first |
| 121 | typed error is handled; other typed errors and interrupts can be discarded. |
| 122 | |
| 123 | ```ts |
| 124 | import { Effect } from "effect" |
| 125 | |
| 126 | const program = Effect.fail("error").pipe( |
| 127 | Effect.ensuring(Effect.die("finalizer defect")), |
| 128 | // The handler does not run: the cause contains a defect |
| 129 | Effect.catch(() => Effect.succeed("recovered")) |
| 130 | ) |
| 131 | // fails with Die("error") + Die("finalizer defect") |
| 132 | ``` |
| 133 | |
| 134 | Use `Effect.catchDefect` or `Effect.catchCause` to recover from causes that |
| 135 | contain defects. |
| 136 | |
| 137 | ### Retry and repeat error paths |
| 138 | |
| 139 | `Effect.retry`, `retryOrElse`, `repeat` and `repeatOrElse` apply this rule to |
| 140 | source failures. `Fail(e) + Interrupt` now enters the typed error path instead |
| 141 | of propagating unchanged. `retry` retries it; when retries run out, or `repeat` |
| 142 | re-raises it, the final cause is `Fail(e)` without the interrupt. The `orElse` |
| 143 | handlers can now receive `e` from these causes. |
| 144 | |
| 145 | `repeat` and `repeatOrElse` also apply the rule to policy failures. A policy |
| 146 | failure containing `Fail(e) + Die(d)` propagates as `Die(e) + Die(d)` without |
| 147 | running `orElse`. In contrast, `retry` and `retryOrElse` do not recover policy |
| 148 | errors, so policy failures keep their original cause. |
| 149 | |
| 150 | ## Error mapping preserves the whole cause |
| 151 | |
| 152 | Error mapping is not recovery. `Effect.mapError`, `mapErrorEager`, `mapBoth` |
| 153 | and `mapBothEager`, `Exit.mapError` and `mapBoth`, `Stream.mapError` and |
| 154 | `mapBoth`, and `Channel.mapError` now map every typed error in place while |
| 155 | preserving defects, interrupts and reason order. Eager and suspended inputs |
| 156 | follow the same rule. For example, `Fail(e) + Interrupt + Die(d)` becomes |
| 157 | `Fail(f(e)) + Interrupt + Die(d)`, not an elected defect cause. |
| 158 | |
| 159 | Previously these operators mapped only the first typed error and discarded |
| 160 | the remaining reasons. If a cause contains several typed errors, the mapper |
| 161 | now runs for each one. Unlike typed recovery, mapping neither skips errors |
| 162 | beside defects nor converts them to defects. |
| 163 | |
| 164 | ## New in v4 |
| 165 | |
| 166 | - **`Effect.catchReason(errorTag, reasonTag, handler)`** — catches a specific |
| 167 | `reason` within a tagged error without removing the parent error from the |
| 168 | error channel. Useful for handling nested error causes (e.g. an `AiError` |
| 169 | with a `reason: RateLimitError | QuotaExceededError`). |
| 170 | - **`Effect.catchReasons(errorTag, cases)`** — like `catchReason` but handles |
| 171 | multiple reason tags at once via an object of handlers. |
| 172 | - **`Effect.catchEager(handler)`** — an optimization variant of `catch` that |
| 173 | evaluates synchronous recovery effects immediately. |