@jsbits/deep-clone
Part of the JSBits suite.
![minified size](https://img.shields.io/bundlephobia/min/@jsbits/deep-clone.svg)
![maintainability](https://img.shields.io/codeclimate/maintainability/ProJSLib/jsbits.svg)
Performs a deep cloning of an object own properties and symbols, with loosy or exact behavior.
Install
For NodeJS and JS bundlers:
npm i @jsbits/deep-clone
yarn add @jsbits/deep-clone
or load deepClone
in the browser:
<script src="https://unpkg.com/@jsbits/deep-clone/index.b.min.js"></script>
Targets
- ES5 compatible browser
- NodeJS v4.2 or later
deepClone(value, [exact])
⇒ T
Performs a deep cloning of an object own properties and symbols, preserving
its prototype.
By default cloneObject
works in "loosy mode", where it clones only
the object enumerable properties and symbols.
To enable the "exact mode" and clone all, pass true
in the second parameter.
Both modes retain all the attributes of the copied properties (enumerable,
configurable, writable) and correctly transfer the get
and/or set
methods, although these, like the other function-type values,
are copied by reference.
Try to limit the usage of this function to POJOs, as this function does not
work for objects with constructor that requires parameters (other than
the most JS built-in Objects), nor objects with recursive references.
Param | Type | Default | Description |
---|
value | T | | Value to clone, mostly an object or array. |
[exact] | boolean | false | If true , also clone the non-enumerable properties |
Returns: T
- The cloned object or value.
Since 1.0.0
Group: object
Author/Maintainer: aMarCruz
Example
import deepClone from '@jsbits/deep-clone'
let obj = {
foo: 1,
bar: 'bar',
baz: { date: new Date() },
}
let clone = deepClone(obj)
console.log('Success?',
clone.baz.date instanceof Date && clone.baz.date !== obj.baz.date)
const baz = Symbol()
obj = {
foo: 'Foo',
arr: [{ bar: 'Bar' }],
[baz]: 'Baz',
}
Object.defineProperty(obj, 'abc', {
value: 'xyz',
enumerable: false,
})
clone = deepClone(obj, true)
console.log(JSON.stringify(clone))
console.log(clone[baz])
console.log(clone.abc)
console.dir(Object.getOwnPropertyDescriptor(clone, 'abc'))
About getter and setters
Cloning of getters and setters work as expected, they are duplicated by reference. However, there' cases where cloning does not work.
Observe this fragment:
const createObj = function () {
let _foo = 'bar'
return Object.defineProperty({}, 'foo', {
get () { return _foo },
set (value) { _foo = value },
enumerable: true,
})
}
const obj = createObj()
const clone = deepClone(obj)
console.log(clone !== obj)
console.log(clone.foo)
clone.foo = 'BAZ'
console.log(clone.foo)
console.log(obj.foo)
This is obvious if you look at the code of deepClone, getters and setters are copied but its closure is the same as the original object.
To date, I haven't found any way to solve this issue ...anyone?
A workaround is to keep the "hidden" variable in the object.
In this case, we move _foo
to inside the object:
const createObj = function () {
return Object.defineProperties({}, {
_foo: {
value: 'bar',
writable: true,
},
foo: {
get () { return this._foo },
set (value) { this._foo = value },
enumerable: true,
},
})
}
const obj = createObj()
const clone = deepClone(obj)
console.log(clone !== obj)
console.log(clone.foo)
clone.foo = 'BAZ'
console.log(clone.foo)
console.log(obj.foo)
console.log(JSON.stringify(obj))
Imports
All the JSBits functions works in strict mode and are compatible with:
- ES5 browsers, through the jQuery
$.jsbits
object or the global jsbits
. - ESM Bundlers, like webpack and Rollup.
- ES modules for modern browsers or NodeJS with the
--experimental-modules
flag. - CommonJS modules of NodeJS, jspm, and others.
- Babel and TypeScript, through ES Module Interop.
Please see the Distribution Formats in the JSBits README to know about all the variants.
Known Issues
This types are copied by reference:
- Function
- AsyncFunction
- Getters and Setters
- GeneratorFunction
- Iterators
- SharedArrayBuffer (ES2017, has a shered data block)
- Atomics object (ES2017)
- JSON object
- Math object
- WeakMap
- WeakSet
- XMLHttpRequest
arguments
object is cloned as an object without prototype.
Untested types:
The Intl object and other classes are cloned as generic Objects.
Support my Work
I'm a full-stack developer with more than 20 year of experience and I try to share most of my work for free and help others, but this takes a significant amount of time and effort so, if you like my work, please consider...
![Support Me on Ko-fi](https://amarcruz.github.io/images/kofi_blue.png)
Of course, feedback, PRs, and stars are also welcome 🙃
Thanks for your support!
License
The MIT License.
© 2018-2019 Alberto Martínez – Readme powered by jscc and jsdoc-to-markdown