Fast and safe JSON deep-cloning utility
POJOs and arrays are always duplicated.
Circular references are carried over to the cloned object.
Objects properties and prototypes are ignored.
The resulting duplicated objects keep the same references to the following objects:
- functions and generator functions
- native Error objects
- object version of scalar values (e.g. BooleanObject)
This module also allows to either keep references or to duplicate the following objects, depending on the provided options:
This module can only be used with NodeJS (tested on all major versions from v4 to v8 included).
How to use
const deepClone = ;/*Clone objects, keeping references to Buffer, TypedArrays,Map, Set, Date and RegExp.This means that modifying one of those objects in thesource object will also impact the target object*/const clonedTarget = ;// or: const clonedTarget = deepClone(source, false);/*Copy objects: new Buffer, TypedArrays, Map, Set, Dateand RegExp objects are created in the target object,and their values are copied from the source*/const copiedTarget = ;
When to use this module
This module is written in C++, using V8 for faster object access.
This is, to my knowledge, the fastest deep-cloning module currently available, but it can only work with NodeJS.
Moreover, if all you need to duplicate are POJO objects (i.e. objects containing only objects, arrays or scalar values), and if you are absolutely certain that there is no circular reference in them, then you may want to use
Duplicating objects using
JSON functions is way faster. Around 2x to 6x faster than this module, depending on the nature of the duplicated object.
This is because these functions are hardcoded within V8 and have access to internal structures, not exposed in the V8 public API. Which is not necessarily a bad thing, if a bit frustrating.
Obtained by running
node benchmark.js at the root of the project, using NodeJS v10.9.0:
== Empty objects lodash.cloneDeep x 2,518,033 ops/sec ±1.44% (92 runs sampled) clone x 2,836,807 ops/sec ±2.49% (89 runs sampled) fast-deepclone (clone mode) x 3,701,173 ops/sec ±0.70% (94 runs sampled) fast-deepclone (copy mode) x 3,517,442 ops/sec ±0.64% (90 runs sampled) == Fast POJO objects (5 properties, depth === 3) lodash.cloneDeep x 206,573 ops/sec ±0.66% (98 runs sampled) clone x 249,522 ops/sec ±1.45% (92 runs sampled) fast-deepclone (clone mode) x 133,702 ops/sec ±0.68% (94 runs sampled) fast-deepclone (copy mode) x 129,638 ops/sec ±0.59% (95 runs sampled) == Slow POJO objects (100 properties, depth === 100) lodash.cloneDeep x 254 ops/sec ±1.19% (84 runs sampled) clone x 297 ops/sec ±1.51% (87 runs sampled) fast-deepclone (clone mode) x 519 ops/sec ±0.51% (91 runs sampled) fast-deepclone (copy mode) x 510 ops/sec ±0.73% (90 runs sampled) == Fast objects w/ constructors and circular refs lodash.cloneDeep x 15,130 ops/sec ±1.02% (91 runs sampled) clone x 15,333 ops/sec ±19.09% (76 runs sampled) fast-deepclone (clone mode) x 87,303 ops/sec ±0.24% (95 runs sampled) fast-deepclone (copy mode) x 45,266 ops/sec ±0.88% (91 runs sampled)