01 - The Problem: Why `try/catch` Falls Short

Next

Errors are part of every program. What matters is whether the language can model them.

With try/catch, every function that throws lies about its return type and every catch clause receives unknown.

This step makes the three concrete consequences observable and motivates the typed alternative that the rest of the tutorial builds on.

What you’ll work through

index.test.ts contains four short beats. The first three are read-only — run them and observe how try/catch fails the type system in three distinct ways.

The final beat is interactive: three stubbed Effect calls you’ll replace to see typed errors in action.

By the end you should be able to answer, in one sentence, why a throwing function’s signature is a lie.

Mental Model

A throwing function communicates failure through a hidden side-channel that the type system does not track. A function that returns number may, at any point, transfer control to a distant catch, and the compiler cannot warn you.

1
try/catch
2
─────────────────────────────────────────────
3
 parseAge("abc")
4
     │
5
     ▼   declared:  string -> number
6
     │
7
     │   ╔══════════════════════════╗
8
     └──►║  throw new Error(...)    ║  ← untracked
9
         ╚══════════════════════════╝
10
                   │
11
                   ▼
12
              discovered at runtime
13

14
Effect
15
─────────────────────────────────────────────
16
 parseAge("abc")
17
     │
18
     ▼   declared:  string -> Effect<number, ParseError>
19
     │
20
     ├── success channel ──► number
21
     └── error channel   ──► ParseError      ← visible to the compiler

The E channel is the entire point: failure becomes part of the signature.

The signature lies

1
// Declared as `number`. May throw at any point.
2
function parseAge(input: string): number {
3
  const n = parseInt(input)
4
  if (isNaN(n)) throw new Error("Not a number")
5
  if (n < 0) throw new Error("Negative age")
6
  return n
7
}
8

9
const age: number = parseAge("banana") // compiles. blows up.

TypeScript has no throws clause. The return type carries no information about failure, and callers receive no warning.

Every throwing function widens the runtime surface the type system pretends does not exist.

Notice. The compiler accepted const age: number = parseAge("banana") without a warning. The runtime throws. The signature and the behaviour disagree, and the compiler has no way to tell you.

Your turn run the tests and confirm both throws fire from a function declared `: number`. You should see two failures inside the success path.

Composition is nesting

Each additional fallible step adds one level of indentation and one error rewrap. The shape of the code grows with the number of error sites, not the number of business steps.

1
async function createUser(nameInput: string, ageInput: string) {
2
  try {
3
    const name = validateName(nameInput)
4
    try {
5
      const age = parseAge(ageInput)
6
      return { name, age }
7
    } catch (ageError) {
8
      throw new Error(`Age validation failed: ${(ageError as Error).message}`)
9
    }
10
  } catch (nameError) {
11
    throw new Error(`Name validation failed: ${(nameError as Error).message}`)
12
  }
13
}

Three steps produce a pyramid. Recovery decisions are inverted (innermost first).

The logical sequence, validate name, parse age, return both, is buried under control flow.

Your turn run the tests and see how each added rule deepens the pyramid.

No exhaustiveness

In strict TypeScript a catch parameter is unknown. Nothing tells you which throws are possible.

Every recovery decision starts with a guess.

1
try {
2
  const result = someLibraryFunction()
3
} catch (e) {
4
  // `e` is unknown. Casting is a bet.
5
  const message = (e as Error).message
6
}

There is no compiler check for “have I handled every failure mode of this function”. The documentation, if it exists, is the only specification.

> hand-written `catch` clauses. The test in this beat throws a plain > `string` — the check returns `false`, and `message` is `undefined`.

Your turn confirm that a thrown `string` slips past `e instanceof Error` at runtime. The assertion checks `typeof e`, not the cast.

The Effect Alternative (preview)

Effect replaces the hidden side-channel with an explicit type parameter.

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, ParseError, never>
4
//      ▼
5
declare const parseAge: (input: string) => Effect.Effect<number, ParseError>

number, the success value.
ParseError, the typed expected error.
never, no required dependencies (covered in step 21).

Callers must handle the error (or propagate it), and the compiler enforces both. Step 03 introduces the type.

Step 05 introduces the constructors.

Your turn replace the three stubs with `Effect.succeed` / `Effect.fail` so the preview parser returns its result as a value. The first assertion runs the happy path; the second asserts the failure surfaces in `Exit`, not as a throw.

Common Pitfalls

1, Expecting TypeScript to track throws. It does not. throws is not part of the type system.

A function declared : number can throw anything.

2, Assuming Error covers all throws. Code can throw strings, numbers, plain objects, or DOMException. e instanceof Error is a runtime check, not a guarantee.

3, Confusing nested try/catch with composition. Nesting hides the business sequence inside error-handling scaffolding. More steps means more pyramid.

— they document the three failure modes of `try/catch`. - [ ] Open `index.test.ts` and find the `effect-preview` beat. Replace the three `/* @stub */` blocks with the appropriate `Effect.succeed` and `Effect.fail` calls. - [ ] Re-run the tests. The happy-path assertion should return `25`; the failure assertion should report `Exit.isFailure === true`. - [ ] In one sentence, write down why TypeScript's `throws`-less type system cannot warn you about the failure surface. (This becomes the answer step 03 builds on.)

The full test suite

The index.test.ts for this lesson, verbatim from steps/01-the-problem/.

1
import { it, expect } from "vite-plus/test"
2
import { Effect, Exit } from "effect"
3

4
// =============================================================================
5
// 01 - The Problem: Why try/catch Falls Short
6
// =============================================================================
7
//
8
// Three failure modes of try/catch made executable:
9
//   1. The signature lies — return type says `number`, function throws.
10
//   2. Composition is nesting — every step adds indentation and an error rewrap.
11
//   3. No exhaustiveness — `catch` receives `unknown`.
12
// The closing block previews the Effect alternative: errors as values in E.
13

14
function parseAge(input: string): number {
15
  const n = parseInt(input)
16
  if (isNaN(n)) throw new Error("Not a number")
17
  if (n < 0) throw new Error("Negative age")
18
  return n
19
}
20

21
function validateName(name: string): string {
22
  if (name.length === 0) throw new Error("Name cannot be empty")
23
  if (name.length > 100) throw new Error("Name too long")
24
  return name
25
}
26

27
async function createUser(nameInput: string, ageInput: string) {
28
  try {
29
    const name = validateName(nameInput)
30
    try {
31
      const age = parseAge(ageInput)
32
      return { name, age }
33
    } catch (ageError) {
34
      throw new Error(`Age validation failed: ${(ageError as Error).message}`)
35
    }
36
  } catch (nameError) {
37
    throw new Error(`Name validation failed: ${(nameError as Error).message}`)
38
  }
39
}
40

41
// @beat
42
//   id: signature-lies
43
//   shape: multi-todo
44
//   title: The signature lies
45
//   teaches: A throwing function's return type hides every failure mode from the compiler.
46
//   hint: the signature says `number` and `string` — predict what each happy-path call returns
47
it("declares `number` and throws on bad input", () => {
48
  // Predict the parsed number for input "25".
49
  expect(parseAge("25")).toBe(/* @stub */ 25 /* @end */)
50
  expect(() => parseAge("banana")).toThrow("Not a number")
51
  expect(() => parseAge("-5")).toThrow("Negative age")
52
})
53

54
it("hides failures in every throwing function", () => {
55
  // Predict what validateName returns for a valid name.
56
  expect(validateName("Alice")).toBe(/* @stub */ "Alice" /* @end */)
57
  expect(() => validateName("")).toThrow("Name cannot be empty")
58
  expect(() => validateName("x".repeat(101))).toThrow("Name too long")
59
})
60
// @end-beat
61

62
// @beat
63
//   id: nested-composition
64
//   shape: multi-todo
65
//   title: Composition is nesting
66
//   teaches: Each fallible step adds one try/catch level and one error rewrap, so shape grows with errors not logic.
67
//   hint: predict the shape returned from the happy path — both fields you pass in survive
68
it("requires one try/catch per fallible step", async () => {
69
  const result = await createUser("Alice", "25")
70
  // Predict the object shape returned on the happy path.
71
  expect(result).toEqual(/* @stub */ { name: "Alice", age: 25 } /* @end */)
72

73
  await expect(createUser("", "25")).rejects.toThrow("Name validation failed")
74
  await expect(createUser("Alice", "banana")).rejects.toThrow("Age validation failed")
75
})
76

77
it("rewraps the error at every level", async () => {
78
  async function createAdult(nameInput: string, ageInput: string) {
79
    try {
80
      const name = validateName(nameInput)
81
      try {
82
        const age = parseAge(ageInput)
83
        try {
84
          if (age < 18) throw new Error("Must be an adult")
85
          return { name, age }
86
        } catch (adultError) {
87
          throw new Error(`Adult check failed: ${(adultError as Error).message}`)
88
        }
89
      } catch (ageError) {
90
        throw new Error(`Age validation failed: ${(ageError as Error).message}`)
91
      }
92
    } catch (nameError) {
93
      throw new Error(`Name validation failed: ${(nameError as Error).message}`)
94
    }
95
  }
96

97
  const ok = await createAdult("Alice", "25")
98
  // Predict the object the happy path returns.
99
  expect(ok).toEqual(/* @stub */ { name: "Alice", age: 25 } /* @end */)
100

101
  await expect(createAdult("Alice", "15")).rejects.toThrow(
102
    "Name validation failed: Age validation failed: Adult check failed: Must be an adult",
103
  )
104
})
105
// @end-beat
106

107
// @beat
108
//   id: catch-is-unknown
109
//   shape: one-todo
110
//   title: catch receives unknown
111
//   teaches: A `catch` parameter is `unknown`; every recovery decision starts with a runtime guess about the error shape.
112
//   hint: the throw is a bare string literal — what does `typeof` report for that value?
113
it("forces a runtime guess at the error shape", () => {
114
  const throwsAString = () => {
115
    throw "string, not Error"
116
  }
117

118
  let kind: string
119
  try {
120
    throwsAString()
121
    kind = "no throw"
122
  } catch (e) {
123
    kind = e instanceof Error ? "Error" : typeof e
124
  }
125

126
  // Predict the `typeof` of the thrown value when it isn't an Error.
127
  expect(kind).toBe(/* @stub */ "string" /* @end */)
128
})
129
// @end-beat
130

131
// @beat
132
//   id: effect-preview
133
//   shape: multi-todo
134
//   title: Preview — errors as values in E
135
//   teaches: Returning Effect.fail puts the failure in a typed E channel the compiler can see and require callers to handle.
136
//   hint: use Effect.succeed for the happy path and Effect.fail for the rejected inputs
137
it("declares failure in the type", async () => {
138
  function parseAgeEffect(input: string): Effect.Effect<number, string> {
139
    const n = parseInt(input)
140
    if (isNaN(n)) return /* @stub */ Effect.fail("Not a number") /* @end */
141
    if (n < 0) return /* @stub */ Effect.fail("Negative age") /* @end */
142
    return /* @stub */ Effect.succeed(n) /* @end */
143
  }
144

145
  const value = await Effect.runPromise(parseAgeEffect("25"))
146
  expect(value).toBe(25)
147
})
148

149
it("places the error in the E channel", async () => {
150
  function parseAgeEffect(input: string): Effect.Effect<number, string> {
151
    const n = parseInt(input)
152
    if (isNaN(n)) return Effect.fail("Not a number")
153
    if (n < 0) return Effect.fail("Negative age")
154
    return Effect.succeed(n)
155
  }
156

157
  const exit = await Effect.runPromiseExit(parseAgeEffect("banana"))
158
  expect(Exit.isFailure(exit)).toBe(true)
159
})
160
// @end-beat

01·01The Problem

01 - The Problem: Why `try/catch` Falls Short

What you’ll work through

Mental Model

The signature lies

Composition is nesting

No exhaustiveness

The Effect Alternative (preview)

Common Pitfalls

See Also

The full test suite