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

Functions

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.

| Param | Type | Description | | --- | --- | --- | | arguments | Injection | * | The list of injections. |

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

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

fore(functions, arguments)

The main entry point. Supports two modes:

The functions passed may have one of the following forms:

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

| 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

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() ⇒ 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.