utils-try-function

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.