Home

Awesome

Middlewarify

Middleware pattern implementation, robust, easy, fast. You can add two types of middleware, a single queue type using the keyword use() or a Before/After type using before() and after() hooks.

Build Status

NPM

Install

npm install middlewarify --save

Documentation

Quick Start Example

Creating a middleware:

const middlewarify = require('middlewarify');

// this is the main callback of your middleware,
// it will be the last callback to be invoked.
function createTask(data) {
    console.log('createTask Final Fn to be invoked');
    return true;
}

const tasks = {};

// Make the'create' Middleware Container.
middlewarify.make(tasks, 'create', createTask);

module.exports = tasks;

...Add middleware

// ... somewhere far far away in another file

const tasks = require('./tasks');

// add middleware to the 'create' operation

tasks.create.use(function (data) {
    console.log('middleware 1');
    data.newAttr = 2;
});

// Add a second middleware to the 'create' operation
tasks.create.use(function (data) {
    console.log('middleware 2. Title:', data.title);
    data.secondAttr = 3;
});

... Invoke all the middleware

// ... Invoking them all together
const result = tasks.create(data);

// The middleware are invoked in sequence and output:
// "middleware 1"
// "middleware 2"
// "createTask Final Fn to be invoked"

console.log(result);
// prints: true

Middlewarify Methods

make(object, property, optMainCallback, optOptions)

The middlewarify.make() method will apply the middleware pattern to an Object's property, this property is the Middleware Container.

// create a Middleware Container
const crud = {};
middlewarify.make(crud, 'create');

This example has created the Middleware Container create in the object crud. crud.create() is a function that will invoke all the middleware.

You can pass a third argument, the optMainCallback, a Function. This will be the Main callback of your middleware, the result returned from that function will be the returning value of the Middleware Container:

const val = crud.create();
// val is passed from the Main callback.

optOptions defines behavior. Both optOptions and optMainCallback are optional. You can pass options as a third argument, read on for examples and what are the available options.

make() Options

make() accepts the following options:

The use(fn) Hook.

The Middleware Container by default exposes a use hook so you can add any number of middleware. use() accepts any number of parameters as long they are of type Function or Array of Functions. When the Before/After flag is enabled use is no longer available and instead you get before, after and last hooks. All hook types accept the same argument types and patterns as described bellow:

// create the Middleware Container
const crud = {};
middlewarify.make(crud, 'create', fnFinal);

// add 3 middleware functions
crud.create.use([fn1, fn2], fn3);

// then add another one
crud.create.use(fn4);

In the above example we added 4 middleware before the final method fnFinal will be invoked. A FIFO queue is implemented so the order of execution will be:

  1. fn1()
  2. fn2()
  3. fn3()
  4. fn4()
  5. fnFinal()

Middleware Arguments

All middleware get invoked with the arguments that the Middleware Container was invoked with. The same number or arguments, the exact same references:

app.connect.use(function (req) {
    req.a === 1; // true
    req.a++;
});
app.connect.use(function (req) {
    req.a === 2; // true
});

const req = { a: 1 };
app.connect(req);

Asynchronous Middleware Using Promises

When the option async: true is defined, all middleware get invoked asynchronously. You can return a Promise from your middleware and Middlewarify will wait for its resolution before passing control to the next one.

// create an async Middleware Container
const crud = {};
middlewarify.make(crud, 'create', fnFinal, { async: true });
crud.create.before(async () {
    await fs.read();
});

Invoking the Middleware

The Middleware Container is a function that accepts any number of arguments.

Any argument passed to the Middleware Container will also be passed to all middleware.

const crud = {};
middlewarify.make(crud, 'create');

// run all middleware
crud.create({ a: 1, b: 2 }, 'bar');

Arguments of all middleware will get:

crud.create.use(function (arg1, arg2) {
    arg1 === { a: 1, b: 2 }; // true

    arg2 === 'bar'; // true
});

Middleware Results and Error Handling

When invoked, the Middleware Container will return the execution outcome. To handle any errors thrown, you simply have to wrap it in a try catch block unless you have defined a catchAll error handler. In that case the catchAll error handler will intercept any and all errors.

try {
    const retVal = crud.create(arg1, arg2, fn1);
} catch (ex) {
    // handle the error...
    console.log('Error:', ex);
}

Using the Before / After / Last Middleware types

To use the Before/After/Last hook types all you need to do is pass the {beforeAfter: true} option to Middlewarify's make() method.

When using the beforeAfter option instead of the typical use() method three new hooks are created on the resulting Middleware Container:

All added hooks are invoked in the order they were added.

Before / After / Last Middleware Example

const middlewarify = require('middlewarify');

const tasks = (module.exports = {});

// This is the main callback of your middleware,
// it will be invoked after all 'before' middleware finish
// and before any 'after' middleware.
function createTask() {
    console.log('Invoked Second');
    return 999;
}

// Make the'create' Middleware Container using before/after hooks
middlewarify.make(tasks, 'create', createTask, { beforeAfter: true });

/** ... */

// add a before hook
tasks.create.before(function () {
    console.log('Invoked First');
});

// add an after hook
tasks.create.after(function () {
    console.log('Invoked Third');
});

// add an always LAST hook, will always invoke last
task.create.last(function () {
    console.log('Will always invoke last');
});

/** ... */

// invoke all middleware
tasks.create().then(
    function (val) {
        // at this point all middleware have finished.
        console.log(val); // 999
    },
    function (err) {
        // handle error
    },
);

After & Last Hooks get the Result as Argument

If your middleware if a Before / After type, then all .after() and .last() hooks will receive an extra argument representing the returned value of the main callback:

middlewarify.make(crud, 'create', function (arg1, arg2) {
    return 'abc';
});

crud.create.after(function (arg1, arg2, val) {
    console.log(val); // prints 'abc'
});

crud.create(1, 2);

After & Last Hooks can Alter the Middleware Container's Return Result

All After & Last hooks may alter the return result as long as they return any type of value except undefined:

middlewarify.make(crud, 'create', function () {
    return 'abc';
});

crud.create.after(function (result) {
    // return an altered outcome
    return 'def';
});

crud.create().then(function (result) {
    console.log(result); // prints "def"
});

Using Concurrent Execution

Concurrent execution will use the Promise.allSettled() function and return its raw results. So expect an array of result objects containing the status and either value on success or reason on failure.

Release History

License

Copyright Thanos Polychronakis, licensed under the ISC License.