Advanced JavaScript Object Serialization

1.0.5 · active · verified Sun Apr 19

replicator is a JavaScript library designed for advanced object serialization, addressing limitations of standard JSON.stringify. It currently stands at version 1.0.5, with an active release cadence indicated by recent patch versions. A key differentiator is its ability to correctly handle circular references within objects, preventing common serialization errors. Beyond standard JSON-serializable types, replicator offers built-in support for a wide array of JavaScript objects including `undefined`, `NaN`, `Date`, `RegExp`, `Error`, `Map`, `Set`, `ArrayBuffer`, and various Typed Arrays. This makes it suitable for complex data structures that would otherwise require manual transformation before serialization. Furthermore, the library is highly extensible, allowing developers to define custom type transforms to serialize and deserialize any bespoke object types. It is also agnostic to the underlying serialization format, enabling its use with JSON, BSON, Protobuf, or other encoders. This flexibility allows it to be adapted for diverse application needs, from IPC in Node.js to storing complex state in the browser.

Common errors

```
TypeError: Replicator is not a constructor
```
cause Attempting to instantiate `Replicator` when the import did not correctly resolve to the constructor function, often due to incorrect CommonJS/ESM import syntax.

fix Ensure `Replicator` is imported correctly based on your module system. For CommonJS: `const Replicator = require('replicator');`. For ESM: `import Replicator from 'replicator';`.
```
ReferenceError: NodeList is not defined
```
cause Attempting to use browser-specific types (like `NodeList`, `HTMLElement`, `document`) or custom transforms relying on them in a Node.js environment without polyfills or mocks.

fix When running in Node.js, avoid custom transforms that directly interact with browser DOM APIs. If necessary, provide global mocks for these types or use conditional logic based on the environment (`typeof window !== 'undefined'`).
```
Cannot read properties of undefined (reading 'encode') or replicator.encode is not a function
```
cause The `replicator` instance was not properly initialized or the `Replicator` constructor was not called with `new`.

fix Ensure you are creating an instance: `const replicator = new Replicator();` before calling its methods like `encode` or `decode`.

Warnings

gotcha Types like `Error`, `Map`, `Set`, `ArrayBuffer`, and Typed Arrays have specific fallback decoding behavior if the target platform does not natively support them (e.g., `Map` becomes `[key, value][]`). This can lead to unexpected data structures if not accounted for.
Fix: Check the decoded object structure carefully, especially when interoperating across different environments or older JavaScript runtimes. Implement custom transforms if specific fallback behavior is undesirable or to ensure consistent behavior.
gotcha The package provides both CommonJS and ES Module exports. Using the incorrect import syntax for your module environment will result in a runtime error or `undefined` import.
Fix: For CommonJS (e.g., Node.js without `"type": "module"` in `package.json`), use `const Replicator = require('replicator');`. For ES Modules (e.g., modern Node.js with `"type": "module"` or browser bundlers), use `import Replicator from 'replicator';`.
gotcha When adding custom type transforms, you must add them to both the `Replicator` instance used for encoding and the one used for decoding to ensure proper round-trip serialization.
Fix: Call `replicator.addTransforms(myTransforms)` on both the encoder and decoder instances: `const encoder = new Replicator(); encoder.addTransforms(myCustomTransforms);` and `const decoder = new Replicator(); decoder.addTransforms(myCustomTransforms);`.

Install

npm install replicator npm
yarn add replicator yarn
pnpm add replicator pnpm

Imports

Replicator
wrong:
```
import Replicator from 'replicator';
```
correct:
```
const Replicator = require('replicator');
```
For CommonJS environments (e.g., Node.js scripts without 'type: module').
Replicator
wrong:
```
const Replicator = require('replicator');
```
correct:
```
import Replicator from 'replicator';
```
For ES Module environments (e.g., modern Node.js or browser bundles). The library provides a default export.

Replicator instance methods

wrong:

Replicator.encode(...); // Static method does not exist

correct:

const replicator = new Replicator();
replicator.addTransforms(...);
replicator.encode(...);
replicator.decode(...);

All serialization/deserialization operations are performed on an instance of Replicator, not statically.

Quickstart

Demonstrates basic encoding and decoding of an object with various built-in types, including Set, RegExp, Date, undefined, NaN, Error, and a circular reference.

const Replicator = require('replicator');

const replicator = new Replicator();

const a = {};
a.b = a; // Create a circular reference

const complexObject = {
    key1: new Set([1, 2, 3]),
    key2: /\s+/ig,
    key3: a,
    key4: new Date(),
    key5: undefined,
    key6: NaN,
    key7: new Error('Something went wrong')
};

console.log('Original object:', complexObject);

const str = replicator.encode(complexObject);
console.log('Encoded string:', str);

const obj = replicator.decode(str);
console.log('Decoded object:', obj);

// Verify circular reference
console.log('Decoded circular reference:', obj.key3.b === obj.key3);
// Verify Set decoding
console.log('Decoded Set:', obj.key1 instanceof Set && obj.key1.has(1));

view raw JSON →