serify - reversibly transform an unserializable value into a serializable one

deserify - do the exact opposite

Why?

JSON.stringify and JSON.parse are a notoriously bad serializer/deserializer combination. They don't support important Javascript types like BigInt, Date, Map, and Set. Thanks to backward compatibility risk, they probably never will.

There are tons of custom serializers that address this issue, notably serialize-javascript and serializr. Unfortunately, some key Javascript tools like Redux explicitly depend on JSON.stringify & JSON.parse. So if you use Redux, none of those fancy serializers will help you get a Date or a BigInt into your store and back out again in one piece.

serify solves this problem by encoding those values (or structures containing them) into values that JSON.stringify can serialize without throwing an exception. After these values are retrieved and deserialized with JSON.parse, deserify returns them to their original state.

Usage

To install the package, run this command:

npm install @karmaniverous/serify-deserify

Review the unit tests for simple examples of how to use serify and deserify.

Click here for a fully worked out example using the Redux middleware.

Serifiable Types

serify and deserify will work on values of any serifiable type.

A serifiable type is any type that is:

• reversibly supported by JSON.stringify and JSON.parse, i.e. booleans, numbers, strings, plain objects, and arrays
• natively supported by serify, i.e. BigInt, Date, Map, and Set
• added to serify as a custom type
• composed exclusively of any of the above (e.g. an array of BigInt-keyed Maps of objects containing Sets of custom class instances).

To create a new serifiable type or to modify the behavior or an existing one, just pass in an options object that follows the default options pattern.

serifyKey

Consider the highly unlikely event that some data you retrieve from your Redux store contains objects with exactly this form that were not produced by serify:

{
  serifyKey: null,
  type: <string>,
  value: <any>
}

deserify will attempt to deserify this object and your process will fail. In this case, simply add a non-null serifyKey of a serifiable primitive type (meaning a boolean, number, or string) to your options object and everything will work again.

Redux

The createReduxMiddleware function generates a Redux middleware that will serify every value pushed to your Redux store. If you use Redux Toolkit, leave the default serializeCheck middleware in place and it will notify you if you need to add a new type to your serify options!

When retrieving values from the Redux store, either deserify them explicitly or wrap your selectors in the deserify function.

createReduxMiddleware will work anyplace Redux is used, but we're all supposed to be using Redux Toolkit now.

Click here for a fully worked out example using the Redux middleware.

API Documentation

Constants

serifyKey

static property name to override an object's serify key

Functions

createReduxMiddleware([options]) ⇒ function

create redux middleware

deserify([value], [options]) ⇒ *

deserify a value

serify([value], [options]) ⇒ *

serify a value

Typedefs

serifierCallback ⇒ *

callback to serify a custom type.

deserifierCallback ⇒ *

callback to deserify a custom type.

OptionsType : Object

serify-deserify options type

OptionsTypes : Object

serify-deserify options types

Options : Object

serify-deserify options object

serifyKey

static property name to override an object's serify key

Kind: global constant

createReduxMiddleware([options]) ⇒ function

create redux middleware

Kind: global function
Returns: function - redux middleware

deserify([value], [options]) ⇒ *

deserify a value

Kind: global function
Returns: * - deserified value

serify([value], [options]) ⇒ *

serify a value

Kind: global function
Returns: * - serified value

serifierCallback ⇒ *

callback to serify a custom type.

Kind: global typedef
Returns: * - serified value

deserifierCallback ⇒ *

callback to deserify a custom type.

Kind: global typedef
Returns: * - unserified value

OptionsType : Object

serify-deserify options type

Kind: global typedef
Properties

OptionsTypes : Object

serify-deserify options types

Kind: global typedef
Properties

Options : Object

serify-deserify options object

Kind: global typedef
Properties

See more great templates and other tools on my GitHub Profile!