@jsbits/deep-clone

@jsbits/deep-clone

Part of the JSBits suite.

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
# or
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)
// ⇒ true

/*
  Using Symbol() as property name and the additional parameter
  to clone the non-enumerable property "abc".
*/
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))  // ⇒ '{"foo":"Foo","arr":[{"bar":"Bar"}]}'
console.log(clone[baz])             // ⇒ 'Baz'
console.log(clone.abc)              // ⇒ 'xyz'

console.dir(Object.getOwnPropertyDescriptor(clone, 'abc'))
// ⇒ { value: 'xyz',
//      writable: false,
//      enumerable: false,
//      configurable: false }

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' // in closure
  return Object.defineProperty({}, 'foo', {
    get () { return _foo },
    set (value) { _foo = value },
    enumerable: true,
  })
}

// This creates an object with a property `foo` with accessors that use the var `_foo` of its closure.
const obj = createObj()
// This will clone the object and the property `foo` with its accessors.
const clone = deepClone(obj)

// Looks like this works...
console.log(clone !== obj)      // ⇒ true
console.log(clone.foo)          // ⇒ 'bar'
clone.foo = 'BAZ'
console.log(clone.foo)          // ⇒ 'BAZ'
console.log(obj.foo)            // ⇒ 'BAZ' ...ups!

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 () {
  // _foo as property
  return Object.defineProperties({}, {
    _foo: {
      value: 'bar',
      writable: true, // writable, but no enumerable
    },
    foo: {
      get () { return this._foo },
      set (value) { this._foo = value },
      enumerable: true,
    },
  })
}

const obj = createObj()
const clone = deepClone(obj)

// Now this works
console.log(clone !== obj)      // ⇒ true
console.log(clone.foo)          // ⇒ 'bar'
clone.foo = 'BAZ'
console.log(clone.foo)          // ⇒ 'BAZ'
console.log(obj.foo)            // ⇒ 'bar' :)

// and...
console.log(JSON.stringify(obj)) // ⇒ '{"foo":"bar"}' +1

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:

• Workers
• WebAssembly

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...

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

Changelog

[1.1.1] - 2018-11-16

Added

• Codebeat exclussions for some scripts.
• Yarn workspaces, to allow per subrepo testing.

Changes on templates and additional files on suprepos allows granular development and testing.

Changed

• Per subrepo Changelog.
• More strict ESLint rules.
• Links to functions in the main Readme go to subrepo Readme.

From this version, changes that affect the generated code will also be recorded in the Changelog of the affected subrepos.

Fixed

• Issues with codebeat linters.
• Fix script for function list creation, to avoid markdown lint warnings.