Show some ❤️ to process errors in Node.js.

By default Node.js prints uncaughtException, warning and mishandled promises (unhandledRejection, rejectionHandled, multipleResolves) on the console which is very useful. Unfortunately those process errors:

• show neither stack traces nor promise values for warning, rejectionHandled and multipleResolves making it hard to debug.
• are inconvenient to log to an external service.
• cannot be conditionally skipped
• are printed each time an error is repeated (except for warning).
• are not human-friendly.

Without log-process-errors:

log-process-errors fixes those issues:

Installation

Production code (e.g. a web server) can install this either as a production or development dependency:

npm install log-process-errors

However libraries should install this as a development dependency:

npm install -D log-process-errors

This is because logging is modified globally and libraries users might not expect this side-effect. Also this might lead to conflicts between libraries.

Usage

There are two ways to load this library. The first is to use the node -r CLI flag:

node -r log-process-errors/register ...

The second is:

const logProcessErrors = require('log-process-errors')
logProcessErrors(options)

logProcessErrors() should be called as early as possible in the code.

options is an optional object with the following properties:

• log {function}
• level {object}
• message {function}
• colors {boolean}
• exitOn {string[]}

Custom logging

By default events will be logged to the console using console.error(), console.warn(), etc.

This behavior can be overridden with the log option. For example to log events with Winston instead:

logProcessErrors({
  log(message, level, info) {
    winstonLogger[level](message)
  },
})

The function's arguments are message (string), level (string) and info (object).

If logging is asynchronous, the function should return a promise (or use async/await). This is not necessary if logging is using streams (like Winston).

Duplicate events are only logged once (whether the log option is defined or not).

Log level

The default log level is warn for warning, info for multipleResolves and error for the other events.

This can be overridden by using the level option. It should be an object whose:

• keys are the event names among "default", "uncaughtException", "warning", "unhandledRejection", "rejectionHandled" or "multipleResolves".
• values are the log level which can be:
  • a string among "debug", "info", "warn", "error" or "silent".
  • undefined to use the default value.
  • a function using info as argument and returning a string or undefined (as above).

logProcessErrors({
  // Use `debug` log level for `multipleResolves` instead of `info`
  level: { multipleResolves: 'debug' },
})

logProcessErrors({
  // Skip some logs based on a condition
  level: {
    default() {
      if (shouldSkip()) {
        return 'silent'
      }
    },
  },
})

Log message

A nice-looking and descriptive log message is generated by default.

The message will be colorized unless the option colors is set to false.

The message generation can be overridden by using the message option. It should be a function using info as argument and returning a string.

Event information

The log, level and message options all receive as argument an info object.

info.eventName

Can be "uncaughtException", "unhandledRejection", "rejectionHandled", "multipleResolves" or "warning".

info.value

Value:

• thrown by uncaughtException.
• resolved/rejected by the promise with unhandledRejection, rejectionHandled and multipleResolves.
• emitted by warning.

It is usually an Error instance but could be anything.

info.rejected

Boolean indicating whether the promise was initially resolved or rejected. Only defined with multipleResolves.

info.nextValue, info.nextRejected

Like value and rejected but for the second time the promise was resolved/rejected. Only defined with multipleResolves.

info.level

Log level. Only defined with the message option.

info.colors

Chalk instance to colorize strings. Only defined with the message option. Disabled if the colors option is false.

Process exit

The exitOn option specifies which event should trigger process.exit(1):

• the default value is ["uncaughtException"]. This is the default behavior of Node.js.
• we recommend using ["uncaughtException", "unhandledRejection"] instead since this will be the future default behavior of Node.js.
• to prevent any process.exit(1) use []. Recommended if your process is long-running and does not automatically restart on exit.

process.exit(1) will only be fired after successfully logging the event.

Restoring default behavior

Node.js default behavior can be restored by firing the function returned by logProcessErrors().

const restore = logProcessErrors(options)
restore()