mercy

Mercy

Flow control library focused on readability, convenience & analytics.

Table of Contents

• Mercy
  • Table of Contents
  • Introduction
  • API
  • Usage
  • Examples
    • Building basic flows
  • Test case usage

Introduction

Tired of...

• Entering into a new code base with no information? unknown execution paths?
• Juggling asynchronous operations with flow control optimization?
• Building a mock server because your upstream is often unstable or offline?

What if there exists a way to...

• Allow you to create a simple structure that clearly describes your application and/or business logic lifecycle?
• Promote sharing by offering deferred execution for all constructed flows?
• Automatically instrument analytics for all execution paths?

This is Mercy; A hybrid API between Async and Joi

API

See the detailed API Reference.

Usage

Usage is a two steps process. First, a flow must be constructed:

const echo = function (value, next) { return next(null, value); };

const flow1 = Mercy.flow(echo)              // series   - Rest () notation
const flow2 = Mercy.flow([echo]);           // series   - Array [] notation
const flow3 = Mercy.flow({ task_0: echo }); // parallel - Object {} notation
const flow4 = Mercy.flow({                 // auto (dependencies get injected via `...spread` operator)
    echo: echo,
    echoAgain: ['foo', echo]
});

Note that mercy flow objects are immutable which means every additional rule added (e.g. .timeout(1000)) will return a new flow object.

Then the flow is executed:

Mercy.execute(flow, (err, meta, data, next) => {

    // Your bits here
});

// Mercy Flows can directly call `flow.execute(data, callback)`.

flow.execute((err, meta, data, next) => {

    // Your bits here
});

When passing a non-type flow object, the module converts it internally to a flow() type equivalent:

// The following is equivalent
const foo = (data, next) => { return next(null, data) };
const callback = (err, meta, data, result) => {

    console.log(result);    // result is [data object]
};

const flow1 = { foo };
const flow2 = Mercy.flow({ foo });

Mercy.execute(flow1, callback);
Mercy.execute(flow2, callback);

Examples

Building basic flows

const Mercy = require('mercy');

const noop = function (data, next) { return next(); };
const echo = function (value, next) { return next(null, value); };

Empty

const empty = Mercy.flow();

Series

// Series automatically propagates a flow's input/output to proceeding task
let series = Mercy.flow(echo);               // Rest () notation
let series = Mercy.flow([echo]);             // Array [] notation
let series = Mercy.flow({ echo }).series();  // Object {} notation

Mercy.execute('foobar', series, (err, meta, data, result) => {

    console.log(meta);      // returns [object] - Current flow meta data (timers / analytics)
    console.log(data);      // returns [object] - Flow data object. Contains all flow & subflow information
    console.log(result);    // returns 'foobar'
});

Parallel

// Parallel does not propagate flow's input.
// Similar to `auto()`, you must specify a `final()` task to select results.
const parallel = Mercy.flow({
    input: Mercy.input(),       // Pre-built convenience flow to get flow input attached to some key.
    echo: echo                  // Since input is not propagated, echo is executed with (data, next)
}).final((data, next) => {

    const result = [data.input.result, data.echo.result];
    return next(null, result);
});

Mercy.execute('foobar', parallel, (err, meta, data, result) => {

    console.log(result);    // returns ['foobar', [object]] - [object] is the data object
});

Auto

// Auto does not propagate input. However, it does make use of dependency injection.
// Similar to `parallel()`, you must specify a `final()` task to select results.
const auto = Mercy.flow({
    input: Mercy.input(),       // Pre-built convenience flow to get flow input attached to a key.
    echo: ['input', echo]       // Here we use dependency injection, echo is executed with (value, next) where (value === data.input.result)
}).final((data, next) => {

    const result = [data.input.result, data.echo.result];
    return next(null, result);
});

Mercy.execute('foobar', auto, (err, meta, data, result) => {

    console.log(result);    // returns ['foobar', 'foobar']
});

Test case usage

const Mercy = require('mercy');