modern-errors plugin for Winston.

This adds AnyError.fullFormat() and AnyError.shortFormat() which return a format to improve error logging with Winston.

Features

• 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
• Prevents Winston from modifying the error instance
• Works with uncaught exceptions

Example

Adding the plugin to modern-errors.

import modernErrors from 'modern-errors'
import modernErrorsWinston from 'modern-errors-winston'

export const AnyError = modernErrors([modernErrorsWinston])
// ...
export const InputError = AnyError.subclass('InputError')

Using the full format with Winston.

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

const logger = createLogger({
  format: format.combine(AnyError.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(AnyError.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 is an ES module and must be loaded using an import or import() statement, not require().

API

modernErrorsWinston

Type: Plugin

Plugin object to pass to modernErrors().

AnyError.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(error).

AnyError.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(error).

Options

Type: object

level

Type: string
Default: 'error'

Log level.

stack

Type: boolean

Whether to log the stack trace.

By default, this is true if the error (or one of its inner errors) is unknown, and false otherwise.

Configuration

Options can apply to (in priority order):

• Any error: second argument to modernErrors()

export const AnyError = modernErrors(plugins, { winston: { ...options } })

• Any error of multiple classes: using ErrorClass.subclass()

export const SharedError = AnyError.subclass('SharedError', {
  winston: { ...options },
})

export const InputError = SharedError.subclass('InputError')
export const AuthError = SharedError.subclass('AuthError')

• Any error of a specific class: second argument to AnyError.subclass()

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

• A specific error: second argument to the error's constructor

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

• A specific AnyError.fullFormat() or AnyError.shortFormat() call

AnyError.fullFormat(...args, { ...options })

Related projects

• winston: A logger for just about everything
• error-serializer: Convert errors to/from plain objects
• modern-errors: Handle errors like it's 2022 🔮
• 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-stack: Clean stack traces
• modern-errors-http: Create HTTP error responses

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!