Safety Dance

This node.js module provides you exception safety. That is to say that the functions of this module never ever throw.

If you are annoyed with node.js built-in API throwing exceptions and using exceptions as multi-value return statements, this module is for you.

This module catches any exception in the function you want to call. If there is no exception, it behaves as always. If there was an exception, it catches it, makes it available via error property (like errno).

So, instead of:

try {
    var result = JSON.parse(something);
} catch (e) {
    ...
}

you can write:

var result = safe.JSON.parse(something);
if (result === null) { ... }

Installation

npm install safetydance

Usage

You can call arbitrary synchronous functions without having to worry about exceptions.

var safeCall = require('safetydance');
var result = safeCall(function () { return 1 + 2; }); // will return 3
result = safeCall(function () { throw new Error('bad'); }); // will return null

To pass 'this':

var obj = { a: 10 };
var result = safeCall(function () { return this.a; }.bind(obj)); // will return 10

This module provide conveniences for commonly used functions.

var safe = require('safetydance');
var json = safe.JSON.parse('This is totally { not json }');
console.log(json); // will be null
console.log(safe.error); // will contain SyntaxError

The error gets cleared for successful operations.

json = safe.JSON.parse('{ "totally" : "json" }');
console.log(json); // { totally: "json" }
console.log(safe.error); // will be null

safe.query

safe.query can be used to access nested object properties. For example, the code below can throw an exception if any of the nested objects does not contain the accesses properties:

var capital = data.countries.norway.capital;

This can be rewritten as:

var capital = safe.query(data, 'countries.norway.capital'); // returns undefined if not found

You can also specify a default:

var capital = safe.query(data, 'countries.norway.capital', 'oslo'); // return oslo if not found

Works for deeply nested properties as well (use [] for array access):

var item = safe.query(data, 'key[0][3].some.fancy[45].nested.5.value');

Property names with '.' in them are not supported.

safe.set

safe.set is the complement of safe.query.

var obj = { };
safe.set(obj, 'some.deep.value', 42);
console.log(obj.some.deep.value); // prints 42

If obj is not a valid object, it will create one for you

obj = safe.set(null, 'some.deep.value', 42);
console.log(obj.some.deep.value); // prints 42

If any of the values in the chain is not an object, it will get replaced.

var obj = { some: 43 };
safe.set(obj, 'some.deep.value', 42);
console.log(obj.some.deep.value); // prints 42; some is gone

safe.unset

safe.unset unsets properties in objects.

var obj = { some: { deep: { value: 42 } } };
safe.unset(obj, 'some.deep.value');
console.log(obj); // prints { some: { deep: { } } }

API

• safeCall(functionToCall, valueToReturnIfErrored)
• error - the error of the last function call
• Convenience (refer to node.js docs for details)
  • JSON.parse - returns null on error, object on success
  • JSON.stringify - returns null on error, string on success
  • fs.readFileSync - returns null on error, string/buffer on success
  • fs.writeFileSync - returns false on error, true on success
  • fs.statSync - returns null on error, stat object on success
  • fs.existsSync - returns false on error, true/false on success
  • fs.mkdirSync - returns false on error, true on success
  • fs.unlinkSync - returns false on error, true on success
  • fs.renameSync - returns false on error, true on success
  • fs.copyFileSync - returns false on error, true on success
  • fs.readdirSync - returns null on error, file array on success
  • fs.utimesSync - returns false on error, true on success
  • fs.futimesSync - returns false on error, true on success
  • url.parse = returns null on error, object on success
  • require - returns null on error, module on success
  • child_process.execSync - returns null on error, stdio on success
  • child_process.spawnSync - return null on error, object on success