JavaScript Error Handling Patterns

Master exception-based and value-based error handling approaches, from traditional try-catch patterns to modern functional programming techniques with monadic structures.

Abstract

The core decision in JavaScript error handling is where failure information lives: in an invisible control flow path (exceptions) or in the function’s return type (values). This choice ripples through your entire architecture.

Exception model (try/catch): Failure is a side effect. Functions have two exit paths—return and throw—but the type signature only declares one. The runtime unwinds the stack searching for handlers, which is expensive (~10-100x slower than returns) and makes control flow non-local.

Value model (Result<T, E>): Failure is data. Functions return a discriminated union that forces callers to acknowledge both outcomes. Operations compose via .map() (transform success) and .andThen() (chain fallible operations), with failures automatically bypassing subsequent success handlers—this is Railway Oriented Programming.

The trade-off matrix:

Recommendation: Use neverthrow (v8.x) for new TypeScript code—it balances type safety with ergonomics and has ESLint rules that enforce Result consumption. Reserve try/catch for external boundaries (parsing user input, calling throwing APIs) and convert immediately to Result types.

Introduction

Error handling shapes architecture. The choice between exceptions and values determines how failure propagates through your system, how composition works, and what guarantees your type system can provide.

JavaScript’s try...catch mechanism, standardized in ECMAScript 3 (ES3, December 1999), treats errors as exceptional events that halt normal execution and transfer control elsewhere. This model served well for decades but carries fundamental limitations: untyped catch blocks, non-local control flow, and easy error swallowing.

The functional alternative—errors as return values—gained momentum with TypeScript’s adoption and the influence of languages like Rust (Result<T, E>) and Haskell (Either a b). Libraries like neverthrow and fp-ts bring these patterns to JavaScript, offering type safety and composability that exceptions cannot provide.

Version context: This article covers ECMAScript 2025 (ES16) for language features and TypeScript 5.x for type system capabilities. TC39 proposal stages are current as of January 2026.

Section 1: The Orthodox Approach - Exceptions as Control Flow

JavaScript’s exception model, rooted in imperative traditions inherited from C++ and Java, treats errors as control flow events that halt execution and transfer to a handler.

1.1 The Core Mechanics: try, throw, and Error

Per ECMA-262 §14.15, the try statement provides structured exception handling:

2 collapsed lines
1
// ECMA-262 §14.15: TryStatement
2
// try Block Catch | try Block Finally | try Block Catch Finally
3
try {
4
  const result = riskyOperation()
5
  return processResult(result)
6
} catch (error) {
7
  console.error("Operation failed:", error)
8
  return fallbackValue
9
} finally {
10
  cleanup() // Always executes, even after return/throw
11
}

Execution semantics (per ECMA-262 §14.15.3):

1. Execute the try block
2. If an exception is thrown, the runtime creates a ThrowCompletion record and searches the call stack for a matching catch
3. If found, bind the thrown value to the catch parameter and execute the catch block
4. Execute finally regardless of outcome—even if try or catch contains return or throw

Critical edge case: The finally block can override returns and suppress exceptions:

1
function surprising() {
2
  try {
3
    throw new Error("Original error")
4
  } finally {
5
    return "finally wins" // Suppresses the throw!
6
  }
7
}
8
surprising() // Returns "finally wins", no error thrown

The throw statement (ECMA-262 §14.14) accepts any value—this is a design flaw, not a feature:

3 collapsed lines
1
// ECMA-262 allows throwing ANY value
2
// This makes catch blocks fundamentally untyped
3

4
// Anti-patterns (still legal):
5
throw "Something went wrong" // string
6
throw 404 // number
7
throw { code: "E_FAIL" } // plain object
8
throw null // null (breaks error.message access)
9

10
// Correct pattern:
11
throw new Error("Something went wrong")
12
throw new TypeError("Expected string, got number")

Error hierarchy (ECMA-262 §20.5): The built-in error types form a prototype chain:

• Error (base)
  • EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError
  • AggregateError (ES2021, for Promise.any rejections)

Each instance captures:

• message: Human-readable description
• name: Error type name (e.g., “TypeError”)
• stack: Non-standard but universally implemented stack trace
• cause (ES2022): Optional chained error for wrapping

ES2022 addition: The cause option enables error chaining without losing the original stack:

1
throw new Error("High-level failure", { cause: originalError })

1.2 Asynchronous Error Propagation

Promises (ES2015) and async/await (ES2017) extend exception semantics to asynchronous code, but with critical differences in error propagation.

Promise rejection uses .catch() for error handling:

2 collapsed lines
1
// Promise rejection becomes ThrowCompletion when awaited
2
// or is handled by .catch()
3
fetch("/api/data")
4
  .then((response) => response.json())
5
  .then((data) => processData(data))
6
  .catch((error) => {
7
    console.error("Request failed:", error)
8
    return fallbackData
9
  })

async/await (ES2017) unifies syntax but changes timing:

2 collapsed lines
1
// await converts Promise rejection to thrown exception
2
// enabling standard try/catch
3
async function fetchData() {
4
  try {
5
    const response = await fetch("/api/data")
6
    const data = await response.json()
7
    return processData(data)
8
  } catch (error) {
9
    console.error("Request failed:", error)
10
    return fallbackData
11
  }
12
}

Critical edge cases and failure modes:

1. Unhandled rejection (silent failure pre-Node 15):

   1
   async function leaky() {
   2
     fetch("/api/data") // No await, no catch - rejection lost!
   3
   }

   Node.js evolution: Prior to Node.js 15, unhandled rejections only emitted warnings. Node.js 15+ crashes the process by default (--unhandled-rejections=throw).

2. Promise constructor anti-pattern:

   1
   // Exceptions in Promise executor are caught and become rejections
   2
   new Promise((resolve) => {
   3
     throw new Error("Sync throw") // Becomes rejection, not uncaught exception
   4
   })
   5
   
   6
   // BUT: async callbacks inside the executor are NOT caught
   7
   new Promise((resolve) => {
   8
     setTimeout(() => {
   9
       throw new Error("Escapes!") // Uncaught exception
   10
     }, 0)
   11
   })

3. Concurrent await gotcha:

   3 collapsed lines
   1
   // Sequential: Second fetch waits for first
   2
   // If first fails, second never starts
   3
   const a = await fetch("/a") // Throws here
   4
   const b = await fetch("/b") // Never reached
   5
   
   6
   // Concurrent: Both start immediately
   7
   // First rejection wins, second rejection is unhandled!
   8
   const [a, b] = await Promise.all([
   9
     fetch("/a"), // Rejects
   10
     fetch("/b"), // Also rejects - this rejection is "lost"
   11
   ])
   12
   
   13
   // Fix: Use Promise.allSettled for independent operations
   14
   const results = await Promise.allSettled([fetch("/a"), fetch("/b")])

1.3 A Critical Assessment of the Exception Model

Exceptions have fundamental architectural costs that motivate alternatives.

1. Functions have invisible exit paths

A signature like function processData(data): ProcessedData lies—the function has two exit paths (return and throw), but only one is declared. This breaks referential transparency and makes reasoning about code harder.

1
// Type signature promises ProcessedData
2
function processData(data: Input): ProcessedData {
3
  if (!data.valid) throw new Error("Invalid") // Hidden exit
4
  return transform(data)
5
}
6

7
// Caller has no compile-time warning
8
const result = processData(input) // Might throw!

2. Stack unwinding is expensive

When an exception is thrown, the runtime must:

1. Allocate an Error object and capture the stack trace
2. Search up the call stack for a catch handler
3. Unwind each stack frame, running any finally blocks

Performance impact: Throwing is 10-100x slower than returning. In V8, a thrown error costs ~1-2μs vs ~10-50ns for a return. This matters in hot paths.

4 collapsed lines
1
// Benchmark: 1M iterations
2
// Return path: ~15ms
3
// Throw path: ~1500ms (100x slower)
4

5
// Anti-pattern: using exceptions for control flow
6
function findItem(arr, predicate) {
7
  try {
8
    arr.forEach((item) => {
9
      if (predicate(item)) throw item // Don't do this
10
    })
11
  } catch (found) {
12
    return found
13
  }
14
  return null
15
}

3. TypeScript’s unknown catch parameter

Per TypeScript 4.4+, catch variables are typed as unknown (previously any). This is correct—JavaScript allows throwing anything—but forces runtime guards:

1
try {
2
  riskyOperation()
3
} catch (error) {
4
  // error: unknown - must narrow before use
5
  if (error instanceof Error) {
6
    console.log(error.message) // Safe
7
  } else if (typeof error === "string") {
8
    console.log(error) // Also possible
9
  } else {
10
    console.log("Unknown error type", error)
11
  }
12
}

TypeScript history: Prior to 4.4, catch variables were any by default. The useUnknownInCatchVariables compiler option (now default with strict) changed this to unknown, forcing explicit type narrowing.

4. Silent error swallowing

Nothing prevents empty or incomplete catch blocks:

1
try {
2
  await criticalOperation()
3
} catch (e) {
4
  // "I'll handle this later" - famous last words
5
  console.log("Error occurred")
6
  // No re-throw, no recovery, error is lost
7
}

5. Error.isError (ES2026)

A new standard feature advancing to Stage 4 addresses error type checking across realms:

1
// Problem: instanceof fails across iframes/realms
2
const iframe = document.createElement("iframe")
3
document.body.appendChild(iframe)
4
const IframeError = iframe.contentWindow.Error
5
const foreignError = new IframeError("from iframe")
6

7
foreignError instanceof Error // false! Different Error constructor
8

9
// Solution (ES2026):
10
Error.isError(foreignError) // true - works across realms

Section 2: The Paradigm Shift - Errors as Return Values

The functional alternative treats errors as data, not control flow. Failure becomes part of the return type, making it visible in signatures and enforceable by the type system.

2.1 The Go-Style Tuple Pattern

Go’s idiomatic value, err := operation() pattern has been adapted to JavaScript. Functions return [data, error] tuples:

3 collapsed lines
1
// Helper to convert Promise rejections to tuples
2
// Commonly called "to" or "safe"
3

4
function to<T>(promise: Promise<T>): Promise<[T | null, Error | null]> {
5
  return promise.then((data) => [data, null]).catch((err) => [null, err])
6
}
7

8
async function fetchUserData(id: string) {
9
  const [user, err] = await to(fetch(`/api/users/${id}`))
10
  if (err) {
11
    console.error("Failed to fetch user:", err)
12
    return null
13
  }
14
  return user
15
}

Why this pattern exists: Explicit error acknowledgment at call sites. The err variable is visible, nudging developers to handle it.

Why it’s a leaky abstraction:

1. No type-level exclusivity: [T | null, Error | null] allows four states: [value, null], [null, error], [null, null], and [value, error]. Only two are valid.

   1
   // TypeScript cannot prevent this:
   2
   const result: [User | null, Error | null] = [null, null] // Valid type, invalid state

2. Verbose chaining produces “staircase code”:

   5 collapsed lines
   1
   // Each step needs its own error check
   2
   // Compare to .andThen() chaining in Result types
   3
   
   4
   async function processUserOrder(userId: string) {
   5
     const [user, err1] = await to(fetchUser(userId))
   6
     if (err1) return [null, err1]
   7
   
   8
     const [orders, err2] = await to(fetchOrders(user.id))
   9
     if (err2) return [null, err2]
   10
   
   11
     const [processed, err3] = await to(processOrders(orders))
   12
     if (err3) return [null, err3]
   13
   
   14
     return [processed, null]
   15
   }

3. No forced handling: Nothing prevents ignoring the error:

   1
   const [user, err] = await to(fetchUser(id))
   2
   // Oops, forgot to check err
   3
   console.log(user.name) // Runtime error if err was set

4. Stack trace loss: If the caught value isn’t an Error instance, you lose debugging context:

   1
   // Some APIs reject with non-Error values
   2
   const [data, err] = await to(someBadApi())
   3
   // err might be a string, number, or object - no stack trace

When tuples make sense: Simple scripts, prototypes, or when you genuinely cannot add dependencies. For production systems, prefer proper Result types.

2.2 The Functional Evolution: Monadic Error Handling

The Result monad (or Either in Haskell/fp-ts terminology) formalizes error-as-value with type-safe guarantees. This pattern originates from ML-family languages and was popularized in Rust.

The core insight: A discriminated union with exactly two variants:

1
type Result<T, E> =
2
  | { ok: true; value: T } // Success
3
  | { ok: false; error: E } // Failure

This structure makes invalid states impossible at the type level. You cannot have both value and error, or neither.

Railway Oriented Programming (Scott Wlaschin’s term) visualizes this as two parallel tracks:

The chainable API:

3 collapsed lines
1
// Result monad operations compose declaratively
2
// Each transforms or short-circuits based on Ok/Err state
3

4
const result = parseNumber("10")
5
  .map((x) => x * 2) // Transform Ok value (Err passes through)
6
  .andThen(
7
    (
8
      x, // Chain fallible operation
9
    ) => (x > 15 ? ok(x) : err("Value too small")),
10
  )
11
  .orElse((e) => ok(defaultValue)) // Recover from error
12
  .match(
13
    (value) => `Success: ${value}`, // Handle Ok
14
    (error) => `Error: ${error}`, // Handle Err
15
  )

Core methods explained:

Why .andThen() is the key operation: It prevents nested Result types. Without it:

1
// .map() on a fallible function produces nested Results
2
const nested: Result<Result<number, string>, ParseError> = parseNumber("10").map((n) => validateRange(n)) // validateRange returns Result
3

4
// .andThen() flattens automatically
5
const flat: Result<number, string | ParseError> = parseNumber("10").andThen((n) => validateRange(n))

Monad laws (for the mathematically inclined): Any proper Result implementation must satisfy:

1. Left identity: ok(a).andThen(f) ≡ f(a)
2. Right identity: m.andThen(ok) ≡ m
3. Associativity: m.andThen(f).andThen(g) ≡ m.andThen(x => f(x).andThen(g))

Section 3: Implementing Monadic Patterns in Practice

Several TypeScript libraries implement the Result pattern with different trade-offs in API design, scope, and ecosystem integration.

3.1 The Comprehensive Toolkit: fp-ts

fp-ts (v2.16.x, latest as of January 2026) is a complete functional programming toolkit for TypeScript. Its Either<E, A> type implements the Result pattern with Left<E> for failure and Right<A> for success (matching Haskell convention).

Key design choice: Standalone pipeable functions rather than method chaining. Data flows through pipe():

4 collapsed lines
1
import { pipe } from "fp-ts/function"
2
import * as E from "fp-ts/Either"
3
// fp-ts uses free functions + pipe() rather than method chaining
4
// This enables tree-shaking and follows FP conventions
5

6
function parseNumber(s: string): E.Either<string, number> {
7
  const n = parseFloat(s)
8
  return isNaN(n) ? E.left("Invalid number") : E.right(n)
9
}
10

11
const result = pipe(
12
  parseNumber("10"),
13
  E.map((x) => x * 2),
14
  E.chain((x) => (x > 15 ? E.right(x) : E.left("Value too small"))),
15
  E.match(
16
    (error) => `Computation failed: ${error}`,
17
    (value) => `Computation succeeded: ${value}`,
18
  ),
19
)
20
// result is "Computation succeeded: 20"

fp-ts strengths:

• Mathematically rigorous (follows Haskell patterns)
• Rich ecosystem: Option, Task, Reader, State, etc.
• Strong tree-shaking via module imports

fp-ts weaknesses:

• Steep learning curve—requires understanding FP vocabulary
• Verbose for simple cases
• pipe() syntax unfamiliar to OOP developers

Ecosystem evolution: fp-ts is merging with Effect-TS, which represents what would be fp-ts v3. For new projects, consider Effect-TS directly if you want the full FP ecosystem.

3.2 The Pragmatic Choice: neverthrow

neverthrow (v8.2.0, February 2025) focuses specifically on Result types with an ergonomic, method-chaining API familiar to OOP developers.

2 collapsed lines
1
import { ok, err, Result } from "neverthrow"
2
// Method chaining instead of pipe() - more familiar to most JS devs
3

4
function parseNumber(s: string): Result<number, string> {
5
  const n = parseFloat(s)
6
  return isNaN(n) ? err("Invalid number") : ok(n)
7
}
8

9
const result = parseNumber("10")
10
  .map((x) => x * 2)
11
  .andThen((x) => (x > 15 ? ok(x) : err("Value too small")))
12
  .match(
13
    (value) => `Computation succeeded: ${value}`,
14
    (error) => `Computation failed: ${error}`,
15
  )

neverthrow v8.x changes (breaking from v7):

• .orElse() can now change the Ok type (requires explicit type arguments in some cases)
• safeTry no longer requires .safeUnwrap() call
• New .orTee() method for side effects on errors (v8.2.0)
• ok(), err(), okAsync(), errAsync() accept zero arguments for void returns

The killer feature: ESLint enforcement

eslint-plugin-neverthrow enforces Result consumption. This rule fails if you don’t handle a Result:

1
// ESLint error: Result must be consumed
2
const result = parseNumber("10") // Error: unconsumed Result
3

4
// Fixed: must use .match(), .unwrapOr(), or ._unsafeUnwrap()
5
const value = parseNumber("10").unwrapOr(0)

This eliminates the “forgot to check error” class of bugs entirely.

ResultAsync for promises:

3 collapsed lines
1
import { ResultAsync, okAsync, errAsync } from "neverthrow"
2
// ResultAsync wraps Promise<Result> with chainable API
3
// Avoids the awkwardness of Promise + Result nesting
4

5
const fetchUser = (id: string): ResultAsync<User, FetchError> =>
6
  ResultAsync.fromPromise(
7
    fetch(`/api/users/${id}`).then((r) => r.json()),
8
    (e) => new FetchError(e),
9
  )
10

11
// Chains work across async boundaries
12
const result = await fetchUser("123")
13
  .andThen((user) => fetchOrders(user.id))
14
  .map((orders) => orders.filter((o) => o.active))

3.3 The Broader Ecosystem

3.4 Comparative Analysis

Decision matrix:

1
Need simplicity + no deps?     → Go-style tuples (accept limitations)
2
Need type safety + ergonomics? → neverthrow (recommended default)
3
Need full FP ecosystem?        → fp-ts or Effect-TS
4
Need Rust-like API?            → oxide.ts

Section 4: The Future of Ergonomic Error Handling

TC39 proposals in progress could dramatically improve value-based error handling ergonomics. Understanding their current status helps evaluate when (or if) to adopt polyfills.

4.1 The Pipeline Operator (|>): Streamlining Composition

Status: Stage 2 (as of January 2026)

Champions: J. S. Choi, James DiGioia, Ron Buckton, Tab Atkins-Bittner

The Pipeline Operator proposal provides left-to-right function composition. TC39 settled on the Hack pipe variant after rejecting F#-style pipes twice.

Syntax: The right-hand side contains an expression with a topic reference (currently %, but not finalized):

5 collapsed lines
1
import * as E from 'fp-ts/Either';
2
// Future syntax: Hack pipe with topic reference %
3
// The % placeholder represents the value from the previous step
4

5
declare function getUser(id: string): E.Either<Error, User>;
6
declare function validatePermissions(user: User): E.Either<Error, User>;
7

8
// Hack pipe variant (Stage 2)
9
const result = getUser(id)
10
  |> E.chain(%, user => validatePermissions(user))
11
  |> E.map(%, user => user.name)
12
  |> E.match(%,
13
       e => console.error(`Failure: ${e.message}`),
14
       name => console.log(`Success: ${name}`)
15
     );

Why Hack pipes over F# pipes?: F# pipes (|> fn) only work with unary functions. Hack pipes (|> fn(%, arg)) work with any expression, supporting multi-argument functions and method calls.

Current blockers: The topic token (%) is still being bikeshedded. Alternative proposals include ^, #, and @@. This syntactic debate has stalled progress.

Adoption recommendation: Use Babel’s pipeline plugin for experimentation, but don’t rely on it for production—syntax may change.

4.2 Pattern Matching: The Definitive Result Consumer

Status: Stage 1 (since May 2018, limited advancement since April 2021)

The Pattern Matching proposal introduces a match expression far more powerful than switch, with deep destructuring, type guards, and custom matchers.

Proposed syntax:

3 collapsed lines
1
// Pattern matching would be the ideal Result consumer
2
// Exhaustive, declarative, and type-safe
3

4
declare function processData(): Result<string, Error>;
5

6
const result = processData();
7

8
// Future syntax (Stage 1 - may change significantly)
9
const message = match (result) {
10
  when { ok: true, value: let v }:
11
    `Success: ${v}`;
12
  when { ok: false, error: let e }:
13
    `Error: ${e.message}`;
14
}

Key features:

• Exhaustiveness: Missing cases trigger TypeErrors (or compile errors with tooling)
• Binding patterns: let v binds matched values
• Custom matchers: Symbol.customMatcher enables library integration
• is operator: Boolean pattern test for conditionals

Why it matters for error handling: Pattern matching provides a native way to exhaustively handle discriminated unions—exactly what Result types are.

Current reality: Stage 1 with limited recent activity. The proposal has remained at this stage since 2018. Don’t hold your breath; use .match() methods in libraries instead.

4.3 The Safe Assignment Operator (?=): Native Result Types

Status: Community proposal (NOT in TC39 stages)

The Safe Assignment Operator proposal (originally proposal-safe-assignment-operator) is a community-driven attempt to bring Go-style error handling to JavaScript. It is not yet a formal TC39 proposal—it exists in the TC39 discourse forum but hasn’t advanced through official stages.

Proposed syntax:

4 collapsed lines
1
// Proposed ?= operator catches throws and returns tuple
2
// Similar to Go's err, val := operation() pattern
3
// Note: This is NOT in TC39 stages yet
4

5
// Instead of try/catch:
6
const [err, data] ?= JSON.parse(jsonString);
7
if (err) return null;
8

9
// Chains require explicit checks at each step:
10
async function processUserRequest(requestId) {
11
  const [err1, request] ?= await fetchRequest(requestId);
12
  if (err1) return { error: "Failed to fetch request" };
13

14
  const [err2, user] ?= parseUser(request.body);
15
  if (err2) return { error: "Failed to parse user" };
16

17
  const [err3, permissions] ?= await fetchPermissions(user.id);
18
  if (err3) return { error: "Failed to fetch permissions" };
19

20
  return { data: permissions };
21
}

Tuple semantics:

• Success: [null, value]
• Failure: [error, undefined]

Why it’s interesting:

• Works with existing throwing code—no refactoring needed
• Familiar to Go developers
• Symbol.result enables library integration (neverthrow, etc.)

Why it may not succeed:

1. Still verbose: Requires if (err) after each operation—same as Go, worse than .andThen()
2. No composition: Doesn’t chain like Result monads
3. Type system limitations: [T | null, E | null] has the same four-state problem as manual tuples
4. Community-only: No TC39 champion has adopted it yet

Adoption recommendation: Don’t wait for this. Use neverthrow or fp-ts today. If ?= ever ships, migration from Result types is straightforward.

4.4 Supporting Syntax: do and throw Expressions

Two additional TC39 proposals improve error handling ergonomics:

throw Expressions — Stage 2 (has TypeScript support)

Proposal | Champion: Ron Buckton

Allows throw in expression contexts:

2 collapsed lines
1
// throw as expression enables inline validation
2
// TypeScript already supports this syntax
3

4
// Default parameters
5
const greet = (name = throw new Error("Required")) => `Hello, ${name}`
6

7
// Arrow functions (single expression)
8
const fail = () => throw new Error("Not implemented")
9

10
// Ternary and logical operators
11
const value = condition ? result : throw new Error("Failed")
12
const required = maybeValue || throw new Error("Missing")

Grammar restriction: Binary operators cannot directly follow throw without parentheses—use (throw expr) in complex expressions.

do Expressions — Stage 1

Proposal

Allows block statements as expressions:

1
function getUserId(blob) {
2
  const obj = do {
3
    try {
4
      JSON.parse(blob)
5
    } catch {
6
      null // Last value is the expression result
7
    }
8
  }
9
  return obj?.userId
10
}

Note: return inside do exits the containing function, not the block. This is intentional but can surprise.

Section 5: Synthesis and Recommendations

5.1 Decision Framework

When to use try/catch:

• API boundaries (parsing user input, calling external APIs)
• Top-level application safety nets
• When immediate conversion to Result types isn’t practical

When to use Go-style tuples:

• Scripts and prototypes where dependencies are undesirable
• Simple, linear operations with 1-2 fallible calls
• When team consensus on Result types hasn’t been reached

When to use Result types (neverthrow, fp-ts):

• Business logic with multiple fallible operations
• Data processing pipelines
• Any code path where “forgot to check error” would cause production issues
• When type safety and composability outweigh learning curve

Library selection:

5.2 Migration Strategy

Converting an existing codebase to Result types works best incrementally:

1. Start at boundaries: Convert functions that call external APIs or parse user input
2. Install ESLint enforcement: Prevent unconsumed Results from the start
3. Expand inward: Convert business logic functions as you touch them
4. Keep try/catch at the edge: Entry points (HTTP handlers, CLI commands) catch unconverted throws

5 collapsed lines
1
// Migration pattern: wrap throwing functions at boundaries
2
// Internal code uses Result, external boundaries convert
3

4
import { Result, ok, err, ResultAsync } from "neverthrow"
5

6
// Boundary function: converts throws to Result
7
function parseJson<T>(input: string): Result<T, SyntaxError> {
8
  try {
9
    return ok(JSON.parse(input))
10
  } catch (e) {
11
    return err(e instanceof SyntaxError ? e : new SyntaxError(String(e)))
12
  }
13
}
14

15
// Internal function: pure Result-based composition
16
function processUserInput(input: string): Result<User, ParseError | ValidationError> {
17
  return parseJson<UserInput>(input)
18
    .mapErr((e) => new ParseError(e.message))
19
    .andThen(validateUser)
20
}

5.3 Conclusion

The trajectory is clear: JavaScript error handling is moving from implicit exception propagation toward explicit value-based composition. This shift reflects broader industry trends—Rust’s Result, Go’s tuples, and Haskell’s Either have proven that explicit errors produce more reliable systems.

For new TypeScript projects, neverthrow with ESLint enforcement is the pragmatic default. It provides compile-time safety, lint-time consumption enforcement, and an API familiar to JavaScript developers. Reserve exceptions for true boundaries and unexpected failures.

The TC39 proposals (pipeline, pattern matching) may eventually make this pattern feel native, but their uncertain timelines make waiting impractical. The library ecosystem is mature enough today.

The investment in learning Result types pays dividends in reduced production errors, clearer code review conversations (“did you handle the error case?”), and composable business logic that doesn’t hide failure modes in invisible control flow.

Appendix

Prerequisites

• Familiarity with TypeScript generics and union types
• Understanding of Promise and async/await semantics
• Basic functional programming concepts (map, chain/flatMap)

Terminology

Summary

• Exceptions have invisible exit paths, unknown-typed catches, stack unwinding costs (~100x slower than returns), and easy error swallowing
• Go-style tuples make errors explicit but lack type exclusivity, compose poorly, and don’t force handling
• Result monads provide type-safe discriminated unions with composable .map(), .andThen(), .match() APIs
• neverthrow (v8.x) is the recommended default—ergonomic API plus ESLint enforcement of Result consumption
• TC39 proposals (pipeline Stage 2, pattern matching Stage 1, safe assignment community-only) may improve ergonomics but have uncertain timelines
• Migration strategy: Convert at boundaries first, expand inward, keep try/catch at entry points

References

Specifications

• ECMA-262 — ECMAScript Language Specification (ES2025/ES16)
• ECMA-262 §14.15 — The try Statement
• ECMA-262 §14.14 — The throw Statement
• ECMA-262 §20.5 — Error Objects

TC39 Proposals

• Pipeline Operator (Stage 2) — Hack-style |> operator
• Pattern Matching (Stage 1) — match expression
• throw expressions (Stage 2) — throw in expression contexts
• do expressions (Stage 1) — Block statements as expressions
• Safe Assignment Operator — Community proposal for ?=

Libraries

• neverthrow (v8.2.0) — Type-safe Result types for TypeScript
• eslint-plugin-neverthrow — ESLint rules enforcing Result consumption
• fp-ts (v2.16.x) — Typed functional programming library
• Effect-TS — fp-ts successor with full effect system
• ts-results — Minimal Result implementation
• oxide.ts — Rust-like Result API

Core Maintainer Content

• Railway Oriented Programming — Scott Wlaschin’s foundational article on error handling patterns
• Error Handling in Go — Go’s explicit error handling philosophy
• Working with Errors in Go 1.13 — Error wrapping and errors.Is/As