Spec-like structuredClone polyfill with binary support
npm install structuredclone-polyfill-jsstructuredClone polyfill for Node.js and browsers with support for binary types, circular references, Maps, Sets, and more.
DataCloneError)
bash
npm install structuredclone-polyfill-js
`
---
Usage
$3
`js
import structuredClone from "structuredclone-polyfill-js";
const obj = { a: 1, nested: { b: 2 } };
const copy = structuredClone(obj);
`
$3
`js
const obj = {};
obj.self = obj;
const cloned = structuredClone(obj);
console.log(cloned.self === cloned); // true
`
$3
`js
const buffer = new ArrayBuffer(8);
const view = new Uint8Array(buffer);
view[0] = 42;
const cloned = structuredClone(buffer);
`
$3
`js
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
`ts
structuredClone(value: any, options?: {
transfer?: ArrayBuffer[]
}): any
`
---
Benchmark
Environment: Node.js 22.x (Windows)
$3
| Implementation | Time |
| -------------- | -------- |
| Native | 47.66 ms |
| Polyfill | 33.52 ms |
$3
| 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
`bash
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
``