Skip to content package
modern-errors-serialize v2.0.0 `modern-errors` plugin to serialize/parse errors
node >=14.18.0 2 deps esm types open source
overview readme
license MIT
deps 2
unpacked 15.2 kB
files 5
node >=14.18.0 $ npm install modern-errors-serialize@2.0.0n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
browser error error-handler error-handling error-monitoring javascript json library modern-errors modern-errors-plugin nodejs parse
versions Latest published Mar 29, 2025
maintainers Registry package owners.
install size Estimated unpacked size across 7 packages.
164.5 kB
Includes dependencies.
dependencies 2 direct dependencies.
Features
Example import ModernError from 'modern-errors'
import modernErrorsSerialize from 'modern-errors-serialize'
export const BaseError = ModernError. subclass ( 'BaseError' , {
plugins: [modernErrorsSerialize],
})
// ... copy 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",...}' copy const newErrorObject = JSON. parse (errorString)
const newError = BaseError. parse (newErrorObject)
// ExampleError: message
// at ...
// filePath: '...' copy
Install npm install modern-errors-serialize copy This package works in both Node.js >=18.18.0 and
browsers .
API
BaseError.serialize(error) error: ErrorInstance
Return value : ErrorObject
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
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: '...', ... } copy
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' copy
include BaseError. serialize (error, { include: [ 'message' ] }) // { message: 'example' } copy
exclude BaseError. serialize (error, { exclude: [ 'stack' ] }) // { name: 'Error', message: 'example' } copy
Type : (errorObject, errorInstance) => void
errorObject is the error after serialization. It must be directly mutated.
errorInstance is the error before serialization.
Type : (constructorArgs, errorObject, ErrorClass) => void
errorObject is the error before parsing. ErrorClass is its class.
Type : (errorInstance, errorObject) => void
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):
export const BaseError = ModernError. subclass ( 'BaseError' , {
plugins: [modernErrorsSerialize],
serialize: options,
}) copy export const ExampleError = BaseError. subclass ( 'ExampleError' , {
serialize: options,
}) copy throw new ExampleError ( '...' , { serialize: options }) copy BaseError. serialize (error, options) copy BaseError. parse (errorObject, options) copy
Usage
JSON safety const error = new ExampleError ( 'message' )
error.cycle = error
// Cycles make `JSON.stringify()` throw, so they are removed
console. log (BaseError. serialize (error).cycle) // undefined copy
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 ... copy
Automatic serialization 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 ... copy
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: '...' } copy
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' } copy
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 copy
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 copy
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 copy
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] copy
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 copy
Support 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!