@sweet-monads/maybe
v3.3.1
Published
[Maybe Monad](https://en.wikibooks.org/wiki/Haskell/Understanding_monads/Maybe), The Maybe monad represents computations which might "go wrong" by not returning a value.
Downloads
11,778
Readme
@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: "[email protected]", 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 toMaybe<A>
value- Returns function with
Maybe<A>
argument and promisedMaybe
withMaybe.None
or mapped byfn
value (could be used insidePromise#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 containJust<Array<T>>
if all of array elements wasJust<T>
elseNone
.
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
withNone
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
withJust
state which contain value withT
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
withJust
state which contain value withT
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
withJust
state which contain value withT
type if value is not null or undefined andNone
otherwise. Example:
const v1 = fromNullable(2); // Maybe<number>.Just
isMaybe
function isMaybe<T>(value: unknown | Maybe<T>): value is Maybe<T>;
- Returns
boolean
if givenvalue
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 ofMaybe
isNone
otherwisefalse
Example:
const v1 = just(2);
const v2 = none();
v1.isNone(); // false
v2.isNone(); // true
Maybe#isJust
function isJust(): boolean;
- Returns
true
if state ofMaybe
isJust
otherwisefalse
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 ofthis
isJust
thenthis
will be returned otherwisex
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 otherMaybe
instance asJust
value.- Returns unwrapped
Maybe
- if currentMaybe
hasJust
state and innerMaybe
hasJust
state then returns innerMaybe
Just
, otherwise returnsMaybe
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 byMaybe
ifMaybe
isJust
otherwiseNone
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 byMaybe
ifMaybe
isJust
and the returned value is notnull
orundefined
otherwiseNone
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 byMaybe
ifMaybe
isJust
otherwiseNone
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 byfn
function value wrapped byMaybe
ifMaybe
isJust
otherwiseNone
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 valuearg
arg | this
- value which should be applied tofn
- Returns mapped by
fn
function value wrapped byMaybe
ifMaybe
isJust
otherwiseNone
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 valuearg
arg | this
- value which should be applied tofn
- Returns
Promise
with mapped byfn
function value wrapped byMaybe
ifMaybe
isJust
otherwiseNone
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 byMaybe
ifMaybe
isJust
and returned byfn
value isJust
too otherwiseNone
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 byfn
function value wrapped byMaybe
ifMaybe
isJust
otherwiseNone
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
isJust
thenmapJust
is result ofmapJust
is returned, otherwise return ofmapNone
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.