README.md

ResultWire

This library provides a minimal Result type and utility functions that can be sent from server to client with the design being inspired by Rust's Result<T, E> enum. It aims to provide better error handling in TypeScript by representing operations that might fail in a type-safe manner.

Why another error-as-value library?

ResultWire doesn't use classes, and instead uses plain objects. This means that it can be sent from server to client, and the helper methods can check the actual objects contents, instead of relying on instanceOf methods. Specifically, this library is designed to be used with Remix's turbo-stream. The Result type and its variants (Ok, Err) can be serialized and deserialized over the network, making it suitable for use in client-server communication.

Installation

npm install resultwire

Usage

import { ok, err, Result, ... } from 'resultwire'

API

Table of Contents

• Types
  • Ok
  • Err
  • Result
• Functions
  • ok
  • err
  • isOk
  • isErr
  • map
  • mapErr
  • unwrapOr
  • andThen
  • orElse
  • match
  • fromThrowable
  • fromPromise
  • combine
  • combineWithAllErrors
  • unsafeUnwrap

Types

Ok

Represents a successful value wrapped in an Ok variant.

Err

Represents an error value wrapped in an Err variant.

Result

A union type that represents either an Ok value or an Err value.

Functions

ok

Creates a new Ok result.

Example:

const result = ok(42);

err

Creates a new Err result.

Example:

const result = err('Something went wrong');

isOk

Checks if a Result is Ok.

Example:

const result = ok(42);
const isOkResult = isOk(result); // true

isErr

Checks if a Result is Err.

Example:

const result = err('Something went wrong');
const isErrResult = isErr(result); // true

map

Maps a function over the value of an Ok result.

Example:

const result = ok(42);
const mappedResult = map(result, (value) => value * 2);

mapErr

Maps a function over the error of an Err result.

Example:

const result = err('Something went wrong');
const mappedResult = mapErr(result, (error) => new Error(error));

unwrapOr

Unwraps a Result, returning the value if it's Ok, or a default value if it's Err.

Example:

const result = ok(42);
const unwrappedResult = unwrapOr(result, 0); // 42

andThen

Chains a function that returns a Result to the value of an Ok result.

Example:

const result = ok(42);
const chainedResult = andThen(result, (value) => ok(value * 2));

orElse

Chains a function that returns a Result to the error of an Err result.

Example:

const result = err('Something went wrong');
const chainedResult = orElse(result, (error) => ok('Default value'));

match

Matches a Result against two functions, one for Ok and one for Err.

Example:

const result = ok(42);
const matchedResult = match(result, (value) => value * 2, (error) => 0); // 84

fromThrowable

Executes a function that may throw an error and returns the result as a Result.

Example:

const result = fromThrowable(() => {
  // Code that may throw an error
});

fromPromise

Converts a Promise into a Promise<Result>.

Example:

const promise = Promise.resolve(42);
const result = await fromPromise(promise);

combine

Combines an array of Results into a single Result.

Example:

const results = [ok(1), ok(2), ok(3)];
const combinedResult = combine(results);

combineWithAllErrors

Combines an array of Results into a single Result, collecting all errors.

Example:

const results = [ok(1), err('Error 1'), ok(3), err('Error 2')];
const combinedResult = combineWithAllErrors(results);

unsafeUnwrap

Unwraps a Result, throwing an error if it's Err.

Example:

const result = ok(42);
const unwrappedResult = unsafeUnwrap(result); // 42