modern-errors plugin to serialize/parse errors.

This adds BaseError.serialize() and BaseError.parse() to serialize/parse errors to/from plain objects.

Hire me

Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.

Features

• Ensures errors are safe to serialize with JSON
• Deep serialization/parsing
• Custom serialization/parsing (e.g. YAML or process.send())
• Keeps error classes
• Preserves errors' additional properties
• Works recursively with AggregateError
• Safe: this never throws

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'

import modernErrorsSerialize from 'modern-errors-serialize'

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

Serializing errors to plain objects.

const error = new ExampleError('message', { props: { filePath } })

const errorObject = BaseError.serialize(error)
// { name: 'ExampleError', message: 'message', stack: '...', filePath: '...' }
const errorString = JSON.stringify(errorObject)
// '{"name":"ExampleError",...}'

Parsing errors from plain objects.

const newErrorObject = JSON.parse(errorString)
const newError = BaseError.parse(newErrorObject)
// ExampleError: message
//     at ...
//   filePath: '...'

Install

npm install modern-errors-serialize

This package works in both Node.js >=18.18.0 and browsers.

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

modernErrorsSerialize

Type: Plugin

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

BaseError.serialize(error)

error: ErrorInstance
Return value: ErrorObject

Converts error to an error plain object. All error properties are kept. Plugin options are also preserved.

BaseError.parse(errorObject)

errorObject: ErrorObject
Return value: ErrorInstance

Converts errorObject to an error instance. The original error classes are preserved providing they are subclasses of BaseError.

Options

Type: object

shallow

Type: boolean
Default: false

Unless this option is true, nested errors are also serialized/parsed. They can be inside other errors, plain objects or arrays.

const inner = new ExampleError('inner')
const error = new ExampleError('example', { props: { inner } })

BaseError.serialize(error).inner // { name: 'BaseError', message: 'inner', ... }
BaseError.serialize(error, { shallow: true }).inner // BaseError

const errorObject = BaseError.serialize(error)
BaseError.parse(errorObject).inner // BaseError
BaseError.parse(errorObject, { shallow: true }).inner // { name: '...', ... }

loose

Type: boolean
Default: false

By default, when the argument is not an Error instance or an error plain object, it is converted to one. If this option is true, it is kept as is instead.

BaseError.serialize('example') // { name: 'BaseError', message: 'example', ... }
BaseError.serialize('example', { loose: true }) // 'example'

BaseError.parse('example') // BaseError
BaseError.parse('example', { loose: true }) // 'example'

include

Type: string[]

During serialization, only pick specific properties.

BaseError.serialize(error, { include: ['message'] }) // { message: 'example' }

exclude

Type: string[]

During serialization, omit specific properties.

BaseError.serialize(error, { exclude: ['stack'] }) // { name: 'Error', message: 'example' }

transformObject(errorObject, errorInstance)

Type: (errorObject, errorInstance) => void

During serialization, transform each error plain object.

errorObject is the error after serialization. It must be directly mutated.

errorInstance is the error before serialization.

transformArgs(constructorArgs, errorObject, ErrorClass)

Type: (constructorArgs, errorObject, ErrorClass) => void

During parsing, transform the arguments passed to each new Error().

constructorArgs is the array of arguments. Usually, constructorArgs[0] is the error message and constructorArgs[1] is the constructor options object. constructorArgs must be directly mutated.

errorObject is the error before parsing. ErrorClass is its class.

transformInstance(errorInstance, errorObject)

Type: (errorInstance, errorObject) => void

During parsing, transform each Error instance.

errorInstance is the error after parsing. It must be directly mutated.

errorObject is the error before parsing.

Configuration

Options can apply to (in priority order):

• Any error: second argument to ModernError.subclass()

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

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

export const ExampleError = BaseError.subclass('ExampleError', {
  serialize: options,
})

• A specific error: second argument to new ErrorClass()

throw new ExampleError('...', { serialize: options })

• A specific BaseError.serialize(error) or BaseError.parse(errorObject) call

BaseError.serialize(error, options)

BaseError.parse(errorObject, options)

Usage

JSON safety

Error plain objects are always safe to serialize with JSON.

const error = new ExampleError('message')
error.cycle = error

// Cycles make `JSON.stringify()` throw, so they are removed
console.log(BaseError.serialize(error).cycle) // undefined

Deep serialization/parsing

The loose option can be used to deeply serialize/parse objects and arrays.

const error = new ExampleError('message')
const deepArray = BaseError.serialize([{}, { error }], { loose: true })

const jsonString = JSON.stringify(deepArray)
const newDeepArray = JSON.parse(jsonString)

const newError = BaseError.parse(newDeepArray, { loose: true })[1].error
// ExampleError: message
//     at ...

Automatic serialization

error.toJSON() is defined. It is automatically called by JSON.stringify().

const error = new ExampleError('message')
const deepArray = [{}, { error }]

const jsonString = JSON.stringify(deepArray)
const newDeepArray = JSON.parse(jsonString)

const newError = BaseError.parse(newDeepArray, { loose: true })[1].error
// ExampleError: message
//     at ...

Omit additional error properties

const ExampleError = BaseError.subclass('ExampleError', {
  serialize: { include: ['name', 'message', 'stack'] },
})
const error = new ExampleError('example')
error.prop = true

const errorObject = ExampleError.serialize(error)
console.log(errorObject.prop) // undefined
console.log(errorObject) // { name: 'Error', message: 'example', stack: '...' }

Omit stack traces

const ExampleError = BaseError.subclass('ExampleError', {
  serialize: { exclude: ['stack'] },
})
const error = new ExampleError('example')

const errorObject = ExampleError.serialize(error)
console.log(errorObject.stack) // undefined
console.log(errorObject) // { name: 'Error', message: 'example' }

Transforming

const errors = [new ExampleError('message secret')]
errors[0].date = new Date()

const errorObjects = BaseError.serialize(errors, {
  loose: true,
  // Serialize `Date` instances as strings
  transformObject: (errorObject) => {
    errorObject.date = errorObject.date.toString()
  },
})
console.log(errorObjects[0].date) // Date string

const newErrors = BaseError.parse(errorObjects, {
  loose: true,
  // Transform error message
  transformArgs: (constructorArgs) => {
    constructorArgs[0] = constructorArgs[0].replace('secret', '***')
  },
  // Parse date strings as `Date` instances
  transformInstance: (error) => {
    error.date = new Date(error.date)
  },
})
console.log(newErrors[0].message) // 'message ***'
console.log(newErrors[0].date) // `Date` instance

Custom serialization/parsing

Errors are converted to/from plain objects, not strings. This allows any serialization/parsing logic to be performed.

import { dump, load } from 'js-yaml'

const error = new ExampleError('message')
const errorObject = BaseError.serialize(error)
const errorYamlString = dump(errorObject)
// name: ExampleError
// message: message
// stack: ExampleError: message ...
const newErrorObject = load(errorYamlString)
const newError = BaseError.parse(newErrorObject) // ExampleError: message

Additional error properties

const error = new ExampleError('message', { props: { prop: true } })
const errorObject = BaseError.serialize(error)
console.log(errorObject.prop) // true
const newError = BaseError.parse(errorObject)
console.log(newError.prop) // true

Aggregate errors

const error = new ExampleError('message', {
  errors: [new ExampleError('one'), new ExampleError('two')],
})

const errorObject = BaseError.serialize(error)
// {
//   name: 'ExampleError',
//   message: 'message',
//   stack: '...',
//   errors: [{ name: 'ExampleError', message: 'one', stack: '...' }, ...],
// }
const newError = BaseError.parse(errorObject)
// ExampleError: message
//   [errors]: [ExampleError: one, ExampleError: two]

Constructors

If an error with a custom class is parsed, its custom constructor is not called. However, any property previously set by that constructor is still preserved, providing it is serializable and enumerable.

const ExampleError = BaseError.subclass('ExampleError', {
  custom: class extends BaseError {
    constructor(message, options, prop) {
      super(message, options, prop)
      this.prop = prop
    }
  },
})

const error = new ExampleError('message', {}, true)
const errorObject = BaseError.serialize(error)
// `constructor(message, options, prop)` is not called
const newError = BaseError.parse(errorObject)
// But properties set by that `constructor(...)` are kept
console.log(newError.prop) // true

Related projects

• error-serializer: Convert errors to/from plain objects
• modern-errors: Handle errors in a simple, stable, consistent way
• modern-errors-cli: Handle errors in CLI modules
• modern-errors-process: Handle process errors
• modern-errors-bugs: Print where to report bugs
• modern-errors-clean: Clean stack traces
• modern-errors-http: Create HTTP error responses
• modern-errors-winston: Log errors with Winston
• 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!

ehmicky 💻 🎨 🤔 📖

Benjamin Kroeger 🤔