@sweet-monads/maybe

Maybe Monad, The Maybe monad represents computations which might "go wrong" by not returning a value.

This library belongs to sweet-monads project

sweet-monads — easy-to-use monads implementation with static types definition and separated packages.

• No dependencies, one small file
• Easily auditable TypeScript/JS code
• Check out all libraries: either, iterator, interfaces, maybe identity

Usage

npm install @sweet-monads/maybe

import { Maybe, just, none } from "@sweet-monads/maybe";

type User = { email: string; password: string };

function getUser(id: number): Maybe<User> {
  return just({ email: "[e-mail]", password: "test" });
}

// Maybe<string>
const user = getUser(1).map(({ email }) => email);

API

• chain
• merge
• none
• just
• from
• fromNullable
• isMaybe
• Maybe#isNone
• Maybe#isJust
• Maybe#or
• Maybe#join
• Maybe#map
• Maybe#asyncMap
• Maybe#apply
• Maybe#asyncApply
• Maybe#chain
• Maybe#asyncChain
• Maybe#fold
• Helpers

chain

function chain<A, B>(fn: (v: A) => Promise<Maybe<B>>): (m: Maybe<A>) => Promise<Maybe<B>>;

• fn: (v: A) => Promise<Maybe<B>> - function which should be applied asynchronously to Maybe<A> value
• Returns function with Maybe<A> argument and promised Maybe with Maybe.None or mapped by fn value (could be used inside Promise#then function).

Example:

const getValue = async () => just(1);

// Maybe<number>
const result = await getValue()
  .then(Maybe.chain(async v => just(v * 2)))
  .then(Maybe.chain(async v => none()));

merge

function merge<V1>(values: [Maybe<V1>]): Maybe<[V1]>;
function merge<V1, V2>(values: [Maybe<V1>, Maybe<V2>]): Maybe<[V1, V2]>;
function merge<V1, V2, V3>(values: [Maybe<V1>, Maybe<V2>, Maybe<V3>]): Maybe<[V1, V2, V3]>;
// ... until 10 elements

• values: Array<Maybe<T>> - Array of Maybe values which will be merged into Maybe of Array
• Returns Maybe<Array<T>> Maybe of Array which will contain Just<Array<T>> if all of array elements was Just<T> else None.

Example:

const v1 = just(2); // Maybe<number>.Just
const v2 = just("test"); // Maybe<string>.Just
const v3 = none<boolean>(); // Maybe<boolean>.None

merge([v1, v2]); // Maybe<[number, string]>.Just
merge([v1, v2, v3]); // Maybe<[number, string, boolean]>.None

none

function none<T>(): Maybe<T>;

• Returns Maybe with None state Example:

const v1 = none(); // Maybe<never>.None
const v2 = none<number>(); // Maybe<number>.None

just

function just<T>(value: T): Maybe<T>;

• Returns Maybe with Just state which contain value with T type. Example:

const v1 = just(2); // Maybe<number>.Just
const v2 = just<2>(2); // Maybe<2>.Just

from

The same as just

function from<T>(value: T): Maybe<T>;

• Returns Maybe with Just state which contain value with T type. Example:

const v1 = from(2); // Maybe<number>.Just
const v2 = from<2>(2); // Maybe<2>.Just

fromNullable

function fromNullable<T>(value: T): Maybe<NonNullable<T>>;

• Returns Maybe with Just state which contain value with T type if value is not null or undefined and None otherwise. Example:

const v1 = fromNullable(2); // Maybe<number>.Just

isMaybe

function isMaybe<T>(value: unknown | Maybe<T>): value is Maybe<T>;

• Returns boolean if given value is instance of Maybe constructor. Example:

const value: unknown = 2;
if (isMaybe(value)) {
  // ... value is Maybe<unknown> at this block
}

Maybe#isNone

function isNone(): boolean;

• Returns true if state of Maybe is None otherwise false Example:

const v1 = just(2);
const v2 = none();

v1.isNone(); // false
v2.isNone(); // true

Maybe#isJust

function isJust(): boolean;

• Returns true if state of Maybe is Just otherwise false Example:

const v1 = just(2);
const v2 = none();

v1.isJust(); // true
v2.isJust(); // false

Maybe#or

function or<T>(x: Maybe<T>): Maybe<T>;

• Returns Maybe<T>. If state of this is Just then this will be returned otherwise x argument will be returned Example:

const v1 = just(1);
const v2 = none<number>();
const v3 = none<number>();
const v4 = just(4);

v1.or(v2); // v1 will be returned
v2.or(v1); // v1 will be returned
v2.or(v3); // v3 will be returned
v1.or(v4); // v1 will be returned

v2.or(v3).or(v1); // v1 will be returned
v2.or(v1).or(v3); // v1 will be returned
v1.or(v2).or(v3); // v1 will be returned

Maybe#join

function join<V>(this: Maybe<Maybe<V>>): Maybe<V>;

• this: Maybe<Maybe<V>> - Maybe instance which contains other Maybe instance as Just value.
• Returns unwrapped Maybe - if current Maybe has Just state and inner Maybe has Just state then returns inner Maybe Just, otherwise returns Maybe None. Example:

const v1 = just(just(2));
const v2 = just(none());
const v3 = none<Maybe<number>>();

v1.join(); // Maybe.Just with value 2
v2.join(); // Maybe.None without value
v3.join(); // Maybe.None without value

Maybe#map

function map<Val, NewVal>(fn: (val: Val) => NewVal): Maybe<NewVal>;

• Returns mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();

const newVal1 = v1.map(a => a.toString()); // Maybe<string>.Just with value "2"
const newVal2 = v2.map(a => a.toString()); // Maybe<string>.None without value

Maybe#mapNullable

function mapNullable<Val, NewVal>(fn: (val: Val) => (NewVal | null | undefined)): Maybe<NonNullable<NewVal>>;

• Returns mapped by fn function value wrapped by Maybe if Maybe is Just and the returned value is not null or undefined otherwise None Example:

const v1 = just(2);
const v2 = none<number>();

const newVal1 = v1.mapNullable(a => a.toString()); // Maybe<string>.Just with value "2"
const newVal2 = v2.mapNullable(a => a.toString()); // Maybe<string>.None without value
const newVal3 = v2.mapNullable<string | null>(a => null); // Maybe<string>.None without value
const newVal4 = v2.mapNullable<string | void>(a => undefined); // Maybe<string>.None without value

Maybe#mapNullable

function map<Val, NewVal>(fn: (val: Val) => NewVal): Maybe<NewVal>;

• Returns mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();

const newVal1 = v1.map(a => a.toString()); // Maybe<string>.Just with value "2"
const newVal2 = v2.map(a => a.toString()); // Maybe<string>.None without value

Maybe#asyncMap

function asyncMap<Val, NewVal>(fn: (val: Val) => Promise<NewVal>): Promise<Maybe<NewVal>>;

• Returns Promise with mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();

// Promise<Maybe<string>.Just> with value "2"
const newVal1 = v1.asyncMap(a => Promise.resolve(a.toString()));
// Promise<Maybe<string>.None> without value
const newVal2 = v2.asyncMap(a => Promise.resolve(a.toString()));

Maybe#apply

function apply<A, B>(this: Maybe<(a: A) => B>, arg: Maybe<A>): Maybe<B>;
function apply<A, B>(this: Maybe<A>, fn: Maybe<(a: A) => B>): Maybe<B>;

• this | fn - function wrapped by Maybe, which should be applied to value arg
• arg | this - value which should be applied to fn
• Returns mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();
const fn1 = just((a: number) => a * 2);
const fn2 = none<(a: number) => number>();

const newVal1 = fn1.apply(v1); // Maybe<number>.Just with value 4
const newVal2 = fn1.apply(v2); // Maybe<number>.None without value
const newVal3 = fn2.apply(v1); // Maybe<number>.None without value
const newVal4 = fn2.apply(v2); // Maybe<number>.None without value

Maybe#asyncApply

Async variant of Maybe#apply

function asyncApply<A, B>(
  this: Maybe<(a: Promise<A> | A) => Promise<B>>,
  arg: Maybe<Promise<A> | A>
): Promise<Maybe<B>>;
function asyncApply<A, B>(this: Maybe<Promise<A> | A>, fn: Maybe<(a: Promise<A> | A) => Promise<B>>): Promise<Maybe<B>>;

• this | fn - function wrapped by Maybe, which should be applied to value arg
• arg | this - value which should be applied to fn
• Returns Promise with mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();
const fn1 = just((a: number) => Promise, resolve(a * 2));
const fn2 = none<(a: number) => Promise<number>>();

const newVal1 = fn1.apply(v1); // Promise<Maybe<number>.Just> with value 4
const newVal2 = fn1.apply(v2); // Promise<Maybe<number>.None> without value
const newVal3 = fn2.apply(v1); // Promise<Maybe<number>.None> without value
const newVal4 = fn2.apply(v2); // Promise<Maybe<number>.None> without value

Maybe#chain

function chain<Val, NewVal>(fn: (val: Val) => Maybe<NewVal>): Maybe<NewVal>;

• Returns mapped by fn function value wrapped by Maybe if Maybe is Just and returned by fn value is Just too otherwise None Example:

const v1 = just(2);
const v2 = none<number>();

const newVal1 = v1.chain(a => just(a.toString())); // Maybe<string>.Just with value "2"
const newVal2 = v1.chain(a => none()); // Maybe<string>.None without value
const newVal3 = v2.chain(a => just(a.toString())); // Maybe<string>.None without value
const newVal4 = v2.chain(a => none()); // Maybe<string>.None without value

Maybe#asyncChain

function asyncChain<Val, NewVal>(fn: (val: Val) => Promise<Maybe<NewVal>>): Promise<Maybe<NewVal>>;

• Returns Promise with mapped by fn function value wrapped by Maybe if Maybe is Just otherwise None Example:

const v1 = just(2);
const v2 = none<number>();
// Promise<Maybe<string>>.Just with value "2"
const newVal1 = v1.asyncChain(a => Promise.resolve(just(a.toString())));
// Promise<Maybe<string>>.None without value
const newVal2 = v1.asyncChain(a => Promise.resolve(none()));
// Promise<Maybe<string>>.None without value
const newVal3 = v2.asyncChain(a => Promise.resolve(just(a.toString())));
// Promise<Maybe<string>>.None without value
const newVal4 = v2.asyncChain(a => Promise.resolve(none()));

Maybe#fold

function fold<C>(mapNone: () => C, mapJust: (value: T) => C): C;

• Returns value mapped by one of mapper functions. If Maybe is Just then mapJust is result of mapJust is returned, otherwise return of mapNone gets returned.

Example:

const v1 = just(2);
const v2 = none<number>();

// "just: 4"
const newVal1 = v1.fold(() => 'none', value => 'just: '+value*2) 
// "none"
const newVal2 = v1.fold(() => 'none', value => 'just: '+value*2)

Helpers

// Value from Maybe instance
const { value } = just(2); // number | undefined

just(2).unwrap(); // returns 2
none().unwrap(); // Throws error

just(2).unwrap(() => new Error("NEVER!")); // returns 2
none().unwrap(() => new CustomError("My error")); // Throws CustomError

just(2).unwrapOr(3) // returns 3
none().unwrapOr(3) // returns 2

just(2).unwrapOrElse(num => num * 2) // returns 4
none().unwrapOrElse(num => num * 2) // returns 2

License

MIT (c) Artem Kobzar see LICENSE file.