|
1 | | -cloner [](http://travis-ci.org/WebReflection/cloner) |
2 | | -============== |
| 1 | +# cloner |
3 | 2 |
|
4 | | -An ES5+ compatible utility to deep or shallow copy and merge objects. |
| 3 | +[](https://travis-ci.com/WebReflection/cloner) [](https://coveralls.io/github/WebReflection/cloner?branch=master) |
5 | 4 |
|
6 | | -### API |
7 | | -The module has two sub modules: `shallow` and `deep`. |
8 | | -Both of them will have two methods: `copy` and `merge`. |
9 | | - |
10 | | -#### cloner.shallow.copy(object):shallowCopy |
11 | | -Will loop over all own keys and copy them to a new object. The equivalent operation can be described as such: |
| 5 | +An utility to deeply clone objects. |
12 | 6 |
|
13 | 7 | ```js |
14 | | -// it's based on descriptors |
15 | | -Object.defineProperties( |
16 | | - // it preserves inheritance |
17 | | - Object.create( |
18 | | - Object.getPrototypeOf(source) |
19 | | - ), |
20 | | - // it does shallow copy |
21 | | - Reflect.ownKeys(source).reduce(function (d, k) { |
22 | | - d[k] = Object.getOwnPropertyDescriptor(source, k); |
23 | | - }, {}) |
24 | | - // or Reflect.getOwnPropertyDescriptors(source) |
25 | | -); |
26 | | -``` |
27 | | -The `cloner.shallow.copy` utility is most likely what you are looking for instead of the underpowered `Object.assign` one. |
28 | | - |
29 | | -#### cloner.shallow.merge(target, source1[, source2, sourceN]):target |
30 | | -Preserves what's already in the `target` and merge all own keys found in one or more passed sources. |
31 | | -```js |
32 | | -var a = {a: 1, b: 2}; |
33 | | -var b = cloner.shallow.merge({a: 3}, a); |
34 | | - |
35 | | -b; // {a: 3, b: 2} |
36 | | -``` |
37 | | -Probably the best option to merge states, ideal for statics or immutable properties. |
38 | | - |
39 | | - |
40 | | -#### cloner.deep.copy(object):deepCopy |
41 | | -Same as `cloner.shallow.copy` beside the fact every single own key will be deeply copied. |
42 | | -Like its shallow counterpart, it does preserve inheritance and it's **recursion aware**, meaning it shouldn't fail with recursive properties, as already [tested](test/cloner.js). |
43 | | - |
44 | | - |
45 | | -#### cloner.deep.merge(target, source1[, source2, sourceN]):target |
46 | | -Same as `cloner.shallow.merge` but each new own key will be deeply copied. |
47 | | - |
48 | | - |
49 | | -### How to use |
50 | | -`npm install cloner` should do, otherwise [grab the file you like the most](build/) in here. |
51 | | - |
52 | | - |
53 | | -### License |
54 | | -``` |
55 | | -Copyright (C) 2015 by Andrea Giammarchi - @WebReflection |
56 | | -
|
57 | | -Permission is hereby granted, free of charge, to any person obtaining a copy |
58 | | -of this software and associated documentation files (the "Software"), to deal |
59 | | -in the Software without restriction, including without limitation the rights |
60 | | -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
61 | | -copies of the Software, and to permit persons to whom the Software is |
62 | | -furnished to do so, subject to the following conditions: |
63 | | -
|
64 | | -The above copyright notice and this permission notice shall be included in |
65 | | -all copies or substantial portions of the Software. |
66 | | -
|
67 | | -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
68 | | -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
69 | | -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
70 | | -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
71 | | -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
72 | | -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
73 | | -THE SOFTWARE. |
| 8 | +import cloner from 'cloner'; |
| 9 | +// const cloner = require('cloner'); |
| 10 | +// <script src=//unpkg.com/cloner></script> |
74 | 11 |
|
| 12 | +const target = cloner(source); |
75 | 13 | ``` |
0 commit comments