@kenavr/promise-operators

Operators for Promise chains

The project includes a couple of rxjs inspired operators for promises

Installation

npm i @kenavr/promise-operators

import { map } from '@kenavr/promise-operators';

Promise.resolve([1, 2, 3])
  .then(map(val => val + 1))
  .then(/*[2,3,4]*/);

Operators

Descriptions

All functions return a Promise making it simple to chain them.

map

Maps an array or value into a new one using a specified function

filter

Either filters an array or throws an error if an object doesn't pass the condition

reduce

Either reduces an array or runs the passed object through the reducer function

pipe

Enables the use of operators without creating unnecessary Promises along the way

flatMap

Maps an array or value into a new one using a function that returns a Promise (the Promise gets resolved)

parallel

Runs multiple functions parallel all receiving the same initial value

throwIf

Throws an error if the passed data doesn't meet the condition

tap

Executes a side effect without modifying the passed data

map

Takes a mapping function and an array or object as value. If an array is passed it runs through the array and applies the mapping function to each value. If an object is passed the mapping function is applied once on the object.

Param	Type	Description
mapper	Function	The mapping function applied to the passed value, returns a function
value	*	The data the mapping function should be applied on

Isolated Example

map(val => val + 1)(1).then(/* 2 */);

Example

Promise.resolve([1, 2, 3])
  .then(map(val => val + 1))
  .then(/*[2,3,4]*/);

filter

Takes a filter function and an array or object as value. If an array is passed its values are filtered based on the condition. If an object is passed the filter function is applied once on the object.

Param	Type	Description
filter	Function	The filter function applied to the passed value, returns a function
value	*	The data the filter function should be applied on

Isolated Example

filter(val => val < 10)([2, 3, 5, 7, 11, 13, 17, 19]).then(/* [2,3,5,7] */);

Example

Promise.resolve([2, 3, 5, 7, 11, 13, 17, 19])
  .then(filter(val => val < 10))
  .then(/*[2,3,5,7]*/);

reduce

Takes a reducer function with an initial value and an array or object as value. If an array is passed the function is applied on the array and return a single value. If an object is passed the reducer function is applied once on the object.

Param	Type	Description
reducer	Function (acc, val) => acc	The reducer function applied to the passed value
initialValue	*	The value the reducer function starts with
value	*	The data the filter function should be applied on

Isolated Example

reduce((sum, val) => sum + val, 0)([1, 2, 3, 4, 5]).then(/* 15 */);

Example

Promise.resolve([5, 4, 3, 2, 1])
  .then(reduce((product, val) => product * val, 1))
  .then(/* 120 */);

pipe

Takes a list of operators and executes them sequentially.

Param	Type	Description
operators	List	A comma seperated list of all operators that should be applied sequentially
value	*	The data the piped operators should be applied on

Isolated Example

pipe(
  map(val => val * 10),
  filter(val => val < 30)
)([1, 2, 3, 4, 5]).then(/* [10,20] */);

Example

Promise.resolve([1, 2, 3, 4, 5])
  .then(
    pipe(
      map(val => val * 10), // [10, 20, 30, 40, 50]
      filter(val => val < 30), // [10, 20]
      reduce((acc, val) => acc + val, 0) // 30
    )
  )
  .then(/* 30 */);

flatMap

Takes a mapping function that returns a Promise and an array or object as value. If an array is passed it runs through the array and applies the mapping function to each value. If an object is passed the mapping function is applied once on the object. The inner promises are resolved before returning a single Promise.

Param	Type	Description
mapper	Function	The mapping function applied to the passed value, returns a Promise
value	*	The data the mapping function should be applied on

Isolated Example

flatMap(val => Promise.resolve(val + 1))(1).then(/* 2 */);

Example

Promise.resolve([1, 2, 3])
  .then(flatMap(val => Promise.resolve(val + 1)))
  .then(/*[2,3,4]*/);

parallel

Takes an array of functions and runs them parallel all receiving the same initial value

Param	Type	Description
workers	Function[]	Array of functions
value	*	The data passed to each function

Isolated Example

const addOne = val => val + 1;
const subOneAsync = val => Promise.resolve(val - 1);

parallel([addOne, subOneAsync])(1).then(/* [2, 0]*/);

Example

const sum = array => array.reduce((sum, val) => sum + val, 0);
const multiply = array => array.reduce((sum, val) => sum * val, 1);

Promise.resolve([2, 3, 4])
  .then(parallel([sum, multiply]))
  .then(/*[ 9, 24 ]*/);

throwIf

Throws an error if the passed data doesn't meet the condition

Param	Type	Description
function	Function	Condition the passed value needs to meet
error	Error | string optional	An optional Error or error message which is thrown when the condition is not met
value	*	The data that needs to meet the criteria

Isolated Example

throwIf(val <= 5, 'Value is larger than 5')(10)
  .then(/**/)
  .catch(error => /* 'Value is larger than 5' */);

Example

Promise.resolve([2, 3, 4])
  .then(throwIf(array => array.length < 5, new Error('Array is too small!')))
  .then(/**/)
  .catch(error => /* 'Array is too small!' */);

tap

Executes a side effect without modifying the passed data

Param	Type	Description
function	Function	Function executing side effect
value	*	Data passed to the function

Isolated Example

tap(val => console.log('Value: ', val))(10) // Value: 10
  .then(/* 10 */);

Example

let counter = 0;

Promise.resolve([2, 3, 4])
  .then(tap(val => counter++))
  .then(/* [2, 3, 4] */);