176 lines
8.8 KiB
Markdown
176 lines
8.8 KiB
Markdown
|
|
[](https://coveralls.io/github/shaochuancs/esserializer?branch=master)
|
|
[](https://codeclimate.com/github/shaochuancs/esserializer/maintainability)
|
|
|
|
# esserializer
|
|
ESSerializer is a JavaScript serialization and deserialization utility.
|
|
|
|
With ESSerializer, you can serialize JavaScript class instance in JSON format, and later on deserialize it into an instance object, with all Class/Property/Method etc. retained, recursively.
|
|
This works in both browser and Node.js environment. ESSerializer also support almost all builtin classes and types.
|
|
|
|
No `eval` is used during serialization or deserialization. ESSerializer does not introduce any security risk.
|
|
|
|
## Features
|
|
ESSerializer offers following features:
|
|
* Retain class information of instance field value, recursively
|
|
* Retain class extension structure
|
|
* Detect class definition automatically, during serialization and deserialization
|
|
* Support both ES6 class and old function style class
|
|
* Support following operator during serialization & deserialization:
|
|
* getter & setter
|
|
* instanceof
|
|
* Support following JavaScript builtin class and type:
|
|
* Array (and all 11 specific array types)
|
|
* ArrayBuffer & SharedArrayBuffer
|
|
* BigInt
|
|
* Boolean
|
|
* DataView
|
|
* Date
|
|
* Error (and all 7 sub-error classes)
|
|
* Infinity
|
|
* Intl (and all 7 specific internationalization classes)
|
|
* Map (with ESSerializer Pro)
|
|
* NaN
|
|
* RegExp
|
|
* Set
|
|
* String
|
|
* Symbol (with ESSerializer Pro)
|
|
* undefined
|
|
* Support properties defined by `Object.defineProperty()` or `Object.defineProperties`.
|
|
* Support ignoring target properties during serialization or deserialization
|
|
* Support intercept target properties during serialization
|
|
* Support circular structure (with ESSerializer Pro)
|
|
|
|
## Installation
|
|
```sh
|
|
$ npm install esserializer --save
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Import the module
|
|
|
|
For ES6:
|
|
|
|
```js
|
|
import ESSerializer from 'esserializer';
|
|
```
|
|
|
|
Or for CommonJS:
|
|
```js
|
|
const ESSerializer = require('esserializer');
|
|
```
|
|
|
|
### Serialization
|
|
To serialize JavaScript object, invoke ESSerializer's `serialize` method:
|
|
|
|
```js
|
|
const ClassA = require('./ClassA');
|
|
|
|
const obj = new ClassA();
|
|
// do something here, such as obj.methodOfClassA()
|
|
const serializedString = ESSerializer.serialize(obj);
|
|
```
|
|
|
|
### Deserialization
|
|
To deserialize text and turn it into a corresponding instance object, invoke ESSerializer's `deserialize` method,
|
|
with all involved custom classes as parameter (you don't need to include builtin classes such as `Date` in this parameter):
|
|
```js
|
|
const ESSerializer = require('esserializer');
|
|
const ClassA = require('./ClassA');
|
|
const ClassB = require('./ClassB');
|
|
const ClassC = require('./ClassC');
|
|
|
|
const deserializedObj = ESSerializer.deserialize(serializedString, [ClassA, ClassB, ClassC]);
|
|
```
|
|
|
|
You can also make ESSerializer detecting those involved custom classes automatically, please check [Advanced usage](#Deserialization-1) for detail.
|
|
|
|
## Demo
|
|
Please check the [demo](https://github.com/shaochuancs/esserializer/tree/master/demo) page for all examples:
|
|
* [basic.js](https://github.com/shaochuancs/esserializer/blob/master/demo/basic.js)
|
|
* [support_of_OO_extension.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_OO_extension.js)
|
|
* [support_of_array.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_array.js)
|
|
* [support_of_builtin_types.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_builtin_types.js)
|
|
* [support_of_date.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_date.js)
|
|
* [support_of_deserialize_options.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_deserialize_options.js)
|
|
* [support_of_function_style_class_definition.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_function_style_class_definition.js)
|
|
* [support_of_intercept_require.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_intercept_require.js)
|
|
* [support_of_properties_defined_in_constructor.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_properties_defined_in_constructor.js)
|
|
* [support_of_register_classes.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_register_classes.js)
|
|
* [support_of_serialize_options.js](https://github.com/shaochuancs/esserializer/blob/master/demo/support_of_serialize_options.js)
|
|
|
|
## Advanced usage
|
|
|
|
### Serialization
|
|
You can also pass an options object during serialization and ignore unwanted properties, or intercept target properties:
|
|
|
|
```js
|
|
const serializedString = ESSerializer.serialize(obj, {
|
|
ignoreProperties: ['unwantedFieldX', 'unwantedFieldY'],
|
|
interceptProperties: {
|
|
propertyX: function (value) {
|
|
return value + 1; // After serialization, value of propertyX would be equal to its original value plus 1. Also, "this" can be used here to represent obj.
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
Serialization options:
|
|
|
|
| Option | Type | Description |
|
|
|---------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| ignoreProperties | Array | Array of string, represent all properties that would be ignored. |
|
|
| interceptProperties | Object | Object whose key represents property to be intercepted, and its Function value represents how to intercept. The function would take properties' original value as its first parameter. |
|
|
|
|
### Deserialization
|
|
You can also register some classes globally for deserialization. Once class is registered, it will be remembered by ESSerializer in all files:
|
|
```js
|
|
ESSerializer.registerClasses([ClassA, ClassB, ClassC]);
|
|
const deserializedObj = ESSerializer.deserialize(serializedString);
|
|
```
|
|
|
|
Or, you can let ESSerializer intercept require operation and detect classes automatically. Once class is detected, it will
|
|
be remembered by ESSerializer in all files:
|
|
```js
|
|
ESSerializer.interceptRequire();
|
|
require('./ClassA');
|
|
require('./ClassB');
|
|
require('./ClassC');
|
|
const deserializedObj = ESSerializer.deserialize(serializedString);
|
|
```
|
|
|
|
Custom-Classes-Parameter / Class-Registry / Require-Interception, these 3 methods can be used in combination during deserialzation.
|
|
|
|
During deserialization, you can also pass an options object to indicate which fields of parsed object can be used as constructor parameters:
|
|
|
|
```js
|
|
const User = require('./User');
|
|
const serializedString = '{"idNum":"P123456","name":"Mike","ess_cn":"User"}';
|
|
const deserializedObj = ESSerializer.deserialize(serializedString, [User], {
|
|
fieldsForConstructorParameters: ['idNum', 'name']
|
|
}); // value of field 'idNum' ('P123456') and 'name' ('Mike') will be used as constructor parameters to initialize User instance.
|
|
```
|
|
|
|
Deserialization options:
|
|
|
|
| Option | Type | Description |
|
|
|--------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| fieldsForConstructorParameters | Array | Array of string, represent fields of parsed object whose value would be used as constructor parameters. |
|
|
| ignoreProperties | Array | Array of string, represent all properties that would be ignored. |
|
|
| rawProperties | Array | Array of string, represent all properties whose raw text value would be retained in deserialization result. |
|
|
|
|
## ESSerializer Pro
|
|
With a cup of coffee ($5), you can download & update ESSerializer Pro and get following additional features:
|
|
* Support circular structure
|
|
* Support additional builtin object and type:
|
|
* Map
|
|
* Symbol
|
|
|
|
Please contact shaochuancs@gmail.com if you are interested.
|
|
|
|
## License
|
|
(The MIT License for ESSerializer and private license for ESSerializer Pro)
|
|
|
|
Copyright (c) 2019-2023 Chuan Shao <shaochuancs@gmail.com>
|