@sweet-monads/either

Either Monad, The Either monad represents values with two possibilities: a value of type Either a b is either Left a or Right b.

$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

Usage

> npm install @sweet-monads/either

``typescript
import { Either, right } from "@sweet-monads/either";

class UserNotFoundError extends Error {
name: "UserNotFoundError";
}
type User = { email: string; password: string };

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

// Either
const user = getUser(1).map(({ email }) => email);
`

API

- chain
- merge
- mergeInOne
- mergeInMany
- left
- right
- from
- fromTry
- fromPromise
- isEither
- Either#isLeft
- Either#isRight
- Either#or
- Either#join
- Either#map
- Either#mapRight
- Either#mapLeft
- Either#asyncMap
- Either#apply
- Either#asyncApply
- Either#chain
- Either#asyncChain
- Either#fold
- Helpers

#### chain

`typescript
function chain(fn: (v: R) => Promise>): (m: Either) => Promise>;
`

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

Example:

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

// Either
const result = await getValue()
.then(Either.chain(async v => right(v * 2)))
.then(Either.chain(async v => left(new TypeError("Unexpected"))));
`

#### merge

Alias for mergeInOne

`typescript
function merge(values: [Either]): Either;
function merge(values: [Either, Either]): Either;
function merge(
values: [Either, Either, Either]
): Either;
// ... until 10 elements
`

- values: Array> - Array of Either values which will be merged into Either of Array
- Returns Either> which will contain Right> if all of array elements was Right otherwise Left.

Example:

`typescript
const v1 = right(2); // Either.Right
const v2 = right("test"); // Either.Right
const v3 = left(new Error()); // Either.Left

merge([v1, v2]); // Either.Right
merge([v1, v2, v3]); // Either.Left
`

#### mergeInOne

`typescript
function merge(values: [Either]): Either;
function merge(values: [Either, Either]): Either;
function merge(
values: [Either, Either, Either]
): Either;
// ... until 10 elements
`

- values: Array> - Array of Either values which will be merged into Either of Array
- Returns Either> which will contain Right> if all of array elements was Right otherwise Left.

Example:

`typescript
const v1 = right(2); // Either.Right
const v2 = right("test"); // Either.Right
const v3 = left(new Error()); // Either.Left

merge([v1, v2]); // Either.Right
merge([v1, v2, v3]); // Either.Left
`

#### mergeInMany

`typescript
function mergeInMany(values: [Either]): Either, [R1]>;
function mergeInMany(values: [Either, Either]): Either, [R1, R2]>;
function mergeInMany(
values: [Either, Either, Either]
): Either, [R1, R2, R3]>;
// ... until 10 elements
`

- values: Array> - Array of Either values which will be merged into Either of Array
- Returns Either, Array> which will contain Right> if all of array elements was Right otherwise array of all caught Left values.

Example:

`typescript
const v1 = right(2); // Either.Right
const v2 = right("test"); // Either.Right
const v3 = left(new Error()); // Either.Left

merge([v1, v2]); // Either, [number, string]>.Right
merge([v1, v2, v3]); // Either, [number, string, boolean]>.Left
`

#### left

`typescript
function left(value: L): Either;
`

- Returns Either with Left state which contain value with L type.
Example:

`typescript
const v1 = left(new Error()); // Either.Left
const v2 = left(new Error()); // Either.Left
`

#### right

`typescript
function right(value: R): Either;
`

- Returns Either with Right state which contain value with R type.
Example:

`typescript
const v1 = right(2); // Either.Right
const v2 = right(2); // Either.Right
`

#### from

The same as right

Return only Right typed value.

`typescript
function from(value: R): Either;
`

- Returns Either with Right state which contain value with R type.
Example:

`typescript
from(2); // Either.Right
`

#### fromTry

Returns Right with function result or Left if function execution throws an error.

`typescript
function fromTry(fn: () => R): Either;
`

`typescript
fromTry(() => 2); // Either.Right
fromTry(() => {
throw new Error("test");
}); // Either.Left
`

#### fromPromise

Returns Right with the promise value if the provided promise fulfilled or Left with the error value if the provided promise rejected.

`typescript
function fromPromise(promise: Promise): Promise>;
`

`typescript
fromPromise(Promise.resolve(2)); // Either.Right
fromPromise(Promise.reject(new Error("test"))); // Either.Left
`

#### isEither

`typescript
function isEither(value: unknown | Either): value is Either;
`

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

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

#### Either#isLeft

`typescript
function isLeft(): boolean;
`

- Returns true if state of Either is Left otherwise false
Example:

`typescript
const v1 = right(2);
const v2 = left(2);

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

#### Either#isRight

`typescript
function isRight(): boolean;
`

- Returns true if state of Either is Right otherwise false
Example:

`typescript
const v1 = right(2);
const v2 = left(2);

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

#### Either#or

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

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

`typescript
const v1 = right(2);
const v2 = left("Error 1");
const v3 = left("Error 2");
const v4 = right(3);

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
`

#### Either#join

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

- this: Either> - Either instance which contains other Either instance as Right value.
- Returns unwrapped Either - if current Either has Right state and inner Either has Right state then returns inner Either Right, if inner Either has Left state then return inner Either Left otherwise outer Either Left.
Example:

`typescript
const v1 = right(right(2));
const v2 = right(left(new Error()));
const v3 = left>(new TypeError());

v1.join(); // Either.Right with value 2
v2.join(); // Either.Left with value new Error
v3.join(); // Either.Left with value new TypeError
`

#### Either#map

`typescript
function map(fn: (val: R) => NewR): Either;
`

- Returns mapped by fn function value wrapped by Either if Either is Right otherwise Left with L value
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

const newVal1 = v1.map(a => a.toString()); // Either.Right with value "2"
const newVal2 = v2.map(a => a.toString()); // Either.Left with value new Error()
`

#### Either#mapRight

`typescript
function mapRight(fn: (val: R) => NewR): Either;
`

The same as Either#map

- Returns mapped by fn function value wrapped by Either if Either is Right otherwise Left with L value
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

const newVal1 = v1.map(a => a.toString()); // Either.Right with value "2"
const newVal2 = v2.map(a => a.toString()); // Either.Left with value new Error()
`

#### Either#mapLeft

`typescript
function mapLeft(fn: (val: L) => NewL): Either;
`

- Returns mapped by fn function value wrapped by Either if Either is Left otherwise Right with R value
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

const newVal1 = v1.mapLeft(a => a.toString()); // Either.Right with value 2
const newVal2 = v2.mapLeft(a => a.toString()); // Either.Left with value "Error"
`

##### Either#asyncMap

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

- Returns Promise with mapped by fn function value wrapped by Either if Either is Right otherwise Left with value L
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

// Promise.Right> with value "2"
const newVal1 = v1.asyncMap(a => Promise.resolve(a.toString()));
// Promise.Left> with value new Error()
const newVal2 = v2.asyncMap(a => Promise.resolve(a.toString()));
`

##### Either#apply

`typescript
function apply(this: Either B>, arg: Either): Either;
function apply(this: Either, fn: Either B>): Either;
`

- this | fn - function wrapped by Either, which should be applied to value arg
- arg | this - value which should be applied to fn
- Returns mapped by fn function value wrapped by Either if Either is Right otherwise Left with L value
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());
const fn1 = right number>((a: number) => a * 2);
const fn2 = left number>(new Error());

const newVal1 = fn1.apply(v1); // Either.Right with value 4
const newVal2 = fn1.apply(v2); // Either.Left with value new Error()
const newVal3 = fn2.apply(v1); // Either.Left with value new Error()
const newVal4 = fn2.apply(v2); // Either.Left with value new Error()
`

##### Either#asyncApply

Async variant of Either#apply

`typescript
function asyncApply(this: Either Promise>, arg: Either | A>): Promise>;
function asyncApply(this: Either | A>, fn: Either Promise>): Promise>;
function asyncApply(
this: Either | A> | Either Promise>,
argOrFn: Either | A> | Either Promise>
): Promise>;
`

- this | fn - function wrapped by Either, 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 Either if Either is Right otherwise Left with L value
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());
const fn1 = right Promise>((a: number) => Promise.resolve(a * 2));
const fn2 = left Promise>(new Error());

const newVal1 = fn1.apply(v1); // Promise.Right> with value 4
const newVal2 = fn1.apply(v2); // Promise.Left> with value new Error()
const newVal3 = fn2.apply(v1); // Promise.Left> with value new Error()
const newVal4 = fn2.apply(v2); // Promise.Left> with value new Error()
`

#### Either#chain

`typescript
function chain(fn: (val: R) => Either): Either;
`

- Returns mapped by fn function value wrapped by Either if Either is Right and returned by fn value is Right too otherwise Left
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

// Either.Right with value "2"
const newVal1 = v1.chain(a => right(a.toString()));
// Either.Left with value new TypeError()
const newVal2 = v1.chain(a => left(new TypeError()));
// Either.Left with value new Error()
const newVal3 = v2.chain(a => right(a.toString()));
// Either.Left with value new Error()
const newVal4 = v2.chain(a => left(new TypeError()));
`

##### Either#asyncChain

`typescript
function chain(fn: (val: R) => Promise>): Promise>;
`

- Returns Promise with mapped by fn function value wrapped by Either if Either is Right and returned by fn value is Right too otherwise Left
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

// Promise.Right> with value "2"
const newVal1 = v1.asyncChain(a => right(a.toString()));
// Promise.Left> with value new TypeError()
const newVal2 = v1.asyncChain(a => left(new TypeError()));
// Promise.Left> with value new Error()
const newVal3 = v2.asyncChain(a => right(a.toString()));
// Promise.Left> with value new Error()
const newVal4 = v2.chain(a => left(new TypeError()));
`

##### Either#fold

`typescript
function fold(mapLeft: (value: L) => C, mapRight: (value: R) => C): C;
`

- Returns values mapped by mapRight if Either is Right, otherwise value mapped by mapLeft
Example:

`typescript
const v1 = right(2);
const v2 = left(new Error());

// 4
const newVal1 = v1.fold(() => 'fail', value => value * 2);
// "fail"
const newVal2 = v2.fold(() => 'fail', value => value * 2);
`

#### Helpers

`typescript
// Value from Either instance
const { value } = right(2); // number | Error
const { value } = right(2); // number
const { value } = left(new Error()); // number | Error
const { value } = left(new Error()); // Error
`

`typescript
right(2).unwrap(); // number
left(new TypeError()).unwrap(); // throws error

right(2).unwrap(); // number
left(new TypeError()).unwrap(x => x); // throws TypeError provied in arguments

left(2).unwrapOr(3) // returns 3
rigth(2).unwrapOr(3) // returns 2

left(2).unwrapOrElse(num => num * 2) // returns 4
right(2).unwrapOrElse(num => num * 2) // returns 2
``

License

MIT (c) Artem Kobzar see LICENSE file.