replicator

library1.0.5jsnpmunverified

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.

serialization

github ↗package ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

For CommonJS environments (e.g., Node.js scripts without 'type: module').

const Replicator = require('replicator');

For ES Module environments (e.g., modern Node.js or browser bundles). The library provides a default export.

import Replicator from 'replicator';

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

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

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));

Debug

Known footguns

gotchaTypes 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.

gotchaThe 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.

gotchaWhen 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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

9 hits · last 30 days

gptbot

ahrefsbot

script

Resources

githubhttps://github.com/inikulin/replicator ↗

packagehttps://www.npmjs.com/package/replicator ↗