supermacro/neverthrow

★ 7,490TypeScriptAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((NeverThrow))
    Core concept
      Result type
      Ok and Err values
      No exceptions thrown
    Usage
      Sync functions
      Async with ResultAsync
      Chain operations
    Error safety
      TypeScript compiler checks
      ESLint plugin rule
    Integration
      Wrap existing libraries
      fromThrowable helper
      npm install

mindmap root((NeverThrow)) Core concept Result type Ok and Err values No exceptions thrown Usage Sync functions Async with ResultAsync Chain operations Error safety TypeScript compiler checks ESLint plugin rule Integration Wrap existing libraries fromThrowable helper npm install

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Replace try/catch blocks in TypeScript with Result types so the compiler catches any unhandled failure cases at build time.

USE CASE 2

Chain multiple async operations where each step might fail, with failures passing through automatically without nested conditionals.

USE CASE 3

Wrap a third-party library that throws exceptions to give it a type-safe Result-returning API your TypeScript code can reason about.

USE CASE 4

Add the ESLint plugin to enforce that every Result value in your codebase is explicitly handled before the code compiles.

Tech stack

TypeScriptJavaScriptnpmESLint

Getting it running

Difficulty · easy Time to first run · 5min

No license information specified in the README.

In plain English

NeverThrow is a TypeScript library that changes how you handle errors in JavaScript and TypeScript code. In most JavaScript programs, errors are thrown as exceptions using try/catch blocks, which can be easy to forget and hard to track through a codebase. NeverThrow takes a different approach borrowed from languages like Rust: instead of throwing, functions return a Result value that is explicitly either a success (Ok) or a failure (Err). Your code then checks which one it got and handles both cases deliberately. The practical effect is that errors become part of your function's return type, so the TypeScript compiler can warn you if you forget to handle a failure case. You can chain operations together: if one step succeeds, the next step runs, if any step fails, the failure passes through automatically without you writing nested conditionals. This style is sometimes called railway-oriented programming or functional error handling. The library covers both regular (synchronous) functions and async operations. For async work, it provides a ResultAsync class that wraps a Promise but gives you all the same chaining and checking methods. You can also convert existing functions that throw exceptions into ones that return Results, which is useful for wrapping third-party libraries. An optional companion package called eslint-plugin-neverthrow adds a lint rule that forces you to actually handle every Result your code produces, similar to a compiler feature in Rust. This prevents you from silently ignoring errors. Installation is a single npm command. The README is extensive and documents every method with signatures and examples. The library is aimed at TypeScript developers who want stricter, more explicit error handling without relying on exceptions. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1

Using NeverThrow, refactor this TypeScript async function that uses try/catch into one that returns a ResultAsync, and show me how to chain it with a second operation that might also fail.

Prompt 2

I'm using neverthrow in TypeScript. Write a function that calls an API, parses the JSON response, and validates the schema, each step returning a typed Result, and chain them with proper error types.

Prompt 3

Show me how to use neverthrow's fromThrowable to wrap the Node.js fs.readFileSync function so it returns an Ok or Err Result instead of throwing an exception.

Prompt 4

Set up the eslint-plugin-neverthrow lint rule in my TypeScript project so the linter fails if I forget to handle a Result value anywhere in my code.

Open on GitHub → Explain another repo

← supermacro on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.