Really Fast Deep Clone
const clone = require('rfdc')()
clone({a: 1, b: {c: 2}}) // => {a: 1, b: {c: 2}}
Copy prototype properties as well as own properties into the new object.
It's marginally faster to allow enumerable properties on the prototype to be copied into the cloned object (not onto it's prototype, directly onto the object).
To explain by way of code:
require('rfdc')({ proto: false })(Object.create({a: 1})) // => {}
require('rfdc')({ proto: true })(Object.create({a: 1})) // => {a: 1}
Setting proto
to true
will provide an additional 2% performance boost.
Keeping track of circular references will slow down performance with an
additional 25% overhead. Even if an object doesn't have any circular references,
the tracking overhead is the cost. By default if an object with a circular
reference is passed to rfdc
, it will throw (similar to how JSON.stringify
would throw).
Use the circles
option to detect and preserve circular references in the
object. If performance is important, try removing the circular reference from
the object (set to undefined
) and then add it back manually after cloning
instead of using this option.
It is also possible to directly import the clone function with all options set to their default:
const clone = require("rfdc/default")
clone({a: 1, b: {c: 2}}) // => {a: 1, b: {c: 2}}
rfdc
clones all JSON types:
Object
Array
Number
String
null
With additional support for:
Date
(copied)undefined
(copied)Buffer
(copied)TypedArray
(copied)Map
(copied)Set
(copied)Function
(referenced)AsyncFunction
(referenced)GeneratorFunction
(referenced)arguments
(copied to a normal object)
All other types have output values that match the output
of JSON.parse(JSON.stringify(o))
.
For instance:
const rfdc = require('rfdc')()
const err = Error()
err.code = 1
JSON.parse(JSON.stringify(e)) // {code: 1}
rfdc(e) // {code: 1}
JSON.parse(JSON.stringify({rx: /foo/})) // {rx: {}}
rfdc({rx: /foo/}) // {rx: {}}
npm run bench
benchDeepCopy*100: 550.406ms
benchLodashCloneDeep*100: 1.479s
benchCloneDeep*100: 761.46ms
benchFastCopy*100: 800.38ms
benchFastestJsonCopy*100: 369.979ms // See note below
benchJsondiffpatchClone*100: 285.914ms // See note below
benchPlainObjectClone*100: 544ms
benchNanoCopy*100: 640.636ms
benchRamdaClone*100: 2.936s
benchJsonParseJsonStringify*100: 2.239s // JSON.parse(JSON.stringify(obj))
benchRfdc*100: 403.151ms
benchRfdcProto*100: 416.896ms
benchRfdcCircles*100: 453.706ms
benchRfdcCirclesProto*100: 404.127ms
It is true that jsondiffpatch.clone()
from jsondiffpatch is the fastest in that benchmark run, but it cannot handle as many situations as rfdc
can. Also, this and this benchmark result suggest that rfdc
is faster in Firefox and Chrome at this different benchmark.
It is true that fastest-json-copy is faster than rfdc
in this particular benchmark, but we have seen that, with different input, the opposite is true. Also, fastest-json-copy has such huge limitations that it is rarely useful. For example, it treats things like Date
and Map
instances the same as empty {}
. It can't handle circular references.
plain-object-clone is also really limited in capability.
npm test
169 passing (342.514ms)
npm run cov
----------|----------|----------|----------|----------|-------------------|
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
----------|----------|----------|----------|----------|-------------------|
rfdc
works the same way as Object.assign
when it comes to copying ['__proto__']
(e.g. when
an object has an own property key called 'proto'). It results in the target object
prototype object being set per the value of the ['__proto__']
own property.
For detailed write-up on how a way to handle this security-wise see https://www.fastify.io/docs/latest/Guides/Prototype-Poisoning/.
MIT