{"id":11938,"library":"replicator","title":"Advanced JavaScript Object Serialization","description":"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.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/inikulin/replicator","tags":["javascript","JSON","serialization","deserialization","circular","circularJSON","structured-clone","structured","clone"],"install":[{"cmd":"npm install replicator","lang":"bash","label":"npm"},{"cmd":"yarn add replicator","lang":"bash","label":"yarn"},{"cmd":"pnpm add replicator","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS environments (e.g., Node.js scripts without 'type: module').","wrong":"import Replicator from 'replicator';","symbol":"Replicator","correct":"const Replicator = require('replicator');"},{"note":"For ES Module environments (e.g., modern Node.js or browser bundles). The library provides a default export.","wrong":"const Replicator = require('replicator');","symbol":"Replicator","correct":"import Replicator from 'replicator';"},{"note":"All serialization/deserialization operations are performed on an instance of Replicator, not statically.","wrong":"Replicator.encode(...); // Static method does not exist","symbol":"Replicator instance methods","correct":"const replicator = new Replicator();\nreplicator.addTransforms(...);\nreplicator.encode(...);\nreplicator.decode(...);"}],"quickstart":{"code":"const Replicator = require('replicator');\n\nconst replicator = new Replicator();\n\nconst a = {};\na.b = a; // Create a circular reference\n\nconst complexObject = {\n    key1: new Set([1, 2, 3]),\n    key2: /\\s+/ig,\n    key3: a,\n    key4: new Date(),\n    key5: undefined,\n    key6: NaN,\n    key7: new Error('Something went wrong')\n};\n\nconsole.log('Original object:', complexObject);\n\nconst str = replicator.encode(complexObject);\nconsole.log('Encoded string:', str);\n\nconst obj = replicator.decode(str);\nconsole.log('Decoded object:', obj);\n\n// Verify circular reference\nconsole.log('Decoded circular reference:', obj.key3.b === obj.key3);\n// Verify Set decoding\nconsole.log('Decoded Set:', obj.key1 instanceof Set && obj.key1.has(1));","lang":"javascript","description":"Demonstrates basic encoding and decoding of an object with various built-in types, including Set, RegExp, Date, undefined, NaN, Error, and a circular reference."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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);`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `Replicator` is imported correctly based on your module system. For CommonJS: `const Replicator = require('replicator');`. For ESM: `import Replicator from 'replicator';`.","cause":"Attempting to instantiate `Replicator` when the import did not correctly resolve to the constructor function, often due to incorrect CommonJS/ESM import syntax.","error":"TypeError: Replicator is not a constructor"},{"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'`).","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.","error":"ReferenceError: NodeList is not defined"},{"fix":"Ensure you are creating an instance: `const replicator = new Replicator();` before calling its methods like `encode` or `decode`.","cause":"The `replicator` instance was not properly initialized or the `Replicator` constructor was not called with `new`.","error":"Cannot read properties of undefined (reading 'encode') or replicator.encode is not a function"}],"ecosystem":"npm"}