serialize-error

Serialize/deserialize an error into a plain object

Useful if you for example need to JSON.stringify() or process.send() the error.

npm install serialize-error

import{serializeError,deserializeError}from'serialize-error';consterror=newError('🦄');console.log(error);//=> [Error: 🦄]constserialized=serializeError(error);console.log(serialized);//=> {name: 'Error', message: '🦄', stack: 'Error: 🦄\n at Object.<anonymous> …'}constdeserialized=deserializeError(serialized);console.log(deserialized);//=> [Error: 🦄]

When a serialized error with a known name is encountered, it will be deserialized using the corresponding error constructor, while unknown error names will be deserialized as regular errors:

import{deserializeError}from'serialize-error';constknown=deserializeError({name: 'TypeError',message: '🦄'});console.log(known);//=> [TypeError: 🦄] <-- Still a TypeErrorconstunknown=deserializeError({name: 'TooManyCooksError',message: '🦄'});console.log(unknown);//=> [Error: 🦄] <-- Just a regular Error

The list of known errors can be extended globally. This also works if serialize-error is a sub-dependency that's not used directly.

import{addKnownErrorConstructor}from'serialize-error';import{MyCustomError}from'./errors.js'addKnownErrorConstructor(MyCustomError);

For error constructors that require arguments, you can provide a factory function:

import{addKnownErrorConstructor}from'serialize-error';classCustomErrorextendsError{name='CustomError';constructor(message,options){super(message);this.code=options.code;}}addKnownErrorConstructor(CustomError,()=>newCustomError('',{code: 'ERR_UNICORN'}));

Serialize an Error object into a plain object.

• Custom properties are preserved.
• Non-enumerable properties are kept non-enumerable (name, message, stack).
• Enumerable properties are kept enumerable (all properties besides the non-enumerable ones).
• Primitive values (including null, undefined, strings, numbers, etc.) and functions are wrapped in a NonError error and serialized.
• Buffer properties are replaced with [object Buffer].
• Circular references are handled.
• If the input object has a .toJSON() method, then it's called instead of serializing the object's properties.
• It's up to .toJSON() implementation to handle circular references and enumerability of the properties.

Type: Error | unknown

import{serializeError}from'serialize-error';classErrorWithDateextendsError{constructor(){super();this.date=newDate();}}consterror=newErrorWithDate();console.log(serializeError(error));//=> {date: '1970-01-01T00:00:00.000Z', name, message, stack}

import{serializeError}from'serialize-error';consterror=newError('Unicorn');error.horn={toJSON(){return'x';}};serializeError(error);// => {horn: 'x', name, message, stack}

Deserialize a plain object or any value into an Error object.

• Error objects are passed through.
• Objects that have at least a message property are interpreted as errors.
• All other values are wrapped in a NonError error.
• Custom properties are preserved.
• Non-enumerable properties are kept non-enumerable (name, message, stack, cause).
• Enumerable properties are kept enumerable (all properties besides the non-enumerable ones).
• Circular references are handled.
• Native error constructors are preserved (TypeError, DOMException, etc) and more can be added.

Type: {message: string} | unknown

Type: object

Type: number
Default: Number.POSITIVE_INFINITY

The maximum depth of properties to preserve when serializing/deserializing.

import{serializeError}from'serialize-error';consterror=newError('🦄');error.one={two: {three: {}}};console.log(serializeError(error,{maxDepth: 1}));//=> {name: 'Error', message: '🦄', one: {}}console.log(serializeError(error,{maxDepth: 2}));//=> {name: 'Error', message: '🦄', one: { two: {}}}

Type: boolean
Default: true

Indicate whether to use a .toJSON() method if encountered in the object. This is useful when a custom error implements its own serialization logic via .toJSON() but you prefer to not use it.

Predicate to determine whether a value looks like an error, even if it's not an instance of Error. It must have at least the name, message, and stack properties.

import{isErrorLike}from'serialize-error';consterror=newError('🦄');error.one={two: {three: {}}};isErrorLike({name: 'DOMException',message: 'It happened',stack: 'at foo (index.js:2:9)',});//=> trueisErrorLike(newError('🦄'));//=> trueisErrorLike(serializeError(newError('🦄')));//=> trueisErrorLike({name: 'Bluberricious pancakes',stack: 12,ingredients: 'Blueberry',});//=> false