A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!

Features

Super tiny and performant
Deep clone / recursive copies
Safely handles complex data types
Array, Date, Map, Object, RegExp, Set, TypedArray, and more

Unlike a "shallow copy" (eg, Object.assign), a "deep clone" recursively traverses a source input and copies its values — instead of references to its values — into a new instance of that input. The result is a structurally equivalent clone that operates independently of the original source and controls its own values.

Why "klona"? It's "clone" in Swedish.
What's with the sheep? Dolly.

Install

$ npm install --save klona

Modes

There are multiple "versions" of klona available, which allows you to bring only the functionality you need!

`klona/json`

Size (gzip): 240 bytes
Availability: CommonJS, ES Module, UMD
Ability: JSON data types

js import { klona } from 'klona/json';

`klona/lite`

Size (gzip): 354 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona/json with support for custom class, Date, and RegExp

js import { klona } from 'klona/lite';

`klona`

Size (gzip): 451 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona/lite with support for Map, Set, DataView, ArrayBuffer, TypedArray

js import { klona } from 'klona';

`klona/full`

Size (gzip): 501 bytes
Availability: CommonJS, ES Module, UMD
Ability: extends klona with support for Symbol properties and and non-enumerable properties

js import { klona } from 'klona/full';

Usage

```js import { klona } from 'klona';

const input = { foo: 1, bar: { baz: 2, bat: { hello: 'world' } } };

const output = klona(input);

// exact copy of original assert.deepStrictEqual(input, output);

// applying deep updates... output.bar.bat.hola = 'mundo'; output.bar.baz = 99;

// ...doesn't affect source! console.log( JSON.stringify(input, null, 2) ); // { // "foo": 1, // "bar": { // "baz": 2, // "bat": { // "hello": "world" // } // } // } ```

API

klona(input)

Returns: typeof input

Returns a deep copy/clone of the input.

Benchmarks

Running Node v12.18.3

The benchmarks can be found in the /bench directory. They are separated into multiple categories:

JSON – compares an array of objects comprised of JSON data types (String, Number, null, Array, Object)
LITE – like JSON, but adds RegExp, Date and undefined values
DEFAULT – object with RegExp, Date, Array, Map, Set, custom class, Int8Array, DataView, Buffer values
FULL – like DEFAULT, but adds Symbol and non-enumerable properties

Important: Only candidates that pass validation step(s) are listed.
However, lodash and clone are kept to highlight important differences.

Note: The clone/include candidate refers to its includeNonEnumerable option enabled.

``` Load times: lodash/clonedeep 29.257ms rfdc 0.511ms clone 0.576ms clone-deep 2.494ms deep-copy 0.451ms klona/full 0.408ms klona 0.265ms klona/lite 0.308ms klona/json 0.263ms

Benchmark :: JSON JSON.stringify x 53,899 ops/sec ±0.76% (92 runs sampled) lodash x 46,800 ops/sec ±0.86% (90 runs sampled) rfdc x 221,456 ops/sec ±0.88% (92 runs sampled) clone x 39,537 ops/sec ±0.68% (92 runs sampled) clone/include x 25,488 ops/sec ±1.06% (88 runs sampled) clone-deep x 99,998 ops/sec ±0.91% (93 runs sampled) deep-copy x 141,270 ops/sec ±0.95% (92 runs sampled) klona/full x 55,016 ops/sec ±0.68% (94 runs sampled) klona x 281,215 ops/sec ±0.77% (93 runs sampled) klona/lite x 318,481 ops/sec ±0.72% (91 runs sampled) klona/json x 334,932 ops/sec ±0.66% (93 runs sampled)

Benchmark :: LITE lodash x 36,992 ops/sec ±0.65% (91 runs sampled) clone x 35,974 ops/sec ±1.13% (88 runs sampled) clone/include x 22,609 ops/sec ±1.02% (91 runs sampled) clone-deep x 92,846 ops/sec ±0.66% (93 runs sampled) klona/full x 47,873 ops/sec ±0.83% (88 runs sampled) klona x 226,638 ops/sec ±1.16% (93 runs sampled) klona/lite x 257,900 ops/sec ±0.82% (93 runs sampled)

Benchmark :: DEFAULT lodash x 55,914 ops/sec ±0.75% (93 runs sampled) ✘ Buffer ✘ Map keys clone x 92,127 ops/sec ±0.83% (94 runs sampled) ✘ DataView clone/include x 62,052 ops/sec ±0.88% (93 runs sampled) ✘ DataView klona/full x 90,308 ops/sec ±0.68% (89 runs sampled) klona x 230,257 ops/sec ±0.71% (91 runs sampled)

Benchmark :: FULL lodash x 60,361 ops/sec ±0.65% (91 runs sampled) ✘ Buffer ✘ Map keys ✘ Missing non-enumerable Properties clone/include x 47,263 ops/sec ±0.85% (93 runs sampled) ✘ DataView ✘ Incorrect non-enumerable Properties klona/full x 82,346 ops/sec ±0.62% (93 runs sampled) ```

dlv – safely read from deep properties in 120 bytes
dset – safely write into deep properties in 160 bytes
dequal – safely check for deep equality in 304 to 489 bytes