Universal Serialize and Deserialize

Common errors

• SyntaxError: Unexpected token 'u' in JSON at position X

  cause Attempting to deserialize an invalid JSON string, or a string that is not valid JSON produced by `universal-serialize`.
  fix Ensure the input to `deserialize()` is a valid JSON string. Check that the string was correctly produced by `serialize()` and not corrupted or truncated. Use a JSON linter to validate the string if necessary.

• TypeError: Cannot read properties of undefined (reading 'stack')

  cause An `Error` object was serialized, but its prototype chain or properties were not fully restored during deserialization, leading to a plain object that lacks `Error` methods.
  fix While `universal-serialize` claims to handle `Error` objects, ensure that the deserialized `error` property is correctly re-instantiated as an `Error` object. If custom serialization was used, verify the `deserialize` handler correctly reconstructs the `Error` instance.

• ReferenceError: TYPE is not defined

  cause `TYPE` constant was used in a custom serialization/deserialization handler without being imported.
  fix Add `import { TYPE } from 'universal-serialize';` to the top of your file where `TYPE` is used.

Warnings

• breaking The package appears to be abandoned with its last release over seven years ago. There will be no further updates, bug fixes, or security patches, which could lead to compatibility issues with newer JavaScript features or runtime environments.
  Fix: Consider migrating to a actively maintained serialization library that supports modern JavaScript features and provides ongoing security support. For simple cases, `JSON.stringify`/`parse` with custom `replacer`/`reviver` functions can suffice.
• gotcha Using `eval()` in custom deserialization handlers (as shown in the README example for functions) is a significant security risk. Maliciously crafted serialized data could execute arbitrary code on the deserializing system.
  Fix: Avoid `eval()` for deserializing executable code. If functions must be transmitted, consider safer alternatives like serializing ASTs or limiting functions to a pre-defined whitelist of known, safe operations. Re-evaluate if deserializing functions directly is a necessary requirement.
• gotcha The library does not explicitly mention handling circular references. Serializing objects with circular structures using this library (or any serializer without specific handling) can lead to infinite loops or stack overflows during serialization.
  Fix: Ensure objects to be serialized are free of circular references. If circular references are unavoidable, pre-process the object to break cycles (e.g., replacing references with placeholders) or use a serializer specifically designed to handle them.
• gotcha Lack of support for newer JavaScript types such as `BigInt`, `Symbol`, `Map`, `Set`, `Promise`, `WeakMap`, `WeakSet`, or custom classes beyond the explicitly defined custom types. These will likely not be serialized or deserialized correctly by default.
  Fix: Implement custom serialization and deserialization handlers for any modern JavaScript types or custom classes that need to be preserved. For `BigInt`, ensure it's converted to a string before serialization and parsed back on deserialization. For `Map`/`Set`, convert to arrays/objects.

Install

• npm install universal-serialize npm
• yarn add universal-serialize yarn
• pnpm add universal-serialize pnpm

Imports

• serialize
  wrong:

  const serialize = require('universal-serialize').serialize;

  correct:

  import { serialize } from 'universal-serialize';

  ESM is shown in README; CommonJS requires accessing named exports from the module object.
• deserialize
  wrong:

  const deserialize = require('universal-serialize').deserialize;

  correct:

  import { deserialize } from 'universal-serialize';

  ESM is shown in README; CommonJS requires accessing named exports from the module object.
• TYPE
  wrong:

  const TYPE = require('universal-serialize').TYPE;

  correct:

  import { TYPE } from 'universal-serialize';

  TYPE is an object containing predefined string constants for built-in serialization types, used for custom handlers.

Quickstart

This example demonstrates basic serialization and deserialization of an object containing strings, dates, errors, and regular expressions, showing how `universal-serialize` preserves their types.

import { serialize, deserialize } from 'universal-serialize';

// Define a complex object with built-in non-primitive types
const originalObject = {
  foo: 'bar',
  date: new Date('2023-01-01T12:00:00.000Z'),
  error: new Error('Something went wrong'),
  regex: /test/gi
};

// Serialize the complex object into a JSON string
const jsonString = serialize(originalObject);
console.log('Serialized JSON:', jsonString);

// Deserialize the JSON string back into an object
const deserializedObject = deserialize(jsonString);

// Verify the types and values of the deserialized objects
console.log('Deserialized foo:', deserializedObject.foo);
console.log('Deserialized date (instanceof Date):', deserializedObject.date instanceof Date);
console.log('Deserialized date (value):', deserializedObject.date.toISOString());
console.log('Deserialized error (instanceof Error):', deserializedObject.error instanceof Error);
console.log('Deserialized error (message):', deserializedObject.error.message);
console.log('Deserialized regex (instanceof RegExp):', deserializedObject.regex instanceof RegExp);
console.log('Deserialized regex (value):', deserializedObject.regex.source);