superserial

A comprehensive Serializer/Deserializer that can handle any data type.

Usage

with Deno

1deno add @denostack/superserial

1import { Serializer } from "@denostack/superserial";
2
3const serializer = new Serializer();
4
5const nodes = [{ self: null as any, siblings: [] as any[] }, {
6  self: null as any,
7  siblings: [] as any[],
8}];
9nodes[0].self = nodes[0];
10nodes[0].siblings = nodes;
11nodes[1].self = nodes[1];
12nodes[1].siblings = nodes;
13
14const serialized = serializer.serialize(nodes);
15
16console.log(serialized);
17// [$1,$2];{"self":$1,"siblings":$0};{"self":$2,"siblings":$0}

with Node.js & Browser

Install

1npm install superserial

1import { Serializer } from "superserial";
2
3// Usage is as above :-)

Index

• Built-in Objects
• Circular Reference
• Class Support

Built-in Objects

Value Properties

• NaN
• Infinity, -Infinity
• undefined

1serializer.serialize({
2  und: undefined,
3  nan: NaN,
4  inf: Infinity,
5  ninf: -Infinity,
6}); // {"und":undefined,"nan":NaN,"inf":Infinity,"ninf":-Infinity}

Fundamental Objects

• Symbol

ETC

• BigInt
• Date
• RegExp
• Map
• Set

1const symbol = Symbol();
2serializer.serialize({
3  sym: symbol,
4  bigint: 100n,
5  date: new Date(),
6  regex: /abc/gmi,
7  map: new Map([["key1", "value1"], ["key2", "value2"]]),
8  set: new Set([1, 2, 3, 4]),
9});
10// {"sym":$1,"bigint":100n,"date":$2,"regex":$3,"map":$4,"set":$5};Symbol();Date(1648740167514);/abc/gim;Map("key1"=>"value1","key2"=>"value2");Set(1,2,3,4)

Circular Reference

Existing JSON functions do not support circular references, but superserial has solved this problem.

1const nodes = [{ self: null as any, siblings: [] as any[] }, {
2  self: null as any,
3  siblings: [] as any[],
4}];
5nodes[0].self = nodes[0];
6nodes[0].siblings = nodes;
7nodes[1].self = nodes[1];
8nodes[1].siblings = nodes;
9
10const serialized = serializer.serialize(nodes);
11
12console.log(serialized);
13// [$1,$2];{"self":$1,"siblings":$0};{"self":$2,"siblings":$0}
14
15const deserialized = serializer.deserialize(serialized) as typeof nodes;
16
17console.log(deserialized === deserialized[0].siblings); // true
18console.log(deserialized[0] === deserialized[0].self); // true
19console.log(deserialized === deserialized[1].siblings); // true
20console.log(deserialized[1] === deserialized[1].self); // true

Circular Set & Map

1const set = new Set();
2set.add(set);
3
4serializer.serialize(set); // Set($0)
5
6const map = new Map();
7map.set(map, map);
8
9serializer.serialize(map); // Map($0=>$0)

Deserialization also works perfectly!

1const set = serializer.deserialize("Set($0)");
2
3console.log(set === [...set][0]); // true
4
5const map = serializer.deserialize("Map($0=>$0)");
6
7console.log(map === [...map.keys()][0]); // true
8console.log(map === map.get([...map.keys()][0])); // true

Class Support

Classes contain methods, getters, etc., but JSON doesn't fully support them. superserial includes features that make it easy to use.

The class to be used for deserialize is defined when the Serializer is created.

1class TestUser {
2  constructor(
3    public name?: string,
4    public age?: number,
5  ) {
6  }
7}
8
9const serializer = new Serializer({ classes: { TestUser } });

Serializes the object and then deserializes it again. Since the original class object is converted as it is, all getters and methods can be used as they are.

1const serialized = serializer.serialize(new TestUser("wan2land", 20));
2console.log(serialized);
3// TestUser{"name":"wan2land","age":20}
4
5const user = serializer.deserialize(serialized);
6console.log(user); // TestUser { name: "wan2land", age: 20 }

Alias

If you want to serialize a class with a different name, you can use the classes option.

1class TestUser {
2  constructor(
3    public name?: string,
4    public age?: number,
5  ) {
6  }
7}
8
9const serializer = new Serializer({
10  classes: {
11    AliasTestUser: TestUser,
12  },
13});

1const serialized = serializer.serialize(new TestUser("wan2land", 20));
2console.log(serialized);
3// AliasTestUser{"name":"wan2land","age":20}   <--- AliasTestUser
4
5const user = serializer.deserialize(serialized);
6console.log(user); // TestUser { name: "wan2land", age: 20 }

toSerialize / toDeserialize

Private variables can be converted using two special symbols (toSerialize, toDeserialize).

When serializing(serialize), the object's data is created based on the toSerialize method. You can check the result of toSerialize by looking at the serialized string.

When deserializing(deserialize), it is impossible to create an object without a constructor call. (ref. No backdoor to access private) If the toDeserialize method is included, a value can be injected through toDeserialize after calling the constructor.

1import {
2  Serializer,
3  toDeserialize,
4  toSerialize,
5} from "https://deno.land/x/superserial/mod.ts";
6
7class TestUser {
8  #_age = 0;
9  constructor(public name: string) {
10    this.#_age = 0;
11  }
12
13  setAge(age: number) {
14    this.#_age = age;
15  }
16
17  getAge() {
18    return this.#_age;
19  }
20
21  [toSerialize]() {
22    return {
23      name: this.name,
24      age: this.#_age,
25    };
26  }
27
28  [toDeserialize](
29    value: {
30      name: string;
31      age: number;
32    },
33  ) {
34    this.name = value.name;
35    this.#_age = value.age;
36  }
37}
38
39const serializer = new Serializer({ classes: { TestUser } });
40
41{
42  const user = new TestUser("wan2land");
43  user.setAge(20);
44
45  console.log(serializer.serialize(user)); // TestUser{"name":"wan2land","age":20}
46}
47{
48  const user = serializer.deserialize<TestUser>(
49    'TestUser{"name":"wan2land","age":20}',
50  );
51  console.log(user); // TestUser { name: "wan2land" }
52  console.log(user.getAge()); // 20
53}

Benchmark

Please see benchmark results.

See also

• Creating Superserial - My blog post about superserial. (Korean)
• SuperClosure PHP Serialize Library, superserial was inspired by this.
• flatted
• lave
• arson
• devalue
• superjson