bluebird-promisell
A functional programming library for promises.
bluebird-promisell
provides a set of composable functions that allows you to write flat async code with promises.
Usage
Write flat async code with "liftp"
Let's say we have the following sync code to get a list of userId.
var { return 'token'; };var { return 'secret'; };var { return 1 2 3;}; // Tokenvar token = ; // Secretvar secret = ; // [UserId]var userIds = ; console; // [1, 2, 3]
Now, if the sub functions getToken
, getSecret
, getUserIds
becomes async (all return Promise),
the only change we need to make is "lifting" getUserIds
with liftp
.
var Promise = ;var P = ; var { return Promise; };var { return Promise; };var { return Promise;}; // Promise Tokenvar tokenP = ; // Promise Secretvar secretP = ; // Promise [UserId]var userIdsP = PtokenP secretP; userIdsP; // [1, 2, 3]
Now the code runs async, but it reads like sync code.
Making async calls in parallel with "traversep"
var { if userId === 1 return ':)'; else if userId === 2 return ':D'; else return ':-|'; }; // Promise Tokenvar tokenP = ; // Promise Secretvar secretP = ; // Promise [UserId]var userIdsP = PtokenP secretP; // Promise [Photo]var photosP = PuserIdsP;photosP; // [":)", ":D", ":-|"]
Making async calls sequentially with "foldp"
// Promise [UserId]var userIdsP = PtokenP secretP; // [Photo] -> Photo -> [Photo]var { return photos;}; // Promise [Photo]var photosP = PuserIdsP; photosP; // [":)", ":D", ":-|"]
The above code will fetch photo by userId sequentially. If it fails to fetch the first photo, it will reject the promise without fetching next photo. And it will resolve the promise once all the photos have been fetched.
Wait until the second async call to finish, then return the value of the first async call
Let's say we want to send an email with all the photos, and wait until the email has been sent, then resolve the promise with the photos
With firstp
, we can wait until the email has been sent, and return the result of photos which
is from the first promise.
var { return Promise;}; // Promise [Photo]var photosP = PuserIdsP; // Promise Stringvar sentP = PphotosP;// ^^^^^^^^ P.liftp1 is equivalent to P.liftp when there is only one promise to resolve.// But P.liftp1 has better performance than P.liftp. P; // [":)", ":D", ":-|"]
API
purep :: a -> Promise a
Takes any value, returns a resolved Promise with that value
> promise3
fmapp :: (a -> b) -> Promise a -> Promise b
Transforms a Promise of value a into a Promise of value b
> promise7
voidp :: Promise a -> Promise undefined
Takes a Promise, returns a Promise that resolves with undefined when the input promise is resolved, or reject with the same error when the input promise is rejected.
> promiseundefined
sequencep :: Array Promise a -> Promise Array a
Transforms an array of Promise of value a into a Promise of array of a.
> promise3 4
traversep :: (a -> Promise b) -> Array a -> Promise Array b
Maps a function that takes a value a and returns a Promise of value b over an array of value a,
then use sequencep
to transform the array of Promise b into a Promise of array b
> 2 3 4promise5 6 7
pipep :: [(a -> Promise b), (b -> Promise c), ... (m -> Promise n)] -> a -> Promise n
Performs left-to-right composition of an array of Promise-returning functions.
> 6;promise90
liftp :: (a -> b -> ... n -> x) -> Promise a -> Promise b -> ... -> Promise n -> Promise x
Takes a function so that this function is able to read input values from resolved Promises, and return a Promise that will resolve with the output value of that function.
> Promise Promise Promise;promise35
liftp1 :: (a -> b) -> Promise a -> Promise b
Takes a function and apply this function to the resolved Promise value, and return a Promise that will resolve with the output of that function.
> Promise;promiseabc@examplecom
firstp :: Promise a -> Promise b -> Promise a
Takes two Promises and return the first if both of them are resolved
> promise1 > promiseError 3
secondp :: Promise a -> Promise b -> Promise b
Takes two Promises and return the second if both of them are resolved
> promise2 > promiseError 3
filterp :: (a -> Promise Boolean) -> Array a -> Promise Array a
Takes a predicat that returns a Promise and an array of a, returns a Promise of array a which satisfy the predicate.
> 2 3 4promise4
foldp :: (b -> a -> Promise b) -> b -> Array a -> Promise b
Returns a Promise of value b by iterating over an array of value a, successively calling the iterator function and passing it an accumulator value of value b, and the current value from the array, and then waiting until the promise resolved, then passing the result to the next call.
foldp resolves promises sequentially
> 12 3 4promise10
unfold :: (a -> Promise [b, a]?) -> a -> Promise [b]
Builds a list from a seed value. Accepts an iterator function, which takes the seed and return a Promise.
If the Promise resolves to a false
value, it will return the list.
If the Promise resolves to a pair, the first item will be appended to the list and the second item will be used as the new seed in the next call to the iterator function.
> 1;promise12345
mapError :: (Error -> Error) -> Promise a -> Promise a
Transform the rejected Error.
> Promise;rejected promise
resolveError :: (Error -> b) -> Promise a -> Promise b
Recover from a rejected Promise
> ;
promise false
toPromise :: ((a -> Boolean), (a -> Error)) -> a -> Promise a
Takes a predict
function and a toError
function, return a curried
function that can take a value and return a Promise.
If this value passes the predict, then return a resolved Promise with
that value, otherwise pass the value to the toError
function, and
return a rejected Promise with the output of the toError
function.
var validateGreaterThan0 = ; > promise10 > rejected promiseError 'value is not greater than 0'
bimap :: (a -> Promise b) -> (Error -> Promise b) -> Promise a -> Promise b
Takes two functions and return a function that can take a Promise and return a Promise. If the received Promise is resolved, the first function will be used to map over the resolved value; If the received Promise is rejected, the second function will be used to map over the Error.
Like Promise.prototype.then function, but takes functions first.
var add1OrReject = ; > promise3 > ;promise'can not add value for NaN'