source: trip-planner-front/node_modules/copy-anything/README.md@ 8d391a1

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

initial commit

  • Property mode set to 100644
File size: 3.8 KB
Line 
1# Copy anything 🎭
2
3```
4npm i copy-anything
5```
6
7An optimised way to copy'ing (cloning) an object or array. A small and simple integration.
8
9## Motivation
10
11I created this package because I tried a lot of similar packages that do copy'ing/cloning. But all had its quirks, and _all of them break things they are not supposed to break_... 😞
12
13I was looking for:
14
15- a simple copy/clone function
16- has to be fast!
17- props must lose any reference to original object
18- works with arrays and objects in arrays!
19- supports symbols
20- can copy non-enumerable props as well
21- **does not break special class instances** ‼️
22
23This last one is crucial! So many libraries use custom classes that create objects with special prototypes, and such objects all break when trying to copy them inproperly. So we gotta be careful!
24
25copy-anything will copy objects and nested properties, but only as long as they're "plain objects". As soon as a sub-prop is not a "plain object" and has a special prototype, it will copy that instance over "as is". ♻️
26
27## Meet the family
28
29- [copy-anything 🎭](https://github.com/mesqueeb/copy-anything)
30- [merge-anything 🥡](https://github.com/mesqueeb/merge-anything)
31- [filter-anything ⚔️](https://github.com/mesqueeb/filter-anything)
32- [find-and-replace-anything 🎣](https://github.com/mesqueeb/find-and-replace-anything)
33- [compare-anything 🛰](https://github.com/mesqueeb/compare-anything)
34- [flatten-anything 🏏](https://github.com/mesqueeb/flatten-anything)
35- [is-what 🙉](https://github.com/mesqueeb/is-what)
36
37## Usage
38
39```js
40import { copy } from 'copy-anything'
41
42const original = { name: 'Ditto', type: { water: true } }
43const copy = copy(original)
44
45// now if we change a nested prop like the type:
46copy.type.water = false
47copy.type.fire = true(
48 // new prop
49
50 // then the original object will still be the same:
51 original.type.water === true
52)(original.type.fire === undefined)
53```
54
55> Please note, by default copy-anything does not copy non-enumerable props. If you need to copy those, see the instructions further down below.
56
57## Works with arrays
58
59It will also clone arrays, **as well as objects inside arrays!** 😉
60
61```js
62const original = [{ name: 'Squirtle' }]
63const copy = copy(original)
64
65// now if we change a prop in the array like so:
66copy[0].name = 'Wartortle'
67copy.push({ name: 'Charmander' })(
68 // new item
69
70 // then the original array will still be the same:
71 original[0].name === 'Squirtle'
72)(original[1] === undefined)
73```
74
75## Non-enumerable
76
77By default, copy-anything only copies enumerable properties. If you also want to copy non-enumerable properties you can do so by passing that as an option.
78
79```js
80const original = { name: 'Bulbasaur' }
81// bulbasaur's ID is non-enumerable
82Object.defineProperty(original, 'id', {
83 value: '001',
84 writable: true,
85 enumerable: false,
86 configurable: true,
87})
88const copy1 = copy(original)
89const copy2 = copy(original, { nonenumerable: true })(copy1.id === undefined)(copy2.id === '001')
90```
91
92## Limit to specific props
93
94You can limit to specific props.
95
96```js
97const original = { name: 'Flareon', type: ['fire'], id: '136' }
98const copy = copy(original, { props: ['name'] })(copy === { name: 'Flareon' })
99```
100
101> Please note, if the props you have specified are non-enumerable, you will also need to pass `{nonenumerable: true}`.
102
103## Source code
104
105The source code is literally just these lines. Most of the magic comes from the isPlainObject function from the [is-what library](https://github.com/mesqueeb/is-what).
106
107```JavaScript
108import { isPlainObject } from 'is-what'
109
110export function copy (target) {
111 if (isArray(target)) return target.map(i => copy(i))
112 if (!isPlainObject(target)) return target
113 return Object.keys(target)
114 .reduce((carry, key) => {
115 const val = target[key]
116 carry[key] = copy(val)
117 return carry
118 }, {})
119}
120```
Note: See TracBrowser for help on using the repository browser.