Express Handler #

This node modules is designed for express.js. It can create a per-request this object for all express route handlers. With this this object, handlers can access req, res and next in any async function without closure or extra arguments.

Install ##

Install this module through npm.

npm install --save express-handler

Usage ##

This node module provide a function to wrap route handler. Here is a typical way to use it.

``javascript
var fs = require('fs');
var express = require('express');
var handler = require('express-handler');
var app = express();

// Wrap a handler to provide this object.
app.get('/foo', handler(foo));
app.post('/bar', handler(bar));

// There is no need to list req, res and next in handler signature.
// All these arguments can be retrieved from this object.
function foo() {
// Get req, res and next.
var req = this.req;
var res = this.res;
var next = this.next;

// this object is unique for one request.
// Set any value on this to share it.
this.myErrorCode = 500;

// Bind current this object with an async function.
fs.readFile('foo', this.wrap(readFoo));
}

function readFoo(err, data) {
// Get res in async function through this.
var res = this.res;

if (err) {
// Use shared value.
res.status(this.myErrorCode);
return;
}

res.send(data);
}

// Still want to use req and res as arguments?
// No problem. All arguments are forwarded from express to handler.
// So no need to modify existing handler code for express-handler.
function bar(req, res) {
// The old way to write a handler...
}
`

Extra features ##

This node module provides some extra features for special needs. All features are disabled by default.

Features can be enabled/disabled globally or per handler basis. handler.set is to update global feature status. The feature argument in handler is to set per handler features which will override global feature status.

`javascript
var handler = require('express-handler');

// Enable trace feature.
handler.set('trace', true);

// Disable trace feature only in this handler.
app.get('/foo', handler(foo, {trace: false}));
`

Following are all available features.

* trace: Trace all async calls' stack. It's useful when debugging in async function callback.
* globalize: Current running handler can be retrieved by handler.current anywhere.

$3

Call stack in async function callback is not very meaningful. There is no way to find out which function initiate the async call inside the callback.

trace feature is designed to address the problem. With this feature, Handler#stack method can return current call stack plus stack of the function initiating the async call.

`javascript
// Enable "trace".
handler.set('trace', true);
app.get('/foo', handler())

function foo() {
setTimeout(this.wrap(function() {
console.log('Stack:\n%s', this.stack().join('\n'));
// Will output something like following:
//
// Stack:
// at Handler. (/path/to/your/app.js:22:21)
// at null._onTimeout (/path/to/node_modules/express-handler/lib/handler.js:70:19)
// at Timer.listOnTimeout [as ontimeout] (timers.js:112:15)
//
// at Handler.foo (/path/to/your/app.js:21:19)
// at /path/to/node_modules/express-handler/index.js:50:15
// at Layer.handle [as handle_request] (/path/to/node_modules/express/lib/router/layer.js:82:5)
// at next (/path/to/node_modules/express/lib/router/route.js:100:13)
// at Route.dispatch (/path/to/node_modules/express/lib/router/route.js:81:3)
// at Layer.handle [as handle_request] (/path/to/node_modules/express/lib/router/layer.js:82:5)
// at /path/to/node_modules/express/lib/router/index.js:235:24
// at Function.proto.process_params (/path/to/node_modules/express/lib/router/index.js:313:12)
// at /path/to/node_modules/eexpress/lib/router/index.js:229:12
}), 100);
}
`

$3

With this feature, current running handler can be retrieved by handler.current. It makes current handler globally available anywhere in code like a global variable.

If this feature is disabled or there is no handler running, handler.current will return null.

`javascript
// ENable "globalize".
handler.set('globalize', true);
app.get('/foo', handler(foo));

function foo() {
doSomething();
}

function doSomething() {
// Get current running handler.
var h = handler.current();
// ...
}
`

Extend handler object ##

handler.Handler is the constructor of handler's this object. Use Handler.extend to add new methods to this object.

Method init is a special case. If it exists in prototype, Handler will call it in constructor.

`javascript
var handler = require('express-handler');
var Handler = handler.Handler;

Handler.extend({
f: function() {
// ...
}
});

app.get('/foo', handler(foo));

function foo() {
this.f();
};
``

License ##

This module is licensed under the MIT license that can be found in the LICENSE file.