structuredclone-polyfill-js

Spec-inspired structuredClone polyfill for Node.js and browsers with support for binary types, circular references, Maps, Sets, and more.

Features

• Deep clone for complex object graphs

• Circular reference handling

• Supports:

  • Object, Array
  • Date, RegExp
  • Map, Set
  • ArrayBuffer
  • TypedArrays (Uint8Array, Int32Array, Float32Array, etc.)
  • DataView
  • Error objects

• Prototype preservation

• Transfer list support (zero‑copy semantics)

• TypeScript support

Non‑goals / Limitations

• Functions are not cloneable (throws DataCloneError)
• DOM nodes are not supported
• WeakMap / WeakSet are not supported
• ArrayBuffer detachment cannot be implemented in JavaScript (engine limitation). Transfer is simulated by reusing the same buffer.

Installation

npm install structuredclone-polyfill-js

Usage

Basic

import structuredClone from "structuredclone-polyfill-js";

const obj = { a: 1, nested: { b: 2 } };
const copy = structuredClone(obj);

Circular references

const obj = {};
obj.self = obj;

const cloned = structuredClone(obj);
console.log(cloned.self === cloned); // true

Binary types

const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[0] = 42;

const cloned = structuredClone(buffer);

Transferable buffers (zero‑copy)

const buf = new ArrayBuffer(4);
const cloned = structuredClone(buf, { transfer: [buf] });

cloned === buf; // true

Note: JavaScript cannot detach ArrayBuffers manually. The polyfill reuses the same memory to simulate transfer semantics.

API

structuredClone(value: any, options?: {
  transfer?: ArrayBuffer[]
}): any

Benchmark

Environment: Node.js 22.x (Windows)

Large object graph (10,000 nodes)

| Implementation | Time | | -------------- | -------- | | Native | 47.66 ms | | Polyfill | 33.52 ms |

Binary cloning (10 MB ArrayBuffer)

| Implementation | Time | | -------------- | ------- | | Native | 8.62 ms | | Polyfill | 9036 ms |

Notes:

• Native implementation uses optimized C++ engine paths.
• Polyfill performance for large binary buffers is limited by JavaScript memory copying.
• Object graph cloning performance is competitive for moderate sizes.

Supported Types

| Type | Supported | | ----------- | --------- | | Object | Yes | | Array | Yes | | Date | Yes | | RegExp | Yes | | Map | Yes | | Set | Yes | | ArrayBuffer | Yes | | TypedArray | Yes | | DataView | Yes | | Error | Yes | | Function | No | | DOM Node | No |

Development

npm install
npm test
npm run build
npm run bench

Project structure

src/        # polyfill implementation
tests/      # vitest test suite
bench/      # benchmark script
dist/       # compiled output

Why this project

This project demonstrates:

• Deep understanding of JavaScript runtime internals
• Binary memory handling (ArrayBuffer, TypedArrays)
• Graph cloning with circular references
• Prototype preservation
• Spec‑aware error behavior
• TypeScript library packaging
• Benchmarking and performance analysis

License

MIT