Daniel Bannert's open source work is supported by the community on GitHub Sponsors
npm install @visulima/deep-clone
yarn add @visulima/deep-clone
pnpm add @visulima/deep-clone
Copy or deep clone an input value to an arbitrary depth. The function accepts both objects and primitives.
import deepClone from "@visulima/deep-clone";
const cloned = deepClone({ a: 1, b: { c: 2 } });
console.log(cloned); // => {a: 1, b: {c: 2}}
Type: any
The input value to copy.
Type: object
Type: boolean
Default: false
If true
, it will copy all properties, including non-enumerable ones and symbols.
Type: object
A set of custom handlers for specific type of value. Each handler is a function that takes the original value and returns a new value or throws an error if the value is not supported.
- Array: InternalHandler<unknown[]>;
- ArrayBuffer: InternalHandler;
- Blob: InternalHandler;
- DataView: InternalHandler;
- Date: InternalHandler;
- Error: InternalHandler;
- Float32Array: InternalHandler;
- Float64Array: InternalHandler;
- Int8Array: InternalHandler;
- Int16Array: InternalHandler;
- Int32Array: InternalHandler;
- Map: InternalHandler<Map<unknown, unknown>>;
- Object: InternalHandler<Record<string, unknown>>;
- Promise: InternalHandler<Promise>;
- RegExp: InternalHandler;
- Set: InternalHandler<Set>;
- WeakMap: InternalHandler<WeakMap<any, unknown>>;
- WeakSet: InternalHandler<WeakSet>;
Copy all properties contained on the object.
import { copyOwnProperties } from "@visulima/deep-clone/utils";
const obj = { a: 1, b: 2 };
const copy = copyOwnProperties(obj);
console.log(copy); // => {a: 1, b: 2}
Get an empty version of the object with the same prototype it has.
import { getCleanClone } from "@visulima/deep-clone/utils";
const obj = { a: 1, b: 2 };
const clean = getCleanClone(obj);
console.log(clean); // => {}
-
List of supported values/types:
-
undefined
(original value is returned) -
null
(original value is returned) -
boolean
/Boolean
(original value is returned) -
string
/String
(original value is returned) -
number
/Number
(original value is returned) function
Object
Date
RegExp
Set
Map
Error
URIError
ReferenceError
SyntaxError
RangeError
EvalError
TypeError
-
System Error
(Node.js) Array
Int8Array
Uint8Array
Uint8ClampedArray
Init16Array
Uint16Array
Int32Array
Uint32Array
Float32Array
Float64Array
-
Buffer
(Node.js) DataView
Blob
-
-
List of unsupported values/types:
-
DOMElement
: to copy DOM elements, useelement.cloneNode()
. Symbol
WeakMap
WeakSet
File
FileList
ImageData
ImageBitmap
Promise
SharedArrayBuffer
-
-
The implementation can handle circular references.
-
If a
Number
,String
, orBoolean
object is encountered, the value is cloned as a primitive. This behavior is intentional. The implementation is opinionated in wanting to avoid creatingnumbers
,strings
, andbooleans
via thenew
operator and a constructor. -
The implementation only checks whether basic
Objects
,Arrays
, and class instances areextensible
,sealed
, and/orfrozen
. -
functions
are not cloned; their reference is copied. -
The implementation supports custom
error
types which areError
instances (e.g., ES2015 subclasses).
Note:
It is true that jsondiffpatch.clone()
from jsondiffpatch is faster than @visulima/deep-clonse
in this particular benchmark, but it cannot handle as many situations as @visulima/deep-clonse
can.
It is true that fastest-json-copy is faster than @visulima/deep-clonse
in this particular benchmark. 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.
Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.
If you would like to help take a look at the list of issues and check our Contributing guild.
Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
The visulima deep-clone is open-sourced software licensed under the MIT