foreJs
ForeJs is a lightweight but powerful module which provides rich functionality to organize asynchronous JavaScript code. Linearize nested callback functions to simple call chains or let foreJs automatically resolve dependencies between the single functions and figure out the perfect execution order. Asynchronously process iterables and collect the modified values later again.
ForeJs uses a syntax similar to async's waterfall
or auto
function. This
syntax is extended by additional features like flexible value injections while at the same time offering similar or even
better performance.
It is written in pure ECMAScript 5 and thus runs on older node versions or the browser.
Nonetheless modern features like promises, generators and Symbol.iterator
are supported.
Usage
const fore = ; ;
See below for documentation and more examples.
Installation
$ npm install --save forejs
For browser usage
$ bower install forejs
Load via script-tags, RequireJs (amd) or CommonJs, e.g.:
Examples
Chain mode
ForeJs provides two different run modes: "chain" and "auto". Chain mode executes the functions one by one, auto mode allows a more complex structure (directed acyclic graphs). The example in the Usage paragraph shows the auto mode, so here is a chain mode sample:
;
Injections
Sometimes it is necessary to provide constant values to functions in addition to the values provided by previous functions:
const fs = ;const ref = foreref; ;
It is also possible to inject values or dependencies as this
argument:
someFunctioninject;
Or-injections
Sometimes it is convenient to merge several execution branches into a single variable. This can be done via so called "or-injections". Simply put all dependencies into one injection separated by "|":
;
More syntax sugar
Occasionally you want to chain some function calls in auto mode without giving each result a separate name. You can do this using an array:
;
Catching errors
Errors can be caught either directly at a single function:
;
or generally:
// don't forget the ".try"fore;
Multiple return values
Some functions like fs.read
pass multiple values to the callback. In chain mode those are simply passed to the
subsequent function:
;
In auto mode, those are condensed to an array (see why?):
;
Iteration
The most powerful feature of foreJs is to asynchronously process iterables:
const each = foreeach;const collect = forecollect;;
Merge multiple iterables into one:
const each = foreeach;const reduce = forereduce;;
For more examples take a look at the build and test files.
Documentation
Classes
Functions
- fore(functions, arguments)
The main entry point. Supports two modes:
- chain: In chain mode,
fore
accepts a list of functions that are executed sequentially. - auto: In auto mode,
fore
accepts an object with identifiers as keys and functions as values. The identifiers can be referenced by other functions to retrieve its "return value" (see inject and ref). ForeJs now figures out the perfect execution order and runs as much code in parallel as possible.
The functions passed may have one of the following forms:
- Node-style asynchronous function: Accepts a number of arbitrary arguments followed by an error-first callback function. The function must call this callback with either a non-null first argument to signal an error or with null as first argument followed by any number of "return values". In chain mode those "return values" are directly passed on to the next function. In auto mode those values are passed to all dependent functions. If more than one value is passed to the callback, those values are passed as array to the dependents. Additionally all arguments but the last (callback) must be eliminated by injections (inject).
- Synchronous function: Sometimes you want to mix synchronous functions into asynchronous code. This is perfectly
ok: Simply put a plain
return
statement and ignore the callback. If you want to returnundefined
on purpose you will need to invoke the callback, however. - Promise: Promises are supported as well. Plain promises must be in a root position.
- Promise returning function: A function may as well return a promise instead of invoking the callback. Unfortunately, the function will still get passed a callback as last argument. If your function cannot cope with the extra argument, simply wrap it with another function.
- Array: As shown in Injector.prototype.args injections can be syntactically sugared. If you are looking for a way to iterate over arrays see each.
- Instances of Injector: An Injector is simply the wrapping type of injected functions.
- chain: In chain mode,
- inject() ⇒
Injector
Starts the injection of values or dependencies into this function. Should be followed by one of the Injector methods. Use
inject
to avoid function wrappers or things like Function.prototype.bind.
Injector
Kind: global class
Injector
injector.args(arguments) ⇒ Injects constant values or dependencies into this function starting from the left. Use ref to inject
dependencies in auto mode. If no string constants need to be injected, inject.args(...)
can also be
written using a shorter array notation, which is especially handy for anonymous functions:
Kind: instance method of Injector
Chainable
Returns: Injector
- this
.
Param | Type | Description |
---|---|---|
arguments | Injection | * |
The list of injections. |
Example
...inject// shorter:"arg1" "arg2" ...
Injector
injector.this(object) ⇒ Injects a constant value or dependency as this
argument. Use ref to inject dependencies in
auto mode. In chain mode, call this function without arguments in order to retrieve the "return value" of the previous
function as this
argument instead of as first argument. If the previous function "returns" multiple values
only the first one will be passed, the others are ignored.
Kind: instance method of Injector
Chainable
Returns: Injector
- this
Param | Type | Description |
---|---|---|
object | Injection | Object |
The injection. |
Injector
injector.catch(errorHandler) ⇒ Attaches an error handler to this function that will be called if the function invokes its callback with a non-null first argument. This error will be passed as first argument to the errorHandler. Once an error occurs, the propagation of this execution branch will be stopped.
It is also possible to register a general error handler to the entire fore-block using try. Error handlers attached directly to the function are prioritized.
If an error occurs and no error handler has been registered the execution will break. So catch your errors!
Kind: instance method of Injector
Chainable
Returns: Injector
- this
Param | Type | Description |
---|---|---|
errorHandler | function |
The error handler, a function which accepts one argument. |
fore(functions, arguments)
The main entry point. Supports two modes:
- chain: In chain mode,
fore
accepts a list of functions that are executed sequentially. - auto: In auto mode,
fore
accepts an object with identifiers as keys and functions as values. The identifiers can be referenced by other functions to retrieve its "return value" (see inject and ref). ForeJs now figures out the perfect execution order and runs as much code in parallel as possible.
The functions passed may have one of the following forms:
- Node-style asynchronous function: Accepts a number of arbitrary arguments followed by an error-first callback function. The function must call this callback with either a non-null first argument to signal an error or with null as first argument followed by any number of "return values". In chain mode those "return values" are directly passed on to the next function. In auto mode those values are passed to all dependent functions. If more than one value is passed to the callback, those values are passed as array to the dependents. Additionally all arguments but the last (callback) must be eliminated by injections (inject).
- Synchronous function: Sometimes you want to mix synchronous functions into asynchronous code. This is perfectly
ok: Simply put a plain
return
statement and ignore the callback. If you want to returnundefined
on purpose you will need to invoke the callback, however. - Promise: Promises are supported as well. Plain promises must be in a root position.
- Promise returning function: A function may as well return a promise instead of invoking the callback. Unfortunately, the function will still get passed a callback as last argument. If your function cannot cope with the extra argument, simply wrap it with another function.
- Array: As shown in Injector.prototype.args injections can be syntactically sugared. If you are looking for a way to iterate over arrays see each.
- Instances of Injector: An Injector is simply the wrapping type of injected functions.
Kind: global function
Param | Type | Description |
---|---|---|
functions | Object.<String, (function()|Array|Injector|Promise)> |
For auto mode: an object hash with ids as keys and functions as values. |
arguments | function | Array | Injector | Promise |
For chain mode: a list of functions. |
Example
// chain mode:;// auto mode:;
Object
fore.try() ⇒ Wraps fore with a try-catch mechanism, which registers a general error handler for all provided functions. Once any of these functions "returns" an error this error handler will be invoked and the propagation of the respective execution branch will be stopped.
This error handler can be shadowed for single functions using Injector.prototype.catch.
Kind: static method of fore
Returns: Object
- An object with a single function catch
to pass the error handler to.
Example
fore
Injector
fore.each(iterable) ⇒ Successively returns all values the iterable provides. Values will be processed in parallel.
Kind: static method of fore
Returns: Injector
- An injector which can be used to inject arguments to the iterable in case it is a generator
function (function*
).
See
- fore.collect
- fore.reduce
Param | Type | Description |
---|---|---|
iterable | Array | Iterator | Iterable | function | Injector |
One of the following:
fore.each to be in a root position (they don't depend on other functions). The last case is allowed in any position. Any iterable type may also provide promises as values in order to asynchronously generate values. Values generated by fore.each will be propagated through subsequent functions causing them to be called multiple times. If a function has several dependencies (in auto mode) that originate in a fore.each , it will be invoked with any possible combinations of the incoming values. |
Injector
fore.collect(fn) ⇒ The counterpart to each. Collects all values that were generated by each and modified by
in-between functions. The results will be passed on to fn
as array. If it depends on multiple iterables
fore.collect
waits for all branches to finish and each result array will be passed on as separate argument.
Naturally for asynchronous code the result array will not necessarily have the same order as the input.
Kind: static method of fore
Returns: Injector
- An injector which can be used to inject arguments to the function.
See: fore.reduce
Param | Type |
---|---|
fn | function | Injector | Array.<*> |
Injector
fore.reduce(fn, initialValue) ⇒ Another counterpart to each. Behaves much like collect but provides the results not as array
but in a fashion similar to Array.prototype.reduce: fn
will be called once for each element of
the result. It will receive the accumulator followed by injections followed by a callback
(accumulator, injections, ..., callback)
. The "return value" of this call will be the new accumulator
for the next invocation. For the first invocation the accumulation variable is initialValue
.
If there is more than one dependency (and several of these originate in a each) fn
will
be called once for every possible combination of the incoming values.
Likewise, no specific execution order can be guaranteed.
Kind: static method of fore
Returns: Injector
- An injector which can be used to inject arguments to the function.
Param | Type | Description |
---|---|---|
fn | function | Injector | Array.<*> |
The function which will be invoked with (accumulator, value, ..., callback) |
initialValue | * |
The value for the accumulator during the first invocation. |
Example
fore.ref(id)
References the result of another function when using auto mode. To be used within Injector.prototype.args or Injector.prototype.this
Kind: static method of fore
Param | Type | Description |
---|---|---|
id | String |
The id to reference. |
fore.config([properties])
Configures foreJs.
Kind: static method of fore
Param | Type | Description |
---|---|---|
[properties] | object |
The configuration object. |
[properties.dontHackFunctionPrototype] | boolean |
Set true to keep Function.prototype clean and omit the inject getter. inject now exists as static property of fore instead: fore.inject(myFunction).args(...) . Default: false |
Injector
inject() ⇒ Starts the injection of values or dependencies into this function. Should be followed by one of the Injector
methods. Use inject
to avoid function wrappers or things like Function.prototype.bind.
Kind: global function
Returns: Injector
- The injector.
License
Copyright (c) 2017 Lukas Hollaender
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.