deep-copy-all #

A fast, compact, and robust method to deep copy all JavaScript data types
---
!GitHub top language
!GitHub package.json version
!David
!NPM Downloads
!NPM License

deep-copy-all JavaScript object deep cloner is:

- fast – ranking highly on common benchmark speed tests

- compact – about 5k (minified)

- robust – correctly handling all
standard JavaScript data types, as well as custom types

Install ##

``shell script
$ npm install deep-copy-all
`

Usage ##

Node.js
``javascript
const deepCopy = require('deep-copy-all');
/ ... /
copy = deepCopy(source);
``
HTML file:
`html


`
---

Comparison

The accuracy of deep-copy-all compares well against other deep copying
packages.

Legend:     ☑️ - deep copy
    🚧 - shallow copy
    🗑️ - data loss
    ⚠️ - Error

data type | JSON.* | ce | d-c | dc | cl | f-c | deep-copy-all
----------------- | ------ | --- | --- | --- | --- | --- | -------------
Array | ☑️ | ☑️ |☑️|☑️|☑️|☑️|☑️
ArrayBuffer | 🗑️ | 🗑️ |🗑️|☑️|🗑️|☑️|☑️
BigInt | ⚠️ | ☑️ |☑️|☑️|☑️|☑️|☑️
BigInt64Array | ⚠️ | 🗑️ |🗑️|🚧|☑️|☑️|☑️
BigUint64Array | ⚠️ | 🗑️ |🗑️|🚧|☑️|☑️|☑️
Buffer | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Date | 🗑️ | ☑️ |☑️|☑️|☑️|☑️|☑️
Error | 🗑️ | 🗑️ |🗑️|🚧|☑️|🚧|☑️
Float32Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Float64Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Int8Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Int8Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Int32Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Map | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Object | ☑️ | ☑️ |☑️|☑️|☑️|☑️|☑️
RegExp | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Set | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Uint8Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Uint8ClampedArray | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Uint16Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
Uint32Array | 🗑️ | 🗑️ |🗑️|☑️|☑️|☑️|☑️
WeakMap | 🗑️ | 🗑️ |🗑️|🚧|⚠️|🚧|🚧
WeakSet | 🗑️ | 🗑️ |🗑️|🚧|⚠️|🚧|🚧
enumerable:false | 🗑️ | 🗑️ |🗑️|🗑️|🗑️|🗑️|☑️
custom Array | 🗑️ | 🗑️ |🗑️|🗑️|🗑️|☑️|☑️
custom Object | 🗑️ | 🗑️ |🗑️|🗑️|☑️|☑️|☑️
circular Object | ⚠️ | ☑️ |⚠️|☑️|☑️|🗑️|☑️

JSON.* - JSON.parse(JSON.stringify())

ce - cloneextend

d-c - deep-copy

dc - deepcopy

cl - clone

f-c - fast-copy

---

deepCopy() ##


Perform deep copy of a JavaScript object or array.
#### Syntax ####
``
deepCopy(source [, options])
``
#### Parameters ####
source

    The item to copy.

options

    {Object} [optional] - Modifies copying behavior.

options properties:

    goDeep

       {Boolean} [optional] - Perform deep copy if true (default).

       Set to false to perform shallow copy.

    includeNonEnumerable

       {Boolean} [optional] - Copies non-enumerable properties if true.

       Skips non-enumerable properties if false (default).

    detectCircular

       {Boolean} [optional] - Detect circular references if true (default).

       May be set to false if source has no circular references.

    maxDepth

       {number} [optional] - The maximum depth to copy, default is 20 levels.

#### Return value ####
The copied data.

---

Performance ##

The following data types — passed directly to deepCopy or embedded within
another object — have been verified to be copied correctly:

- Array
- ArrayBuffer
- Buffer (node.js)
- Date
- Error
- RegExp
- Int8Array
- Uint8Array
- Uint8ClampedArray
- Int16Array
- Uint16Array
- Int32Array
- Uint32Array
- Float32Array
- Float64Array
- BigInt64Array
- BigUint64Array
- Map
- Set
- Object
- custom Array
- custom Object

Primtive data types are not deep copied. Instead, their
values are copied:

- Number
- String
- Boolean
- undefined
- BigInt
- Symbol
- null

The following object types are not deep copied, as no way has been found to copy
them. They are copied by reference only:

- Function
- WeakMap
- WeakSet`

Benchmark ##

In a standard
benchmark test
of 14 commonly used deep copy modules, deep-copy-all
was 4th fastest.