Error Handling and Result Types

The TypeScript for Beginners series has typed values, functions, promises and components — but not failure. That gap is real: exceptions are the one JavaScript mechanism TypeScript cannot describe. This twenty-first chapter of the 24-chapter series explains why throw is untyped, how to handle what you catch safely, and how a discriminated-union Result<T, E> puts failure back into the type system where your call sites can see it.

Why exceptions are untyped

TypeScript's type system describes values that flow through your program. An exception does not flow — it unwinds the stack, skipping every return type you declared. The language has no throws clause, and no annotation tells a caller what a function might raise:

The consequence is a discipline rather than a feature: because the compiler will not check thrown values, you decide what a function throws, you document it, and you narrow it at the boundary. Everything else — expected, branchable failure — you return instead.

Catching safely: unknown and narrowing

Under strict, useUnknownInCatchVariables types the catch parameter as unknown, which means no property access is allowed until you have narrowed it. Three checks cover nearly every real error:

function messageOf(err: unknown): string {
  if (err instanceof Error) return err.message;   // built-in or your subclass
  if (typeof err === 'string') return err;        // throw 'something broke'
  if (err && typeof err === 'object' && 'message' in err) {
    return String((err as { message: unknown }).message);
  }
  return 'Unknown error';
}
try {
  JSON.parse('{ not json }');
} catch (err) {
  console.log(messageOf(err));
}

Expected output: the parser's own message — current Node prints Expected property name or '}' in JSON at position 2 (line 1 column 3), older runtimes print Unexpected token ... — extracted without a single unchecked property read. Note the order: instanceof first, then primitives, then a structural check. When several call sites need the same answer, extract the first check as a reusable guard: function isError(value: unknown): value is Error { return value instanceof Error; }. That type predicate narrows the value so err.name is a string with no assertion — the same technique you met in Narrowing and Type Guards, applied at the one place where types are weakest.

Results: failure you can see in the signature

An alternative treats failure as a value. A Result is a discriminated union of success and failure, so the ok property decides which branch exists:

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

Expected output: no output — but from now on, a function like parseConfig(text: string): Result<Config, ParseError> announces its failure mode in the one place every caller must read: the return type. Compare the two styles:

Neither is universally correct. Throw for bugs and for failures nobody can recover from; return a result for outcomes the caller genuinely branches on. The hybrid in the worked example below uses both: it catches internally, then returns the outcome.

Exhaustive handling with never

A discriminated union only helps if every branch is handled. Make the compiler prove it by writing a function whose final case can never be reached:

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}
type Status = 'idle' | 'loading' | 'success' | 'error';
function labelFor(status: Status): string {
  switch (status) {
    case 'idle': return 'Nothing yet';
    case 'loading': return 'Working...';
    case 'success': return 'Done';
    case 'error': return 'Failed';
    default: return assertNever(status);
  }
}

Expected output: labelFor('loading') returns Working.... Now add a fifth member to Status and the switch fails to compile — ex.ts(11,33): error TS2345: Argument of type '"cancelled"' is not assignable to parameter of type 'never'.

The error appears exactly at the branch that has not been written yet. This is the payoff of chapter 21: a type that describes failure states, a switch that must cover them, and a compiler that refuses to let the two drift apart.

Optional Error subtypes

Plain Error loses information, so model the failures you actually handle. A subclass carries typed fields and still passes every instanceof Error check:

export class HttpError extends Error {
  constructor(readonly status: number, readonly url: string) {
    super(`HTTP ${status} from ${url}`);
    this.name = 'HttpError';
  }
}
export class ParseError extends Error {
  constructor(message: string, readonly snippet: string) {
    super(message);
    this.name = 'ParseError';
  }
}

Set this.name in the constructor so console.log output is readable, and keep the constructors' parameter types simple — every field you add is a field call sites must narrow to. One caveat from Classes and Access Modifiers: with target: "ES5" extending built-ins breaks instanceof unless you restore the prototype with Object.setPrototypeOf(this, new.target.prototype). Modern targets (ES2015 and later) do it for you.

Worked example: parseJson and safeFetch

Here is the pattern in full: parse defensively, fetch defensively, and let callers switch on a value they can trust.

Reusing the Result type defined above (exported from its module):

export function parseJson<T>(text: string): Result<T, ParseError> {
  try {
    return { ok: true, value: JSON.parse(text) as T };
  } catch (err: unknown) {
    const detail = err instanceof Error ? err.message : String(err);
    return { ok: false, error: new ParseError(detail, text.slice(0, 40)) };
  }
}

export async function safeFetch<T>(
  url: string,
  init?: RequestInit,
): Promise<Result<T, HttpError | ParseError>> {
  const response = await fetch(url, init);
  if (!response.ok) {
    return { ok: false, error: new HttpError(response.status, url) };
  }
  const text = await response.text();
  return parseJson<T>(text);
}

Consuming it costs one if, and inside each branch the type is exact — no assertion, no optional chaining:

const result = await safeFetch<Course[]>('/api/courses');
if (result.ok) {
  console.log(`loaded ${result.value.length} courses`);
} else {
  console.log(`${result.error.name}: ${result.error.message}`);
}

Expected output: exactly one of the two lines, depending on the world — either loaded 3 courses, or HttpError: HTTP 404 from /api/courses / ParseError: Unexpected token '<', "<html><bod"... is not valid JSON.

What makes this work is that ok is a literal type in each union member. Narrowing on it is the same mechanism as narrowing a Status string, so the pattern scales from a two-member union to a full request state machine without new machinery.

Common mistakes

• Annotating the catch parameter — catch (e: ApiError) is a compile error (TS1196); narrow the unknown you are given instead.
• Catching and doing nothing — an empty catch {} hides the bug and the data at once; at minimum log messageOf(err).
• Using a Result for programmer bugs — returning { ok: false } for an impossible state just moves the crash; throw and fix the caller.
• Assertions inside the catch — (err as Error).message compiles and then throws on the one failure that mattered; use instanceof.
• Forgetting the default branch — without assertNever or an exhaustive check, adding a union member silently skips your switch.

Practice checklist

1. Write messageOf(err: unknown) and prove it handles an Error, a string and a plain object.
2. Define Result<T, E> from memory, then implement safeDivide(a: number, b: number): Result<number, string>.
3. Refactor a function that throws into one that returns a Result, and list in prose which callers should switch from one style to the other.
4. Add a member to a Status union and observe every non-exhaustive switch report TS2345.
5. Build an HttpError subclass, throw it, and confirm instanceof HttpError narrows the caught value in a catch block.

What's next?

Failure now has a type. Next you prove the types behave, with tests that are themselves checked by the compiler: Testing with TypeScript.