Ts-option-result NPM

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.

Install / Import

$ npm install --save ts-option-result

Usage example

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);

API

Option

Constructors

some T => Some<T>
none () => None
fromNullable (T | null | undefined) => Option<T>

Functions and methods

isNone Option<A> -> boolean
map (f: A => B) -> Option<A> -> Option
flatMap (f: A => Option) -> Option<A> -> Option
caseOf ({some: A => B, none: () => B}) -> Option<A> -> B
getOrElse (f: () => A) -> Option<A> -> A
getOrNull Option<A> -> A | null

OptionAsync

Constructors

someAsync A => OptionAsync<A>
noneAsync () => OptionAsync<A>

Functions and methods

map (f: A => B) -> OptionAsync<A> -> OptionAsync
flatMap (f: A => Option | OptionAsync) -> OptionAsync<A> -> OptionAsync
caseOf ({some: A => B, none: () => B}) -> OptionAsync<A> -> Promise
getOrElse (f: () => B) -> OptionAsync<A> -> Promise
getOrNull OptionAsync<A> -> Promise<A | null>

Result

Constructors

Functions and methods

ResultAsync

Constructors

okAsync
errAsync
fromPromise

Functions and methods

Option

Option - Constructors

type Option<T> = Some<T> | None

Option can either be Some<T> or None, there are 3 constructors.

some: T => Some<T> creates a Some<T> instance
none: () => 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 - Function and instance methods

Option - isNone

Option<A> -> boolean

const someStr = some("my string");
const noneStr = none();

// instance method
const isFalse = someStr.isNone();
const isTrue = noneStr.isNone();

Option - map

(f: A => B) -> Option<A> -> Option

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>

Option - flatMap:

(f: A => Option) -> Option<A> -> Option

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>

Option - caseOf:

({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,
});

Option - getOrElse:

(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 - getOrNull:

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

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.

OptionAsync - Constructors

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();

OptionAsync - Function and instance methods

OptionAsync - map

(f: A => B) -> OptionAsync<A> -> OptionAsync

const someAsyncStr = someAsync("my string");

// curried function
const resultAsyncNum = OptionAsync.map(str => str.length, someAsyncStr);

// instance method
const resultAsyncNum = someAsyncStr.map(str => str.length);

OptionAsync - flatMap

(f: A => Option | OptionAsync) -> OptionAsync<A> -> OptionAsync

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));

OptionAsync - caseOf

({some: A => B, none: () => B}) -> OptionAsync<A> -> Promise

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,
});

OptionAsync - getOrElse

(f: () => B) -> OptionAsync<A> -> Promise

const someAsyncStr = someAsync("my string");

// curried function
const resultAsyncNum = OptionAsync.getOrElse(() => "No string", someAsyncStr);

// instance method
const resultAsyncNum = someAsyncStr.getOrElse(() => "No string");

OptionAsync - getOrNull

OptionAsync<A> -> Promise<A | null>

const someAsyncStr = someAsync("my string");

// curried function
const resultAsyncNum = OptionAsync.getOrNull(someAsyncStr);

// instance method
const resultAsyncNum = someAsyncStr.getOrNull();

Result

Result - Constructors

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 a Ok<A, unknown> instance
err: 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");

Result - Function and instance methods

Result - isOk

Option<A> -> boolean

const okStr = ok("my string");
const errStr = err();

// instance method
const thisIsTrue = okStr.isOk();
const thisIsFalse = errStr.isOk();

Result - isErr

Result<A, E> -> boolean

const okStr = ok("my string");
const errStr = err();

// instance method
const thisIsFalse = okStr.isErr();
const thisIsTrue = errStr.isErr();

Result - map

(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>

Result - flatMap

(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">

Result - caseOf:

({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 - getOrThrow

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 - getErrorOrThrow

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

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.

ResultAsync - Constructors

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);

ResultAsync - Function and instance methods

ResultAsync - map

(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);

ResultAsync - flatMap

(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));

ResultAsync - caseOf

({ok: A => B, err: () => B}) -> ResultAsync<A, E> -> Promise

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,
});

@infinitebrahmanuniverse/nolb-ts-o @everything-registry/sub-chunk-2978

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago