# supermacro/neverthrow

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/supermacro-neverthrow).**

7,201 stars · 144 forks · TypeScript · mit

## Links

- GitHub: https://github.com/supermacro/neverthrow
- awesome-repositories: https://awesome-repositories.com/repository/supermacro-neverthrow.md

## Topics

`functional-programming` `typescript`

## Description

neverthrow is a TypeScript result type library that implements railway oriented programming. It provides a functional error handling framework using type-safe wrappers to represent operation outcomes as either success or failure variants, eliminating the need to throw exceptions.

The library features adapters that convert throwing functions and asynchronous promises into typed result objects. This allows asynchronous rejections and unsafe code to be handled as explicit return values rather than uncaught exceptions.

The framework covers a broad range of functional computation capabilities, including monadic chaining for sequential operations, error aggregation for collecting multiple failures, and result matching to ensure exhaustive error handling. It also provides mechanisms for error recovery, value transformation, and the execution of side effects on both success and failure tracks.

Additional support is provided for generator functions to implicitly handle errors and unwrap success values within a block.

## Tags

### Programming Languages & Runtimes

- [Result](https://awesome-repositories.com/f/programming-languages-runtimes/language-features-paradigms/type-system-tools/type-definitions/sum-types/result.md) — Implements a type-safe result wrapper based on sum types to represent operation outcomes as success or failure variants.
- [Promise-to-Result Converters](https://awesome-repositories.com/f/programming-languages-runtimes/fallible-type-conversion/promise-to-result-converters.md) — Transforms promises into result types by mapping rejections into specific, type-safe errors. ([source](https://github.com/supermacro/neverthrow#readme))
- [Async Result Wrappers](https://awesome-repositories.com/f/programming-languages-runtimes/promise-based-api-wrappers/async-result-wrappers.md) — Provides wrappers that convert promises into result types to handle asynchronous rejections as typed values.
- [Promise-to-Result Wrappers](https://awesome-repositories.com/f/programming-languages-runtimes/runtime-execution-environments/runtime-environments/runtimes/asynchronous-execution-engines/asynchronous-control-flows/promise-based-flow-control/promise-based-chains/promise-to-result-wrappers.md) — Transforms asynchronous promises into typed result objects with integrated mapping and chaining capabilities.
- [Exhaustive Result Handling](https://awesome-repositories.com/f/programming-languages-runtimes/enforced-result-handling/exhaustive-result-handling.md) — Executes one of two functions based on whether the outcome is a success or failure to ensure both cases are handled. ([source](https://github.com/supermacro/neverthrow#readme))

### Software Engineering & Architecture

- [Monadic Error Handling](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling.md) — Implements a comprehensive framework for monadic error handling using Result types to manage flow without exceptions.
- [Result Sequence Processing](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/result-sequence-processing.md) — Allows executing a sequence of dependent operations that halt immediately upon the first encountered error. ([source](https://github.com/supermacro/neverthrow/blob/master/README.md))
- [Throwable Function Adapters](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/error-management/error-type-compositions/throwable-function-adapters.md) — Converts functions that throw exceptions into result-returning functions by mapping unknown errors to known types. ([source](https://github.com/supermacro/neverthrow#readme))
- [Exception-to-Result Adapters](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/exception-logic-structures/exception-hierarchies/exception-type-enforcers/exception-to-result-adapters.md) — Provides a utility to wrap throwing functions, ensuring all potential failures are handled via return types.
- [Result Transformations](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/result-transformations.md) — Provides monadic chaining to transform success values while automatically propagating errors. ([source](https://github.com/supermacro/neverthrow#readme))
- [Asynchronous Result Wrappers](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/result-transformations/asynchronous-result-wrappers.md) — Wraps promises in a specialized class to provide mapping and chaining without requiring immediate awaiting. ([source](https://github.com/supermacro/neverthrow#readme))
- [Throwable Function Adapters](https://awesome-repositories.com/f/software-engineering-architecture/error-reporting/custom-error-interfaces/error-wrapping/throwable-function-adapters.md) — Result converts potentially throwing functions into a consistent result type to ensure all errors are handled explicitly. ([source](https://github.com/supermacro/neverthrow/blob/master/CHANGELOG.md))
- [Success and Failure Wrapping](https://awesome-repositories.com/f/software-engineering-architecture/failure-handling-policies/success-and-failure-wrapping.md) — Wraps return values in specific types to distinguish between successful outcomes and expected errors without throwing. ([source](https://github.com/supermacro/neverthrow/wiki/Basic-Usage-Examples))
- [Promise-To-Result Adaptation](https://awesome-repositories.com/f/software-engineering-architecture/higher-order-function-wrapping/sync-to-promise-wrappers/promise-to-result-adaptation.md) — Includes adapters that convert asynchronous promises into typed result objects to handle rejections as explicit values.
- [Operation Chaining](https://awesome-repositories.com/f/software-engineering-architecture/optional-value-types/operation-chaining.md) — Provides monadic chaining mechanisms to sequentially transform values through a series of functions.
- [Railway Oriented Programming](https://awesome-repositories.com/f/software-engineering-architecture/railway-oriented-programming.md) — Implements a pipeline pattern where operations either continue on a success track or diverge to an error track.
- [Generator-Based Error Propagation](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/generator-based-error-propagation.md) — Utilizes generator functions and yield expressions to implicitly handle errors and unwrap success values. ([source](https://github.com/supermacro/neverthrow#readme))
- [Generator-Based Unwrapping](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/generator-based-unwrapping.md) — Supports generator functions to implicitly handle errors and unwrap success values within a block.
- [Generator Block Aborting](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/result-sequence-processing/generator-block-aborting.md) — Uses generator functions to yield values and automatically abort the block if any operation returns a failure. ([source](https://github.com/supermacro/neverthrow/blob/master/README.md))
- [Validation Error Aggregators](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/validation-error-aggregators.md) — Allows collecting multiple independent failures into a single structured collection instead of stopping at the first error.
- [Cumulative Error Collection](https://awesome-repositories.com/f/software-engineering-architecture/error-handling/validation-error-aggregators/cumulative-error-collection.md) — Implements error aggregation logic to collect multiple independent failures into a single list.
- [Error Recovery](https://awesome-repositories.com/f/software-engineering-architecture/error-recovery.md) — Handles failure cases and optionally transforms the resulting type to resume normal execution. ([source](https://github.com/supermacro/neverthrow#readme))
- [Exhaustive Matching](https://awesome-repositories.com/f/software-engineering-architecture/failure-handling-policies/success-and-failure-wrapping/exhaustive-matching.md) — Provides result matching to ensure exhaustive error handling by requiring specific functions for both success and failure cases.
- [Result Value Extraction](https://awesome-repositories.com/f/software-engineering-architecture/result-value-extraction.md) — Provides methods to retrieve a success value or return a specified default if the operation failed. ([source](https://github.com/supermacro/neverthrow/blob/master/README.md))
- [Railway Side Effects](https://awesome-repositories.com/f/software-engineering-architecture/side-effect-handlers/railway-side-effects.md) — Provides mechanisms for executing side effects on both success and failure tracks without altering the result value.
- [Result-Track Side Effects](https://awesome-repositories.com/f/software-engineering-architecture/side-effect-handlers/result-track-side-effects.md) — Provides utilities to execute arbitrary logic on either the success or failure track without changing the result's state. ([source](https://github.com/supermacro/neverthrow#readme))
- [Task Result Aggregation](https://awesome-repositories.com/f/software-engineering-architecture/task-result-aggregation.md) — Merges a list of outcomes into one result by either stopping at the first failure or gathering all errors. ([source](https://github.com/supermacro/neverthrow#readme))

### Development Tools & Productivity

- [TypeScript Utility Libraries](https://awesome-repositories.com/f/development-tools-productivity/typescript-utility-libraries.md) — Provides a type-safe result utility library for TypeScript to represent operation outcomes as success or failure variants.

### Testing & Quality Assurance

- [Variant-Based Outcome Encoding](https://awesome-repositories.com/f/testing-quality-assurance/validation-verification/input-validation/agent-input-and-output-validators/automated-assertion-validators/action-result-validators/outcome-assertions/variant-based-outcome-encoding.md) — Encodes the result of an action as either a success or failure variant to avoid throwing exceptions. ([source](https://github.com/supermacro/neverthrow/blob/master/README.md))

### Web Development

- [Result-Track Side Effects](https://awesome-repositories.com/f/web-development/side-effect-synchronization/result-track-side-effects.md) — Enables performing actions like logging specifically when an operation fails without altering the error object. ([source](https://github.com/supermacro/neverthrow/blob/master/CHANGELOG.md))

### Part of an Awesome List

- [Algebraic Data Types](https://awesome-repositories.com/f/awesome-lists/data/algebraic-data-types.md) — Result type for representing success or failure.