Description

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

Any bugs found? Give me to know on GitHub.

Usage

Node

Browsers

Add the move-on.js library to the HTML file.
The library is located in ./dist/move-on.js directory.
It is a webpack&babel bundled cross-browser library version.
The library is accessible as moveOn variable in the global (window) scope.
```html ```

Tests

Simple sample

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.
See the samples: [sample] [sample] [sample] [sample] [sample] [sample] [sample]

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.
See the samples: [sample]

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.
See the samples: [sample]

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.
See the samples: [sample]

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]
• Samples: [sample] [sample] [sample] [sample] [sample] [sample] [sample]

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]
• Samples: [sample]

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 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]
• Samples: [sample]

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]
• Samples: [sample]

Arguments

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

list [Array: function | array]

• [Function] items [see below] [sample] [sample] [sample] [sample]
  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] [sample]
  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])
• Samples: [sample] [sample] [sample] [sample]

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] item 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's 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's functions still have the access to the config.context parameter
• the list can still contain the [Function] items next to this [Array] item

3. [Array: string] items for methods

• 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
• Samples: [sample]

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 [sample] [sample] [sample]
• any error is thrown when any config property is defined incorrectly (the default value is used instead)

config.timeout

• 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 resolves s and reject s 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
• Samples: [sample] [sample]

Timeout error

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

config.context

• 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
• Samples: [sample] [sample] [sample]

config.passContext

• 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
• Samples: [sample] [sample]

config.bind

• 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]

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) => {} );
• Samples: [sample] [sample]

catch( context ) [Function]

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 [sample] [sample] [sample] [sample]
• 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

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
• Samples: [sample] [sample]

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
• Samples: [sample] [sample]

Code examples

1. The move-on chain of synchronous and asynchronous functions

2. The move-on module with the user config.context and the arguments passed through the resolve and reject arrow callback functions

3. The move-on module that rejects

Mind that the second rejected function ends up the execution of further chained functions.

4. The move-on instructions after resolve call

In order to end up the chained function's execution, call return resolve();

5. The inner move-on module and multiple resolve and reject calls

Mind how X, Y and Z functions of the inner module execute between A, B and C chained functions.
Mind how the B and C chained functions are executed twice, by double resolve call in A chained function.

6. The move-on.all chain

It calls done callback function right after all chained functions are resolved.
The user's shorter config.timeout is set.
The reject callback functions are not used. In case of error, the catch callback function will still be called with config.timeout error.
All retrieved data is passed through the resolve callback and accessible in the ResolveMap done callback function.

7. The move-on.each inner module

The move-on is used to get the files list asynchronously and then to copy all files asynchronously.
The inner move-on.each module is injected in the second chained function in order to report the success | failure message for each copied file.
Each copying failure occurrence calls reject callback and logs the warning.
When all files are (un)successfully copied, the done callback function is called, that indicates the end of files copying action.

8. The move-on.first module

It sends the request for the three urls and waits for the first (fastest) response.

9. The chain of class instance's methods

The config.context is set to the class instance's this reference, thus the chained methods still have the access to all instance's properties and methods.

10. The email validation sample

Mind that chained functions are passed as [String] methods' names to retain the access to the this reference to the class instance.
The done and catch calls the same callback function. The reject is used to terminate the further chained functions and the resolve to continue execution. Mind that isString and isAvailable methods call reject to stop the module execution.
The [Array] errorMessages stores all validation error messages, that will be printed out for the user.
The isAvailable chained function is asynchronous and simulates the request sent to the server to check whether the email address is available.