File size: 4,571 Bytes
bc20498 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 |
# rfdc
Really Fast Deep Clone
[](https://travis-ci.org/davidmarkclements/rfdc)
[](https://codecov.io/gh/davidmarkclements/rfdc)
[](http://standardjs.com/)
## Usage
```js
const clone = require('rfdc')()
clone({a: 1, b: {c: 2}}) // => {a: 1, b: {c: 2}}
```
## API
### `require('rfdc')(opts = { proto: false, circles: false }) => clone(obj) => obj2`
#### `proto` option
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:
```js
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.
#### `circles` option
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.
### `default` import
It is also possible to directly import the clone function with all options set
to their default:
```js
const clone = require("rfdc/default")
clone({a: 1, b: {c: 2}}) // => {a: 1, b: {c: 2}}
```
### Types
`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:
```js
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: {}}
```
## Benchmarks
```sh
npm run bench
```
```
benchDeepCopy*100: 671.675ms
benchLodashCloneDeep*100: 1.574s
benchCloneDeep*100: 936.792ms
benchFastCopy*100: 822.668ms
benchFastestJsonCopy*100: 363.898ms // See note below
benchPlainObjectClone*100: 556.635ms
benchNanoCopy*100: 770.234ms
benchRamdaClone*100: 2.695s
benchJsonParseJsonStringify*100: 2.290s // JSON.parse(JSON.stringify(obj))
benchRfdc*100: 412.818ms
benchRfdcProto*100: 424.076ms
benchRfdcCircles*100: 443.357ms
benchRfdcCirclesProto*100: 465.053ms
```
It is true that [fastest-json-copy](https://www.npmjs.com/package/fastest-json-copy) may be faster, BUT it 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](https://www.npmjs.com/package/plain-object-clone) is also really limited in capability.
## Tests
```sh
npm test
```
```
169 passing (342.514ms)
```
### Coverage
```sh
npm run cov
```
```
----------|----------|----------|----------|----------|-------------------|
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
----------|----------|----------|----------|----------|-------------------|
```
### `__proto__` own property copying
`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/.
## License
MIT
|