1 | deepmerge
|
2 | =========
|
3 |
|
4 | > ~540B gzipped, ~1.1kB minified
|
5 |
|
6 | Merge the enumerable attributes of two objects deeply.
|
7 |
|
8 | the future
|
9 | ----------
|
10 |
|
11 | Should we publish a version 2? [Give your opinion.](https://github.com/KyleAMathews/deepmerge/issues/72)
|
12 |
|
13 | example
|
14 | =======
|
15 |
|
16 |
|
17 | var merge = require('./')
|
18 | -->
|
19 |
|
20 | ```js
|
21 | var x = {
|
22 | foo: { bar: 3 },
|
23 | array: [{
|
24 | does: 'work',
|
25 | too: [ 1, 2, 3 ]
|
26 | }]
|
27 | }
|
28 |
|
29 | var y = {
|
30 | foo: { baz: 4 },
|
31 | quux: 5,
|
32 | array: [{
|
33 | does: 'work',
|
34 | too: [ 4, 5, 6 ]
|
35 | }, {
|
36 | really: 'yes'
|
37 | }]
|
38 | }
|
39 |
|
40 | var expected = {
|
41 | foo: {
|
42 | bar: 3,
|
43 | baz: 4
|
44 | },
|
45 | array: [{
|
46 | does: 'work',
|
47 | too: [ 1, 2, 3, 4, 5, 6 ]
|
48 | }, {
|
49 | really: 'yes'
|
50 | }],
|
51 | quux: 5
|
52 | }
|
53 |
|
54 | merge(x, y) // => expected
|
55 | ```
|
56 |
|
57 | methods
|
58 | =======
|
59 |
|
60 | ```
|
61 | var merge = require('deepmerge')
|
62 | ```
|
63 |
|
64 | merge(x, y, [options])
|
65 | -----------
|
66 |
|
67 | Merge two objects `x` and `y` deeply, returning a new merged object with the
|
68 | elements from both `x` and `y`.
|
69 |
|
70 | If an element at the same key is present for both `x` and `y`, the value from
|
71 | `y` will appear in the result.
|
72 |
|
73 | Merging creates a new object, so that neither `x` or `y` are be modified. However, child objects on `x` or `y` are copied over - if you want to copy all values, you must pass `true` to the clone option.
|
74 |
|
75 | merge.all(arrayOfObjects, [options])
|
76 | -----------
|
77 |
|
78 | Merges two or more objects into a single result object.
|
79 |
|
80 | ```js
|
81 | var x = { foo: { bar: 3 } }
|
82 | var y = { foo: { baz: 4 } }
|
83 | var z = { bar: 'yay!' }
|
84 |
|
85 | var expected = { foo: { bar: 3, baz: 4 }, bar: 'yay!' }
|
86 |
|
87 | merge.all([x, y, z]) // => expected
|
88 | ```
|
89 |
|
90 | ### options
|
91 |
|
92 | #### arrayMerge
|
93 |
|
94 | The merge will also merge arrays and array values by default. However, there are nigh-infinite valid ways to merge arrays, and you may want to supply your own. You can do this by passing an `arrayMerge` function as an option.
|
95 |
|
96 | ```js
|
97 | function concatMerge(destinationArray, sourceArray, options) {
|
98 | destinationArray // => [1, 2, 3]
|
99 | sourceArray // => [3, 2, 1]
|
100 | options // => { arrayMerge: concatMerge }
|
101 | return destinationArray.concat(sourceArray)
|
102 | }
|
103 | merge([1, 2, 3], [3, 2, 1], { arrayMerge: concatMerge }) // => [1, 2, 3, 3, 2, 1]
|
104 | ```
|
105 |
|
106 | To prevent arrays from being merged:
|
107 |
|
108 | ```js
|
109 | const dontMerge = (destination, source) => source
|
110 | const output = merge({ coolThing: [1,2,3] }, { coolThing: ['a', 'b', 'c'] }, { arrayMerge: dontMerge })
|
111 | output // => { coolThing: ['a', 'b', 'c'] }
|
112 | ```
|
113 |
|
114 | #### clone
|
115 |
|
116 | Defaults to `false`. If `clone` is `true` then both `x` and `y` are recursively cloned as part of the merge.
|
117 |
|
118 | install
|
119 | =======
|
120 |
|
121 | With [npm](http://npmjs.org) do:
|
122 |
|
123 | ```sh
|
124 | npm install deepmerge
|
125 | ```
|
126 |
|
127 | Just want to download the file without using any package managers/bundlers? [Download the UMD version from unpkg.com](https://unpkg.com/deepmerge/dist/umd.js).
|
128 |
|
129 | test
|
130 | ====
|
131 |
|
132 | With [npm](http://npmjs.org) do:
|
133 |
|
134 | ```sh
|
135 | npm test
|
136 | ```
|
137 |
|
138 | license
|
139 | =======
|
140 |
|
141 | MIT
|