@sweet-monads/maybe

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

$3

> 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

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

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

function getUser(id: number): Maybe {
return just({ email: "test@gmail.com", password: "test" });
}

// Maybe
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

`typescript
function chain(fn: (v: A) => Promise>): (m: Maybe) => Promise>;
`

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

Example:

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

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

#### merge

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

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

Example:

`typescript
const v1 = just(2); // Maybe.Just
const v2 = just("test"); // Maybe.Just
const v3 = none(); // Maybe.None

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

#### none

`typescript
function none(): Maybe;
`

- Returns Maybe with None state
Example:

`typescript
const v1 = none(); // Maybe.None
const v2 = none(); // Maybe.None
`

#### just

`typescript
function just(value: T): Maybe;
`

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

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

#### from

The same as just

`typescript
function from(value: T): Maybe;
`

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

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

#### fromNullable

`typescript
function fromNullable(value: T): Maybe>;
`

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

`typescript
const v1 = fromNullable(2); // Maybe.Just
`

#### isMaybe

`typescript
function isMaybe(value: unknown | Maybe): value is Maybe;
`

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

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

#### Maybe#isNone

`typescript
function isNone(): boolean;
`

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

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

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

#### Maybe#isJust

`typescript
function isJust(): boolean;
`

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

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

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

#### Maybe#or

`typescript
function or(x: Maybe): Maybe;
`

- Returns Maybe. If state of this is Just then this will be returned otherwise x argument will be returned
Example:

`typescript
const v1 = just(1);
const v2 = none();
const v3 = none();
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

`typescript
function join(this: Maybe>): Maybe;
`

- this: Maybe> - 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:

`typescript
const v1 = just(just(2));
const v2 = just(none());
const v3 = none>();

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

#### Maybe#map

`typescript
function map(fn: (val: Val) => NewVal): Maybe;
`

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

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

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

#### Maybe#mapNullable

`typescript
function mapNullable(fn: (val: Val) => (NewVal | null | undefined)): Maybe>;
`

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

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

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

#### Maybe#mapNullable

`typescript
function map(fn: (val: Val) => NewVal): Maybe;
`

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

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

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

##### Maybe#asyncMap

`typescript
function asyncMap(fn: (val: Val) => Promise): Promise>;
`

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

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

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

##### Maybe#apply

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

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

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

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

##### Maybe#asyncApply

Async variant of Maybe#apply

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

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

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

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

#### Maybe#chain

`typescript
function chain(fn: (val: Val) => Maybe): Maybe;
`

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

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

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

##### Maybe#asyncChain

`typescript
function asyncChain(fn: (val: Val) => Promise>): Promise>;
`

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

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

##### Maybe#fold

`typescript
function fold(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:
`typescript
const v1 = just(2);
const v2 = none();

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

#### Helpers

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

`typescript
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.