node-err

Simplify error handling and logging for Node.

Index

• Overview
• Technical
• Examples
  

Overview

One Error Handler

With node-err, you always use the same error handler, giving you expected behavior...

nodeErr.repeat(err);

const nodeErr = require('node-err');

return fetch()
  .catch(err => {
    return nodeErr.repeat(err);
  });

Bubbling-up Errors

With consistent error handling, bubbling-up errors is super easy...

return fetch()
  .catch(err => {
    return nodeErr.repeat(err);
  })
  .catch(err => {
    return nodeErr.repeat(err);
  })
  .catch(err => {
    return nodeErr.repeat(err);
  })
  .catch(err => {
    return next(err);
  });

Automatic logging

And logging/reporting is a breeze, it happens automatically...

nodeErr.repeat(err, details);

return fetchUsers()
  .catch(err => {

    let details = {
      name: 'FETCH_USERS',
      status: 500,
    };

    return nodeErr.repeat(err, details);
  });

Server Logging

Server logging happens out-of-the-box so you can set-up alerts with a service such as Papertrail...

papertrail -f SERVER_ERROR

Custom Logging

But you can set up your only logger too...

nodeErr.setup({ logger: myOwnLogger });

Custom Output Responses

Configure and send response data for outputting to the browser. View the Simple Promises example to see it in action.

nodeErr.setup({ responses: ['user_message','internal_code'] });

return saveAnalytics()
  .catch(err => {

    return nodeErr.repeat(err, {
      status: 500,
      responses: {
        user_message: 'Oops! Something went wrong.',
        internal_code: '2352',
      }
    });
  })
  .catch(err => {

    let statusCode = nodeErr.getStatus(err);
    let outputResponse = nodeErr.getResponse(err);
    
    return res.status(statusCode).send(outputResponse);
  });
}

Localized/Silent Error Handling

Sometimes you need to handle some errors a little differently, while still allowing other errors to bubble-up or pass through...

nodeErr.repeat(customVal)(err);

return saveAnalytics()
  .then(() => {

    // do more stuff with the ability to
    // bubble up a different fatal error

    return true;
  })
  .catch(err => {

    // if our saveAnalytics() failed, lets 
    // keep going and just return false

    return nodeErr.repeat(false)(err);
  })
  .then(result => {

    // did the analytics save ok?

    return (result) ? next() : retry();
  });
}

For more details, view the handling sections below.

Async/Await

(async function() {
  try {
    throw new Error('cubitum irem');
  } catch(err) {
    await nodeErr.repeat(err, { name: 'Do I know latin?' });
  }
})().catch(err => {
  // Hey Alexa...
});

Express Middleware

How about some Express middleware to catch/report any un-reported errors?

nodeErr.stop(err);

app.use((err, req, res, next) => {
  let details = { req };
  nodeErr.stop(err, details);
  return next(err);
});

Error Output

What should you do with all of these errors? Whatever you like...

app.use((err, req, res, next) => res.sendStatus( nodeErr.getStatus(err) ));

Technical

Getting Started

Just require node-err and start using repeat to automatically log and bubble-up errors...

const nodeErr = require('node-err');

return fetch()
  .catch(err => {
    return nodeErr.repeat(err);
  });

Config Vars (optional)

Call the setup function in your entry file (index.js or server.js) and pass config vars (optional)...

const nodeErr = require('node-err');

nodeErr.setup({
  prefix: 'FIND_THIS_ERROR',
  status: 401,
  debug: true,
  logger: (err) => slackChannel('Doh', err)),
  responses: ['user_message'],
  overrideResponses: true,
});

Key	Type	Description
prefix	string	Global prefix added to all error logs.
status	number	Default HTTP status code error.
debug	bool	Output error repetition tracing.
logger	func	Custom logging function (accepts Error obj).
responses	array	Array of response properties.
overrideResponses	bool	Allow automatic overwrite of responses when bubbling up.

Additional Error Details (optional)

When calling repeat add some more details so you know what went wrong (optional)...

nodeErr.repeat(err, {
  name: 'AWS_IMAGE_NOT_SAVED',
  req: req,
  status: 400,
  context: { imageName: 'budget-report.ppt'},
  responses: { user_message: 'Oops! Something went wrong.' },
  log: false,
  censor: true,
});

Key	Type	Description
name	string	(optional) Custom error name.
req	object	(optional) Express request object.
status	bool	(optional) Desired http status response code.
context	any	(optional) Whatever works.
responses	object	(optional) Data to place on the response output.
log	bool	(optional) Skip logging at this repeat node (intentional errors).
censor	bool	(optional) Skip request body log (persists with bubbling up).

If req is provided, you'll also get access to:

• IP Address
• Requested URL
• Request Body
• Request Method
• User Agent

Any responses data provided, must have its property added to the setup config.

Basic Block Error Handling/Bubbling

By default, calling repeat on an error the first time will create an error report and then reject it again with a Promise.reject.

Calling repeat again (in subsequent catch block) on an already reported error will just reject the same error again (no further reporting).

return fetch()
  .then(() => Promise.reject('level 1 error please'))
  .catch(err => {
    return nodeErr.repeat(err, { name: 'level 1' }); // report and rejects again
  })
  .then(() => doSomething()
  .catch(err => {
    return nodeErr.repeat(err, { name: 'level 2' }); // rejects level 1 error again
  })
  .then(() => doSomething()
  .catch(err => {
    return nodeErr.repeat(err, { name: 'level 3' }); // rejects level 1 error again
  })
  .catch(err => {
    return next(err); // returns level 1 error
  });

In this way, errors can bubble back up and be handled however you like.

Multi-directional Error Handling

You might want to handle some error differently, while still allowing processes above it to pass/bubble their errors through.

By using repeat with a custom value, which returns a callback and accepts, you can achieve multi-directional functionality:

• Any previously reported will continue to bubble up and through.
• Any un-reported errors will output with whatever value you set.

In this way, you can have a silent error handler for one process without breaking promise chain for processes above/before it.

nodeErr.repeat('It failed!')(err);

return saveAnalytics()
  .then(() => {
    return fetchUser();
  })
  .catch(err => {

    // if we didnt have a db conn error, and instead had an error
    // from saveAnalytics, the below would just return `false`

    return nodeErr.repeat(false)(err); // our db conn error will pass through
  })
  .then(result => {
    return (result) ? next() : retry(); // this is skipped because of our db conn error
  })
  .catch(err => {
    return next(err); // return db conn error
  })
}

function fetchUser() {

  return fetch()
    .then(result => {
      throw new Error('remote db conn err'); // fire error
    })
    .then(() => true) // this is skipped
    .catch(err => {
      return nodeErr.repeat(err, { name: 'FETCH_USER' }); // this will reject again
    })
}

You can also force an error report on a silent/custom error, so it will still show in the logs:

nodeErr.repeat('It failed!', true)(err);

Examples

Viewing the Examples

There are several examples included in the project. To run these...

1. $ cd examples
2. $ npm install
3. $ npm run start
4. Navigate to http://localhost:5000 for a directory of examples.