bex

bex

Express.js application bootstrapper. Simplicity, brevity, flexibility.

Installation

npm i bex --save

Example

app.js

var config = require('./config').web;
var ong = require('ong').init();

require('bex').createApp({
	basedir: __dirname,
	bodyParser: { limit: '1mb' },
	viewEngine: require('express-dot').__express,
	hooks: { after: initialize }
}).listen(config.port);

function initialize (app) {
	ong.register('db', require('knex')(config.db));
	ong.register(this.requireAll(__dirname + '/modules'));
}

controllers/items.js

module.exports = {

	create: _.flow($.sanitize, $.validate, $.authorize, function (params) {
		return $.db('items').insert(params).then(this.json);
	}),

	'&/:id/render': function (params) {
		return Promise
			.props({ item: $.db('items').where('id', params.id).first() })
			.then(_.partial(this.view, 'items/index'));
	},

	'PUT items/:id/star': _.flow($.authorize, function (params) {
		return $.db('items').where('id', params.id).update('is_starred', 1).then(this.json);
	})

};

Quick notes (on example)

As you probably noted, there are 2 ways of specifying the route-handler pair:

• implicit: via method names like list (GET resource), view (GET resource/:id), create (POST resource), update (PUT resource/:id) and remove (DELETE resource/:id)
• explicit: by specifying exact route (GET resource/:from/:to) or exact route with resource name placeholder (GET &/:id) where kebab-cased controller's name will be substituted

In case of explicit route, you can omit GET verb, it is being used by default (&/:id is the same as GET &/:id or get &/:id).

What does it do?

• creates express.js app
• calls hook (before), if it is passed via hooks param
• sets 'trust proxy' to true (very often node.js app is hosted behind nginx)
• initializes view-related stuff, can be omitted by specifying views: false
• initializes body-parser (almost every express.js-based project needs this)
• creates router based on controllers modules (see example), can be omitted, if no controllers param is passed
• calls hook (after), if it is passed via hooks param

Few words about route handling

• it is expected, that route handler returns view result (or promise with view result): return this.json({ my: 'data' });
• there are 3 built-it view results: view(name, data) (ends with rendering of name view with data), redirect(url) and json(data)
• you can register your own result, which will be available via this inside route handler: bex.registerResult('myresult', function (anyarg) { return { type: 'myresult', arg: anyarg }; }); - minimal requirement for result constructor is to return result object with mandatory type property
• you can register your own result handler, which will be called once result of given type is obtained from any of your route handlers: bex.registerHandler('myresult', function (req, res, result) { res.send(result.anyarg); });

There are 2 special results

• exception - generated when exception occurs inside route handler (default handler will cause empty response with 500 code)
• undefined - generated when no view result is returned from route handler (its default handler will cause empty response with 404 status)

You can override how bex reacts to these 2 special results (as well as other "ordinary" results) via overwriting their handlers: bex.registerHandler('exception', function (req, res, exception) { logstash.send(req.url, exception); }, true);.

Few words regarding hooks

• there are 2 hooks: before (called just after express.js app is created, but nothing was performed with it) and after (called after everything is done and bex is ready to return bootstrapped app)
• each hook will have this populated with utility methods: requireAll, registerResult, registerHandler, createRouter

Utility methods

requireAll(path)

Requires all modules which exist inside specified folder (see require-all docs for details).

regiserResult(name, value, [overwrite]) or registerResult(nameValueObject, [overwrite])

Registers view result(s).

regiserResult(name, value, [overwrite]) or registerResult(nameValueObject, [overwrite])

Registers view result handler(s).

createRouter(path)

Loads everything from specified path and maps converts to route-handler pairs, applying them to express.Router. Returns express.Router instance ready to be used by express.js app. Also accepts object as argument, each property-value of which will be treated as controllerName-controllerInstance pairs.

License

MIT