Making TypeScript Safer with Neverthrow

How explicit error handling transformed my codebase from fragile to robust

For years, I wrote TypeScript the same way most developers do: throwing exceptions, wrapping everything in try-catch blocks, and hoping for the best. Then I discovered neverthrow, and it fundamentally changed how I think about error handling.

The Problem with Exceptions

Traditional exception-based error handling in TypeScript has a critical flaw: it’s invisible. When you call a function, you have no idea whether it might throw an error unless you read the implementation or the documentation. TypeScript’s type system, which catches so many bugs at compile time, offers zero help here.

Consider this seemingly innocent function:

function parseUserData(json: string): User {
  return JSON.parse(json);
}

This function can fail in multiple ways. The JSON might be malformed, the structure might not match the User type, or the string might be empty. But none of that is reflected in the type signature. The caller has no way of knowing they need to handle errors unless they encounter them at runtime.

Enter Neverthrow

Neverthrow brings Result types to TypeScript, a pattern popularized by languages like Rust and Haskell. Instead of throwing exceptions, functions return a Result type that explicitly indicates success or failure:

type Result<T, E> = Ok<T> | Err<E>

A Result is either Ok (containing a success value) or Err (containing an error). The beauty is that this is encoded in the type system, so you can’t ignore errors even if you try.

How I Transformed My Codebase

When I started refactoring my application to use neverthrow, I began with the most fragile parts: API calls, database queries, and data parsing. Here’s a real example of how a typical API function evolved.

Before neverthrow, my API client looked like this:

async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) {
    throw new Error('Failed to fetch user');
  }
  return await response.json();
}

After refactoring with neverthrow:

import { Result, ok, err } from 'neverthrow';

async function fetchUser(id: string): Promise<Result<User, ApiError>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      return err({ type: 'HTTP_ERROR', status: response.status });
    }
    const data = await response.json();
    return ok(data);
  } catch (e) {
    return err({ type: 'NETWORK_ERROR', message: e.message });
  }
}

Now the function signature tells you everything you need to know. It returns a Result that might contain a User or an ApiError. No surprises.

The Power of Composition

What really sold me on neverthrow was how elegantly Results compose. The library provides methods like map, andThen, and match that let you chain operations while maintaining type safety.

Here’s how I built a user registration flow:

function registerUser(input: RegistrationInput): Result<User, RegistrationError> {
  return validateEmail(input.email)
    .andThen(email => validatePassword(input.password).map(() => email))
    .andThen(email => createUser({ email, password: input.password }))
    .andThen(user => sendWelcomeEmail(user).map(() => user));
}

Each step in this pipeline can fail, and the error automatically short-circuits the chain. If validateEmail fails, none of the subsequent operations execute. The types guide you through handling every possible failure case.

Real-World Impact

After converting my core business logic to use neverthrow, I saw immediate benefits:

Fewer runtime errors. Errors that previously crashed my application were now handled explicitly. The compiler forced me to deal with every possible failure path.

Better error messages. Instead of generic “something went wrong” messages, I could provide specific, actionable feedback to users because I knew exactly what failed and why.

Easier refactoring. When I changed a function to return a new error type, TypeScript showed me every place in the codebase that needed updating. No more hunting through logs to find missed edge cases.

Clearer code reviews. New team members could look at a function signature and immediately understand what could go wrong. The learning curve for the codebase decreased significantly.

The Learning Curve

I won’t pretend the transition was effortless. The functional programming concepts took time to internalize, and I had to resist the urge to fall back on try-catch for “just this one function.” But once the patterns clicked, I found myself writing safer code naturally.

The key insight was realizing that Result types don’t add complexity; they make existing complexity visible. The errors were always there, lurking in my code. Neverthrow just forced me to acknowledge and handle them.

Should You Use Neverthrow?

If you’re building anything more complex than a prototype, I think the answer is yes. The upfront investment in learning Result types pays dividends in reduced bugs, improved maintainability, and better sleep at night knowing your error handling is comprehensive.

Start small. Pick one module or feature and convert it to use Results. Once you experience the difference between “I think I handled all the errors” and “the compiler verified I handled all the errors,” you’ll never want to go back.

Error handling isn’t glamorous, but it’s the difference between software that works and software that works reliably. Neverthrow helped me build the latter, and I’m convinced it can do the same for you.

Article