serialize-error

Serialize/deserialize an error into a plain object

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

Install

1npm install serialize-error

Usage

1import {serializeError, deserializeError} from 'serialize-error';
2
3const error = new Error('🦄');
4
5console.log(error);
6//=> [Error: 🦄]
7
8const serialized = serializeError(error);
9
10console.log(serialized);
11//=> {name: 'Error', message: '🦄', stack: 'Error: 🦄\n    at Object.<anonymous> …'}
12
13const deserialized = deserializeError(serialized);
14
15console.log(deserialized);
16//=> [Error: 🦄]

Error constructors

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:

1import {deserializeError} from 'serialize-error';
2
3const known = deserializeError({
4	name: 'TypeError',
5	message: '🦄'
6});
7
8console.log(known);
9//=> [TypeError: 🦄] <-- Still a TypeError
10
11const unknown = deserializeError({
12	name: 'TooManyCooksError',
13	message: '🦄'
14});
15
16console.log(unknown);
17//=> [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.

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

Warning: The constructor must work without any arguments or this function will throw.

API

serializeError(value, options?)

Serialize an Error object into a plain object.

• Non-error values are passed through.
• 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).
• 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.

value

Type: Error | unknown

toJSON implementation examples

1import {serializeError} from 'serialize-error';
2
3class ErrorWithDate extends Error {
4	constructor() {
5		super();
6		this.date = new Date();
7	}
8}
9
10const error = new ErrorWithDate();
11
12serializeError(error);
13// => {date: '1970-01-01T00:00:00.000Z', name, message, stack}

1import {serializeError} from 'serialize-error';
2
3const error = new Error('Unicorn');
4
5error.horn = {
6	toJSON() {
7		return 'x';
8	}
9};
10
11serializeError(error);
12// => {horn: 'x', name, message, stack}

deserializeError(value, options?)

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.

value

Type: {message: string} | unknown

options

Type: object

maxDepth

Type: number
Default: Number.POSITIVE_INFINITY

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

1import {serializeError} from 'serialize-error';
2
3const error = new Error('🦄');
4error.one = {two: {three: {}}};
5
6console.log(serializeError(error, {maxDepth: 1}));
7//=> {name: 'Error', message: '🦄', one: {}}
8
9console.log(serializeError(error, {maxDepth: 2}));
10//=> {name: 'Error', message: '🦄', one: { two: {}}}

useToJSON

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.

isErrorLike(value)

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.

1import {isErrorLike} from 'serialize-error';
2
3const error = new Error('🦄');
4error.one = {two: {three: {}}};
5
6isErrorLike({
7	name: 'DOMException',
8	message: 'It happened',
9	stack: 'at foo (index.js:2:9)',
10});
11//=> true
12
13isErrorLike(new Error('🦄'));
14//=> true
15
16isErrorLike(serializeError(new Error('🦄'));
17//=> true
18
19isErrorLike({
20	name: 'Bluberricious pancakes',
21	stack: 12,
22	ingredients: 'Blueberry',
23});
24//=> false