serialize-error

What is serialize-error?

The serialize-error npm package is used to serialize error objects into plain objects, retaining as much information as possible. It can be useful for logging errors or sending them over the network, as standard Error objects may not be properly serialized by default JSON.stringify.

What are serialize-error's main functionalities?

Serialize an Error object

This feature allows you to serialize a standard Error object into a JSON-friendly format, including properties like name, message, and stack.

{"error": {"name": "Error", "message": "An error occurred!", "stack": "Error: An error occurred!\n    at Object.<anonymous> (/path/to/file.js:2:15)\n    at Module._compile (internal/modules/cjs/loader.js:1137:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1157:10)\n    at Module.load (internal/modules/cjs/loader.js:985:32)\n    at Function.Module._load (internal/modules/cjs/loader.js:878:14)\n    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:71:12)\n    at internal/main/run_main_module.js:17:47"}}

Serialize custom error properties

This feature allows you to serialize Error objects that have custom properties beyond the standard Error properties.

{"error": {"name": "CustomError", "message": "Something custom happened!", "customProperty": "Custom value", "stack": "CustomError: Something custom happened!\n    at Object.<anonymous> (/path/to/file.js:2:15)\n    at Module._compile (internal/modules/cjs/loader.js:1137:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1157:10)\n    at Module.load (internal/modules/cjs/loader.js:985:32)\n    at Function.Module._load (internal/modules/cjs/loader.js:878:14)\n    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:71:12)\n    at internal/main/run_main_module.js:17:47"}}

Other packages similar to serialize-error

error-to-json

This package is similar to serialize-error in that it provides a way to serialize error objects to JSON. It may differ in the specific implementation or additional options provided for serialization.

serialize-javascript

While not exclusively for error objects, serialize-javascript allows for the serialization of JavaScript expressions, including errors. It can serialize functions, regexes, and dates, in addition to errors, which may make it more versatile in some scenarios compared to serialize-error.

README

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

npm install serialize-error

Usage

import {serializeError, deserializeError} from 'serialize-error';

const error = new Error('🦄');

console.log(error);
//=> [Error: 🦄]

const serialized = serializeError(error)

console.log(serialized);
//=> {name: 'Error', message: '🦄', stack: 'Error: 🦄\n    at Object.<anonymous> …'}

const deserialized = deserializeError(serialized);

console.log(deserialized);
//=> [Error: 🦄]

API

serializeError(value, options?)

Type: Error | unknown

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.

.toJSON examples:

import {serializeError} from 'serialize-error';

class ErrorWithDate extends Error {
	constructor() {
		super();
		this.date = new Date();
	}
}

const error = new ErrorWithDate();

serializeError(error);
// => {date: '1970-01-01T00:00:00.000Z', name, message, stack}

import {serializeError} from 'serialize-error';

class ErrorWithToJSON extends Error {
	constructor() {
		super('🦄');
		this.date = new Date();
	}

	toJSON() {
		return serializeError(this);
	}
}

const error = new ErrorWithToJSON();

console.log(serializeError(error));
// => {date: '1970-01-01T00:00:00.000Z', message: '🦄', name, stack}

deserializeError(value, options?)

Type: {[key: string]: unknown} | unknown

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

• Error objects are passed through.
• Non-error values are wrapped in a NonError error.
• 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).
• Circular references are handled.

options

Type: object

maxDepth

Type: number
Default: Number.POSITIVE_INFINITY

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

import {serializeError} from 'serialize-error';

const error = new Error('🦄');
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: {}}}