Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/klona
A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!
https://github.com/lukeed/klona
Last synced: 4 days ago
JSON representation
A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!
- Host: GitHub
- URL: https://github.com/lukeed/klona
- Owner: lukeed
- License: mit
- Created: 2020-01-09T09:27:47.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-11T13:49:32.000Z (4 months ago)
- Last Synced: 2024-10-29T13:04:25.815Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 97.7 KB
- Stars: 1,612
- Watchers: 13
- Forks: 43
- Open Issues: 13
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: license
Awesome Lists containing this project
- awesome-github-repos - lukeed/klona - A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more! (JavaScript)
- awesome-github-star - klona
- awesome-list - klona
- awesome-node-esm - klona - tiny (240B to 507B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more! (Packages / Utility)
- awesome-javascript - klona
- awesome-javascript - klona
README
A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!
## Features
* Super tiny and [performant](#benchmarks)
* 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](https://en.wikipedia.org/wiki/Dolly_(sheep)).
## 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](https://unpkg.com/klona/json/index.js), [ES Module](https://unpkg.com/klona/json/index.mjs), [UMD](https://unpkg.com/klona/json/index.min.js)
> **Ability:** JSON data types
```js
import { klona } from 'klona/json';
```
#### `klona/lite`
> **Size (gzip):** 354 bytes
> **Availability:** [CommonJS](https://unpkg.com/klona/lite/index.js), [ES Module](https://unpkg.com/klona/lite/index.mjs), [UMD](https://unpkg.com/klona/lite/index.min.js)
> **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](https://unpkg.com/klona/dist/index.js), [ES Module](https://unpkg.com/klona/dist/index.mjs), [UMD](https://unpkg.com/klona/dist/index.min.js)
> **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](https://unpkg.com/klona/full/index.js), [ES Module](https://unpkg.com/klona/full/index.mjs), [UMD](https://unpkg.com/klona/full/index.min.js)
> **Ability:** extends `klona` with support for Symbol properties 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`](/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](https://www.npmjs.com/package/clone#api) 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)
```
## Related
* [dlv](https://github.com/developit/dlv) – safely **read** from deep properties in 120 bytes
* [dset](https://github.com/lukeed/dset) – safely **write** into deep properties in 160 bytes
* [dequal](https://github.com/lukeed/dequal) – safely check for deep equality in 304 to 489 bytes
## License
MIT © [Luke Edwards](https://lukeed.com)