try-catch-finally
v2.0.2
Published
[![Travis CI](https://img.shields.io/travis/c24w/try-catch-finally.js.svg?style=flat-square)](https://travis-ci.org/c24w/try-catch-finally.js 'Build') [![Coveralls](https://img.shields.io/coveralls/c24w/try-catch-finally.js.svg?style=flat-square)](https:/
Downloads
54
Readme
try-catch-finally.js
Installation
Browser
<script src="try-catch-finally.js"></script>
console.log(typeof window.try) // -> function
console.log(typeof window._try) // -> function
AMD
define(['try-catch-finally'], function (_try) {
console.log(typeof _try); // -> function
});
Node
npm install --save try-catch-finally
var _try = require('try-catch-finally');
console.log(typeof _try); // -> function
Usage
API
_try ( tryBlock )
- tryBlock
<function>
- code which may throw errors
.catch ( [ error, ] handleError )
- error
<any>
- (optional) error to catch - handleError
<function>
- handle errors which correspond to error (if defined); else handle any error
.finally ( finallyBlock )
- finallyBlock
<function>
- code which will always exectue
Examples
Catch anything
_try(function () {
throw new Eroror('boom');
})
.catch(function (e) {
console.log('Caught', e);
});
Error value matches by strict equality (===
).
Catch-by-value
_try(function () {
throw 12345;
})
.catch(12345, function (e) {
console.log('Caught', e);
});
Error value matches by strict equality (===
).
Catch-by-name
_try(function () {
throw { error: 'boom' };
})
.catch('object', function (e) {
console.log('Caught', e);
});
Error name matches similarly to typeof
, with the bonus that it:
- is case-insensitive
- works for boxed primitives (e.g.
new String()
)
Catch-by-type
_try(function () {
throw 'boom';
})
.catch(Object, function (e) {
console.log('Caught', e);
});
_try(function () {
throw new TypeError('boom');
})
.catch(Error, function (e) {
console.log('Caught', e);
});
Error type matches similarly to instanceof
, with the bonus that it works for literal primitives ('hello'
, 123
, etc).
Warnings
Catch-by-name may not work
It's not always possible to get the name of an object in JavaScript, such as for objects created using non-native constructors:
function CustomError() {}
_try(function () {
throw new CustomError();
})
.catch('CustomError', function (e) {
console.log('Caught CustomError: ' + e);
});
Or for some native objects which use inheritance:
_try(function () {
throw new TypeError();
})
.catch('TypeError', function (e) {
console.log('Caught TypeError: ' + e);
});
Those catch blocks won't execute. The best this library can do is find out that:
- the
new CustomError()
is some kind ofobject
, but not specifically aCustomError
by name - the
new TypeError()
is some kind ofError
, but not specifically aTypeError
by name
It's best to use the catch-by-type style in those cases.
Catch-by-type won't work across frames/processes
This quirk exists in the native instanceof
, which fails across browser frames and node processes when the instance's constructor is different one passed to instanceof
. It's best to use the catch-by-name in those cases.
Errors are consumed
Any error thrown synchronously in the try block is consumed by this library. There are two ways to ensure errors which aren't caught/handled by any catch
don't disappear:
Use an indiscriminate catch block
_try(function () {
throw new Error('boom');
})
.catch(String, function (e) {
// Catch doesn't apply
})
.catch(function (e) {
// Handle all other errors
});
Use a finally block
This will cause any unhandled error to be re-thrown:
_try(function () {
throw new Error('boom');
})
.catch(String, function (e) {
// Catch doesn't apply
})
.finally(function () {
// Error is re-thrown after finally block
});