uffbasse

Bouncing async/await wrapper for smart error handling

1. Introduction
2. Installation
3. Example
4. API
5. Developing and Testing
6. Contribution

Introduction

uffbasse is an enhanced async/await wrapper for smart error handling and is based on the articles Learning to Throw Again and How to write async await without try-catch blocks in Javascript. So it returns a [err, result] array quite similar to the error-first callbacks. Like described in the articles using async/await both run-time and developer errors are merged into one single channel. uffbasse enables to differ between types of errors and behave based on this distinction. There are basically three behaviours:

1. promise resolves
   returns [null, result]
2. promise rejects with a matching error
   returns [err, undefined]
3. promise rejects with a non-matching error
   returns [null, defaultResult] and logs the error

The modules standard and ava are used to grant a high quality implementation.
uffbasse is the Swabian translation for take care.

Installation

For installation use the Node Package Manager ⇗:

$ npm install --save uffbasse

or clone the repository:

$ git clone https://github.com/felixheck/uffbasse

Example

With uffbasse

const to = require('uffbasse');

const succeeded = Promise.resolve({ test: 123 });
const failedMatched = Promise.reject(new SyntaxError('foobar'));
const failedNonMatched = Promise.reject(new Error('foobar'));

(async () => {
  await to(succeeded);
  // returns: [null, { test: 123 }]

  await to(failedMatched);
  // returns: ['SyntaxError: foobar', undefined]

  const [err, res] = await to(failedMatched);
  if (err) throw err;
  // returns: ['SyntaxError: foobar', undefined]
  // throws:   'SyntaxError: foobar'

  await to(failedNonMatched);
  // logs: foobar
  // returns: [null, undefined]

  await to(failedNonMatched, { defaults: {} });
  // logs: foobar
  // returns: [null, {}]
})();

Without uffbasse

const bounce = require('bounce');

const succeeded = Promise.resolve({ test: 123 });
const failedMatched = Promise.reject(new SyntaxError('foobar'));
const failedNonMatched = Promise.reject(new Error('foobar'));

(async () => {
  let res;

  try {
    res = await succeeded;
  } catch(err) {
    bounce.rethrow(err, 'system');
    console.error(err);
  }

  try {
    res = await failedMatched;
  } catch(err) {
    bounce.rethrow(err, 'system');
    console.error(err);
  }

  try {
    res = await failedNonMatched;
  } catch(err) {
    bounce.rethrow(err, 'system');
    console.error(err);
    res = {}
  }
})();

API

uffbasse(promise, [options]): Returns a [err, result] array.

• promise {Promise}: The promise to be handled
  Required.

• options {Object}: Additional options to customize the behaviour.
  Optional.

  • defaults {*}: Default value to be returned if it is a non-matching error.
    Optional. Default: undefined.
  • log {null|Function}: Function utilized to log non-matching errors. If null, logging is disabled. Optional. Default: console.error.
  • is {Function}: Function utilized to distinct between error types.
    Optional. Default: bounce.isSystem.

By default it just returns run-time errors.
Errors due to developers are logged with console.error.

Developing and Testing

First you have to install all dependencies:

$ npm install

To execute all unit tests once, use:

$ npm test

or to run tests based on file watcher, use:

$ npm start

To get information about the test coverage, use:

$ npm run coverage

Contribution

Fork this repository and push in your ideas.

Do not forget to add corresponding tests to keep up 100% test coverage.
For further information read the contributing guideline.