move-on

Description

move-on is a module that:

• executes the chosen functions (synchronous and | or asynchronous) in the chain
• can be a (really, really great) alternative for Promises
• supports timeout
• contains four methods that immitate the Promises' .all and .race methods
• allows to set the this reference inner context for all functions in the chain to transmit data between functions

Any bugs found? Give me to know on GitHub.

Usage

Node

npm install move-on

Browsers

Load the `move-on.min.js` file from the `src` folder in your `.html` file. The module is accessible as `moveOn` in the global scope. It is a `babel` converted and `webpack` bundled module version. ```html ```

Tests

npm test

Simple sample

const moveOn = require('move-on');
/* [Function] moveOn(list, config, onDone, onCatch)
   [Function] moveOn.all(list, config, onDone, onCatch)
   [Function] moveOn.each(list, config, onDone, onCatch)
   [Function] moveOn.first(list, config, onDone, onCatch) */
   
const list = [retrieveData, computeData, displayData];
const config = { timeout: 5000 };

moveOn(list, config, onDone, onCatch);

function retrieveData(resolve, reject, context){
  setTimeout(resolve, 1000); //asynchronous resolve
}
function computeData(resolve, reject, context){
  resolve(); //synchronous resolve
}
function displayData(resolve, reject, context){
  resolve();
}
function onDone(reject, context){ }
function onCatch(context){ }

Methods short description

The module's methods expect the [Array] list of functions to be passed as the first argument. Each function in the chain has the resolve and reject parameter, that should be called when ready (or failed) in order to move the functions execution forward. When the functions chain is successfully executed, the done callback function is called finally, otherwise the catch callback function is called.

1. moveOn

The chained functions are executed sequentially (one after another). Each function is expected to be resolved, so that the next chained function was executed. The done function is called as the last one, when all previous chained functions resolved. The catch function is called instead of done function, when at least one chained function failed (rejected). See the full description below.

2. moveOn.all

The all static method of move-on module executes all chosen functions at the same time (similarly to Promises' .all method). All chained functions are expected to be resolved so that the final done function was called. The catch function is called instead of done function, when at least one chained function failed (rejected). See the full description below.

3. moveOn.each

The each static method of move-on module executes all chosen functions at the same time. Each chained function is expected to be either resolved or rejected, so that the final done function was called. The failed (rejected) function does not stop the further functions execution. It can be used eg. to log the warnings in the catch callback function. See the full description below.

4. moveOn.first

The first static method of move-on module executes all chained functions at the same time. It expects the first (fastest) function to be resolved, so that the done function was called (similarly to Promises' .race method). When all functions failed (rejected), the catch function is called instead. See the full description below.

Methods behaviour

moveOn(list, config, done, catch)

• The move-on module function executes the list functions sequentially (one after another) in the chain
• When one list function resolves, the next list function is called, and so on...
• When the last list function resolves, the done function is called once (it ends up the module execution)
• When whichever list function rejects, the farther list functions and the done function are not called in the end
• When whichever list function rejects, the catch function is called instead once (it ends up the module execution)
• Each list function can be resolved and | or rejected multiple times. The forks of chain are created and executed then [read more]
• Each list function can execute the inner move-on module [read more]

moveOn.all(list, config, done, catch)

• move-on.all static method executes all the list functions simultaneously (at the same time)
• When one list function resolves, the done is not called immediately
• The done waits, till all list functions are resolved, to be called (it ends up the module execution - after that, all resolve and reject calls are ignored)
• When whichever list function rejects, the done function is not called in the end
• When whichever list function rejects, the catch function is called instead once (it ends up the module execution - after that, all resolve and reject calls are ignored)
• When whichever list function resolves and | or rejects multiple times, only the first call is respected [read more]
• Each list function can execute the inner move-on module [read more]

moveOn.each(list, config, done, catch)

• move-on.each static method executes all the list functions simultaneously (at the same time)
• When one list function resolves, the done is not called immediately
• The done waits, till each list function is either resolved or rejected, to be called (it ends up the module execution - after that, all resolve and reject calls are ignored)
• When whichever list function rejects, the catch function is called for each function individually
• When whichever list function rejects and the catch is called, it does not end up the module execution
• When whichever list function resolves and | or rejects multiple times, only the first call is respected [read more]
• Each list function can execute the inner move-on module [read more]

moveOn.first(list, config, done, catch)

• move-on.first static method executes all the list functions simultaneously (at the same time)
• The done waits, till the first (fastest) list function is resolved, to be called (it ends up the module execution - after that, all resolve and reject calls are ignored)
• When all list functions reject, the done function is not called in the end
• When all list functions reject, the catch function is called instead once (it ends up the module execution - after that, all resolve and reject calls are ignored)
• When whichever list function resolves and | or rejects multiple times, only the first call is respected [read more]
• Each list function can execute the inner move-on module [read more]

Arguments

1. list
2. config
3. done
4. catch

list [Array: function | array]

The [Array] list stores the list of functions, that should be called. It can contain:

• [Function] items [see below]
  const list = [fnA, fnB, fnC];
• or [Array] items that store the [Function] items [see below]
  const list = [fnA, [obj, fnB, fnC], fnD]
• or [Array] items that store the [String] names of methods [see below]
  const list = [fnA, [obj, 'fnB', 'fnC'], fnD]

1. [Function] items

• The [Array] list can contain [Function] items. It may be function, arrow function or object's method
• All functions are bound by default to the config.context reference (except arrow functions and already bound functions [read more])

const retrieveData = function(){};
const computeData = ()=>{};
const displayData = { display:()=>{} };

const list = [retrieveData, computeData, displayData.display];

2. [Array: function] items for individual binding

• All chained functions are bound by default to the config.context reference
• You can set the individual this reference for the chosen functions (except arrow functions and already bound functions [read more])
• In order to bind the chained functions individually, push [Array] items into the list:
  • The [0] item should indicate the object or value to be the this reference for the functions
  • The [1], [2], etc... item(s) should indicate the function(s), that will be bound to the [0] object or value
• The [Array] item functions are bound to the given [0] object or value instead of the config.context
• The config.bind setting does not affect the individual this reference setting
• The [Array] item functions still have the access to the config.context parameter
• the list can still contain the [Function] items next to this [Array] item

const workers = {}, earnings = {}, tasks = {};
const config = {context: tasks}; //the default this reference
const list = [
  functionA,  //this === tasks
  [workers, functionB],  //this === workers
  [earnings, functionC]  //this === earnings
];
moveOn(list, config, onDone, onCatch));

3. [Array: string] items for methods

The methods passed to the list loses their this reference to the object, they were declared in, what may be undesirable.

const workers = {
  addWorker: function(){},
  listEarnings: function(){}
;
const list = [
  workers.addWorker,    //this !== workers
  workers.listEarnings  //this !== workers
];

• to retain the this reference to the object, that the methods are declared in, push [Array] item with methods' [String] names into the list:
  • The [0] item should indicate the object, that the methods are declared in
  • The [1], [2], etc... item(s) should indicate the [String] name(s) of the method(s) declared in the [0] object
• These methods retain the this reference to the [0] object and are not bound to the config.context
• The config.bind setting does not affect the this reference
• The [Array] item functions still have the access to the config.context parameter
• the list can still contain the [Function] items or [Array] items with functions next to this [Array] item with [String] method's names

const displayData = function(){};
const workers = {
  addWorker: function(){},
  listEarnings: function(){}
};
const list = [ [workers, 'addWorker', 'listEarnings'], displayData ];
moveOn(list, config, onDone, onCatch));

config [Object | null]

• the [Object] config argument allows to set the following config properties: timeout, bind, context, passContext
• when the config is set to null or when it does not define the particular config property or when it defines the config property incorrectly, the default value is used for this config property instead
• any error is thrown when any config property is defined incorrectly (the default value is used instead)

config.timeout

Type: [Number | null | Infinity]
Default: 10000
Description:

• It must be a [Number] integer, equal or bigger than 0, that indicates the milliseconds
• it behaves different for each method:
  1. moveOn: The config.timeout starts out counting down individually for each chained function immediately after it is called. It expects each function to be resolved or rejected before timeout pass, otherwise it calls the catch function with the timeout error argument passed
  2. moveOn.all: The config.timeout starts out counting down once for all chained functions when the module is fired. It expects all functions to be resolved or any function to be rejected before timeout pass, otherwise it calls the catch function with the timeout error argument passed
  3. moveOn.each: The config.timeout starts out counting down once for all chained functions when the module is fired. It expects all functions to be either resolved or rejected before timeout pass, otherwise it calls the catch function with the timeout error argument passed
  4. moveOn.first: The config.timeout starts out counting down once for all chained functions when the module is fired. It expects at least one function to be resolved or all functions to be rejected before timeout pass, otherwise it calls the catch function with the timeout error argument passed
• All resolvess and rejects that are called after the config.timeout pass are ignored
• When the config.timeout is set to null or Infinity, the timeout is not set at all. If any of the chained function does not resolve (or reject), anything happen then and the done or catch function is never called in the end
• When the config.timeout is not defined, or if it is defined with incorrect value, the default value is set instead

Timeout error

It is an [Error] object with the following properties, that allow to distinguish, that the timeout error has been passed:

• message: eg. "Timeout. The chained function did not respond in the expected time of 10000 ms."
• info: "timeout"
• code: "ETIMEDOUT"

config.context

Type: [any]
Default: {}
Description:

• The config.context refers to the object (or value), that will be used as the this reference in all list functions, done and catch
• It is usefull to transmit data between functions; eg. the [Object] config.context's properties can be defined and got in any function
• The config.context can be any value, as any value can be used as the this reference in Function.prototype.bind [read more]
• The config.context is used as the this reference by default, unless you set config.bind to false
• The config.context is also accessible as the parameter, unless you set config.passContext to false

config.passContext

Type: [Boolean]
Default: true
Description:

• By default, the config.context object (or value) is passed through each list function, the done and catch as the argument:
  • arguments passed through list functions: {0: resolve, 1: reject, 2: context}
  • arguments passed through done function: {0: reject, 1: context}
  • arguments passed through catch function: {0: context}
• In order not to pass the config.context as the argument, set config.passContext to false
• The config.context accessible as the parameter is usefull:
  • if the list functions, done or catch are arrow functions, that are non-binding and cannot refer to the config.context via this keyword
  • if you compose the list with individually bound functions or methods names, that do not refer to the config.context via this keyword
  • if list functions, done or catch are already bound

config.bind

Type: [Boolean]
Default: true
Description:

• By default, each list function, done and catch are bound to the config.context object (or value), thus the this keyword refers to the config.context
• In order to retain the former this reference of all functions, set the config.bind to false
• In order to set the individual this reference for chosen functions, see the list constructing options
• keep in mind, that arrow functions are non-binding and that already bound functions cannot have the this reference changed anymore

done(reject, context) [Function]

The done is a callback function, that (in general) is called as the last one, when the list functions have been successfully executed. The done is called in a different way and time, depending on which method is called:

1. moveOn The done is called, when the last function from the list collection is resolved.
   The arguments passed through done:
   [0] reject
[1] config.context
[2], [3], etc... The arguments passed by the last resolved list function
2. moveOn.all The done is called, when all list functions are resolved.
   The arguments passed through done:
   [0] reject
[1] config.context
[2] resolveMap
3. moveOn.each The done is called, when all list functions are either resolved or rejected.
   The arguments passed through done:
   [0] reject
[1] config.context
[2] resolveMap
4. moveOn.first The done is called, when the first (fastest) list function is resolved.
   The arguments passed through done:
   [0] reject
[1] config.context
[2], [3], etc... The arguments passed by the first (fastest) resolved list function

resolveMap object

• The resolveMap object is passed through done callback when the moveOn.all and moveOn.each method is executed. It stores all arguments that have been passed by each list function's resolve call.
• The resolveMap contains all arguments objects at the indeces that correspond to the order of list functions calling; the third list function's arguments are accessible via resolveMap[2], and so on...
• The resolveMap properties:
  • missing It returns the [Array] list of those list functions' indeces (due to the order of calling) that have not been resolved
• The resolveMap methods:
  • forEach
    It loops through each arguments object.
    It expects the [0] parameter to be the [Function] callback.
    The [Function] callback is called for each arguments object.
    The callback parameters: {0: arguments, 1: argumentsIndex, 2: resolveMap}
    Usage: resolveMap.forEach((arguments, argumentsIndex, resolveMap) => { } );
  • forAll
    It loops through each item (argument) of each arguments object.
    It expects the [0] parameter to be the [Function] callback.
    The [Function] callback is called for each item (argument).
    The callback parameters: {0: argument, 1: argumentsIndex, 2: itemIndex, 3: resolveMap}
    Usage: resolveMap.forAll((argument, argumentsIndex, itemIndex, resolveMap) => { } );

catch(context) [Function]

The catch is a callback function, that (in general) is called as the last one, when the list function(s) have failed. The catch is called in a different way and time, depending on which method is called:

1. moveOn The catch is called, when any list function rejects.
   The arguments passed through catch:
   [0] config.context
[1], [2], etc... The arguments passed by the rejected list function
2. moveOn.all The catch is called, when any list function rejects.
   The arguments passed through catch:
   [0] config.context
[1], [2], etc... The arguments passed by the rejected list function
3. moveOn.each The catch is called for each list function rejection.
   The arguments passed through catch:
   [0] config.context
[1], [2], etc... The arguments passed by the rejected list function
4. moveOn.first The catch is called, when all list function rejected.
   The arguments passed through catch:
   [0] config.context
[1] rejectMap

rejectMap object

• The rejectMap object is passed through catch callback when the moveOn.first method is executed. It stores all arguments that have been passed by all list functions' reject calls
• The rejectMap contains all arguments objects at the indeces that correspond to the order of list functions calling; the third list function's arguments are accessible via rejectMap[2], and so on...
• The rejectMap methods:
  • forEach
    It loops through each arguments object.
    It expects the [0] parameter to be the [Function] callback.
    The [Function] callback is called for each arguments object.
    The callback parameters: {0: arguments, 1: argumentsIndex, 2: rejectMap}
    Usage: rejectMap.forEach((arguments, argumentsIndex, rejectMap) => { } );
  • forAll
    It loops through each item (argument) of each arguments object.
    It expects the [0] parameter to be the [Function] callback.
    The [Function] callback is called for each item (argument).
    The callback parameters: {0: argument, 1: argumentsIndex, 2: itemIndex, 3: rejectMap}
    Usage: rejectMap.forAll((argument, argumentsIndex, itemIndex, rejectMap) => { } );

Chained functions

• Each list function is called with the following arguments passed:
  • [0] resolve callback function
  • [1] reject callback function
  • [2] config.context object (or value)
  • [3], [4], etc... (for moveOn method only) The arguments passed by the previous list function
• Both resolve and reject can be called with any number of arguments
• When the resolve is called with arguments, these arguments will be passed:
  • moveOn: for the further list function (or for the done function, when the last list function resolves)
  • moveOn.first: for the done function
  • moveOn.all, moveOn.each: for the done function in the resolveMap object
• When the reject is called with arguments, these arguments will be passed:
  • moveOn, moveOn.all, moveOn.each: for the catch function
  • moveOn.first: for the catch function in the rejectMap object

function fetchData(resolve, reject, context){
  this.someAsyncAjaxHere((err, data) => {
    if(err) return reject(new Error('Could not read the data.'));
    this.data = data;
    return resolve();
  });
}

Multiple resolve | reject calls

• keep in mind that both resolve and reject do not end function execution. In order to end function execution, use return resolve(); or return reject();
• the moveOn.all, moveOn.each and moveOn.first methods expect the list functions to call resolve or reject once
• the moveOn method, as it calls the list functions sequentially, accepts the multiple resolve and reject calls:
  • when the list function calls the resolve twice, it runs the further list functions twice (the forks are created); the resolve can be called eg. with different arguments
  • when the list function calls the reject twice, it calls the catch twice; the reject can be called eg. with different [Error] objects
  • when the list function calls both resolve and reject, it both runs the further list functions and calls the catch

inner move-on module

• the list function can also contain the inner move-on module execution, that has the done argument set to the resolve callback of this list function