API.md

API

You can try all the examples below:

• either directly in your browser.
• or by executing the examples files in a terminal.

logProcessErrors([options])

Initializes log-process-errors. Returns a function that can be fired to restore Node.js default behavior.

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

const restore = logProcessErrors(options)
restore()

Full example:

logProcessErrors({
  log(error, level) {
    winstonLogger[level](error.stack)
  },

  level: { multipleResolves: 'debug' },

  exitOn: ['uncaughtException', 'unhandledRejection'],

  testing: 'ava',

  colors: false,
})

options

Type: object

log

Type: function(error, level, originalError)

By default process errors 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 process errors with Winston instead:

logProcessErrors({
  log(error, level, originalError) {
    winstonLogger[level](error.stack)
  },
})

The function's arguments are error, level and originalError.

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 process errors are only logged once (whether the log option is defined or not).

level

Type: object
Default: { warning: 'warn', multipleResolves: 'info', default: 'error' }

Which log level to use.

Object keys are the error names: uncaughtException, warning, unhandledRejection, rejectionHandled, multipleResolves or default.

Object values are the log level: 'debug', 'info', 'warn', 'error', 'silent' or 'default'. It can also be a function using error as argument and returning one of those log levels.

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

    // Skip some logs based on a condition
    default(error) {
      return shouldSkip(error) ? 'silent' : 'default'
    },
  },
})

exitOn

Type: string[]
Value: array of 'uncaughtException', 'unhandledRejection', 'rejectionHandled', 'multipleResolves' or 'warning'
Default: ['uncaughtException', 'unhandledRejection'] for Node >= 15.0.0, ['uncaughtException'] otherwise.

Which process errors should trigger process.exit(1):

• ['uncaughtException', 'unhandledRejection'] is Node.js default behavior since Node.js 15.0.0. Before, only uncaughtException was enabled.
• use [] to prevent any process.exit(1). 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 process error.

logProcessErrors({ exitOn: ['uncaughtException', 'unhandledRejection'] })

testing

Type: string
Value: 'ava', 'mocha', 'jasmine', 'tape' or 'node-tap'
Default: undefined

When running tests, makes them fail if there are any process errors.

Example with Ava:

const logProcessErrors = require('log-process-errors')
// Should be initialized before requiring other dependencies
logProcessErrors({ testing: 'ava' })

const test = require('ava')

// Tests will fail because a warning is triggered
test('Example test', (t) => {
  process.emitWarning('Example warning')
  t.pass()
})

Alternatively, you can just require log-process-errors/build/register/{testRunnerName}:

// Should be initialized before requiring other dependencies
require('log-process-errors/build/register/ava')

const test = require('ava')

// Tests will fail because a warning is triggered
test('Example test', (t) => {
  process.emitWarning('Example warning')
  t.pass()
})

This can also be used with node -r or any equivalent CLI flag for your test runner:

ava --require log-process-errors/build/register/ava

To ignore specific process errors, use the level option:

const logProcessErrors = require('log-process-errors')
// Should be initialized before requiring other dependencies
logProcessErrors({ testing: 'ava', level: { warning: 'silent' } })

const test = require('ava')

// Tests will not fail because warnings are `silent`
test('Example test', (t) => {
  process.emitWarning('Example warning')
  t.pass()
})

colors

Type: boolean
Default: true if the output is a terminal.

Colorizes messages.

logProcessErrors({ colors: false })

error

Type: Error

The log and level options receive as argument an error instance.

This error is generated based on the original process error but with an improved name, message and stack. However the original process error is still available as a third argument to log.

error.name

Type: string
Value: 'UncaughtException', 'UnhandledRejection', 'RejectionHandled', 'MultipleResolves' or 'Warning'

error.stack

error is prettified when using console or util.inspect():

console.log(error)

But not when using error.stack instead:

console.log(error.stack)