@philiprehberger/result

Rust-inspired Result type for type-safe error handling without try/catch

Installation

npm install @philiprehberger/result

Usage

Creating Results

import { ok, err, tryCatch, tryCatchAsync } from '@philiprehberger/result';

const success = ok(42);
const failure = err(new Error('something broke'));

// Wrap throwing functions
const result = tryCatch(() => JSON.parse(input));
// Result<unknown, Error>

// Wrap async functions
const apiResult = await tryCatchAsync(() => fetch('/api/data'));
// Result<Response, Error>

Extracting Values

result.unwrap();              // returns value or throws
result.unwrapOr('default');   // returns value or default
result.unwrapErr();           // returns error or throws

Pattern Matching

result.match({
  ok: (value) => `Got: ${value}`,
  err: (error) => `Error: ${error.message}`,
});

Chaining

const name = tryCatch(() => JSON.parse(input))
  .map(data => data.name)
  .map(name => name.toUpperCase())
  .unwrapOr('UNKNOWN');

Error Recovery

const result = err('not found')
  .orElse(e => ok('fallback value'));
// Ok('fallback value')

Side Effects

tryCatch(() => JSON.parse(input))
  .tap(data => console.log('Parsed:', data))
  .tapErr(err => console.error('Parse failed:', err))
  .map(data => data.name);

Type Guards

if (result.isOk()) {
  result.value; // typed as T
}
if (result.isErr()) {
  result.error; // typed as E
}

Collecting Results

import { all, combine, partition } from '@philiprehberger/result';

const results = all([ok(1), ok(2), ok(3)]);
// Ok([1, 2, 3])

const withError = all([ok(1), err('fail'), ok(3)]);
// Err('fail') — returns first error

// combine is an alias of all
combine([ok(1), ok(2)]);

// partition keeps every result and splits oks from errs
const { oks, errs } = partition([ok(1), err('a'), ok(2)]);
// oks = [1, 2], errs = ['a']

From Promise

import { fromPromise } from '@philiprehberger/result';

const result = await fromPromise(fetch('/api'));
// Result<Response, Error>

To Promise

const result = ok(42);
await result.toPromise(); // resolves to 42

const failure = err(new Error('fail'));
await failure.toPromise(); // rejects with Error

Filter

const result = ok(42).filter(
  (n) => n > 0,
  () => new Error('must be positive'),
);
// Ok(42)

ok(-1).filter(
  (n) => n > 0,
  () => new Error('must be positive'),
);
// Err('must be positive')

Flatten

import { flatten } from '@philiprehberger/result';

const nested = ok(ok(42)); // Result<Result<number, Error>, Error>
const flat = flatten(nested); // Ok(42)

Custom Error Mapper

const result = tryCatch(
  () => JSON.parse(input),
  (e) => ({ code: 'PARSE_ERROR', cause: e }),
);
// Result<unknown, { code: string; cause: unknown }>

const asyncResult = await tryCatchAsync(
  () => fetch('/api'),
  (e) => new MyCustomError(e),
);

API

Factory Functions

Function	Returns	Description
ok(value)	Ok<T>	Create a success result
err(error)	Err<E>	Create a failure result
tryCatch(fn, mapError?)	Result<T, E>	Wrap a throwing function
tryCatchAsync(fn, mapError?)	Promise<Result<T, E>>	Wrap an async throwing function
fromPromise(promise)	Promise<Result<T, Error>>	Convert a promise to a Result
all(results)	Result<T[], E>	Collect an array of Results; returns first error
combine(results)	Result<T[], E>	Alias of all
partition(results)	{ oks, errs }	Split a list of Results into success and failure values
flatten(result)	Result<T, E>	Unwrap a nested Result<Result<T, E>, E>

Result Instance Methods

Method	Returns	Description
isOk()	boolean	Type guard for Ok
isErr()	boolean	Type guard for Err
map(fn)	Result<U, E>	Transform the success value
mapErr(fn)	Result<T, F>	Transform the error value
flatMap(fn)	Result<U, E>	Chain with a Result-returning function
unwrap()	T	Extract value or throw
unwrapOr(default)	T	Extract value or return default
unwrapErr()	E	Extract error or throw
orElse(fn)	Result<T, F>	Recover from an error
tap(fn)	this	Side effect on success value
tapErr(fn)	this	Side effect on error value
match({ ok, err })	U	Pattern match on Ok/Err
toPromise()	Promise<T>	Convert to a Promise
filter(predicate, errorFactory)	Result<T, E>	Keep Ok if predicate passes, else Err
mapAsync(fn)	Promise<Result<U, E>>	Async version of map
flatMapAsync(fn)	Promise<Result<U, E>>	Async version of flatMap

Development

npm install
npm run build
npm test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT