neverthrow

What is neverthrow?

The neverthrow npm package provides a functional way to handle errors in TypeScript and JavaScript. It introduces the Result and Option types, which help in managing success and failure cases without using exceptions.

What are neverthrow's main functionalities?

Result Type

The Result type is used to represent either a success (ok) or a failure (err). This example demonstrates a division function that returns a Result type, handling division by zero as an error.

const { ok, err, Result } = require('neverthrow');

function divide(a, b) {
  if (b === 0) {
    return err(new Error('Division by zero'));
  }
  return ok(a / b);
}

const result = divide(4, 2);
result.match({
  ok: value => console.log('Result:', value),
  err: error => console.error('Error:', error.message)
});

Option Type

The Option type is used to represent an optional value that may or may not be present. This example shows a function that looks up a user by ID and returns an Option type.

const { some, none, Option } = require('neverthrow');

function findUserById(id) {
  const users = { 1: 'Alice', 2: 'Bob' };
  return users[id] ? some(users[id]) : none();
}

const user = findUserById(1);
user.match({
  some: value => console.log('User found:', value),
  none: () => console.log('User not found')
});

Chaining Operations

Chaining operations with Result types allows for sequential error handling. This example demonstrates parsing a number and then dividing it, with each step returning a Result type.

const { ok, err, Result } = require('neverthrow');

function parseNumber(str) {
  const num = Number(str);
  return isNaN(num) ? err(new Error('Invalid number')) : ok(num);
}

function divide(a, b) {
  if (b === 0) {
    return err(new Error('Division by zero'));
  }
  return ok(a / b);
}

const result = parseNumber('4').andThen(num => divide(num, 2));
result.match({
  ok: value => console.log('Result:', value),
  err: error => console.error('Error:', error.message)
});

Other packages similar to neverthrow

folktale

Folktale is a standard library for functional programming in JavaScript. It provides similar functionality to neverthrow with its Result and Maybe types, but also includes a broader range of functional programming utilities.

fp-ts

fp-ts is a library for functional programming in TypeScript. It offers a comprehensive set of tools for functional programming, including Result and Option types, similar to neverthrow, but with a more extensive ecosystem and integration with other functional programming concepts.

purify-ts

Purify is a functional programming library for TypeScript that provides Maybe and Either types, which are analogous to neverthrow's Option and Result types. It focuses on immutability and functional programming patterns.

README

NeverThrow

Encode failure into your program.

This program contains a Result type that represents either success (Ok) or failure (Err).

This package works for both JS and TypeScript. However, the types that this package provides will allow you to get compile-time guarantees around error handling if you are using TypeScript.

A note on the Package Name

Although the package is called neverthrow, please don't take this literally. I am simply encouraging the developer to think a bit more about the ergonomics and usage of whatever software they are writing. Throwing and catching is syntactic sugar for goto statements - in other words; it makes reasoning about your programs harder.

With all that said, there are definitely good use cases for throwing in your program. But much less than you might think.