better-json-serializer v3.0.0

Better JSON Serializer

A tool that enables to use non-standard types in JSON (such as Sets, Maps, etc).

import BetterJSONSerializer from 'better-json-serializer';
import { PluginSet } from 'better-json-serializer/plugins';

const serializer = new BetterJSONSerializer();

serializer.use(PluginSet);

const obj = {
  a: new Set([1, 2, false, 'b', null]),
};

console.log(obj.a instanceof Set); // ==> true
console.log(obj.a); // ==> Set(5) { 1, 2, false, 'b', null }

const str = serializer.stringify(obj);

console.log(typeof str); // ==> 'string'

const secondObj = serializer.parse(str);

console.log(secondObj.a instanceof Set); // ==> true
console.log(secondObj.a); // ==> Set(5) { 1, 2, false, 'b', null }

Installation

$ npm install better-json-serializer

Features

• No external dependencies
• Support for any kind of non-standard object
• Minimal setup required
• Easy to implement
• Full Typescript support
• Easily extendable using custom plugins

Usage

// Import the main class
import BetterJSONSerializer from 'better-json-serializer';
// Import any additional default plugins
import { PluginSet } from 'better-json-serializer/plugins';

// Create an instance
const serializer = new BetterJSONSerializer();

// Configure it (if needed)
serializer.config.serializedObjectIdentifier = '_@serialized-object-identifier';

// Load the appropriate plugin(s)
serializer.use(PluginSet);

// Start using it
const str = serializer.stringify(new Set([1, 2, false, 'b', null])); // ==> A string
const obj = serializer.parse(str); // ==> Set(5) { 1, 2, false, 'b', null }

Configuration

Configuration properties

Accessing the configuration

The configuration can be accessed using the .config property on the instance of the serializer.

const serializer = new BetterJSONSerializer();

// Retrieve the whole configuration
console.log(serializer.config);

// Retrieve only a single configuration property
console.log(serializer.config.serializedObjectIdentifier);

Trying to get a configuration property that does not exist will throw a ReferenceError.

Updating the configuration

Configuration properties can be updated by accessing the .config property on the instance of the serializer.

const serializer = new BetterJSONSerializer();

// Update a configuration property
serializer.config.serializedObjectIdentifier = 'Foo bar baz';

A TypeError will be thrown while trying to configure the property with an invalid type.

A ReferenceError will be thrown if you try to define a configuration property that does not exist.

Using the package

The main use of the package is based on the interface implemented by the JSON object.

Serializing an object into a string

In order to serialize an object, you need to call the .stringify method on the serializer object.

const serializer = new BetterJSONSerializer();

serializer.stringify(myObj); // ==> Returns a serialized object as a string

Parameters

Return

Deserializing a string into an object

In order to deserialize a JSON string into an object, you need to call the .parse method on the serializer object.

const serializer = new BetterJSONSerializer();

serializer.parse(myString); // ==> Returns a deserialized object

Parameters

Return

Extend with plugins

The package is shipped with default plugins for those objects, however they are not loaded by default:

• BigInt
• Infinity
• Map
• NaN
• RegExp
• Set
• undefined

To load a default plugin, simply import it, and then load it as a normal plugin:

// Import the main class
import BetterJSONSerializer from 'better-json-serializer';

// Import the plugin for 'Set'
import { PluginSet } from 'better-json-serializer/plugins';

// Create a serializer instance
const serializer = new BetterJSONSerializer();

// Add the plugin
serializer.use(PluginSet);

You can also load all the default plugins at once:

// Import the main class
import BetterJSONSerializer from 'better-json-serializer';

// Import all the default plugins
import plugins from 'better-json-serializer/plugins';

// Create a serializer instance
const serializer = new BetterJSONSerializer();

// Add the plugins
serializer.use(plugins);

But you can always extend the package by providing your own plugin to the .use method on the serializer. To define a plugin, simply call the createPlugin function that comes with the package:

createPlugin(pluginName, finderFunction, serializeFunction, deserializeFunction)

Both the serializer and deserializer functions accept 2 parameters that are inspired by the replacer/reviver functions from the JSON package:

1. key A string that indicate the key associated with this object
2. value The actuel object to serialize/deserialize

Example

// Import the main class and the createPlugin function
import BetterJSONSerializer, { createPlugin } from 'better-json-serializer';

class Person {
  constructor(firstName, lastName) {
    this.firstName = firstName;
    this.lastName = lastName;
  }

  get fullName() {
    return `${this.firstName}  ${this.lastName}`;
  }
}

const person = new Person('John', 'Doe');

const PersonPlugin = createPlugin(
  'PersonPlugin'
  (value) => value instanceof Person && value.constructor === Person,
  // A function that will serialize the object
  (key, { firstName, lastName }) => ({ firstName, lastName }),
  // A function that will deserialize the serialized object into the original one
  (key, { firstName, lastName }) => Object.assign(Object.create(Person.prototype), {
    firstName,
    lastName,
  }),
);

const serializer = new BetterJSONSerializer();

serializer.use(PersonPlugin);

const serializedPerson = serializer.stringify(person);

console.log(typeof serializedPerson); // ==> 'string'

const deserializedPerson = serializer.parse(serializedPerson);

console.log(deserializedPerson instanceof Person); // ==> true
console.log(deserializedPerson.fullName); // ==> 'John Doe'

Changelog

v3.0.0 - November 3th 2021

Changes

• Added new built-in plugins for special cases values:
  • Infinity
  • NaN
  • undefined

Breaking changes

• Reworked configuration management

   Configuration is now managed by the .config property on the serializer instance.

• Removed version property from serialized object.

  This property was already unused and was taking space on the serialized object making it heavier for nothing.

• Removed built-in plugin for null, value will be inserted as native JSON's null value.
• Plugins are now middlewares, deferring the roles to them to identify if a value should be serialized instead of leaving the job to the serializer