resultwire
v3.0.0
Published
Rust-like Result types, easily serialized over the wire
Downloads
173
Readme
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
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 Result
s into a single Result
.
Example:
const results = [ok(1), ok(2), ok(3)];
const combinedResult = combine(results);
combineWithAllErrors
Combines an array of Result
s 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