Package Exports

modern-errors-winston

Readme

modern-errors plugin for Winston.

This adds BaseError.fullFormat() and BaseError.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 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 >=14.18.0. It 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 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(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(error).

Options

Type: object

level

Type: string
Default: 'error'

Log level.

stack

Type: boolean
Default: true

Whether to log the stack trace.

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(...args, { ...options })

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-clean: 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!

modern-errors-winston