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 = 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.:

<script src="bower_components/forejs/dist/forejs.min.js"></script>

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:

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:

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:

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 "|":

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:

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:

fore(
    raisesError.inject.catch(error => /* handle error */)
);

or generally:

// 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:

fore(
    callback => callback(null, 1, 2, 3),
    (one, two, three, callback) => two === 2
);

In auto mode, those are condensed to an array (see why?):

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:

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:

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

Classes

Injector

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 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.

Injector

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.

Example

((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

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

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.

Kind: global function

Example

// 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.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

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

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

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.

Example

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

fore.config([properties])

Configures foreJs.

Kind: static method of fore

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.

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.