tsmonads provides some basic, strictly typed monadic data types for use with TypeScript, namely MayBe, Try and Either monads. It's API is heavily inspired by the according types in the Scala lanaguge API. It has no dependencies and can even be used (although without most of it's benefits) in JavaScript.
NPM: npm install tsmonads
Yarn: yarn add tsmonads
Simply import the needed functions and classes from "tsmonad.
- We improved statical type analysis in 3.0. This might lead to incompatibilities when using the library without checking the return values correctly.
- Global functions (map, flatMap) now return the correct type inferred from the incoming monad's type and the mapping function
unsafeLift()was removed from all monads to ensure type safety- Where default types are set for
Either::Left,Erroris now used instead ofstring
A Maybe either contains just a value or nothing. You can easily create new Maybe instances using the maybe factory function:
import {maybe} from "tsmonads";
const five = maybe(5); // Type of Maybe is infereed to be "number"
const n?: number;
[...]
const maybeANumber = maybe(n); // maybeANumber will be a Maybe<number>. Wether it contains a value depends on n being a number or undefined.
const nothingAtAll = maybe<number>(null); // nothingAtAll is Nothing. The generic type has to given explicitly because it cannot be inferred from the argument.
You can use map() and forEach() to transform the Maybe into another contained type or to perform side-effects on it's value. If the maybe is nothing, this is a no-op.
import {maybe} from "tsmonads";
const m = maybe(5);
const seven = m.map(x => x + 2);
const show = m.forEach(x => console.log(x));
You can extract the value from a maybe safely by supplying a default to its orElse()-function. If you need more control, you can use match() and suppy functions to handle the value and nothing case explicitly:
import {maybe} from "tsmonads";
const m: Maybe<number>;
[...]
const extractedValueOrZero = m.orElse(0);
const doSomethingWithTheValue = m.match(x => 2*x, () => -1);
Use Try to safely encapsulate a function call that may throw an exception. Try will either be a Success wrapping the return value of the function or a Failure. Use try via the call factory function.
import {call} from "tsmonads";
const retVal = call(() => 2+5); // retVal is Success<number>(7)
const fail = call(() => throw "Error"); // retVal is Failure("Error");
Like a Maybe, you can use map() and forEach() on a Try. For more control, supply functions to its onSuccess() and onFailure() handlers:
import {call} from "tsmonads";
const retVal = call(() => 2+5);
retVal.onSuccess(s => console.log(s)).onFailure(e => console.log("An error occured"));
If the Error encapsulated by the Failure doesn't matter to you, you can also convert the Try into a Maybe using its toMaybe() method.
An Either holds either a left or a right value. Usually, the left value denotes an error an the right value represents a successful result. Construct it using the left() and right() factory functions.
Besides the above functions, we also provide some utilities you can use when working with arrays of Monads. The clean() function will extract all values
from the monads, throw away any non-values (Nothing, Failure, Left) and return an array of the extracted values. The flatten() function will turn an Array<Monad<T>> into a Monad<Array<T>>. Note that you will receive a "negatively typed" array if even single value in the original array is Nothing/Failure/Left. Otherwise, you'll get a Just<Array<T>>, Success<Array<T>> or Right<Array<T>>. All monad types provide a typed wrapper
of flatten as a static method so you don't need to type-cast any results of the flatten method.