asyncator v1.0.2
asyncator
Class to be extended to fastly concatenate asynchronous tasks in parallel or series.
1. Installation
~$ npm install --save asyncator
2. Import package
a) Via browsers:
< script src="node_modules/asyncator/dist/asyncator.js" >< /script >
And then, in your JavaScript:
const { Asyncator } = AsyncatorAPI;
Note: in browser environments, you need to load async
library before Asyncator
class.
b) Via Node.js:
const { Asyncator } = require("asyncator");
3. Usage
1. Create a new instance (providing the new methods, if any):
const asyncSet = Asyncator.from({
a: (done) => done(null, 10),
b: (done) => done(null, 20),
c: (done) => done(null, 30)
});
// You can provide no parameters too, and initiate the instance with the `new` constructor:
const asyncSet = new Asyncator();
// Or:
const asyncSet = Asyncator.from();
2. Start running tasks asynchronously:
asyncSet
.parallel(["a","b","c", (done) => setTimeout(done, 1000)])
.then((data) => console.log("Ok..."))
.catch((error) => console.log("Error"));
asyncSet
.series(["a","b","c", (done) => setTimeout(done, 1000)])
.then((data) => console.log("Ok..."))
.catch((error) => console.log("Error"));
asyncSet
.each(["hola","que","tal"], (value, key, done) => {
console.log("Item:", item);
done();
})
.then((data) => console.log("Ok..."))
.catch((error) => console.log("Error"));
Note: if you pass a string instead of a function as the task, it
will be replaced by the method of that Asyncator
instance with that
same name.
4. API Reference
AsyncatorAPI = require("asyncator")
Type: {Object}
Description: Object that contains the whole Asyncator
API.
Note that in browser environments, this object is accessible
via the global window.AsyncatorAPI
, while in Node.js you
need to import the asyncator
node_module to have access to
it.
Asyncator = AsyncatorAPI.Asyncator
Type: {Class}
Description: Main class of the API. This class is used to define the
asycnhronous operations we want to have access to as member methods
that do asynchronous tasks (as async
node module) expects.
new Asyncator(Object:propsAndMethods = {})
Type: {Class constructor}
Description: It creates new Asyncator
instances. You pass an object
with all the new properties and methods you want the class to have,
and it will add them to the instance itself. The same can be done
through the static method Asyncator.from(...)
, where the same passed
parameters are passed to the class constructor too.
Parameter: {Object} propsAndMethods
. Object containing all the
properties and methods to be added to the current Asyncator
instance.
Returns: {Object:Asyncator}
Asyncator#series(Object|Array:methodNamesAndFunctions = {})
Type: {Member method}
Description: It runs multiple tasks in serie. You can provide functions as
async
node_module expects, or
strings referring to member method names (that are defined as async
node_module functions.
Parameter: {Object | Array} methodNamesAndFunctions
. Array or object
of strings (with names of member methods) or functions (that must work
well for async
node_module)
containing the callbacks of the current asynchronous operation.
Note that you can pass objects or arrays. This is because async.series(...)
node_module method can receive any of them, and when the success callback
is called, the data is returned in the same format and with the same
keys, either object or array.
Returns: {Object:Promise}
. Once you call this method, you can set
the success
and error
callbacks of a typical Promise.
Example: This is an example:
Asyncator
.from({a: (done) => done(null, 50)})
.series({a: "a"})
.then((data) => console.log(data.a + " is 50"))
.catch((error) => console.log("There were errors:", error))
This is another example, but with arrays now:
Asyncator
.from({a: (done) => done(null, 50)})
.series(["a"])
.then((data) => console.log(data[0] + " is 50"))
.catch((error) => console.log("There were errors:", error))
Asyncator#parallel(Object|Array:methodNamesAndFunctions = {})
Type: {Member method}
Description: It works exactly the same as Asyncator#series(...)
, but
instead of running the tasks in serie, they are run parallelly.
Parameter: {Object | Array} methodNamesAndFunctions
. The same as Asyncator#series
.
Returns: {Object:Promise}
. The same as Asyncator#series
.
Asyncator#get(String:properties, Any:defaultValue=undefined, String|RegExp:separator="." )
Type: {Member method}
Description: It retrieves property values from the Asyncator
instance
easierly, or returns the defaultValue
, and using the separator
to
separate the name of each property. So, for example, if I wanted to get
a value placed in asyncator.my.inner.properties.firstProperty
, all you
need to do is:
asyncator.get("my/inner/properties/firstProperty", 800, "/");
Or simply:
asyncator.get("my.inner.properties.firstProperty").
Both codes will do the same, except that the first, if it cannot
retrieve the specified property, it will return 800
.
Parameter: {String} properties
. Name of the keys we want to access to
retrieve our value, separated, by default, by a ".". The separator
parameter dictates which character should split the names.
Parameter: {Any} defaultValue
. When there are problems to retrieve
the specified property, it will return this value.
Parameter: {String|RegExp} separator
. Used by String#split(~)
to
separate the provided names of properties.
Returns: {Any}
. It returns the retrieved property, or the defaultValue
provided.
Asyncator#mapSeries(Object|Array:items, String|Function:iterator)
Type: {Member method}
Description: It maps an iterable piece of data (Object
or Array
) through
an asynchronous iterator callback, or the name of a member method (which is
coded as an async
function). The iteration is made one after the other.
Parameter: {Object | Array} items
. The piece of data you want to iterate.
Parameter: {Function} callback
. The asynchronous iterator applied for each item.
The callback works exactly as the typical async
callbacks, but receiving the item
which is iterated before the done
callback
Returns: {Object:Promise}
. The same as Asyncator#series
or Asyncator#parallel
.
Asyncator#mapParallel(Object|Array:items, String|Function:iterator)
Type: {Member method}
Description: It maps an iterable piece of data (Object
or Array
) through
an asynchronous iterator callback, or the name of a member method (which is
coded as an async
function). The iteration is made in parallel.
Parameter: {Object | Array} items
. The piece of data you want to iterate.
Parameter: {Function} callback
. The asynchronous iterator applied for each item.
The callback works exactly as the typical async
callbacks, but receiving the item
which is iterated before the done
callback.
Returns: {Object:Promise}
. The same as Asyncator#series
or Asyncator#parallel
.
5. Commands
1. To build the project source code:
~$ npm run build
2. To generate the documentation:
~$ npm run docs
3. To run tests:
~$ npm run test
4. To generate the coverage documentation:
~$ npm run coverage
6. Conclusion
Simple class to ease the asynchronous code of your programs.