Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Simple exception-catching function wrapper with a few extra exception classes.
branch: master

This branch is 6 commits behind brynbellomy:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
node_modules/async
README.md
package.json

README.md

guard.js

Synopsis (or, “Unnameable, unavoidable introductory preamble”)

The idea behind guard.js is to provide the simplest exception-catching/error-handling mechanism possible in an asynchronous environment.

Javascript allows errors and exceptions to be raised outside of the context in which they were defined. This can make try/catch structures unwieldy, depending on how you go about implementing them.

On the other hand, using promises/futures/continuations/&c. solely to try to centralize error handling <polite>can be overkill</polite>, depending on the code you’re working with. Also depending on the brain you’re working with.

So guard.js tries to mediate between the two solutions by providing a one-blade knife: guard().

var guard = require(‘guard’),
    guardFn = guard.guard

...

var reportersIWantToUse = [
  guard.consoleReporter(),
  guard.expressJSONReporter(res, 500)
]

var errback = guard.errback(reportersIWantToUse)

doSomethingAsync(guardFn(function(err, asyncFuncResult) {
  JSON.parse(“FQ DA PO-LICE”)
}, errback))

To sum up, all you have to do is:

  1. (optional) choose which reporters you want to use (a few are included, but you can easily define your own — see below) and...
  2. wrap your callbacks in guardFn(yourUnsafeCallback, errback)

That’s it. Really. And instead of using the errback machinery included in guard.js, you can be ornery and just define your own errbacks. Whatever. I don’t care. I have a life to live.

Defining custom reporters

This is also really easy. A reporter is just a function that takes err as a parameter. I guess it really doesn’t even have to do anything with it. That part is up to you. Something like this will do:

var redisClient = ...
...

var myRainbowColoredRedisReporter = function(redis) {
  return function(err) {
    redis.set(‘err-‘ + new Date.getTime(), err)
  }
}

var errback = guard.errback([myRainbowColoredRedisReporter(redisClient)])
guardFn(..., errback)

Built-in Exception class

guard.js defines an Exception class that extends the native Javascript Error constructor.

The only difference between Exception and Error is that Exception permits objects to be thrown as exceptions. Normally, when you try to throw { statusCode: 500, message: ‘Fail’ }, you’re left with the Hemingway of Error objects — one whose idea of descriptiveness extends only so far as [object Object].

So if you like, you can throw new guard.Exception({ statusCode: 666, message: “REDRUM”}) and, when your errback is called, it will receive the object, still fully intact (rather than toStringified).

If you hadn’t noticed, this is perfect for cleaning up your control flow in web apps/APIs/what have you. For those of you doing that kind of thing, make sure you check out the guard.expressJSONReporter reporter.

Something went wrong with that request. Please try again.