Package Exports

modern-errors-winston

Readme

modern-errors plugin for Winston.

This adds BaseError.fullFormat() and BaseError.shortFormat() which return a Winston format.

Features

Improved error logging with Winston:

Error class/instance-specific log level or verbosity
The full format includes all properties
The short format includes only the error's name, message and stack
Works with uncaught exceptions

Unlike Winston's default error format:

The error name is logged
The full format logs nested errors, including cause and aggregate errors
The full format is JSON-safe
The short format optionally logs the stack trace
The error instance is not modified

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'

import modernErrorsWinston from 'modern-errors-winston'

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsWinston],
})
export const InputError = BaseError.subclass('InputError')
// ...

Using the full format with Winston.

import { createLogger, transports, format } from 'winston'

const logger = createLogger({
  format: format.combine(BaseError.fullFormat(), format.json()),
  transports: [new transports.Http(httpOptions)],
})

const error = new InputError('Could not read file.', { props: { filePath } })
logger.error(error)
// Sent via HTTP:
// {
//   level: 'error',
//   name: 'InputError',
//   message: 'Could not read file.',
//   stack: `InputError: Could not read file.
//     at ...`,
//   filePath: '/...',
// }

Using the short format with Winston.

import { createLogger, transports, format } from 'winston'

const logger = createLogger({
  format: format.combine(BaseError.shortFormat(), format.cli()),
  transports: [new transports.Console()],
})

const error = new InputError('Could not read file.', { props: { filePath } })
logger.error(error)
// Printed on the console:
// error: InputError: Could not read file.
//     at ...

Install

npm install modern-errors-winston

This package requires installing Winston separately.

npm install winston

This package works in Node.js >=16.17.0.

This is an ES module. It must be loaded using an import or import() statement, not require(). If TypeScript is used, it must be configured to output ES modules, not CommonJS.

API

modernErrorsWinston

Type: Plugin

Plugin object to pass to the plugins option of ErrorClass.subclass().

BaseError.fullFormat()

Return value: Format

Returns a logger format to combine with format.json() or format.prettyPrint(). This logs all error properties, making it useful with transports like HTTP.

Errors should be logged using logger.*(error).

BaseError.shortFormat()

Return value: Format

Returns a logger format to combine with format.simple() or format.cli(). This logs only the error name, message and stack, making it useful with transports like the console.

Errors should be logged using logger.*(error).

Options

Type: object

stack

Type: boolean
Default: true

Whether to log the stack trace.

level

Type: string

Override the log level.

Configuration

Options can apply to (in priority order):

Any error: second argument to ModernError.subclass()

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsWinston],
  winston: options,
})

Any error of a specific class (and its subclasses): second argument to ErrorClass.subclass()

export const InputError = BaseError.subclass('InputError', { winston: options })

A specific error: second argument to new ErrorClass()

throw new InputError('...', { winston: options })

A specific BaseError.fullFormat() or BaseError.shortFormat() call

BaseError.fullFormat(options)

winston: A logger for just about everything
modern-errors: Handle errors in a simple, stable, consistent way
winston-error-format: Log errors with Winston
error-serializer: Convert errors to/from plain objects
modern-errors-cli: Handle errors in CLI modules
modern-errors-process: Handle process errors
modern-errors-bugs: Print where to report bugs
modern-errors-serialize: Serialize/parse errors
modern-errors-clean: Clean stack traces
modern-errors-http: Create HTTP error responses
modern-errors-switch: Execute class-specific logic

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!

modern-errors-winston