Error Handling in TypeScript: Comparing try-catch, neverthrow, and Effect.ts

Introduction

Robust error handling is a cornerstone of reliable application development. It's not just about preventing crashes—it's about gracefully handling exceptional cases, providing meaningful feedback, and maintaining application state integrity. In TypeScript applications, developers face particular challenges with traditional error handling mechanisms:

JavaScript's runtime exceptions provide limited type safety
Error propagation can be difficult to track across asynchronous operations
The lack of compile-time checking for unhandled error paths
Potential for inconsistent error handling patterns across teams

This article explores three distinct approaches to error handling in TypeScript, each representing a different paradigm:

try-catch blocks: The built-in, imperative approach familiar to most developers
neverthrow: A functional library providing explicit Result types
Effect.ts: A comprehensive functional effect system

We'll examine each approach in detail, provide practical examples, compare their strengths and weaknesses, and offer guidance on when to choose each one.

Deep Dive: try-catch Blocks

The Mechanism

The try-catch block is JavaScript's native error handling construct, built directly into the language. It consists of:

A try block containing code that might throw an exception
A catch block that executes when an exception occurs
An optional finally block that executes regardless of whether an exception was thrown

Here's a basic example:

1function divideNumbers(a: number, b: number): number {
2  try {
3    if (b === 0) {
4      throw new Error("Division by zero");
5    }
6    return a / b;
7  } catch (error) {
8    console.error("An error occurred:", error);
9    return NaN; // Return a fallback value
10  } finally {
11    console.log("Division operation attempted");
12  }
13}

TypeScript-Specific Considerations

In TypeScript, we can improve type safety by checking error types:

1class DatabaseError extends Error {
2  constructor(message: string) {
3    super(message);
4    this.name = "DatabaseError";
5  }
6}
7
8class ValidationError extends Error {
9  constructor(message: string) {
10    super(message);
11    this.name = "ValidationError";
12  }
13}
14
15function processUserData(userId: string): void {
16  try {
17    const userData = fetchUserData(userId);
18    processData(userData);
19  } catch (error) {
20    if (error instanceof DatabaseError) {
21      // Handle database errors specifically
22      notifyAdmin("Database error: " + error.message);
23    } else if (error instanceof ValidationError) {
24      // Handle validation errors
25      displayUserMessage("Invalid data: " + error.message);
26    } else {
27      // Handle unknown errors
28      logError("Unknown error:", error);
29    }
30  }
31}

Handling Async Operations

With the advent of async/await, try-catch can also handle asynchronous operations:

1async function fetchAndProcessUser(userId: string): Promise<UserData> {
2  try {
3    const response = await fetch(`/api/users/${userId}`);
4
5    if (!response.ok) {
6      throw new Error(`API error: ${response.status}`);
7    }
8
9    const userData = await response.json();
10    return processUserData(userData);
11  } catch (error) {
12    console.error("Failed to fetch user:", error);
13    telemetryClient.trackException(error);
14    throw error; // Re-throw or handle as appropriate
15  }
16}

Pros of try-catch

Built-in language feature: No external dependencies required
Universally understood: Most developers are familiar with this pattern
Works with both sync and async code: Especially with async/await
Simple implementation: Straightforward for basic error handling needs

Cons of try-catch

Untyped errors by default: TypeScript doesn't track which errors might be thrown
Runtime-only mechanism: No compile-time guarantees about error handling
Can lead to verbose code: Especially with nested try-catch blocks
Imperative control flow: Can make code harder to reason about
Doesn't force error handling: Callers can ignore potential errors

Deep Dive: neverthrow Library

The neverthrow library brings the functional "Result" type pattern to TypeScript. This pattern, popular in languages like Rust and Scala, represents computations that might fail, making errors explicit values in the type system.

Core Concept: The Result Type

The central concept is a Result<T, E> type, which can be either:

Ok<T>: Representing success with a value of type T
Err<E>: Representing failure with an error of type E

This explicit representation forces developers to acknowledge and handle potential failures at compile time.

Basic Usage

1import { Result, ok, err } from 'neverthrow';
2
3function divide(a: number, b: number): Result<number, string> {
4  if (b === 0) {
5    return err('Division by zero');
6  }
7  return ok(a / b);
8}
9
10// Using the result
11const result = divide(10, 2);
12
13if (result.isOk()) {
14  console.log('Result:', result.value);
15} else {
16  console.error('Error:', result.error);
17}
18
19// Or using match for more concise handling
20result.match(
21  (value) => console.log('Result:', value),
22  (error) => console.error('Error:', error)
23);

Wrapping Functions That Might Throw

Neverthrow provides utilities to wrap functions that might throw exceptions:

1import { Result, ok, err } from 'neverthrow';
2
3function parseJSON(json: string): Result<unknown, Error> {
4  return Result.fromThrowable(
5    JSON.parse,
6    (error) => error instanceof Error ? error : new Error(String(error))
7  )(json);
8}
9
10// Usage
11const result = parseJSON('{"name": "John"}');
12const invalidResult = parseJSON('{"name": John}'); // Missing quotes, will be an Err

Chaining Operations

One of neverthrow's strengths is operation chaining:

1import { Result, ok, err } from 'neverthrow';
2
3interface User {
4  id: number;
5  name: string;
6}
7
8function findUser(id: number): Result<User, string> {
9  // Simulated database lookup
10  if (id === 1) {
11    return ok({ id: 1, name: 'John' });
12  }
13  return err(`User with id ${id} not found`);
14}
15
16function validateUserName(user: User): Result<User, string> {
17  if (user.name.length >= 3) {
18    return ok(user);
19  }
20  return err('User name too short');
21}
22
23function processUser(user: User): Result<string, string> {
24  // Some processing
25  return ok(`Processed user ${user.name}`);
26}
27
28// Chain operations together
29const result = findUser(1)
30  .andThen(validateUserName)  // Only runs if findUser returns Ok
31  .andThen(processUser);      // Only runs if validateUserName returns Ok
32
33// Handle the final result
34result.match(
35  (success) => console.log(success),
36  (error) => console.error('Error:', error)
37);

Async Support

Neverthrow also handles asynchronous operations:

1import { ResultAsync, okAsync, errAsync } from 'neverthrow';
2
3function fetchUser(id: number): ResultAsync<User, Error> {
4  return ResultAsync.fromPromise(
5    fetch(`/api/users/${id}`).then(res => res.json()),
6    (error) => error instanceof Error ? error : new Error(String(error))
7  );
8}
9
10// Chain async operations
11const result = fetchUser(1)
12  .andThen(user => {
13    if (user.isActive) {
14      return okAsync(user);
15    }
16    return errAsync(new Error('User is inactive'));
17  })
18  .map(user => user.name);
19
20// Handle the result
21result
22  .match(
23    (name) => console.log('User name:', name),
24    (error) => console.error('Error:', error)
25  );

Pros of neverthrow

Type-safe errors: Error types are explicitly declared and checked
Explicit error handling: Makes potential failures visible in function signatures
Composable operations: Easy to chain operations that might fail
Predictable control flow: Clear paths for success and failure cases
Forces acknowledgment: Callers must handle or propagate errors explicitly
Minimal learning curve: Relatively simple concept compared to full effect systems

Cons of neverthrow

External dependency: Requires adding a library to your project
Some boilerplate: Can be more verbose than try-catch for simple cases
Limited scope: Focused primarily on the Result type pattern
Learning curve: Requires adjustment for developers used to imperative error handling

Deep Dive: Effect.ts Library

Effect.ts is a comprehensive functional programming library for TypeScript that goes beyond simple error handling. It represents computations as values through the Effect<A, E, R> type, where:

A: The success type the effect might produce
E: The error type the effect might fail with
R: The environment/dependencies the effect requires to run

This approach treats errors as a fundamental aspect of the type system, integrated with other concerns like dependencies and asynchrony.

Core Concepts

1import { Effect } from 'effect';
2
3// Create a successful effect
4const success = Effect.succeed("hello");
5
6// Create a failing effect
7const failure = Effect.fail(new Error("Something went wrong"));
8
9// Run the effect
10Effect.runSync(success); // Returns "hello"
11Effect.runSyncExit(failure); // Returns a failure Exit value

Wrapping Throwing Functions

Effect provides utilities to safely wrap functions that might throw:

1import { Effect } from 'effect';
2
3// Wrap a synchronous function that might throw
4const parseJson = (input: string) =>
5  Effect.try({
6    try: () => JSON.parse(input),
7    catch: (error) => new Error(`Parse error: ${String(error)}`)
8  });
9
10// Wrap an asynchronous function that might throw
11const fetchData = (url: string) =>
12  Effect.tryPromise({
13    try: () => fetch(url).then(res => res.json()),
14    catch: (error) => new Error(`Fetch error: ${String(error)}`)
15  });

Creating Tagged Errors

Effect encourages the use of tagged errors for better error handling:

1import { Effect, Data } from 'effect';
2
3// Define custom error types
4class ValidationError extends Data.TaggedError("ValidationError")<{
5  message: string;
6}> {}
7
8class DatabaseError extends Data.TaggedError("DatabaseError")<{
9  code: number;
10  message: string;
11}> {}
12
13// Function that can fail with a specific error type
14const validateUser = (user: unknown): Effect.Effect<User, ValidationError> => {
15  if (!user || typeof user !== 'object' || !('name' in user)) {
16    return Effect.fail(new ValidationError({ message: 'Invalid user structure' }));
17  }
18  return Effect.succeed(user as User);
19};
20
21const getUserFromDB = (id: number): Effect.Effect<User, DatabaseError> => {
22  if (id <= 0) {
23    return Effect.fail(new DatabaseError({ code: 404, message: 'User not found' }));
24  }
25  return Effect.succeed({ id, name: 'John Doe' });
26};

Composing Effects

One of Effect's strengths is composition:

1import { Effect } from 'effect';
2
3// Define our effect pipeline
4const program = Effect.gen(function* (_) {
5  // Get user ID from somewhere
6  const userId = yield* _(getUserId);
7
8  // Get user from database
9  const user = yield* _(getUserFromDB(userId));
10
11  // Validate the user
12  const validUser = yield* _(validateUser(user));
13
14  // Process the valid user
15  const result = yield* _(processUser(validUser));
16
17  return result;
18});
19
20// Run the effect
21Effect.runPromise(program)
22  .then(result => console.log('Success:', result))
23  .catch(error => console.error('Error:', error));

Complex Error Handling

Effect provides powerful error handling capabilities:

1import { Effect } from 'effect';
2
3const program = getUserFromDB(5)
4  // Handle specific error types
5  .catchTag('DatabaseError', (error) => {
6    if (error.code === 404) {
7      return Effect.succeed({ id: 5, name: 'Guest User' }); // Fallback
8    }
9    return Effect.fail(error); // Re-throw other database errors
10  })
11  .pipe(
12    // Transform errors
13    Effect.mapError(error =>
14      new Error(`Processing failed: ${error.message}`)
15    ),
16    // Provide retry policy
17    Effect.retry({ times: 3, delay: 1000 }),
18    // Add timeout
19    Effect.timeout('5 seconds')
20  );

Resource Management

Effect also handles resource acquisition and release:

1import { Effect } from 'effect';
2
3const acquireConnection = Effect.acquireRelease(
4  // Acquire resource
5  Effect.sync(() => {
6    console.log('Opening database connection');
7    return { query: (sql: string) => `Result of ${sql}` };
8  }),
9  // Release resource (always called, even on failure)
10  (connection) => Effect.sync(() => {
11    console.log('Closing database connection');
12  })
13);
14
15const program = Effect.gen(function* (_) {
16  const connection = yield* _(acquireConnection);
17  const result = connection.query('SELECT * FROM users');
18  return result;
19});
20
21Effect.runPromise(program);

Pros of Effect.ts

Comprehensive error handling: Fully integrated with dependencies and async operations
Superior type safety: Errors are tracked precisely in the type system
Highly composable: Complex operations can be combined with clear error flow
Powerful combinators: Rich library of utilities for error handling
Resource safety: Built-in constructs for proper resource management
Concurrency support: First-class tools for handling errors in concurrent operations
Testability: Effects are descriptive, making them easier to test

Cons of Effect.ts

Steeper learning curve: Requires understanding functional programming concepts
Significant paradigm shift: Different way of structuring code
Larger dependency: More substantial library than neverthrow
Potential overhead: Slightly more runtime overhead than native constructs
Possibly overkill: May be excessive for simple applications

Comparative Analysis

Criterion	try-catch	neverthrow	Effect.ts
Type Safety	Limited (runtime only)	Good (explicit Result type)	Excellent (integrated with effect system)
Explicitness	Low (hidden in implementation)	High (visible in function signatures)	High (core part of Effect type)
Composability	Poor (imperative, breaks flow)	Good (chainable operations)	Excellent (comprehensive combinators)
Runtime vs. Compile-time	Runtime only	Compile-time enforced	Compile-time enforced
Learning Curve	Low (built-in)	Moderate (simple concept)	Steep (full effect system)
Boilerplate	Low for simple cases, high for complex	Moderate	Initially high, but pays off for complex logic
Scope	Error handling only	Primarily error handling	Complete effect system (errors, async, resources, etc.)
Ecosystem Integration	Native JS/TS	Simple integration	Requires more adaptation
Performance	Native (fastest)	Minor overhead	Some overhead, optimized for larger applications

When to Choose Which

Choose try-catch when:

Building simple scripts or small applications
Working at application boundaries (e.g., top-level error handlers)
Integrating with libraries that rely heavily on exceptions
The team is not familiar with functional programming concepts
You need to minimize dependencies

Example scenario: A small utility script, a prototype, or when wrapping third-party code that throws exceptions at the API boundary.

Choose neverthrow when:

You want explicit, type-safe error handling without a major paradigm shift
Building libraries or modules where error states should be clear to consumers
Working in a team with mixed familiarity with functional programming
You need better composition than try-catch but don't want the full Effect.ts complexity
Your project primarily needs the Result pattern without other functional programming features

Example scenario: A medium-sized application, a shared utility library, or when implementing business logic with clearly defined error states.

Choose Effect.ts when:

Building complex applications with sophisticated error handling needs
Your team is comfortable with functional programming concepts
You need integrated handling of errors, async operations, and resources
Working on a large codebase where consistency and testability are crucial
Performance and scalability are important concerns
You want a comprehensive approach to functional programming in TypeScript

Example scenario: A large-scale backend service, a complex frontend application with extensive state management, or when working in a team fully committed to functional programming principles.

Conclusion

TypeScript offers a spectrum of error handling approaches, from the familiar but limited try-catch blocks to the comprehensive Effect.ts library. Each has its place:

try-catch provides simplicity and familiarity but lacks compile-time safety.
neverthrow strikes a balance with its Result type, offering explicit error handling without a complete paradigm shift.
Effect.ts delivers the most powerful and type-safe approach but requires embracing functional programming concepts.

The trend in modern TypeScript development is clearly moving toward more explicit, type-safe error handling. While try-catch remains useful at application boundaries, libraries like neverthrow and Effect.ts reflect the growing recognition that errors should be first-class citizens in our type systems.

Your choice should reflect your team's expertise, project complexity, and specific requirements. For teams new to functional error handling, neverthrow offers an excellent entry point. For those ready to embrace a more comprehensive approach, Effect.ts provides a robust foundation for building complex, reliable systems.

Remember: the best error handling approach is the one that helps your team build more reliable software while maintaining productivity and code clarity.