seriall 1.0.1 → 1.1.0

package/README.md

@@ -1,12 +1,12 @@
-# Seriall
+# seriall
 
 ## TL;DR
 
-**Seriall serializes JavaScript object graphs while preserving references, circular references, special primitive values, built-in types, and registered custom classes.**
+**seriall is a data-only serialization protocol for JavaScript object graphs, preserving reference identity, circular structures, built-in types, and registered custom classes.**
 
-The only **unsuported datatypes** out-of-the-box are:
+**The only JavaScript values not supported out-of-the-box are:**
 
-- ⚠️ Custom classes instances with **js-private fields** (prefixed with `#`),
+- ⚠️ Custom classes instances with **JavaScript private fields** (`#field`),
 
   there are still configurable workarounds, just no out-of-the-box solution
 
@@ -16,7 +16,7 @@ The only **unsuported datatypes** out-of-the-box are:
 
   even though even this is theoretically configurable
 
-Seriall **does not use `eval` or dynamically execute serialized JavaScript code**. Serialized functions and classes are not supported by default, which helps keep deserialization data-only.
+seriall **does not use `eval` or dynamically execute serialized JavaScript code**. Serialized functions and classes are not supported by default, which helps keep deserialization data-only.
 
 It **conserves refenrential integrity**, so circularly referenced arrays/objects, and cross referenced arrays/objects can be serialized
 
@@ -24,6 +24,27 @@ It **can out-of-the-box register custom classes**, and recreates their instances
 
 It is **highly configurable**, through the usage of `transformers`
 
+## Table of Contents
+
+- [TL;DR](#tldr)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic usage](#basic-usage)
+  - [Registering custom classes](#registering-custom-classes)
+- [Supported](#supported)
+- [Advanced Usages](#advanced-usages)
+  - [Symbols](#symbols)
+  - [Transformers](#transformers)
+  - [Custom Class Serialization](#custom-class-serialization)
+- [Benchmark](#benchmark)
+- [Import Notes](#import-notes)
+  - [JavaScript](#javascript)
+  - [Typescript](#typescript)
+- [Protocol Versioning](#protocol-versioning)
+  - [Motive](#motive)
+  - [Solution](#solution)
+  - [Stable top-level structure](#stable-top-level-structure)
+
 ## Installation
 
 Inside an npm project: `npm install seriall` or `yarn install seriall`
@@ -162,9 +183,206 @@ and boxed primitives
 
 - `String`, `Number`, `Boolean`
 
+## Advanced Usages
+
+### Symbols
+
+By default, seriall ignores symbol keys in objects, for performance reasons.
+You can however enable this feature in the Serializer's options
+
+```ts
+import { Serializer } from "seriall";
+
+const serializer = new Serializer({ enable: { objectSymbolIndexing: true } });
+//                                                                  ^^^^
+//                                                                  false by default
+
+const secretKey = Symbol("secret");
+
+const data = {
+  [secretKey]: "Hello from a symbol key!",
+};
+
+const serialized = serializer.serialize(data);
+const deserialized = serializer.deserialize(serialized);
+
+const restoredKey = Object.getOwnPropertySymbols(deserialized)[0];
+
+console.log(deserialized[restoredKey]);
+// "Hello from a symbol key!"
+
+console.log(restoredKey.description);
+// "secret"
+```
+
+Symbol identity is also preserved across references:
+
+```ts
+const key = Symbol("key");
+
+const data = {
+  [key]: "value",
+  key,
+};
+
+const restored = serializer.deserialize(serializer.serialize(data));
+
+const restoredKey = Object.getOwnPropertySymbols(restored)[0];
+
+console.log(restored[restoredKey]);
+// "value"
+
+console.log(restored.key === restoredKey);
+// true
+```
+
+This works because seriall preserves the object graph, rather than simply converting values to JSON.
+
+### Transformers
+
+seriall's serialization logic is built around **transformers**.
+
+A transformer tells seriall how to:
+
+- identify a specific type of value
+- encode it into serializable data
+- decode that data back into the original type
+
+This makes seriall highly configurable and allows it to support types that are not supported out-of-the-box.
+
+A transformer can be registered using `registerTransformer()`:
+
+```ts
+import { Serializer, Transformer } from "seriall";
+
+const serializer = new Serializer();
+
+const transformer = new Transformer({
+  id: "url",
+  priority: Transformer.PRIORITY.CUSTOM_CLASS,
+  match: (value) => value instanceof URL,
+  encode: (value) => value.toString(),
+  decode: (value) => new URL(value),
+});
+
+serializer.registerTransformer(transformer);
+
+const original = {
+  website: new URL("https://example.com"),
+};
+
+const serialized = serializer.serialize(original);
+const restored = serializer.deserialize(serialized);
+
+console.log(restored.website instanceof URL);
+// true
+
+console.log(restored.website.href);
+// "https://example.com/"
+```
+
+### Custom Class Serialization
+
+The `registerClass()` mechanism introduced earlier is actually built on top of seriall's transformer system.
+
+In other words, **a registered class is ultimately just a transformer**.
+
+This means that the class serialization mechanism can be reproduced and customized using `Transformer` directly when more control is needed.
+
+By default, `SerializableClass` provides the necessary encoding and decoding behavior.
+
+Under the hood, it looks something like:
+
+```ts
+import { SYMBOLS } from "seriall";
+
+export abstract class SerializableClass {
+  [ENCODE]() {...};
+  static [DECODE] = function (this, registerNode) {...};
+};
+```
+
+So you can actually overwrite a class encoding/decoding methods like this:
+
+```ts
+import { SerializableClass, SYMBOLS } from "seriall";
+
+class MyClass extends SerializableClass {
+  [SYMBOLS.ENCODE]() {
+    console.log("Calling a custom encoding function");
+    return super[SYMBOLS.ENCODE]();
+  }
+}
+```
+
+## Benchmark
+
+seriall is designed for **general-purpose JavaScript object graphs**, including circular references, shared references, built-in types, and recursive custom class instances.
+
+Benchmarks were run with **5,000 iterations**, **500 warmup iterations**, and **7 rounds** with randomized benchmark order. Results below use the median of the rounds.
+
+### Common JavaScript graph
+
+This benchmark contains circular references and many shared object references.
+
+| Operation       |          seriall |     V8 | devalue | flatted | superjson |
+| --------------- | ---------------: | -----: | ------: | ------: | --------: |
+| Serialization   | **16,887 ops/s** | 34,903 |   9,674 |   7,086 |     2,727 |
+| Deserialization | **16,077 ops/s** | 18,274 |  16,459 |   3,298 |     6,200 |
+| Round-trip      |  **8,279 ops/s** | 11,727 |   5,974 |   2,218 |     1,875 |
+
+seriall 's serialized size was **6,057 bytes**, compared with 6,029 bytes for devalue, 6,445 bytes for flatted, 15,233 bytes for superjson, and 4,458 bytes for V8.
+
+For this graph, seriall 's complete round-trip was approximately **1.4× faster than devalue** and **3.7× faster than flatted**.
+
+### Rich JavaScript graph
+
+The rich graph includes:
+
+- `Date`, `Map`, `Set`, and `BigInt`
+- shared references
+- circular references
+- recursive custom `User` instances
+- users referencing themselves and each other
+- custom classes nested at multiple levels
+
+| Operation       |         seriall | devalue |
+| --------------- | --------------: | ------: |
+| Serialization   | **2,589 ops/s** |   2,502 |
+| Deserialization | **3,505 ops/s** |   4,157 |
+| Round-trip      | **1,467 ops/s** |   1,519 |
+
+seriall serialized this graph to **16,517 bytes**.
+
+The most important difference in this benchmark is correctness: seriall preserves recursive custom-class identity, including self-references and cross-references between class instances.
+
+```text
+seriall:
+  Self referencing user: PASS
+  Cross referencing users: PASS
+
+devalue:
+  Self referencing user: FAIL
+  Cross referencing users: FAIL
+```
+
+### Plots
+
+![Common JavaScript Graph](./assets/benchmark-common.svg)
+
+![Rich JavaScript Graph](./assets/benchmark-rich.svg)
+
+### Conclusion
+
+In these benchmarks, seriall was the fastest of the tested non-Node.js-only serializers on the common graph, while remaining competitive with devalue on the richer graph.
+
+More importantly, Seriall combines this performance with full referential integrity for recursive custom class instances, configurable transformers, built-in type support, and a data-only serialization format.
+
+That makes Seriall particularly well suited for transferring complex JavaScript object graphs, such as those encountered in network-layer protocols.
+
 ## Import Notes
 
-Seriall is exported in both cjs and mjs.
+seriall is exported in both cjs and mjs.
 
 It therefore supports both CommonJS import (`require`) and ES Module import (`import`)
 
@@ -172,14 +390,14 @@ It also exposes both `.d.cts` and `.d.mts` declaration files, and provides there
 
 ### JavaScript
 
-**CommonJS**
+**ES Module**
 
 ```ts
 // demo.mjs
 import { Serializer } from "seriall";
 ```
 
-**ES Module**
+**CommonJS**
 
 ```ts
 // demo.cjs
@@ -188,7 +406,7 @@ const { Serializer } = require("seriall");
 
 ### Typescript
 
-**CommonJS**
+**ES Module**
 
 ```ts
 // demo.mts
@@ -196,7 +414,7 @@ import { Serializer } from "seriall";
 // Serializer is properly typed
 ```
 
-**ES Module**
+**CommonJS**
 
 either
 
@@ -214,3 +432,36 @@ or
 const { Serializer } = require("seriall") as typeof import("seriall");
 // Serializer is now typed properly
 ```
+
+## Protocol Versioning
+
+### Motive
+
+In the advent of a **breaking protocol change**, serializers running on different platforms (e.g client vs server) could
+go temporarily out of sync regarding their serialization protocol.
+
+### Solution
+
+To handle this case and prevent incompatible data from being deserialized incorrectly, **seriall checks the protocol version before deserializing data** .
+
+⚠️ A protocol mismatch will result in a error being thrown
+
+The protocol is however **not expected to change**, and especially not frequently.
+
+### Stable top level structure:
+
+every serialized data consist of a json string, structured like this:
+
+```ts
+{
+  "lib": "seriall", // stable
+  "v": number, // protocol version
+  "d": any // serialized data
+}
+```
+
+- `lib` identifies the serialization format and is expected to remain stable.
+
+- `v` identifies the protocol version and may change if a breaking protocol change is introduced.
+
+- `d` contains the serialized object graph and may change format between protocol versions.

package/dist/index.cjs

@@ -27,9 +27,11 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/const/const.ts
-var SIGNATURE_KEY = "$";
-var DATA_KEY = "d";
+var SIGNATURE_INDEX = 0;
+var DATA_INDEX = 1;
 var NO_TRANSFORM_DATA = void 0;
+var PROTOCOL_VERSION = 1;
+var LIB = "seriall";
 var PRIORITY = {
   CUSTOM_CLASS: 0,
   NATIVE_CLASS: 1,
@@ -42,13 +44,13 @@ var isSpecialNumber = (value) => {
   return [Infinity, -Infinity, NaN].includes(value) || Object.is(value, -0);
 };
 var encodeSpecialNumber = (value) => {
-  if (Number.isNaN(value)) return 0;
-  if (value === Infinity) return 1;
-  if (value === -Infinity) return 2;
-  if (Object.is(value, -0)) return 3;
+  if (Number.isNaN(value)) return [0];
+  if (value === Infinity) return [1];
+  if (value === -Infinity) return [2];
+  if (Object.is(value, -0)) return [3];
   throw new Error(value + " is not a special number");
 };
-var decodeSpecialNumber = (value) => {
+var decodeSpecialNumber = ([value]) => {
   switch (value) {
     case 0:
       return NaN;
@@ -68,7 +70,7 @@ var isJsonPrimitive = (value) => {
   if (typeof value === "number") {
     return !isSpecialNumber(value);
   }
-  return typeof value === "string" || typeof value === "boolean";
+  return typeof value === "string" || typeof value === "boolean" || value === null;
 };
 
 // src/utils/object.utils.ts
@@ -96,27 +98,30 @@ var serialize = (data, transformers) => {
   const graph = [];
   const seen = /* @__PURE__ */ new Map();
   const addNodeToGraph = (node) => {
-    if (isJsonPrimitive(node)) {
-      const id2 = graph.length;
-      graph.push(node);
-      return id2;
-    }
     let id = seen.get(node);
-    if (id !== void 0) {
+    if (id !== void 0 && !Object.is(node, -0)) {
       return id;
     }
     id = graph.length;
     seen.set(node, id);
+    if (isJsonPrimitive(node)) {
+      const id2 = graph.length;
+      graph.push(node);
+      return id2;
+    }
     const transformer = transformers.find(
       (transformer2) => transformer2.match(node)
     );
     if (transformer) {
-      graph.push({ $: transformer.id });
+      graph.push([]);
       const revivable = graph[id];
+      revivable[SIGNATURE_INDEX] = transformer.id;
       const encoded = transformer.encode(node);
       if (encoded !== NO_TRANSFORM_DATA) {
-        const dataId = addNodeToGraph(encoded);
-        revivable.d = dataId;
+        encoded.forEach((el, index) => {
+          const dataId = addNodeToGraph(el);
+          revivable[DATA_INDEX + index] = dataId;
+        });
       }
       return id;
     }
@@ -129,21 +134,49 @@ var serialize = (data, transformers) => {
       }
       return id;
     }
+    if (typeof node === "object") {
+      graph.push({});
+      const obj = graph[id];
+      for (const key in node) {
+        const elementId = addNodeToGraph(node[key]);
+        obj[key] = elementId;
+      }
+      return id;
+    }
     throw new Error(
       `No transformer found for the current value "${node?.toString()}", please add one`
     );
   };
   addNodeToGraph(data);
-  return JSON.stringify(graph);
+  const serialized = {
+    lib: LIB,
+    v: PROTOCOL_VERSION,
+    d: graph
+  };
+  return JSON.stringify(serialized);
 };
 
 // src/serialization/deserialize.ts
 var deserialize = (data, transformers) => {
-  const graph = JSON.parse(data);
-  const revived = /* @__PURE__ */ new Map();
+  const { lib, v, d } = JSON.parse(data);
+  if (lib !== LIB) {
+    throw new Error(
+      `Can't deserialize data, invalid lib metadata. Expected "${LIB}", got "${lib}"`
+    );
+  }
+  if (v !== PROTOCOL_VERSION) {
+    throw new Error(
+      `Can't deserialize data, invalid protocol version. Expected ${PROTOCOL_VERSION}, got ${v}`
+    );
+  }
+  if (!Array.isArray(d)) {
+    throw new Error("Invalid seriall payload: 'd' must be an array");
+  }
+  const graph = d;
+  const revived = [];
   const reviveNode = (index) => {
-    if (revived.has(index)) {
-      return revived.get(index);
+    if (index in revived) {
+      return revived[index];
     }
     if (graph.length <= index || index < 0) {
       throw new Error(`Invalid serialized graph reference: ${index}`);
@@ -152,37 +185,54 @@ var deserialize = (data, transformers) => {
     if (isJsonPrimitive(node)) {
       return node;
     }
-    if (Array.isArray(node)) {
+    if (!Array.isArray(node) && typeof node === "object") {
+      const obj = {};
+      revived[index] = obj;
+      for (const key of Object.keys(node)) {
+        obj[key] = reviveNode(node[key]);
+      }
+      return obj;
+    }
+    if (typeof node[SIGNATURE_INDEX] !== "string") {
+      const typedNode2 = node;
       const arr = [];
-      revived.set(index, arr);
-      for (const element of node) {
+      revived[index] = arr;
+      for (const element of typedNode2) {
         arr.push(reviveNode(element));
       }
       return arr;
     }
-    const transformerId = node[SIGNATURE_KEY];
-    const transformer = transformers.get(transformerId);
+    const typedNode = node;
+    const transformerId = typedNode[SIGNATURE_INDEX];
+    const transformer = transformers[transformerId];
     if (!transformerId) {
-      throw new Error(`No transformer found for node "${node}"`);
+      throw new Error(`No transformer found for node "${typedNode}"`);
     }
     if (transformer === void 0) {
       throw new Error(`No transformer found with id "${transformerId}"`);
     }
     const nonRecursiveTransformer = transformer;
-    const dataId = node[DATA_KEY];
-    if (dataId === void 0) {
+    if (!transformer.recursive && typedNode[DATA_INDEX] === void 0) {
       const decoded = nonRecursiveTransformer.decode(NO_TRANSFORM_DATA);
-      revived.set(index, decoded);
+      revived[index] = decoded;
       return decoded;
     }
     if (!transformer.recursive) {
-      const decoded = nonRecursiveTransformer.decode(reviveNode(dataId));
-      revived.set(index, decoded);
+      const revivedValues = new Array(typedNode.length - 1);
+      for (let i = 1; i < typedNode.length; i++) {
+        revivedValues[i - 1] = reviveNode(typedNode[i]);
+      }
+      const decoded = nonRecursiveTransformer.decode(revivedValues);
+      revived[index] = decoded;
       return decoded;
     }
     const registerNode = (node2) => {
-      revived.set(index, node2);
-      return reviveNode(dataId);
+      revived[index] = node2;
+      const revivedValues = new Array(typedNode.length - 1);
+      for (let i = 1; i < typedNode.length; i++) {
+        revivedValues[i - 1] = reviveNode(typedNode[i]);
+      }
+      return revivedValues;
     };
     return transformer.decode(registerNode);
   };
@@ -221,15 +271,15 @@ var primitivesTransformers = [
     id: "sym",
     priority: Transformer.PRIORITY.PRIMITIVE,
     match: (node) => typeof node === "symbol",
-    encode: (node) => ({
-      d: node.description,
-      f: Symbol.keyFor(node) === void 0 ? 0 : 1
-    }),
+    encode: (node) => [
+      node.description,
+      Symbol.keyFor(node) === void 0 ? 0 : 1
+    ],
     decode: (encoded) => {
-      if (encoded.f === 1 && encoded.d) {
+      if (encoded[1] === 1) {
         return Symbol.for(encoded.d);
       }
-      return Symbol(encoded.d);
+      return Symbol(encoded[0]);
     }
   }),
   new Transformer({
@@ -246,52 +296,45 @@ var primitivesTransformers = [
     encode: () => NO_TRANSFORM_DATA,
     decode: () => void 0
   }),
-  new Transformer({
-    id: "nul",
-    priority: Transformer.PRIORITY.PRIMITIVE,
-    match: (node) => node === null,
-    encode: () => NO_TRANSFORM_DATA,
-    decode: () => null
-  }),
   new Transformer({
     id: "big",
     priority: Transformer.PRIORITY.PRIMITIVE,
     match: (node) => typeof node === "bigint",
-    encode: (node) => node.toString(),
-    decode: (node) => BigInt(node)
-  }),
-  new Transformer({
-    id: "obj",
-    priority: Transformer.PRIORITY.PRIMITIVE,
-    recursive: true,
-    match: (node) => !Array.isArray(node) && typeof node === "object",
-    encode: (node) => {
-      const obj = [];
-      for (const key of Reflect.ownKeys(node)) {
-        const value = node[key];
-        if (typeof value !== "function") {
-          obj.push([key, node[key]]);
-        }
-      }
-      return obj;
-    },
-    decode: (registerNode) => {
-      const obj = {};
-      const encoded = registerNode(obj);
-      for (const [key, value] of encoded) {
-        obj[key] = value;
-      }
-      return obj;
-    }
+    encode: (node) => [node.toString()],
+    decode: ([node]) => BigInt(node)
   })
 ];
+var objectSymbolIndexingTransformer = new Transformer({
+  id: "obj",
+  priority: Transformer.PRIORITY.PRIMITIVE,
+  recursive: true,
+  match: (node) => !Array.isArray(node) && typeof node === "object",
+  encode: (node) => {
+    const obj = [];
+    for (const key of Reflect.ownKeys(node)) {
+      const value = node[key];
+      if (typeof value !== "function") {
+        obj.push([key, node[key]]);
+      }
+    }
+    return obj;
+  },
+  decode: (registerNode) => {
+    const obj = {};
+    const encoded = registerNode(obj);
+    for (const [key, value] of encoded) {
+      obj[key] = value;
+    }
+    return obj;
+  }
+});
 var nativeClassesTransformers = [
   new Transformer({
     id: "Dte",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Date,
-    encode: (node) => node.getTime(),
-    decode: (node) => new Date(node)
+    encode: (node) => [node.getTime()],
+    decode: ([node]) => new Date(node)
   }),
   new Transformer({
     id: "Set",
@@ -327,29 +370,29 @@ var nativeClassesTransformers = [
     id: "Rgx",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof RegExp,
-    encode: (node) => ({ s: node.source, f: node.flags }),
-    decode: (node) => new RegExp(node.s, node.f)
+    encode: (node) => [node.source, node.flags],
+    decode: (node) => new RegExp(node[0], node[1])
   }),
   new Transformer({
     id: "Str",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof String,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new String(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new String(node)
   }),
   new Transformer({
     id: "Num",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Number,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new Number(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new Number(node)
   }),
   new Transformer({
     id: "Bol",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Boolean,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new Boolean(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new Boolean(node)
   })
 ];
 
@@ -360,20 +403,21 @@ var SYMBOLS = { ENCODE, DECODE };
 var SerializableClass = class {
   constructor(..._) {
   }
-  [ENCODE] = () => {
-    const encoded = {};
-    for (const key of Reflect.ownKeys(this)) {
+  [ENCODE]() {
+    const encoded = [];
+    for (const key of Object.keys(this)) {
       const value = this[key];
       if (typeof value !== "function") {
-        encoded[key] = this[key];
+        encoded.push(this[key]);
       }
     }
     return encoded;
-  };
+  }
   static [DECODE] = function(registerNode) {
     let revivedInstance = {};
     const args = registerNode(revivedInstance);
-    Object.assign(revivedInstance, args);
+    const keys = Reflect.ownKeys(new this({}));
+    keys.forEach((key, index) => revivedInstance[key] = args[index]);
     Object.setPrototypeOf(revivedInstance, this.prototype);
     return revivedInstance;
   };
@@ -392,23 +436,30 @@ var defaultOptions = {
   enable: {
     builtinPrimitiveTransformers: true,
     builtinNativeClasses: true,
-    builtinClassTransformer: true
-  }
+    objectSymbolIndexing: false
+  },
+  classes: {}
 };
 var Serializer = class {
   transformers = [];
-  transformersMap = /* @__PURE__ */ new Map();
+  transformersRecord = {};
   constructor(options = {}) {
     const opt = deepMerge(defaultOptions, options);
     if (opt.enable.builtinPrimitiveTransformers)
       primitivesTransformers.forEach(this.registerTransformer);
     if (opt.enable.builtinNativeClasses)
       nativeClassesTransformers.forEach(this.registerTransformer);
+    if (opt.enable.objectSymbolIndexing) {
+      this.registerTransformer(objectSymbolIndexingTransformer);
+    }
+    for (const className in opt.classes) {
+      this.registerClass(className, opt.classes[className]);
+    }
   }
   serialize = (data) => serialize(data, this.transformers);
-  deserialize = (data) => deserialize(data, this.transformersMap);
+  deserialize = (data) => deserialize(data, this.transformersRecord);
   registerTransformer = (transformer) => {
-    if (this.transformersMap.has(transformer.id)) {
+    if (transformer.id in this.transformersRecord) {
       throw new Error(
         `A transformer with id "${transformer.id}" is already registered, chose another one`
       );
@@ -417,11 +468,11 @@ var Serializer = class {
     this.transformers = this.transformers.sort(
       (a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity)
     );
-    this.transformersMap.set(transformer.id, transformer);
+    this.transformersRecord[transformer.id] = transformer;
   };
   deregisterTransformer = (transformer) => {
     const id = typeof transformer === "object" ? transformer.id : transformer;
-    if (!this.transformersMap.has(id)) {
+    if (!(id in this.transformersRecord)) {
       throw new Error(
         `No transformer found for id "${id}", cannot deregister it`
       );
@@ -429,7 +480,7 @@ var Serializer = class {
     this.transformers = this.transformers.filter(
       (transformer2) => transformer2.id !== id
     );
-    this.transformersMap.delete(id);
+    delete this.transformersRecord[id];
   };
   registerClass = (name, clazz) => {
     this.registerTransformer(createClassTransformer("$" + name, clazz));

package/dist/index.d.cts

@@ -8,22 +8,34 @@ declare namespace Seriall {
     | object
     | Serializable[];
 
-  export type JsonPrimitive = string | number | boolean;
+  export type JsonPrimitive = string | number | boolean | null;
+
+  export type MetaData = {
+    lib: "seriall";
+    v: 1;
+  };
 
   export namespace Serialized {
-    export type RevivableNode = { $: Transformer.Id; d?: number };
-    export type Node = JsonPrimitive | number[] | RevivableNode;
+    export type NodeId = number;
+    export type TransformedNode = [Transformer.Id, NodeId];
+    export type Node =
+      | JsonPrimitive
+      | NodeId[]
+      | TransformedNode
+      | Record<string | number, NodeId>;
     export type Graph = Node[];
   }
 
+  export type Serialized = MetaData & { d: Seriall.Serialized.Graph };
+
   namespace Transformer {
     /** `NoData` is used to signify that no value should be passed to the Revivable node,
      * which is then only described by its tag ($)*/
     type NoData = undefined;
 
     type Encoded<Recursive extends boolean> = Recursive extends false
-      ? JsonPrimitive | object | Encoded<false>[] | NoData
-      : (JsonPrimitive | Encoded<true>)[] | object;
+      ? (JsonPrimitive | object | Encoded<false>)[] | NoData
+      : (JsonPrimitive | object | Encoded<true>)[];
 
     type Id = string | number;
 
@@ -91,7 +103,7 @@ declare const SYMBOLS: {
 };
 declare abstract class SerializableClass {
     constructor(..._: any);
-    [ENCODE]: () => {};
+    [ENCODE](): any;
     static [DECODE]: <T extends typeof SerializableClass>(this: T, registerNode: Parameters<Seriall.Transformer.Decoder<any, any, true>>[0]) => InstanceType<T>;
 }
 
@@ -99,12 +111,13 @@ type SerializerOptions = {
     enable: {
         builtinPrimitiveTransformers: boolean;
         builtinNativeClasses: boolean;
-        builtinClassTransformer: boolean;
+        objectSymbolIndexing: boolean;
     };
+    classes: Record<Seriall.Transformer.Id, typeof SerializableClass>;
 };
 declare class Serializer {
     private transformers;
-    private transformersMap;
+    private transformersRecord;
     constructor(options?: DeepOptional<SerializerOptions>);
     serialize: (data: Seriall.Serializable) => string;
     deserialize: (data: string) => any;

package/dist/index.d.mts

@@ -8,22 +8,34 @@ declare namespace Seriall {
     | object
     | Serializable[];
 
-  export type JsonPrimitive = string | number | boolean;
+  export type JsonPrimitive = string | number | boolean | null;
+
+  export type MetaData = {
+    lib: "seriall";
+    v: 1;
+  };
 
   export namespace Serialized {
-    export type RevivableNode = { $: Transformer.Id; d?: number };
-    export type Node = JsonPrimitive | number[] | RevivableNode;
+    export type NodeId = number;
+    export type TransformedNode = [Transformer.Id, NodeId];
+    export type Node =
+      | JsonPrimitive
+      | NodeId[]
+      | TransformedNode
+      | Record<string | number, NodeId>;
     export type Graph = Node[];
   }
 
+  export type Serialized = MetaData & { d: Seriall.Serialized.Graph };
+
   namespace Transformer {
     /** `NoData` is used to signify that no value should be passed to the Revivable node,
      * which is then only described by its tag ($)*/
     type NoData = undefined;
 
     type Encoded<Recursive extends boolean> = Recursive extends false
-      ? JsonPrimitive | object | Encoded<false>[] | NoData
-      : (JsonPrimitive | Encoded<true>)[] | object;
+      ? (JsonPrimitive | object | Encoded<false>)[] | NoData
+      : (JsonPrimitive | object | Encoded<true>)[];
 
     type Id = string | number;
 
@@ -91,7 +103,7 @@ declare const SYMBOLS: {
 };
 declare abstract class SerializableClass {
     constructor(..._: any);
-    [ENCODE]: () => {};
+    [ENCODE](): any;
     static [DECODE]: <T extends typeof SerializableClass>(this: T, registerNode: Parameters<Seriall.Transformer.Decoder<any, any, true>>[0]) => InstanceType<T>;
 }
 
@@ -99,12 +111,13 @@ type SerializerOptions = {
     enable: {
         builtinPrimitiveTransformers: boolean;
         builtinNativeClasses: boolean;
-        builtinClassTransformer: boolean;
+        objectSymbolIndexing: boolean;
     };
+    classes: Record<Seriall.Transformer.Id, typeof SerializableClass>;
 };
 declare class Serializer {
     private transformers;
-    private transformersMap;
+    private transformersRecord;
     constructor(options?: DeepOptional<SerializerOptions>);
     serialize: (data: Seriall.Serializable) => string;
     deserialize: (data: string) => any;

package/dist/index.mjs

@@ -1,7 +1,9 @@
 // src/const/const.ts
-var SIGNATURE_KEY = "$";
-var DATA_KEY = "d";
+var SIGNATURE_INDEX = 0;
+var DATA_INDEX = 1;
 var NO_TRANSFORM_DATA = void 0;
+var PROTOCOL_VERSION = 1;
+var LIB = "seriall";
 var PRIORITY = {
   CUSTOM_CLASS: 0,
   NATIVE_CLASS: 1,
@@ -14,13 +16,13 @@ var isSpecialNumber = (value) => {
   return [Infinity, -Infinity, NaN].includes(value) || Object.is(value, -0);
 };
 var encodeSpecialNumber = (value) => {
-  if (Number.isNaN(value)) return 0;
-  if (value === Infinity) return 1;
-  if (value === -Infinity) return 2;
-  if (Object.is(value, -0)) return 3;
+  if (Number.isNaN(value)) return [0];
+  if (value === Infinity) return [1];
+  if (value === -Infinity) return [2];
+  if (Object.is(value, -0)) return [3];
   throw new Error(value + " is not a special number");
 };
-var decodeSpecialNumber = (value) => {
+var decodeSpecialNumber = ([value]) => {
   switch (value) {
     case 0:
       return NaN;
@@ -40,7 +42,7 @@ var isJsonPrimitive = (value) => {
   if (typeof value === "number") {
     return !isSpecialNumber(value);
   }
-  return typeof value === "string" || typeof value === "boolean";
+  return typeof value === "string" || typeof value === "boolean" || value === null;
 };
 
 // src/utils/object.utils.ts
@@ -68,27 +70,30 @@ var serialize = (data, transformers) => {
   const graph = [];
   const seen = /* @__PURE__ */ new Map();
   const addNodeToGraph = (node) => {
-    if (isJsonPrimitive(node)) {
-      const id2 = graph.length;
-      graph.push(node);
-      return id2;
-    }
     let id = seen.get(node);
-    if (id !== void 0) {
+    if (id !== void 0 && !Object.is(node, -0)) {
       return id;
     }
     id = graph.length;
     seen.set(node, id);
+    if (isJsonPrimitive(node)) {
+      const id2 = graph.length;
+      graph.push(node);
+      return id2;
+    }
     const transformer = transformers.find(
       (transformer2) => transformer2.match(node)
     );
     if (transformer) {
-      graph.push({ $: transformer.id });
+      graph.push([]);
       const revivable = graph[id];
+      revivable[SIGNATURE_INDEX] = transformer.id;
       const encoded = transformer.encode(node);
       if (encoded !== NO_TRANSFORM_DATA) {
-        const dataId = addNodeToGraph(encoded);
-        revivable.d = dataId;
+        encoded.forEach((el, index) => {
+          const dataId = addNodeToGraph(el);
+          revivable[DATA_INDEX + index] = dataId;
+        });
       }
       return id;
     }
@@ -101,21 +106,49 @@ var serialize = (data, transformers) => {
       }
       return id;
     }
+    if (typeof node === "object") {
+      graph.push({});
+      const obj = graph[id];
+      for (const key in node) {
+        const elementId = addNodeToGraph(node[key]);
+        obj[key] = elementId;
+      }
+      return id;
+    }
     throw new Error(
       `No transformer found for the current value "${node?.toString()}", please add one`
     );
   };
   addNodeToGraph(data);
-  return JSON.stringify(graph);
+  const serialized = {
+    lib: LIB,
+    v: PROTOCOL_VERSION,
+    d: graph
+  };
+  return JSON.stringify(serialized);
 };
 
 // src/serialization/deserialize.ts
 var deserialize = (data, transformers) => {
-  const graph = JSON.parse(data);
-  const revived = /* @__PURE__ */ new Map();
+  const { lib, v, d } = JSON.parse(data);
+  if (lib !== LIB) {
+    throw new Error(
+      `Can't deserialize data, invalid lib metadata. Expected "${LIB}", got "${lib}"`
+    );
+  }
+  if (v !== PROTOCOL_VERSION) {
+    throw new Error(
+      `Can't deserialize data, invalid protocol version. Expected ${PROTOCOL_VERSION}, got ${v}`
+    );
+  }
+  if (!Array.isArray(d)) {
+    throw new Error("Invalid seriall payload: 'd' must be an array");
+  }
+  const graph = d;
+  const revived = [];
   const reviveNode = (index) => {
-    if (revived.has(index)) {
-      return revived.get(index);
+    if (index in revived) {
+      return revived[index];
     }
     if (graph.length <= index || index < 0) {
       throw new Error(`Invalid serialized graph reference: ${index}`);
@@ -124,37 +157,54 @@ var deserialize = (data, transformers) => {
     if (isJsonPrimitive(node)) {
       return node;
     }
-    if (Array.isArray(node)) {
+    if (!Array.isArray(node) && typeof node === "object") {
+      const obj = {};
+      revived[index] = obj;
+      for (const key of Object.keys(node)) {
+        obj[key] = reviveNode(node[key]);
+      }
+      return obj;
+    }
+    if (typeof node[SIGNATURE_INDEX] !== "string") {
+      const typedNode2 = node;
       const arr = [];
-      revived.set(index, arr);
-      for (const element of node) {
+      revived[index] = arr;
+      for (const element of typedNode2) {
         arr.push(reviveNode(element));
       }
       return arr;
     }
-    const transformerId = node[SIGNATURE_KEY];
-    const transformer = transformers.get(transformerId);
+    const typedNode = node;
+    const transformerId = typedNode[SIGNATURE_INDEX];
+    const transformer = transformers[transformerId];
     if (!transformerId) {
-      throw new Error(`No transformer found for node "${node}"`);
+      throw new Error(`No transformer found for node "${typedNode}"`);
     }
     if (transformer === void 0) {
       throw new Error(`No transformer found with id "${transformerId}"`);
     }
     const nonRecursiveTransformer = transformer;
-    const dataId = node[DATA_KEY];
-    if (dataId === void 0) {
+    if (!transformer.recursive && typedNode[DATA_INDEX] === void 0) {
       const decoded = nonRecursiveTransformer.decode(NO_TRANSFORM_DATA);
-      revived.set(index, decoded);
+      revived[index] = decoded;
       return decoded;
     }
     if (!transformer.recursive) {
-      const decoded = nonRecursiveTransformer.decode(reviveNode(dataId));
-      revived.set(index, decoded);
+      const revivedValues = new Array(typedNode.length - 1);
+      for (let i = 1; i < typedNode.length; i++) {
+        revivedValues[i - 1] = reviveNode(typedNode[i]);
+      }
+      const decoded = nonRecursiveTransformer.decode(revivedValues);
+      revived[index] = decoded;
       return decoded;
     }
     const registerNode = (node2) => {
-      revived.set(index, node2);
-      return reviveNode(dataId);
+      revived[index] = node2;
+      const revivedValues = new Array(typedNode.length - 1);
+      for (let i = 1; i < typedNode.length; i++) {
+        revivedValues[i - 1] = reviveNode(typedNode[i]);
+      }
+      return revivedValues;
     };
     return transformer.decode(registerNode);
   };
@@ -193,15 +243,15 @@ var primitivesTransformers = [
     id: "sym",
     priority: Transformer.PRIORITY.PRIMITIVE,
     match: (node) => typeof node === "symbol",
-    encode: (node) => ({
-      d: node.description,
-      f: Symbol.keyFor(node) === void 0 ? 0 : 1
-    }),
+    encode: (node) => [
+      node.description,
+      Symbol.keyFor(node) === void 0 ? 0 : 1
+    ],
     decode: (encoded) => {
-      if (encoded.f === 1 && encoded.d) {
+      if (encoded[1] === 1) {
         return Symbol.for(encoded.d);
       }
-      return Symbol(encoded.d);
+      return Symbol(encoded[0]);
     }
   }),
   new Transformer({
@@ -218,52 +268,45 @@ var primitivesTransformers = [
     encode: () => NO_TRANSFORM_DATA,
     decode: () => void 0
   }),
-  new Transformer({
-    id: "nul",
-    priority: Transformer.PRIORITY.PRIMITIVE,
-    match: (node) => node === null,
-    encode: () => NO_TRANSFORM_DATA,
-    decode: () => null
-  }),
   new Transformer({
     id: "big",
     priority: Transformer.PRIORITY.PRIMITIVE,
     match: (node) => typeof node === "bigint",
-    encode: (node) => node.toString(),
-    decode: (node) => BigInt(node)
-  }),
-  new Transformer({
-    id: "obj",
-    priority: Transformer.PRIORITY.PRIMITIVE,
-    recursive: true,
-    match: (node) => !Array.isArray(node) && typeof node === "object",
-    encode: (node) => {
-      const obj = [];
-      for (const key of Reflect.ownKeys(node)) {
-        const value = node[key];
-        if (typeof value !== "function") {
-          obj.push([key, node[key]]);
-        }
-      }
-      return obj;
-    },
-    decode: (registerNode) => {
-      const obj = {};
-      const encoded = registerNode(obj);
-      for (const [key, value] of encoded) {
-        obj[key] = value;
-      }
-      return obj;
-    }
+    encode: (node) => [node.toString()],
+    decode: ([node]) => BigInt(node)
   })
 ];
+var objectSymbolIndexingTransformer = new Transformer({
+  id: "obj",
+  priority: Transformer.PRIORITY.PRIMITIVE,
+  recursive: true,
+  match: (node) => !Array.isArray(node) && typeof node === "object",
+  encode: (node) => {
+    const obj = [];
+    for (const key of Reflect.ownKeys(node)) {
+      const value = node[key];
+      if (typeof value !== "function") {
+        obj.push([key, node[key]]);
+      }
+    }
+    return obj;
+  },
+  decode: (registerNode) => {
+    const obj = {};
+    const encoded = registerNode(obj);
+    for (const [key, value] of encoded) {
+      obj[key] = value;
+    }
+    return obj;
+  }
+});
 var nativeClassesTransformers = [
   new Transformer({
     id: "Dte",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Date,
-    encode: (node) => node.getTime(),
-    decode: (node) => new Date(node)
+    encode: (node) => [node.getTime()],
+    decode: ([node]) => new Date(node)
   }),
   new Transformer({
     id: "Set",
@@ -299,29 +342,29 @@ var nativeClassesTransformers = [
     id: "Rgx",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof RegExp,
-    encode: (node) => ({ s: node.source, f: node.flags }),
-    decode: (node) => new RegExp(node.s, node.f)
+    encode: (node) => [node.source, node.flags],
+    decode: (node) => new RegExp(node[0], node[1])
   }),
   new Transformer({
     id: "Str",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof String,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new String(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new String(node)
   }),
   new Transformer({
     id: "Num",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Number,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new Number(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new Number(node)
   }),
   new Transformer({
     id: "Bol",
     priority: Transformer.PRIORITY.NATIVE_CLASS,
     match: (node) => node instanceof Boolean,
-    encode: (node) => node.valueOf(),
-    decode: (node) => new Boolean(node)
+    encode: (node) => [node.valueOf()],
+    decode: ([node]) => new Boolean(node)
   })
 ];
 
@@ -332,20 +375,21 @@ var SYMBOLS = { ENCODE, DECODE };
 var SerializableClass = class {
   constructor(..._) {
   }
-  [ENCODE] = () => {
-    const encoded = {};
-    for (const key of Reflect.ownKeys(this)) {
+  [ENCODE]() {
+    const encoded = [];
+    for (const key of Object.keys(this)) {
       const value = this[key];
       if (typeof value !== "function") {
-        encoded[key] = this[key];
+        encoded.push(this[key]);
       }
     }
     return encoded;
-  };
+  }
   static [DECODE] = function(registerNode) {
     let revivedInstance = {};
     const args = registerNode(revivedInstance);
-    Object.assign(revivedInstance, args);
+    const keys = Reflect.ownKeys(new this({}));
+    keys.forEach((key, index) => revivedInstance[key] = args[index]);
     Object.setPrototypeOf(revivedInstance, this.prototype);
     return revivedInstance;
   };
@@ -364,23 +408,30 @@ var defaultOptions = {
   enable: {
     builtinPrimitiveTransformers: true,
     builtinNativeClasses: true,
-    builtinClassTransformer: true
-  }
+    objectSymbolIndexing: false
+  },
+  classes: {}
 };
 var Serializer = class {
   transformers = [];
-  transformersMap = /* @__PURE__ */ new Map();
+  transformersRecord = {};
   constructor(options = {}) {
     const opt = deepMerge(defaultOptions, options);
     if (opt.enable.builtinPrimitiveTransformers)
       primitivesTransformers.forEach(this.registerTransformer);
     if (opt.enable.builtinNativeClasses)
       nativeClassesTransformers.forEach(this.registerTransformer);
+    if (opt.enable.objectSymbolIndexing) {
+      this.registerTransformer(objectSymbolIndexingTransformer);
+    }
+    for (const className in opt.classes) {
+      this.registerClass(className, opt.classes[className]);
+    }
   }
   serialize = (data) => serialize(data, this.transformers);
-  deserialize = (data) => deserialize(data, this.transformersMap);
+  deserialize = (data) => deserialize(data, this.transformersRecord);
   registerTransformer = (transformer) => {
-    if (this.transformersMap.has(transformer.id)) {
+    if (transformer.id in this.transformersRecord) {
       throw new Error(
         `A transformer with id "${transformer.id}" is already registered, chose another one`
       );
@@ -389,11 +440,11 @@ var Serializer = class {
     this.transformers = this.transformers.sort(
       (a, b) => (a.priority ?? Infinity) - (b.priority ?? Infinity)
     );
-    this.transformersMap.set(transformer.id, transformer);
+    this.transformersRecord[transformer.id] = transformer;
   };
   deregisterTransformer = (transformer) => {
     const id = typeof transformer === "object" ? transformer.id : transformer;
-    if (!this.transformersMap.has(id)) {
+    if (!(id in this.transformersRecord)) {
       throw new Error(
         `No transformer found for id "${id}", cannot deregister it`
       );
@@ -401,7 +452,7 @@ var Serializer = class {
     this.transformers = this.transformers.filter(
       (transformer2) => transformer2.id !== id
     );
-    this.transformersMap.delete(id);
+    delete this.transformersRecord[id];
   };
   registerClass = (name, clazz) => {
     this.registerTransformer(createClassTransformer("$" + name, clazz));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seriall",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "A flexible js serializer, capable of serializing/deserializing any js data, while preserving referential integrity, non-json-primitive values, and even custom class instances",
   "author": {
     "email": "loic.duvail.pro@gmail.com",
@@ -25,7 +25,9 @@
     "build:js": "node ./esbuild.js",
     "build:types": "rollup -c",
     "build:test": "node ./esbuild.test.js",
-    "test": "npm run build:test && npx jest"
+    "build:benchmark": "node ./esbuild.benchmark.js",
+    "test": "npm run build:test && npx jest",
+    "bench": "npm run build:benchmark && node benchmark/benchmark.js /"
   },
   "keywords": [
     "serializer",
@@ -43,10 +45,13 @@
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^26.5.1",
+    "devalue": "^6.0.2",
     "esbuild": "^0.28.2",
+    "flatted": "^3.4.4",
     "jest": "^30.5.1",
     "rollup": "^4.63.6",
     "rollup-plugin-dts": "^6.5.1",
+    "superjson": "^2.2.6",
     "typescript": "^6.0.3"
   }
 }