deserializable

Utilities for automatically deserializing certain JavaScript objects and instances.

Table of contents

1. Installation
2. Usage (basic)
3. Usage (advanced)
4. Supported types
5. Example

Installation

npm install deserializable --save

Usage (basic)

Two main exports:

stringify (Mixed value, Optional Mixed space)

Uses JSON.stringify under the hood, but for types that will lose their original form when using JSON.parse on the result (e.g., ES6 Map ES6 Set, Date, RegExp, etc.), it returns an object resembling { __type__, __value__ } so that this package's parse export can return the proper value.

parse (String value)

Uses JSON.parse under the hood, but when an object is found containing a __type__ and __value__, it will attempt to recontruct the proper value using either global[__type__].fromJSON(__value__) (if the fromJSON static method exists) or new global[__type__](__value__).

Usage (advanced)

And other exports that may be useful to you if you have more complex requirements:

getType (Mixed value)

Gets the type of some value if it has a toJSON method and is not typically properly deserialized using JSON.parse.

fixedTypes

Simple object containing toJSON and fromJSON methods for each type. Used for providing enforcing specific methods for certain types. For example, the native Map doesn't have toJSON or fromJSON methods but we fix this by setting:

fixedTypes.Map = {
  toJSON: value => [ ...value ],
  fromJSON: value => new Map(value)
};

ignoredTypes

Simple object containing known deserializable types using JSON.parse. The getType function uses this internally.

reviver (String key, Mixed value)

The parse function uses this internally to return the proper value.

patchAll (Object obj, RegExp ignore)

Since JSON.stringify calls toJSON on values before the replacer function argument receives each value, we have to monkey-patch each prototype.toJSON to attempt to get a type using getType and then return the new value if necessary - i.e., { __type__, __value__ } - which will only occur if this package's stringify method is called, otherwise it will return toJSON's usual value. The patchAll function is immediately called on the window (or global), but you can use it to patch other constructors as values within the obj argument.

patch (String key, Function fn)

Patches the function.

Supported types

This should work for any constructor containing prototype.toJSON, and if you have some special requirements when reconstructing the value using parse, attach a fromJS static method to the constructor. The following types are tested:

Map

ES6 Map instance

Set

ES6 Set instance

Date

Date instance

RegExp

RegExp instance

Note: This package adds prototype.toJSON and fromJSON to the RegExp constructor. See index.js.

Example

See redux-replicate-localforage.