serialize-anything

A universal serializer and de-serializer for JavaScript data

Overview

serialize-anything serializes and de-serializes virtually all JavaScript standard and custom data types, with no data modification.

Compared to commonly used serialize/deserialze methods which convert only a subset of JavaScript data types — serialize-anything converts more without loss of any data.

Exceptions

1. There are two JavaScript types that serialize-anything does not support: WeakMap and WeakSet. Since there is no known way to enumerate their values, they can't be serialized.

Data Types Supported

Comparing support for data types in the most popular methods.

Legend:     ❌ - Error     🗑 - data loss     ✅ - correct

Data Type | JSON.* | s-javascript | s-to-js | s-anything ---------------------- | ------ | ------------ | ------- | ---------- Date | 🗑 | ✅ | ✅ | ✅ RegExp | 🗑 | ✅ | ✅ | ✅ Buffer | 🗑 | 🗑 | ✅ | ✅ Error | 🗑 | 🗑 | ✅ | ✅ BigInt | ❌ | ❌ | 🗑 | ✅ undefined | ❌ | ✅ | ✅ | ✅ {prop: undefined} | 🗑 | ✅ | ✅ | ✅ TypedArray | 🗑 | 🗑 | ✅ | ✅ Map | 🗑 | ✅ | ✅ | ✅ Set | 🗑 | ✅ | ✅ | ✅ Custom Object | 🗑 | 🗑 | 🗑 | ✅ Custom Array | 🗑 | 🗑 | 🗑 | ✅ BigInt64Array | ❌ | ❌ | 🗑 | ✅ BigUint64Array | ❌ | ❌ | 🗑 | ✅ Function | ❌ | ✅ | ❌ | ✅ ArrayBuffer | 🗑 | ✅ | ❌ | ✅ WeakSet | 🗑 | 🗑 | ❌ | ❌ WeakMap | 🗑 | 🗑 | ❌ | ❌ Circular reference | ❌ | ❌ | ❌ | ✅

      JSON.* — JSON.stringify/parse       s-javascript — serialize-javascript       s-to-js — serialize-to-js       s-anything — serialize-anything

Installation

Install as a Node.js module:

 $ npm install serialize-anything

Or download a package from github.

Usage

Node.js:

const SerAny = require('serialize-anything');

// copied from `custom-objects.js` to handle custom objects (optional)
SerAny._custom = function (name) {
  let typeExists = eval('typeof ' + name + '!== "undefined"' );
  return typeExists ? eval('new ' + name + '()') : null;
};
SerAny._ds = SerAny.deserialize;
SerAny.deserialize = source => SerAny._ds(source, SerAny._custom);

From HTML file:

<script src="serialize-any.js"></script>
<script>
    // copied from `custom-objects.js` to handle custom objects (optional)
    SerAny._custom = function (name) {
      let typeExists = eval('typeof ' + name + '!== "undefined"' );
      return typeExists ? eval('new ' + name + '()') : null;
    };
    SerAny._ds = SerAny.deserialize;
    SerAny.deserialize = source => SerAny._ds(source, SerAny._custom);
</script>

To serialize:

// serialize
serialized = SerAny.serialize(source);

To deserialize:

// deserialize
deserialized = SerAny.deserialize(serialized);

Example

Serialize some challenging data:

const custom = new CustomObj();
custom.foo = 'bar';
custom.baz = custom; // circular reference
let source = {
  undef: undefined,
  regexp: /abc/gi,
  bignum: 4000000000000000000n,
  map: new Map([[1, 'one'], [2, 'two']]),
  custom,
  buffer: Buffer.from("hello world")
};

/* source:
{
  undef: undefined,
  regexp: /abc/gi,
  bignum: 4000000000000000000n,
  map: Map(2) { 1 => 'one', 2 => 'two' },
  custom: CustomObj <ref *1> { foo: 'bar', baz: [Circular *1] },
  buffer: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
}
*/

const ser = SerAny.serialize(source);

Serialized result (JSON):

{
  "_Serialize_Any_Encoded": true,
  "_SA_Content": {
    "undef": { "_SAType": "undef" },
    "regexp": {
      "_SAType": "RegExp",
      "_SAId": 1,
      "_SAsource": "abc",
      "_SAflags": "gi"
    },
    "bignum": {
      "_SAType": "BigInt",
      "_SAnum": "4000000000000000000"
    },
    "map": {
      "_SAType": "Map",
      "_SAId": 2,
      "_SAkvPairs": [ [1, "one"], [2,"two"] ]
    },
    "custom": {
      "_SAType": "_SACustomObject",
      "_SAId": 3,
      "_SAconstructorName": "CustomObj",
      "_SAobject": { "foo": "bar", "baz": { "_SAType": "_SACustomObjectRef", "_SAId": 3 } }
    },
    "buffer": {
      "_SAType": "Buffer",
      "_SAutf8String": "hello world"
    }
  }
}

Deserialized:

const deser = SerAny.deserialize(ser);

/* deser:
{
  undef: undefined,
  regexp: /abc/gi,
  bignum: 4000000000000000000n,
  map: Map(2) { 1 => 'one', 2 => 'two' },
  custom: CustomObj <ref *1> { foo: 'bar', baz: CustomObj [Circular *1] },  
  buffer: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
}
*/

Functions

SerAny.serialize()

Serialize JavaScript data

Syntax

SerAny.serialize(source [, options])

Parameters

source     The JavaScript data to serialize

options     (Object) [optional] - Control the serializer's behavior.

options properties:

    maxDepth        (number) [optional] - Limit the number of levels        into the source data. Throws an error if source's        depth is greater than maxDepth. Default is 20 levels.

    pretty        (boolean) [optional] - Return serialized data in        pretty format if true. Default is false - not pretty.

Return value

(string) - The serialized data.

SerAny.deserialize()

Restore serialized data created by SerAny.serialize().

Syntax

SerAny.deserialize(source)

Parameters

source     (string) - Serialized data that was created by SerAny.serialize()

Return value

(any type) - The de-serialized data, matching the type of the original source.