expressjs-async-router

express-async-router

express-async-router is an Express Router wrapper which automatically manage Promise.

Getting Started

express-async-router works exactly as Express Router. If you're not family with Express Router API, please see Router documentation.

Installation

express-async-router can be installed using NPM:

$ npm install express-async-router --save

Usage

First import express-async-router in your project:

var AsyncRouter = require("express-async-router").AsyncRouter;

Then instanciate AsyncRouter:

var router = AsyncRouter();

You're ready to use AsyncRouter the same way as Express Router but without worrying about Promise.

router.get("/", function (req, res) {
    return myGetOperation()
        .then(myOtherOperation);
});
 
router.post("/:test", function (req, res) {
    return myParametrizedOperation(req.params.test)
        .then(myOtherOperation);
});
 
router.use(function (req, res) {
    return myMiddlewareOperation()
        .then(myOtherOperation);
});

Options

express-async-router works exactly as Express Router so it can take the same options plus some additionnals to manage how request is sent.

By default, express-async-router sends the Promise result by using res.send(result) if headers was not already sent. You can customize this behavior by passing sender option when creating AsyncRouter.

options.send

Type: boolean | Default: true

If set to false, AsyncRouter will never try to send Promise result.

options.sender

Type: (req, res, value) => Thenable | Default: function (req, res, value) { res.send(value); }

If set, it will override the default AsyncRouter sender function.

Examples:

var router = AsyncRouter({ send: false });

Or

var router = AsyncRouter({ sender: mySender });
 
function mySender(req, res, value) { 
    res.rend(value.template, value.data); 
}
 
router.get("/", function () {
    return myOperation().then(function (data) {
        return {
            template: "index",
            data: data
        };
    });
});

send

Promise handling

express-async-router automatically handles Promises when it can.

param(name: string, handler: (req, res, param) => Thenable)

A special Router.param override which automatically calls next function when returned Promise resolves. If returned Promise rejects, rejected Error is transfered to next function. If result is not a Promise, next function is immediatelly called.

Example:

router.param("test", function (req, res, param) {
    return getTestEntity(param)
        .then(function(entity) {
            req.test = entity;
        });
});

[method](name: string, handler: (req, res) => Thenable)

A Router[method] wrapper which automatically calls next function when returned Promise resolves. If returned Promise rejects, rejected Error is transfered to next function. If result is not a Promise, next function is immediatelly called.

Examples:

router.get("/", function () {
    return getTestEntities();
});
 
router.post("/:test", function (req) {
    return getTestEntity(req.params.test);
});

use(...handlers[]: (req, res) => Thenable)

use(name: string | RegExp | string[], ...handlers[]: (req, res) => Thenable)

A Router.use wrapper which automatically calls next function when returned Promise resolves. If returned Promise rejects, rejected Error is transfered to next function. If result is not a Promise, next function is immediatelly called.

NOTE: If you declare 3 arguments in your function, next will only be called when an error occured.

Examples:

router.use(function (req) {
    return validateToken(req.header("MyCustomToken"))
        .then(function (user) {
            req.user = user;
        });
});
 
router.use("/test", function (req) {
    return validateToken(req.header("MyCustomToken"))
        .then(function (user) {
            req.user = user;
        });
});
 
router.use(myCustomAuth, serveStatic(__dirname + "/public"), function (req) {
    return logToServer(req)
        .then(function () {
            console.log(req);
        });
});
 

use(...handlers[]: (err, req, res, next) => Thenable)

use(name: string | RegExp | string[], ...handlers[]: (err, req, res, next) => Thenable)

A Router.use wrapper for Error handling which automatically calls next function when returned Promise resolves. If returned Promise rejects, rejected Error is transfered to next function. If result is not a Promise, next function is immediatelly called.

WARNING: You must declare the 4 arguments to your function to be recognized as an Error handler. This is for compatibility with Native Middlewares.

Examples:

router.use(function (err, req, res, next) {
    return logError(err)
        .then(function () {
            console.error(err);
            res.send(500, "An error occured!");
        });
});
 
router.use("/test", function (err, req, res, next) {
    return logError(err)
        .then(function () {
            console.error(err);
            res.send(500, "An error occured!");
        });
});
 
router.use(function (err, req, res, next) {
    return logError(err)
        .then(function () {
            console.error(err);
            res.send(500, "An error occured!");
        });
});

Contribute

Install Global Dependencies

express-router-async needs some development dependencies:

• Grunt
• tsd

$ npm install -g grunt-cli tsd

Install Project dependencies

$ npm install

Build project

$ grunt