Tsoid

Typed functional library to deal with async operations.

Getting Started

Install using npm:

npm install tsoid

Documentation

The key difference is that this library self handles all errors that could be happen during the execution time. In cases that a computation of actions is composed (e.g. many actions run synchronously) if one error occur, it will be propagated till the end.

Promise based functions

pure

Lift a value into a resolved Promise.

Example:

pure(42);
// Promise { 42 }

fail

Helper function that receives an string or an instance of Error and return an Promise of Error.

Example:

fail('This is an error');
// Promise { Error('This is an error) };

when

Execute the action if the condition is true.

Example:

const printOk = () => Promise.resolve(console.log('Ok'));

when(true, printOk); // Ok
when(false, printOk); //

unless

Is the opposite of when.

either

Given two callback functions, and a Promise that can resolve to an Error instance, it calls the first callback passing the promise result if the result is an Error, or it calls the second callback passing the promise result if the result is an instance of Error.

It could act as a default function call if there's any error involved in the computation:

const successCallback = jest.fn((n) => n + 1);
const errorCallback = jest.fn(() => 9);

const action = () => Promise.resolve(new Error('Some error'));
either(successCallback, errorCallback, action);
// Promise { 9 }

But, if the computation throws an Error, that is the case of Promise.reject, the flow will be stopped and the error will be returned as a resolved promise.

Example:

const successCallback = jest.fn((n) => n + 1);
const errorCallback = jest.fn(() => 9);

const action = () => Promise.reject(new Error('Some error'));
either(successCallback, errorCallback, action);
// Promise rejected { Error('Some error') };

map

For a given action function and a list of values, applies the function to each element of the array, waits for each result and return a list of results.

Example:

const getUser = (id) => Promise.resolve({ id, user: 'User' });

map(getUser, [1, 2, 3]);
// Promise { [ { id: 1, user: "User"}, { id: 2, user: "User" }, ... ] }

filter

For a given predicate action function and a list of values, applies the predicate function to each element of the array, and return a list of all values that satisfies the predicate action function.

Example:

const userExist = (id) => Promise.resolve([1, 3].includes(id));

filter(userExist, [1, 2, 3]);
// Promise { [1, 3] };

reduce

Reduce a list of items into a single item using an async function.

Example:

const add = (x, y) => Promise.resolve(x + y);
const list = [1, 2, 3, 4, 5];

reduce(add, 0, list);
// Promise { 15 };

replicate

Performs the action function n times, gathering the results.

Example:

const getRandom = () => Promise.resolve(Math.trunc(Math.random() * 10));

replicate(3, getRandom);
// Promise { [8, 3, 4] }

sequence

Evaluate synchronously each promise in the list from left to right, and collect the results.

Example:

const getTen = () => Promise.resolve(10);
const getTwenty = () => Promise.resolve(20);

sequence([getTen(), getTwenty()]);
// Promise { [10, 20] }

traverse

It is like the map function, but with the arguments flipped.

lift

Lift a pure function into a Promise value.

Example:

const future10 = Promise.resolve(10);
const isTen = (x) => x === 10;

lift(isTen, future10);
// Promise { true };

It is also exported the functions liftP2, liftP3, liftP4 and a type unsafe version called liftPN, that resolves all the promises then apply the n-ary function to its values.

flatMap

Given a Promise and an action function that depends on the value of these promise, flatten the Promise and apply the value into the action, then await for the result.

Example:

const futureSelf = Promise.resolve({ name: 'User' });
const viewName = (user) => user.name;

flatMap(futureSelf, viewName);
// Promise { 'User' }

bind

Given a Promise and one or more actions, sequentially compose these actions, passing any value produced by the first as an argument to the second and so on. Similar to the Haskell >>= operator.

Example:

const initial = Promise.resolve(1);
const doubleP = (x) => Promise.resolve(x * 2);
const tripleP = (x) => Promise.resolve(x * 3);
const stringifyP = (x) => Promise.resolve('' + x);

bind(initial, doubleP, tripleP, stringifyP);
// Promise { '6' }

exec

Given one or more actions, sequentially compose them, discarding any value produced by the first, like sequencing operators. Similar to the Haskell >> operator.

Example:

const updateDatabase = async () => true;
const notifyUsers = async () => true;
const dropInstance = async () => true;

exec(updateDatabase, notifyUsers, dropInstance);

Utilities

This module contains a serie of utility functions that you can use.

id

The identity function, it returns the argument.

Example:

const value = 40;
id(value); // 40

flip

For a given function, it return a new function that has the arguments flipped.

Example:

const div = (n, m) => n / m;
const fdiv = flip(div);

div(4, 2); // 2
fdiv(2, 4); // 2

It is also exported flip3 and flip4 functions that has 3 and 4-arity.

curry

Transform a function into an static curried function.

Example:

const add = (x, y) => x + y;
const add10 = curry(add);

add10(10); // 20

It is also exported curry3 and curry4 functions that deal with function that has 3 and 4-arity.

uncurry

Undo a curried function.

Example:

const lazyAdd = (x) => (y) => x + y;
const add = uncurry(lazyAdd);

add(1, 2); // 3

compose

Compose n pure functions into a single function, applying from right to left.

Example:

const fn1 = (arg) => `fn1(${arg})`;
const fn2 = (arg) => `fn2(${arg})`;
const fn3 = (arg) => `fn3(${arg})`;
const fn4 = (arg) => `fn4(${arg})`;

const composed = compose(fn1, fn2, fn3, fn4);
composed(); // fn1(fn2(fn3(fn4(1))))

pipe

Compose n pure functions into a single function, applying from left to right.

Example:

const fn1 = (arg) => `fn1(${arg})`;
const fn2 = (arg) => `fn2(${arg})`;
const fn3 = (arg) => `fn3(${arg})`;
const fn4 = (arg) => `fn4(${arg})`;

const piped = pipe(fn1, fn2, fn3, fn4);
piped(1); // fn4(fn3(fn2(fn1(1))))