A lightweight module which provides powerful functionality to organize asynchronous JavaScript code.
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
`js
const fore = require("forejs");
fore({
// provide result of "asyncFunction" as "asyncResult"
"asyncResult": asyncFunction,
// promises are supported as well
"promiseResult": promiseReturningFunction,
// inject results of the above functions and the constant value "42" into "anotherAsyncFunction"
"combinedResult": ["asyncResult", 42, "promiseResult", anotherAsyncFunction],
"_": ["combinedResult", combinedResult => {
// do something with combinedResult
}]
});
`
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.:
`html
`
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:
`js
fore(
// function that produces the value 1
one,
(one, callback) => {
setTimeout(() => callback(null, one + 1), 200);
},
// synchronous functions are supported:
two => two + 1,
// prints "3"
console.log
);
`
#### Injections
Sometimes it is necessary to provide constant values to functions in addition to the values provided by previous
functions:
`js
const fs = require("fs");
const ref = fore.ref;
fore({
file: fs.readFile.inject.args("some/file", "utf-8"),
// in auto mode, dependencies are injections, too
modified: modify.inject.args(ref("file")),
// it is possible to write these as array:
customized: ["modified", modified => {
// customize file
}],
write: fs.writeFile.inject.args("out/file", ref("customized"))
});
`
It is also possible to inject values or dependencies as `this` argument:
`js
someFunction.inject.this(ref("myObject"));
`
#### 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 "|":
`js
fore({
// two files, both should be objects providing an output path and the respective content:
// e.g. {outPath: "out/file1, data: "My content"}
file1: ...,
file2: ...,
// will be called twice: once for each file
out: ["file1|file2", (file, callback) => fs.writeFile(file.outPath, file.data, callback)]
});
`
#### 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:
`js
fore({
myPath: getMyPath,
// Read the file and call JSON.parse immediately after:
// The array consists of a list of injections followed by any number of functions. The injections
// are applied to the first function.
jsonObject: ["myPath", (myPath, callback) => fs.readFile(myPath, callback), data => JSON.parse(data)]
});
`
#### Catching errors
Errors can be caught either directly at a single function:
`js
fore(
raisesError.inject.catch(error => / handle error /)
);
`
or generally:
`js
// don't forget the ".try"
fore.try(
raisesError,
).catch(error => / handle error /);
`
#### 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:
`js
fore(
callback => callback(null, 1, 2, 3),
(one, two, three, callback) => two === 2
);
`
In auto mode, those are condensed to an array (see why?):
`js
fore({
oneTwoThree: callback => callback(null, 1, 2, 3),
abc: callback => callback(null, "a", "b", "c"),
_: ["oneTwoThree", "abc", (oneTwoThree, abc, callback) => oneTwoThree[1] === 2 && abc[2] === "c"]
});
`
#### Iteration
The most powerful feature of foreJs is to asynchronously process iterables:
`js
const each = fore.each;
const collect = fore.collect;
fore(
each([1, 2, 3]), // can be an array or any form of iterable
// call this function for any of the above values
n => n + 1,
// combine the results to an array again
collect(numbers => {
// numbers contains now (not necessarily in this order):
// [2, 3, 4]
})
);
`
Merge multiple iterables into one:
`js
const each = fore.each;
const reduce = fore.reduce;
fore({
ones: each([1, 2, 3]),
tens: each([10, 20, 30]),
// will be called for any combination of values:
combined: reduce(["ones", "tens", (array, ones, tens) => array.concat(ones + tens)], []),
_: ["combined", combined => {
// combined contains now those values (not necessarily in this order):
// [11, 12, 13, 21, 22, 23, 31, 32, 33]
}]
});
`
For more examples take a look at the build and test files.
Documentation
$3
$3
- 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 return
undefined 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.
- 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.
$3
Kind: global class * Injector
* .args(arguments) ⇒ Injector
* .this(object) ⇒ Injector
* .catch(errorHandler) ⇒ Injector
#### injector.args(arguments) ⇒ Injector
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
`js
((arg1, arg2) => ...).inject.args(fore.ref("arg1"), fore.ref("arg2"))
// shorter:
["arg1", "arg2", (arg1, arg2) => ...]
`
#### injector.this(object) ⇒ Injector
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.catch(errorHandler) ⇒ Injector
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. |
$3
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 return
undefined 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
js
// chain mode:
fore(
f1,
f2,
...
);
// auto mode:
fore({
a: fa,
b: fb,
c: ["a", "b", fc] // the results of fa and fb are injected into fc once they are ready
});
`* fore(functions, arguments)
* .try() ⇒ Object
* .each(iterable) ⇒ Injector
* .collect(fn) ⇒ Injector
* .reduce(fn, initialValue) ⇒ Injector
* .ref(id)
* [.config([properties])](#fore.config)
#### fore.try() ⇒ Object
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
js
fore.try(
// functions...
).catch(error => ...)
`
#### fore.each(iterable) ⇒ Injector
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:
- An array of arbitrary values. Use to run a sequence of functions for multiple values.
- An Iterator, i.e. an object providing a
next function which itself returns objects in the shape of {value: value|undefined, done: true|false|undefined}. - An Iterable, i.e. an object providing a
Symbol.iterator to retrieve an Iterator like above. - A generator function: A function which returns an Iterator (like ES6
function*s do}. If this function takes arguments make sure to take care of the respective injections.
The cases 1 - 3 require 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. |#### fore.collect(fn) ⇒ Injector
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.<\*> |
#### fore.reduce(fn, initialValue) ⇒ Injector
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
js
fore(
fore.each([1, 2, 3, 4]),
plusOne,
fore.reduce((accumulator, value, callback) => callback(null, accumulator * value), 1),
console.log
// result: 1 2 3 * 4 = 24
)
``#### 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 |
inject to avoid function wrappers or things like Function.prototype.bind.Kind: global function
Returns: Injector - The injector.
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.