843 byte library for more flexible error catching in JavaScript.

• Installation
  • Browser
  • AMD
  • Node
• Usage
  • API
  • Examples
• Caveats
  • Catch-by-name may not work
  • Catch-by-type won't work across frames/processes
  • Errors are consumed
• Tests

<script src="try-catch-finally.js"></script>

console.log(typeof window.try) // -> function
console.log(typeof window._try) // -> function

define(['try-catch-finally'], function (_try) {
  console.log(typeof _try); // -> function
});

npm install --save try-catch-finally

var _try = require('try-catch-finally');
console.log(typeof _try); // -> function

• tryBlock <function> - code which may throw errors

• error <any> - (optional) error to catch
• handleError <function> - handle errors which correspond to error (if defined); else handle any error

• finallyBlock <function> - code which will always exectue

_try(function () {
  throw new Error('boom');
})
.catch(function (e) {
  console.log('Caught', e);
});

_try(function () {
  throw 12345;
})
.catch(12345, function (e) {
  console.log('Caught', e);
});

Error value matches by strict equality (===).

_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())

_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).

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', e);
});

Or for some native objects which use inheritance:

_try(function () {
  throw new TypeError();
})
.catch('TypeError', function (e) {
  console.log('Caught', e);
});

Those catch blocks won't execute. The best this library can do is find out that:

• the new CustomError() is some kind of object, but not specifically a CustomError by name
• the new TypeError() is some kind of Error, but not specifically a TypeError by name

It's best to use the catch-by-type style in those cases.

This quirk exists in the native instanceof (which fails across browser frames and node processes) when the instance's constructor differs to the one passed to instanceof. It's best to use the catch-by-name in those cases.

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:

_try(function () {
  throw new Error('boom');
})
.catch(String, function (e) {
  console.log('Caught String', e);
})
.catch(function (e) {
  console.log('Caught other', e);
});

The first catch block won't execute and the second ensures other errors don't go unhandled.

_try(function () {
  throw new Error('boom');
})
.catch(String, function (e) {
  console.log('Caught', e);
})
.finally();

That catch block won't execute and the finally call ensures any caught error is re-thrown.

The following tests are continually run in TravisCI:

The tests can be run in any browsers supported by Karma. See the npm scripts and travis configuration for more details.