source: trip-planner-front/node_modules/klona/readme.md@ 76712b2

Last change on this file since 76712b2 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 7.0 KB
Line 
1<div align="center">
2 <img src="logo.png" alt="klona" height="100" />
3</div>
4
5<div align="center">
6 <a href="https://npmjs.org/package/klona">
7 <img src="https://badgen.now.sh/npm/v/klona" alt="version" />
8 </a>
9 <a href="https://github.com/lukeed/klona/actions">
10 <img src="https://github.com/lukeed/klona/workflows/CI/badge.svg" alt="CI" />
11 </a>
12 <a href="https://npmjs.org/package/klona">
13 <img src="https://badgen.now.sh/npm/dm/klona" alt="downloads" />
14 </a>
15 <a href="https://codecov.io/gh/lukeed/klona">
16 <img src="https://codecov.io/gh/lukeed/klona/branch/master/graph/badge.svg?token=8ej0WeKqz7" alt="codecov" />
17 </a>
18</div>
19
20<div align="center">A tiny (240B to 501B) and fast utility to "deep clone" Objects, Arrays, Dates, RegExps, and more!</div>
21
22
23## Features
24
25* Super tiny and [performant](#benchmarks)
26* Deep clone / recursive copies
27* Safely handles complex data types<br>
28 _Array, Date, Map, Object, RegExp, Set, TypedArray, and more_
29
30Unlike a "shallow copy" (eg, `Object.assign`), a "deep clone" recursively traverses a source input and copies its _values_ &mdash; instead of _references_ to its values &mdash; 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.
31
32> **Why "klona"?** It's "clone" in Swedish.<br>
33> **What's with the sheep?** [Dolly](https://en.wikipedia.org/wiki/Dolly_(sheep)).
34
35
36## Install
37
38```
39$ npm install --save klona
40```
41
42
43## Modes
44
45There are multiple "versions" of `klona` available, which allows you to bring only the functionality you need!
46
47#### `klona/json`
48> **Size (gzip):** 240 bytes<br>
49> **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)<br>
50> **Ability:** JSON data types
51
52```js
53import { klona } from 'klona/json';
54```
55
56#### `klona/lite`
57> **Size (gzip):** 354 bytes<br>
58> **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)<br>
59> **Ability:** extends `klona/json` with support for custom class, Date, and RegExp
60
61```js
62import { klona } from 'klona/lite';
63```
64
65#### `klona`
66> **Size (gzip):** 451 bytes<br>
67> **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)<br>
68> **Ability:** extends `klona/lite` with support for Map, Set, DataView, ArrayBuffer, TypedArray
69
70```js
71import { klona } from 'klona';
72```
73
74#### `klona/full`
75> **Size (gzip):** 501 bytes<br>
76> **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)<br>
77> **Ability:** extends `klona` with support for Symbol properties and and non-enumerable properties
78
79```js
80import { klona } from 'klona/full';
81```
82
83
84## Usage
85
86```js
87import { klona } from 'klona';
88
89const input = {
90 foo: 1,
91 bar: {
92 baz: 2,
93 bat: {
94 hello: 'world'
95 }
96 }
97};
98
99const output = klona(input);
100
101// exact copy of original
102assert.deepStrictEqual(input, output);
103
104// applying deep updates...
105output.bar.bat.hola = 'mundo';
106output.bar.baz = 99;
107
108// ...doesn't affect source!
109console.log(
110 JSON.stringify(input, null, 2)
111);
112// {
113// "foo": 1,
114// "bar": {
115// "baz": 2,
116// "bat": {
117// "hello": "world"
118// }
119// }
120// }
121```
122
123
124## API
125
126### klona(input)
127Returns: `typeof input`
128
129Returns a deep copy/clone of the input.
130
131
132## Benchmarks
133
134> Running Node v12.18.3
135
136The benchmarks can be found in the [`/bench`](/bench) directory. They are separated into multiple categories:
137
138* `JSON` – compares an array of objects comprised of JSON data types (`String`, `Number`, `null`, `Array`, `Object`)
139* `LITE` – like `JSON`, but adds `RegExp`, `Date` and `undefined` values
140* `DEFAULT` – object with `RegExp`, `Date`, `Array`, `Map`, `Set`, custom class, `Int8Array`, `DataView`, `Buffer` values
141* `FULL` – like `DEFAULT`, but adds `Symbol` and non-enumerable properties
142
143> **Important:** Only candidates that pass validation step(s) are listed. <br>However, `lodash` and `clone` are kept to highlight important differences.
144
145> **Note:** The `clone/include` candidate refers to its [`includeNonEnumerable` option](https://www.npmjs.com/package/clone#api) enabled.
146
147```
148Load times:
149 lodash/clonedeep 29.257ms
150 rfdc 0.511ms
151 clone 0.576ms
152 clone-deep 2.494ms
153 deep-copy 0.451ms
154 klona/full 0.408ms
155 klona 0.265ms
156 klona/lite 0.308ms
157 klona/json 0.263ms
158
159Benchmark :: JSON
160 JSON.stringify x 53,899 ops/sec ±0.76% (92 runs sampled)
161 lodash x 46,800 ops/sec ±0.86% (90 runs sampled)
162 rfdc x 221,456 ops/sec ±0.88% (92 runs sampled)
163 clone x 39,537 ops/sec ±0.68% (92 runs sampled)
164 clone/include x 25,488 ops/sec ±1.06% (88 runs sampled)
165 clone-deep x 99,998 ops/sec ±0.91% (93 runs sampled)
166 deep-copy x 141,270 ops/sec ±0.95% (92 runs sampled)
167 klona/full x 55,016 ops/sec ±0.68% (94 runs sampled)
168 klona x 281,215 ops/sec ±0.77% (93 runs sampled)
169 klona/lite x 318,481 ops/sec ±0.72% (91 runs sampled)
170 klona/json x 334,932 ops/sec ±0.66% (93 runs sampled)
171
172Benchmark :: LITE
173 lodash x 36,992 ops/sec ±0.65% (91 runs sampled)
174 clone x 35,974 ops/sec ±1.13% (88 runs sampled)
175 clone/include x 22,609 ops/sec ±1.02% (91 runs sampled)
176 clone-deep x 92,846 ops/sec ±0.66% (93 runs sampled)
177 klona/full x 47,873 ops/sec ±0.83% (88 runs sampled)
178 klona x 226,638 ops/sec ±1.16% (93 runs sampled)
179 klona/lite x 257,900 ops/sec ±0.82% (93 runs sampled)
180
181Benchmark :: DEFAULT
182 lodash x 55,914 ops/sec ±0.75% (93 runs sampled)
183 ✘ Buffer
184 ✘ Map keys
185 clone x 92,127 ops/sec ±0.83% (94 runs sampled)
186 ✘ DataView
187 clone/include x 62,052 ops/sec ±0.88% (93 runs sampled)
188 ✘ DataView
189 klona/full x 90,308 ops/sec ±0.68% (89 runs sampled)
190 klona x 230,257 ops/sec ±0.71% (91 runs sampled)
191
192Benchmark :: FULL
193 lodash x 60,361 ops/sec ±0.65% (91 runs sampled)
194 ✘ Buffer
195 ✘ Map keys
196 ✘ Missing non-enumerable Properties
197 clone/include x 47,263 ops/sec ±0.85% (93 runs sampled)
198 ✘ DataView
199 ✘ Incorrect non-enumerable Properties
200 klona/full x 82,346 ops/sec ±0.62% (93 runs sampled)
201```
202
203
204## Related
205
206* [dlv](https://github.com/developit/dlv) – safely **read** from deep properties in 120 bytes
207* [dset](https://github.com/lukeed/dset) – safely **write** into deep properties in 160 bytes
208* [dequal](https://github.com/lukeed/dequal) – safely check for deep equality in 304 to 489 bytes
209
210
211## License
212
213MIT © [Luke Edwards](https://lukeed.com)
Note: See TracBrowser for help on using the repository browser.