time-to-botec/js/node_modules/@stdlib/utils/try-function/README.md

Try Function

Wrap a function in a try/catch block.

Usage

var wrap = require( '@stdlib/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 );
    // => '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 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 argument.' );
    }
    setTimeout( onTimeout, 0 );
    function onTimeout() {
        if ( !b ) {
            throw new Error( 'invalid 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.
• If a function throws a literal, the literal is serialized as a string and returned as an Error object.

Examples

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

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

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

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

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

var out;
var f;

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

out = f( 'boop' );
console.log( out );
// => 'beep boop'

out = f( null );
console.log( out.message );
// => '...'

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

out = f( 'beep', done );
console.log( out );
// => undefined

out = f( 'foo', done );
console.log( out );
// => undefined