1 | deepmerge
|
2 | =========
|
3 |
|
4 | > ~554B gzipped, ~1.10KiB minified
|
5 |
|
6 | Merge the enumerable attributes of two objects deeply.
|
7 |
|
8 | [***Check out the changes from version 1.x to 2.0.0***](https://github.com/KyleAMathews/deepmerge/blob/master/changelog.md#200)
|
9 |
|
10 | For the old array element-merging algorithm, see [the `arrayMerge` option below](#arraymerge).
|
11 |
|
12 | example
|
13 | =======
|
14 |
|
15 |
|
16 | var merge = require('./')
|
17 | -->
|
18 |
|
19 | ```js
|
20 | var x = {
|
21 | foo: { bar: 3 },
|
22 | array: [{
|
23 | does: 'work',
|
24 | too: [ 1, 2, 3 ]
|
25 | }]
|
26 | }
|
27 |
|
28 | var y = {
|
29 | foo: { baz: 4 },
|
30 | quux: 5,
|
31 | array: [{
|
32 | does: 'work',
|
33 | too: [ 4, 5, 6 ]
|
34 | }, {
|
35 | really: 'yes'
|
36 | }]
|
37 | }
|
38 |
|
39 | var expected = {
|
40 | foo: {
|
41 | bar: 3,
|
42 | baz: 4
|
43 | },
|
44 | array: [{
|
45 | does: 'work',
|
46 | too: [ 1, 2, 3 ]
|
47 | }, {
|
48 | does: 'work',
|
49 | too: [ 4, 5, 6 ]
|
50 | }, {
|
51 | really: 'yes'
|
52 | }],
|
53 | quux: 5
|
54 | }
|
55 |
|
56 | merge(x, y) // => expected
|
57 | ```
|
58 |
|
59 | methods
|
60 | =======
|
61 |
|
62 | ```
|
63 | var merge = require('deepmerge')
|
64 | ```
|
65 |
|
66 | merge(x, y, [options])
|
67 | -----------
|
68 |
|
69 | Merge two objects `x` and `y` deeply, returning a new merged object with the
|
70 | elements from both `x` and `y`.
|
71 |
|
72 | If an element at the same key is present for both `x` and `y`, the value from
|
73 | `y` will appear in the result.
|
74 |
|
75 | Merging creates a new object, so that neither `x` or `y` are be modified.
|
76 |
|
77 | merge.all(arrayOfObjects, [options])
|
78 | -----------
|
79 |
|
80 | Merges any number of objects into a single result object.
|
81 |
|
82 | ```js
|
83 | var x = { foo: { bar: 3 } }
|
84 | var y = { foo: { baz: 4 } }
|
85 | var z = { bar: 'yay!' }
|
86 |
|
87 | var expected = { foo: { bar: 3, baz: 4 }, bar: 'yay!' }
|
88 |
|
89 | merge.all([x, y, z]) // => expected
|
90 | ```
|
91 |
|
92 | ### options
|
93 |
|
94 | #### arrayMerge
|
95 |
|
96 | The merge will also concatenate arrays and merge array values by default.
|
97 |
|
98 | 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.
|
99 |
|
100 | ```js
|
101 | function overwriteMerge(destinationArray, sourceArray, options) {
|
102 | return sourceArray
|
103 | }
|
104 | merge(
|
105 | [1, 2, 3],
|
106 | [3, 2, 1],
|
107 | { arrayMerge: overwriteMerge }
|
108 | ) // => [3, 2, 1]
|
109 | ```
|
110 |
|
111 | To prevent arrays from being merged:
|
112 |
|
113 | ```js
|
114 | const dontMerge = (destination, source) => source
|
115 | const output = merge({ coolThing: [1,2,3] }, { coolThing: ['a', 'b', 'c'] }, { arrayMerge: dontMerge })
|
116 | output // => { coolThing: ['a', 'b', 'c'] }
|
117 | ```
|
118 |
|
119 | To use the old (pre-version-2.0.0) array merging algorithm, pass in this function:
|
120 |
|
121 | ```js
|
122 | const isMergeableObject = require('is-mergeable-object')
|
123 | const emptyTarget = value => Array.isArray(value) ? [] : {}
|
124 | const clone = (value, options) => merge(emptyTarget(value), value, options)
|
125 |
|
126 | function oldArrayMerge(target, source, optionsArgument) {
|
127 | const destination = target.slice()
|
128 |
|
129 | source.forEach(function(e, i) {
|
130 | if (typeof destination[i] === 'undefined') {
|
131 | const cloneRequested = !optionsArgument || optionsArgument.clone !== false
|
132 | const shouldClone = cloneRequested && isMergeableObject(e)
|
133 | destination[i] = shouldClone ? clone(e, optionsArgument) : e
|
134 | } else if (isMergeableObject(e)) {
|
135 | destination[i] = merge(target[i], e, optionsArgument)
|
136 | } else if (target.indexOf(e) === -1) {
|
137 | destination.push(e)
|
138 | }
|
139 | })
|
140 | return destination
|
141 | }
|
142 |
|
143 | merge(
|
144 | [{ a: true }],
|
145 | [{ b: true }, 'ah yup'],
|
146 | { arrayMerge: oldArrayMerge }
|
147 | ) // => [{ a: true, b: true }, 'ah yup']
|
148 | ```
|
149 |
|
150 | #### clone
|
151 |
|
152 | *Deprecated.*
|
153 |
|
154 | Defaults to `true`.
|
155 |
|
156 | If `clone` is `false` then child objects will be copied directly instead of being cloned. This was the default behavior before version 2.x.
|
157 |
|
158 | install
|
159 | =======
|
160 |
|
161 | With [npm](http://npmjs.org) do:
|
162 |
|
163 | ```sh
|
164 | npm install deepmerge
|
165 | ```
|
166 |
|
167 | 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).
|
168 |
|
169 | test
|
170 | ====
|
171 |
|
172 | With [npm](http://npmjs.org) do:
|
173 |
|
174 | ```sh
|
175 | npm test
|
176 | ```
|
177 |
|
178 | license
|
179 | =======
|
180 |
|
181 | MIT
|