@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
md 173 lines 5.9 KB
Rendered Raw
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.