utils-try-function v1.0.0

Try Function

Wraps a function in a try/catch block.

Installation

$ npm install utils-try-function

Usage

var wrap = require( 'utils-try-function' );

wrap( fcn )

Wraps a function in a try/catch block.

function fcn() {
	throw new Error( 'beep boop' );
}

var f = wrap( fcn );

var out = f();
if ( out instanceof Error ) {
	console.error( out.message );
	// returns 'beep boop'
}

The returned function has the same signature as the wrapped function.

function fcn( a, b, c, d ) {
	var sum = a + b + c + d;
	if ( sum < 10 ) {
		throw new Error( 'invalid input arguments. Arguments must sum to a number greater than or equal to 10.' );
	}
	return sum;
}

var f = wrap( fcn );

var out = f( 5, 6, 7, 8 );
// returns 26

out = f( 1, 2, 3, 1 );
// returns <Error>

If provided an asynchronous function, the returned function only traps errors which occur during the current event loop tick.

function fcn( a, b, clbk ) {
	if ( !a ) {
		throw new Error( 'invalid input argument.' );
	}
	process.nextTick( onTick );
	function onTick() {
		if ( !b ) {
			throw new Error( 'invalid input argument.' );
		}
		clbk();
	}
}

function done() {
	console.log( 'beep' );
}

var f = wrap( fcn );

var out = f( null, 5, done );
// returns <Error>

out = f( true, null, done );
// returns undefined

Notes

• Isolating try/catch blocks as separate wrapped functions prevents a parent scope from permanently entering optimization hell.

Examples

var isString = require( 'validate.io-string-primitive' ),
	wrap = require( 'utils-try-function' );

function beep( str ) {
	if ( !isString( str ) ) {
		throw new TypeError( 'invalid input argument. Must provide a string primitive. Value: `' + str + '`.' );
	}
	return 'beep' + str;
}

function boop( str, clbk ) {
	if ( !isString( str ) ) {
		throw new TypeError( 'invalid input argument. Must provide a string primitive. Value: `' + str + '`.' );
	}
	setTimeout( done, 1000 );

	function done() {
		if ( str !== 'beep' ) {
			throw new Error( 'invalid input argument. String must equal `beep`. Value: `' + str + '`.' );
		}
		clbk( str + ' boop' );
	}
}

function done( str ) {
	if ( str !== 'beep boop' ) {
		throw new Error( 'huh?' );
	}
}

var out, f;

// Synchronous...
f = wrap( beep );

out = f( 'boop' );
// returns 'beep boop'

out = f( null );
// returns <Error>


// Asynchronous...
f = wrap( boop );

out = f( 'beep', done );
// returns undefined

out = f( 'foo', done );
// returns undefined and then throws

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

$ 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.