Boot

Boot an application.

Installation

$ npm install app-boot

Usage

var bootable = require( 'app-boot' );

bootable( [...args] )

Returns a boot function. All provided arguments are passed to each registered phase.

var app = require( 'express' )();

var boot = bootable( app );

boot.phase( fcn[, thisArg] )

Registers a new boot phase. On boot, phases sequentially execute according to registration order.

function phase1( app, next ) {
	// ...do something...
	next();
}

function phase2( app, next ) {
	var err;
	// ...do something...
	if ( err ) {
		return next( err );
	}
	next();
}

boot.phase( phase1 ).phase( phase2 );

Each phase receives all boot arguments plus an additional callback to invoke after a phase is complete.

var logger = require( './logger.js' ),
	config = require( './config.js' );

function phase( app, config, logger, next ) {
	logger.info( 'Here!' );
	next();
}

boot = bootable( app, config, logger );
boot.phase( phase );

To specify the this context for a phase, provide a thisArg.

var ctx = {
	'beep': 'boop'
};

function phase( app, config, logger, next ) {
	console.log( this.beep );
	// returns 'boop'

	next();
}

boot = bootable( app, config, logger );
boot.phase( phase, ctx );

To mimic async-waterfall, provide a locals object upon creating a boot sequence.

function phase1( app, locals, next ) {
	locals.beep = 'boop';
	next();
}

function phase2( app, locals, next ) {
	console.log( locals.beep );
	// returns 'boop'

	next();
}

boot = bootable( app, {} );
boot.phase( phase1 ).phase( phase2 );

boot( clbk )

Boots an application and invokes a callback once all phases complete.

boot( done );

function done( error ) {
	if ( error ) {
		throw error;
	}
	console.log( 'Finished booting...' );
}

Calling any phase's next callback with an error argument will cause the boot sequence to abort.

function phase1( app, next ) {
	// ...do something...
	next( new Error( 'phase1 error' ) );
}

function phase2( app, next ) {
	// ...never reached...
	next();
}

function done( error ) {
	if ( error ) {
		console.log( error.message );
		// returns 'phase1 error'
	}
}

boot = bootable( app );
boot.phase( phase1 ).phase( phase2 );
boot( done );

See Also

• parallel-boot-phase
  • Creates a parallel boot phase when booting an application. Useful for when phase functions are independent; e.g., connecting to two mutually exclusive databases.
• series-boot-phase
  • Creates a series boot phase containing subphases when booting an application. Useful for phase abstraction; e.g., creating a higher-level middleware phase from several subphases (initial tasks, routes, error handling, etc).
• bootable
  • Whereas bootable binds an application to the phase this context, this module allows passing the application and any other parameters as arguments to each phase.
  • Rather than hang methods off (and thus mutate) the application, this module returns a function which wraps the application in a closure.
• express
  • This module employs a design pattern similar to Express' middleware pattern, but with a more general interface.

Examples

var express = require( 'express' ),
	debug = require( 'debug' )( 'app-boot:example' ),
	bootable = require( 'app-boot' );

var boot, app;

// Bind middleware to the application...
function mw( app, next ) {
	debug( 'Binding middleware...' );
	app.get( '/beep', onRequest );
	next();
	function onRequest( request, response, next ) {
		console.log( 'Request received...' );
		next();
	}
}

// Mock connecting to a db...
function db( app, next ) {
	debug( 'Connecting to a database...' );
	process.nextTick( onConnect );
	function onConnect() {
		app.db = {};
		next();
	}
}

// Mock creating a server and listening on a port...
function server( app, next ) {
	debug( 'Creating a server and listening for requests...' );
	process.nextTick( onListen );
	function onListen() {
		app.server = {};
		next();
	}
}

// Callback invoked after completing a boot sequence...
function onReady( error ) {
	if ( error ) {
		throw error;
	}
	debug( 'Boot sequence completed...' );
}

// Create an application:
app = express();

// Create a boot function:
boot = bootable( app );

// Register phases:
boot.phase( mw )
	.phase( db )
	.phase( server );

// Boot the application:
boot( onReady );

To run the example code from the top-level application directory,

$ DEBUG=* node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2015. Athan Reines.