async-ls

This library provides powerful higher-order functions and other utilities for working with asynchronous functions with callbacks or ES6 promises.

Callback utility functions are in

{callbacks} = require \async-ls

and promise based functions are in

{promises} = require \async-ls

There's also a monad library accessible by:

{monads} = require \async-ls

Callback and promise functions are similar in their input arguments and their result. Callback functions return a callback function with the signature of (error, result) -> void and promise functions return a Promise object.

To get the individual functions use LiveScript pattern matching syntax:

{
	promises: {
		LazyPromise, parallel-map, parallel-limited-filter
	},
	monads: {
	    filterM, liftM
	}
} = require \async-ls

To build:

make build

Build for browsers (using Browserify):

make async-browser.js

Build for browsers (callbacks library only):

make callbacks-browser.js 

Build for browsers (promises library only):

make promises-browser.js

To test:

./test.sh

Monads

{monads} = require \async-ls

monadize

Monads work best in statically typed languages. To make monadic functions work in LiveScript, we need to pass the type of the monad to many of the monadic operations. monadize encapsulates the monad's type: return aka pure, fmap and bind functions.

monadize :: 
    (a -> m a) ->                   # pure
    ((a -> b) -> m a -> m b) ->     # fmap
    (m a -> (a -> m b) -> m b) ->   # bind
    Monad

kcompM

Left-to-right Kleisli composition of monads.

kcompM :: (Monad m) => (a -> m b) -> (b -> m c) -> (a -> m c)

joinM

Remove one level of monadic structure, projecting its bound argument into the outer level.

(Monad m) => m m x -> m x

filterM

Filter the list by applying the predicate function to each of its element one-by-one in serial order.

filterM :: (Monad x) => (x -> m Boolean) -> [x] -> m [x]

foldM

The foldM function is analogous to foldl, except that its result is encapsulated in a monad.

foldM :: (Monad a) => (a -> b -> m a) -> a -> [b] -> m a

sequenceM

Evaluate each action in the sequence from left to right, and collect the results.

sequenceM :: (Monad x) => [m x] -> m [x]

mapM

It is equivalent to sequenceM . (map f).

(Monad m) => (x -> m x) -> [x] -> m [x]

liftM

Promote a function to a monad.

liftM  :: (Monad m) => (a -> r) -> m a -> m r

liftM2

Promote a function to a monad, scanning the monadic arguments from left to right.

liftM2 :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r

ap

monad.pureM f `ap` x1 `ap` ... `ap` is equivalent to (liftMn monad) f x1 x2 ... xn

ap :: (Monad m) => m (a -> b) -> m a -> m b

Some Monad Instances:

list-monad :: Monad     # []

either-monad :: Monad   # [error, right]

writer-monad :: Monad   # [value, monoid]

Promises

{promises} = require \async-ls

Lazy Promise

LazyPromise only starts getting evaluated after then is called.

LazyPromise : Promise

Compositions

promise-monad :: Monad

returnP

Inject a value into a promise.

returnP :: x -> Promise x

fmapP

Map a normal function over a promise.

fmapP :: (x -> y) -> Promise x -> Promise y

ffmapP

fmapP with its arguments flipped.

ffmapP :: Promise x -> (x -> y) -> Promise y

bindP

Sequentially compose two promises, passing the value produced by the first as an argument to the second.

bindP :: Promise x -> (x -> Promise y) -> Promise y

fbindP

bindP with its arguments flipped.

fbindP :: (x -> Promise y) -> Promise x -> Promise y

filterP

Filter the list by applying the promise predicate function to each of its element one-by-one in serial order.

filterP :: (x -> Promise Boolean) -> [x] -> Promise [x]

foldP

The foldP function is analogous to foldl, except that its result is encapsulated in a promise.

foldP :: (a -> b -> Promise a) -> a -> [b] -> Promise a

sequenceP

Run its input (an array of Promise s) in parallel (without waiting for the previous promise to fulfill), and return the results encapsulated in a promise.

The returned promise immidiately gets rejected, if any of the promises in the input list fail.

sequenceP :: [Promise x] -> Promise [x]

Lists

parallel-map

parallel-map :: (a -> Promise b) -> [a] -> Promise [b]

serial-map

serial-map :: (a -> Promise b) -> [a] -> Promise [b]

parallel-limited-map

parallel-limited-map :: Int -> (x -> Promise y) -> [x] -> Promise [y]

parallel-filter

parallel-filter :: (x -> m Boolean) -> [x] -> m [x]

serial-filter

Synonym for filterP

serial-filter :: (x -> Promise Boolean) -> [x] -> Promise [x]

parallel-limited-filter

parallel-limited-filter :: Int -> (x -> Promise Boolean) -> [x] -> Promise x

parallel-any

Run the boolean predicate (that is encapsulated in a promise) on the list in parallel. The returned promise fulfills as soon as a matching item is found with true, otherwise false if no match was found.

parallel-any :: (x -> Promise Boolean) -> [x] -> Promise Boolean

serial-any

serial-any :: (x -> m Boolean) -> [x] -> m Boolean

parallel-limited-any

parallel-limited-any :: Int -> (x -> Promise Boolean) -> [x] -> Promise Boolean

parallel-all

parallel-all :: (x -> Promise Boolean) -> [x] -> Promise Boolean

serial-all

serial-all :: (x -> Promise Boolean) -> [x] -> Promise Boolean

parallel-limited-all

parallel-limited-all :: Int -> (x -> Promise Boolean) -> [x] -> Promise Boolean

parallel-find

Run the boolean predicate (that is encapsulated in a promise) on the list in parallel. The returned promisefulfills as soon as a matching item is found with the matching value, otherwise with null if no match was found.

parallel-find :: (x -> Promise Boolean) -> [x] -> m 

serial-find

serial-find :: (x -> Promise Boolean) -> [x] -> m x

parallel-limited-find

parallel-limited-find :: Int -> (x -> Promise Boolean) -> [x] -> Promise x

parallel-sequence

Synonym for sequenceP

parallel-sequence :: [Promise x] -> Promise [x]

serial-sequence

The serial version of sequenceP.

To run the list one by one in a serial order, its items must be instances of LazyPromise type. This function runs the list in parallel, if it is a list of normal Promise s.

serial-sequence :: [LazyPromise x] -> LazyPromise [x]

parallel-limited-sequence

parallel-limited-sequence :: Int -> [LazyPromise x] -> LazyPromise [x]

parallel-apply-each

parallel-apply-each :: x -> [x -> Promise y] -> Promise [y]

serial-apply-each

serial-apply-each :: x -> [x -> Promise y] -> Promise [y]

parallel-limited-apply-each

parallel-limited-apply-each :: x -> [x -> Promise y] -> Promise [y]

parallel-sort-by

Sort the list using the given function for making the comparison between the items.

parallel-sort-by :: (a -> Promise b) -> [a] -> Promise [a]

parallel-sort-with

parallel-sort-with takes a binary function which compares two items and returns either a positive number, 0, or a negative number, and sorts the inputted list using that function.

parallel-sort-with :: (a -> a -> Promise i) -> [a] -> Promise [a]

waterfall

waterfall :: x -> (x -> Promise x) -> Promise x

transform-promise-either

Bind a promise monad to an either monad. The result is a promise monad. Since we can think of promise as a superset of either in the way it handles errors.

transform-promise-either :: Promise x -> (x -> Either y) -> Promise y

ftransform-promise-either

transform-promise-either with its arguments flipped.

ftransform-promise-either :: (x -> Either y) -> Promise x -> Promise y

transform-either-promise

Bind an either monad to a promise monad.

transform-either-promise :: Either x -> (x -> Promise y) -> Promise y

ftransform-either-promise

transform-either-promise with its arguments flipped.

ftransform-either-promise :: (x -> Promise y) -> Either x -> Promise y

to-callback

Convert the promise object to a callback with the signature of (error, result) -> void

Promise x -> CB x

from-value-callback

Make a promise object from a callback with the signature of (result) -> void, like fs.exist

Cb x -> Promise x

from-error-value-callback

Make a promise object from a callback with the signature of (error, result) -> void, like fs.stat

CB x -> Promise x

from-named-callbacks

Make a promise object from obj.

String -> String -> obj -> Promise x

Callbacks

These functions are analogous to their promise-based counterparts that are documented above. But instead of a Promise their last argument is a callback. You can think of curried version of these functions as functions that return a function that takes callback.

{callbacks} = require \prelude-ls

Convention

This would be our definition of asynchronous functions:

If function f returns function g and g takes a callback as its only argument; then f is an asynchronous function.

Our callbacks will always receive two parameters: (error, result).

Here CB a stands for a callback function with signature: (err, a) -> void You can get the result of an asynchronous function (with a callback of type of CB a) by:

(err, a) <- f

Composition of Asynchronous Actions

returnA

Inject a value into an asynchronous action.

returnA :: x -> CB x

fmapA

Map a normal function over an asynchronous action.

fmapA :: (x -> y) -> CB x -> CB y

ffmapA

fmapA with its arguments flipped

ffmapA :: CB x -> (x -> y) -> CB y

bindA

Sequentially compose two asynchronous actions, passing the value produced by the first as an argument to the second.

bindA :: CB x -> (x -> CB y) -> CB y

fbindA

bindA with its arguments flipped

fbindA :: (x -> CB y) -> CB x -> CB y

kcompA

Similar to Left-to-right Kleisli composition, kcompA composes two asynchronous actions passing the value produced by the first as an argument to the second. The result is a new asynchronous function that takes the argument of the first function.

kcompA :: (x -> CB y) -> (y -> CB z) -> (x -> CB z)

foldA

The foldA function is analogous to foldl, except that its result is encapsulated in an asynchronous callback.

foldA :: (a -> b -> m a) -> a -> [b] -> m a

sequenceA

Evaluate each action in the sequence from left to right, and collect the results.

sequenceA :: [CB x] -> CB [x]

filterA

Filter the list by applying the asynchronous predicate function.

filterA :: (x -> CB Boolean) -> [x] -> CB [x]

Either

returnE

Inject a value into an either action.

returnE :: x -> Either x

fmapE

fmapE :: (x -> y) -> Either x -> Either y

fmapE

ffmapE :: Either x -> (x -> y) -> Either y

bindE

bindE :: Either x -> (x -> Either y) -> Either y

bindE

bindE :: (x -> Either y) -> Either x -> Either y

kcompE

Left to right Kleisli composition

kcompE :: (x -> Either y) -> (y -> Either z) -> (x -> Either z)

foldE

foldE :: (a -> b -> Either a) -> a -> [b] -> Either a

sequenceE

sequenceE :: [Either x] -> Either [x]

transformAE

transformAE :: CB x -> (x -> Either y) -> CB y

ftransformAE

ftransformAE :: (x -> Either y) -> CB x -> CB y

transformEA

transformEA :: Either x -> (x -> CB y) -> CB y

ftransformEA

ftransformEA :: (x -> CB y) -> Either x -> CB y

Lists

Map

parallel-map

parallel-map :: (a -> CB b) -> [a] -> CB [b]

serial-map

Serial Asynchronous Map

serial-map :: (a -> CB b) -> [a] -> CB [b]

parallel-map-limited

Similar to parallel-map, only no more than limit iterators will be simultaneously running at any time.

parallel-map-limited :: Int -> (x -> CB y) -> [x] -> CB [y]

Filter

parallel-filter

parallel-filter :: (x -> CB Boolean) -> [x] -> CB [x]

serial-filter

serial-filter :: (x -> CB Boolean) -> [x] -> CB [x]

parallel-limited-filter

parallel-limited-filter :: Int -> (x -> CB Boolean) -> [x] -> CB x

Any, All, Find

parallel-any

parallel-any :: (x -> CB Boolean) -> [x] -> CB Boolean

serial-any

serial-any :: (x -> CB Boolean) -> [x] -> CB Boolean

parallel-limited-any

parallel-limited-any :: Int -> (x -> CB Boolean) -> [x] -> CB Boolean

parallel-all

parallel-all :: (x -> CB Boolean) -> [x] -> CB Boolean

serial-all

serial-all :: (x -> CB Boolean) -> [x] -> CB Boolean

parallel-limited-all

parallel-limited-all :: Int -> (x -> CB Boolean) -> [x] -> CB Boolean

parallel-find

paralel-find :: (x -> CB Boolean) -> [x] -> CB x

serial-find

serial-find :: (x -> CB Boolean) -> [x] -> CB x

Sort

parallel-sort-by

Sorts a list using the inputted function for making the comparison between the items.

parallel-sort-by :: (a -> CB b) -> [a] -> CB [a]

parallel-sort-with

Takes a binary function which compares two items and returns either a positive number, 0, or a negative number, and sorts the inputted list using that function.

parallel-sort-with :: (a -> a -> CB i) -> [a] -> CB [a]

Control Flow

serial-sequence

serial-sequence :: [CB x] -> CB [x]

parallel-sequence

Run its sole input (a tasks array of functions) in parallel, without waiting until the previous function has completed. If any of the functions pass an error to its callback, the main callback is immediately called with the value of the error. Once the tasks have completed, the results are passed to the final callback as an array.

parallel-sequence :: [CB x] -> CB [x]

parallel-limited-sequence

parallel-limited-sequence :: Int -> [CB x] -> CB [x]

parallel-apply-each

parallel-apply-each :: x -> [x -> CB y] -> CB [y]

serial-apply-each

serial-apply-each :: x -> [x -> CB y] -> CB [y]

parallel-limited-apply-each

parallel-limited-apply-each :: x -> [x -> CB y] -> CB [y]

waterfall

waterfall :: x -> (x -> CB x) -> CB x

serial-fold

serial-fold :: (a -> b -> m a) -> a -> [b] -> m a