ts-option-result provides is a small library to handle null cases and error cases in a clean way.
Option and OptionAsync are used to handle cases of nullity. Result and ResultAsync are used for error handling in a descriptive and type safe way.
$ npm install --save ts-option-result
Most methods have an equivalent function, which is curried. The usage depends on weather you like chaining methods or piping functions. The pipe function used below is the one from Ramda
const optionAge = some(25);
class NoEmailFoundError extends Error {}
class NoAgeProvidedError extends Error {}
class NotOldEnoughError extends Error {}
let getEmail: () => Result<string, NoEmailFoundError>;
// Usage with methods chaining:
optionAge // Option<number>
.toResult(new NoAgeProvidedError()) // Result<number, NoAgeProvidedError>
.flatMap((age): Result<number, NotOldEnoughError> => {
if (age < 20) return err(new NotOldEnoughError());
return ok(age);
}) // Result<number, NoAgeProvidedError | NotOldEnoughError>
.flatMap(oldEnoughAge =>
getEmail().map(email => ({
email,
age: oldEnoughAge,
})),
) // Result<{email: string, age: number}, NoAgeProvidedError | NotOldEnoughError | NoEmailFoundError>
.caseOf({
ok: user => `User with ${user.email} email, is ${user.age} years old`,
err: err => `Something wrong happened: ${err.message}`,
}); // string
// Usage with piping (pipe function from ramda):
pipe<
Option<number>,
Result<number, NoAgeProvidedError>,
Result<number, NoAgeProvidedError | NotOldEnoughError>,
Result<{ email: string; age: number }, NoAgeProvidedError | NotOldEnoughError | NoEmailFoundError>,
string
>(
Option.toResult(new NoAgeProvidedError()),
Result.flatMap((age): Result<number, NotOldEnoughError> => {
if (age < 20) return err(new NotOldEnoughError());
return ok(age);
}),
Result.flatMap(oldEnoughAge =>
getEmail().map(email => ({
email,
age: oldEnoughAge,
})),
),
Result.caseOf({
ok: user => `User with ${user.email} email, is ${user.age} years old`,
err: err => `Something wrong happened: ${err.message}`,
}),
)(optionAge);
- some
T => Some<T>
- none
() => None
- fromNullable
(T | null | undefined) => Option<T>
- isNone
Option<A> -> boolean
- map
(f: A => B) -> Option<A> -> Option<B>
- flatMap
(f: A => Option<B>) -> Option<A> -> Option<B>
- caseOf
({some: A => B, none: () => B}) -> Option<A> -> B
- getOrElse
(f: () => A) -> Option<A> -> A
- getOrNull
Option<A> -> A | null
- someAsync
A => OptionAsync<A>
- noneAsync
() => OptionAsync<A>
- map
(f: A => B) -> OptionAsync<A> -> OptionAsync<B>
- flatMap
(f: A => Option<B> | OptionAsync<B>) -> OptionAsync<A> -> OptionAsync<B>
- caseOf
({some: A => B, none: () => B}) -> OptionAsync<A> -> Promise<B>
- getOrElse
(f: () => B) -> OptionAsync<A> -> Promise<B>
- getOrNull
OptionAsync<A> -> Promise<A | null>
- ok
- err
- okAsync
- errAsync
- fromPromise
type Option<T> = Some<T> | None
Option
can either be Some<T>
or None
, there are 3 constructors.
some: T => Some<T>
creates aSome<T>
instancenone: () => None
fromNullable: (T | null | undefined) => Option<T>
creates an option from a nullable of T
import { some, none, Option, fromNullable } from "ts-option-result";
const someStr: Option<string> = some("my string");
const noneStr: Option<string> = none();
const myString = "my nullable string" as string | null | undefined;
const optionStr = fromNullable(myString);
Option<A> -> boolean
const someStr = some("my string");
const noneStr = none();
// instance method
const isFalse = someStr.isNone();
const isTrue = noneStr.isNone();
(f: A => B) -> Option<A> -> Option<B>
const optionStr = some("my string");
// curried function
const optionNum = Option.map(str => str.length, optionStr); // Option<number>
// instance method
const optionNum = optionStr.map(str => str.length); // Option<number>
(f: A => Option<B>) -> Option<A> -> Option<B>
const optionStr = some("my string");
// curried function
const optionNum = Option.map(str => some(str.length), optionStr); // Option<number>
// instance method
const optionNum = optionStr.flatMap(str => some(str.length)); // Option<number>
({some: A => B, none: () => B}) -> Option<A> -> B
const optionStr = some("my string");
// curried function
const lengthOfString: number = Option.caseOf(
{
some: str => str.length,
none: () => 0,
},
optionStr,
);
// instance method
const lengthOfString: number = optionStr.flatMap({
some: str => str.length,
none: () => 0,
});
(f: () => A) -> Option<A> -> A
const optionStr = some("my string");
// curried function
const myString = Option.getOrElse(() => "No string", optionStr);
// instance method
const myString = optionStr.getOrElse(() => "No string");
Option<A> -> A | null
const optionStr = some("my string");
// curried function
const myString = Option.getOrNull(optionStr); // const myString = "my string"
const myNull = Option.getOrNull(none()); // const myNull = null
// instance method
const myString = optionStr.getOrNull(); // const myString = "my string"
const myNull = none().getOrNull(); // const myNull = null
OptionAsync is a wrapper around promises. It is similar to Promise<Option> with extra methods.
You can use then
and await
on OptionAsync just like a promise.
someAsync: T => OptionAsync<T>
noneAsync: () => OptionAsync<T>
import { someAsync, noneAsync, OptionAsync } from "ts-option-result";
const someAsyncStr: OptionAsync<string> = someAsync("my string");
const noneAsyncStr: OptionAsync<string> = noneAsync();
(f: A => B) -> OptionAsync<A> -> OptionAsync<B>
const someAsyncStr = someAsync("my string");
// curried function
const resultAsyncNum = OptionAsync.map(str => str.length, someAsyncStr);
// instance method
const resultAsyncNum = someAsyncStr.map(str => str.length);
(f: A => Option<B> | OptionAsync<B>) -> OptionAsync<A> -> OptionAsync<B>
The function provided to flatMap can either return Option or OptionAsync
const someAsyncStr = someAsync("my string");
// curried function
const resultAsyncNum = OptionAsync.map(str => some(str.length), someAsyncStr);
// instance method
const resultAsyncNum = someAsyncStr.map(str => someAsync(str.length));
({some: A => B, none: () => B}) -> OptionAsync<A> -> Promise<B>
The function provided to flatMap can either return Option or OptionAsync
const someAsyncStr = someAsync("my string");
// curried function
const lengthOfString: Promise<number> = OptionAsync.caseOf(
{
some: str => str.length,
none: () => 0,
},
someAsyncStr,
);
// instance method
const lengthOfString: Promise<number> = someAsyncStr.caseOf({
some: str => str.length,
none: () => 0,
});
(f: () => B) -> OptionAsync<A> -> Promise<B>
const someAsyncStr = someAsync("my string");
// curried function
const resultAsyncNum = OptionAsync.getOrElse(() => "No string", someAsyncStr);
// instance method
const resultAsyncNum = someAsyncStr.getOrElse(() => "No string");
OptionAsync<A> -> Promise<A | null>
const someAsyncStr = someAsync("my string");
// curried function
const resultAsyncNum = OptionAsync.getOrNull(someAsyncStr);
// instance method
const resultAsyncNum = someAsyncStr.getOrNull();
type Result<A, E> = Ok<A, E> | Err<A, E>
Result
can either be Ok<A, E>
or Err<A, E>
, there are 2 constructors.
ok: A => Ok<A, unknown>
creates aOk<A, unknown>
instanceerr: E => Err<unknown, E>
import { ok, err, Result } from "ts-option-result";
const okStr = ok("my string");
const errStr = err("some error");
// you can provide an expected type for the E or T :
const okNum: Result<number, string> = ok(10);
const errNum: Result<number, string> = err("some error");
Option<A> -> boolean
const okStr = ok("my string");
const errStr = err();
// instance method
const thisIsTrue = okStr.isOk();
const thisIsFalse = errStr.isOk();
Result<A, E> -> boolean
const okStr = ok("my string");
const errStr = err();
// instance method
const thisIsFalse = okStr.isErr();
const thisIsTrue = errStr.isErr();
(f: A => B) -> Result<A, E> -> Result<B, E>
const okStr: Result<string, string> = ok("my string");
// curried function
const okNum = Result.map(str => str.length, okStr); // Result<number, string>
// instance method
const okNum = okStr.map(str => str.length); // Result<number, string>
(f: A => Result<B, F>) -> Result<A, E> -> Result<B, E | F>
const okStr: Result<string, "anError"> = ok("my string");
// curried function
const okNum = Result.flatMap(str => {
if (str.length > 2) return ok(str.length);
return err("NotLongEnough");
}, okStr); // Result<number, "anError" | "NotLongEnough">
// instance method
const okNum = okStr.flatMap(str => {
if (str.length > 2) return ok(str.length);
return err("NotLongEnough");
}); // Result<number, "anError" | "NotLongEnough">
({ok: A => B, err: () => B}) -> Result<A, E> -> B
const okStr: Result<string, string> = some("my string");
// curried function
const lengthOfString: number = Result.caseOf(
{
ok: str => str.length,
err: e => {
console.error("Error : " + e);
return 0;
},
},
okStr,
);
// instance method
const lengthOfString: number = okStr.caseOf({
ok: str => str.length,
err: e => {
console.error("Error : " + e);
return 0;
},
});
Result<A, E> -> Promise<A>
(but may also throw E)
const okStr = ok("my string");
const errStr: Result<number, string> = err("FAILURE !");
// curried function
const num = Result.getOrThrow(okStr); // returns "my string"
Result.getOrThrow(errStr); // throws "FAILURE !"
// instance method
const okNum = okStr.getOrThrow(); // returns "my string";
errStr.getOrThrow(); // throws "FAILURE !"
Result<A, E> -> Promise<E>
(but may also throw E)
Careful with this, as it will throw on OK values. It should only be used after an isErr
check.
const okStr = ok("my string");
const errStr: Result<number, string> = err("My error");
// curried function
Result._getErrorOrThrow(okStr); // throws "Cannot get error on Ok value"
const stringInErr = Result._getErrorOrThrow(errStr); // returns "My error"
// instance method
okStr._getErrorOrThrow(); // throws "Cannot get error on Ok value"
const stringInErr = errStr._getErrorOrThrow(); // returns "My error"
ResultAsync is a wrapper around promises. It is similar to Promise<Result<A, E>> with extra methods.
You can use then
and await
on ResultAsync just like a promise.
okAsync: T => ResultAsync<T, unknown>
errAsync: E => ResultAsync<unknown, E>
fromPromise: Promise<A> => ResultAsync<A, unknown> -- or -- (Promise<A>, errHandler: () => F) => ResultAsync<A, F>
import { okAsync, noneAsync, ResultAsync, fromPromise } from "ts-option-result";
const okAsyncStr: ResultAsync<string> = okAsync("my string");
const noneAsyncStr: ResultAsync<string> = noneAsync();
const resolveStr = Promise.resolve("myStr");
const okAsyncStr = fromPromise(resolveStr);
const rejectStr: Promise<string> = Promise.reject("failure");
const errAsyncStr = fromPromise(rejectStr2, e => "error was " + e);
(f: A => B) -> ResultAsync<A, E> -> ResultAsync<B, E>
const okAsyncStr = okAsync("my string");
// curried function
const resultAsyncNum = ResultAsync.map(str => str.length, okAsyncStr);
// instance method
const resultAsyncNum = okAsyncStr.map(str => str.length);
(f: A => Result<B, F> | ResultAsync<B, F>) -> ResultAsync<A, E> -> ResultAsync<B, E | F>
The function provided to flatMap can either return Result<B, F> or ResultAsync<B, F>
const okAsyncStr = okAsync("my string");
// curried function
const resultAsyncNum = ResultAsync.map(str => some(str.length), okAsyncStr);
// instance method
const resultAsyncNum = okAsyncStr.map(str => okAsync(str.length));
({ok: A => B, err: () => B}) -> ResultAsync<A, E> -> Promise<B>
const okAsyncStr = okAsync("my string");
// curried function
const lengthOfString: Promise<number> = ResultAsync.caseOf(
{
ok: str => str.length,
err: e => {
console.error(e);
return 0;
},
},
okAsyncStr,
);
// instance method
const lengthOfString: Promise<number> = okAsyncStr.caseOf({
ok: str => str.length,
err: () => 0,
});