serialize-anything
Version:
serialize and de-serialize any JavaScript data
223 lines (197 loc) • 7.52 kB
Markdown
# serialize-anything
A universal serializer and de-serializer for JavaScript data
[](https://codebeat.co/projects/github-com-terrymorse58-serialize-anything-master)
[](https://twitter.com/terrymorse)
## 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<br>
s-javascript — [serialize-javascript](https://github.com/yahoo/serialize-javascript) <br>
s-to-js — [serialize-to-js](https://github.com/commenthol/serialize-to-js) <br>
s-anything — [serialize-anything](https://github.com/terrymorse58/serialize-anything)
## Installation
Install as a Node.js module:
```
$ npm install serialize-anything
```
Or download a package from [github](https://github.com/terrymorse58/serialize-anything.git).
## Usage
Node.js:
```javascript
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:
```HTML
<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:
```javascript
// serialize
serialized = SerAny.serialize(source);
```
To deserialize:
```javascript
// deserialize
deserialized = SerAny.deserialize(serialized);
```
### Example
Serialize some challenging data:
```javascript
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):
```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:
```javascript
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
```javascript
SerAny.serialize(source [, options])
```
#### Parameters
`source`<br>
The JavaScript data to serialize
`options`<br>
(Object) *[optional]* - Control the serializer's behavior.
`options` properties:
`maxDepth`<br>
(number) *[optional]* - Limit the number of levels<br>
into the source data. Throws an error if source's<br>
depth is greater than *maxDepth*. Default is 20 levels.
`pretty`<br>
(boolean) *[optional]* - Return serialized data in<br>
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
```javascript
SerAny.deserialize(source)
```
#### Parameters
`source`<br>
(string) - Serialized data that was created by `SerAny.serialize()`
#### Return value
(any type) - The de-serialized data, matching the type of the original source.