replicator

library0.0.1jsnpmunverified

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

npm install replicator

github ↗package ↗

INSTALL

IMPORT

SIG · REPLICATOR

replicator

serializationjavascriptv0.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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.

Replicator

✓ const Replicator = require('replicator');

✗ import Replicator from 'replicator';

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

Replicator

✓ import Replicator from 'replicator';

✗ const Replicator = require('replicator');

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

Replicator instance methods

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

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

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

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 issues

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.

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.

affects: >=1.0.0

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.

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';`.

affects: >=1.0.0

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.

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

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Replicator is not a constructor

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

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

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

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

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

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