deepmerge

You can install deepmerge using npm for Node.js environments, or use the UMD version directly in the browser via unpkg.com.

npm install deepmerge

The merge(x, y, [options]) function merges the enumerable properties of two objects x and y deeply. It returns a new object and does not modify the original inputs. If a key exists in both objects, the value from y is used. By default, arrays are merged by concatenation.

const x = {
	foo: { bar: 3 },
	array: [{ 
		does: 'work',
		too: [ 1, 2, 3 ]
	}]
}

const y = {
	foo: { baz: 4 },
	quux: 5,
	array: [{ 
		does: 'work',
		too: [ 4, 5, 6 ]
	}, { 
		really: 'yes'
	}]
}

const output = merge(x, y)
// output contains the deep merge of x and y

By default, deepmerge concatenates arrays. You can override this behavior by providing an arrayMerge function in the options object.

Your arrayMerge function receives three arguments:

1. target: The existing array.
2. source: The new array to merge.
3. options: An object containing isMergeableObject(value) and cloneUnlessOtherwiseSpecified(value, options).

Example: Overwrite the target array instead of concatenating:

const overwriteMerge = (destinationArray, sourceArray, options) => sourceArray

merge(
	[1, 2, 3],
	[3, 2, 1],
	{ arrayMerge: overwriteMerge }
) // => [3, 2, 1]

The customMerge option allows you to specify a function that overrides the default merge behavior based on the property name (the key).

The customMerge function is passed the key for each property. It should return a function that defines how to merge the values for that key. If it returns undefined, the default merge behavior is used.

const mergeNames = (nameA, nameB) => `${nameA.first} and ${nameB.first}`

const options = {
	customMerge: (key) => {
		if (key === 'name') {
			return mergeNames
		}
	}
}

const result = merge(alex, tony, options)
// result.name will use the mergeNames logic

By default, deepmerge clones properties of almost every kind of object. If you have special types (like class instances) that you want to copy by reference rather than merging their properties, provide a custom isMergeableObject function in the options object. Using a library like is-plain-object is a common way to ensure only plain objects are deeply merged.

const { isPlainObject } = require('is-plain-object')

// This configuration ensures that only plain objects are merged,
// while special instantiated objects are copied directly.
const customMergeOutput = merge(target, source, {
	isMergeableObject: isPlainObject
})

The merge.all(arrayOfObjects, [options]) function merges an array of multiple objects into a single result object.

const foobar = { foo: { bar: 3 } }
const foobaz = { foo: { baz: 4 } }
const bar = { bar: 'yay!' }

merge.all([ foobar, foobaz, bar ]) // => { foo: { bar: 3, baz: 4 }, bar: 'yay!' }

The deepmerge(target, source, [options]) function performs a deep merge of a source object into a target object.

• If both target and source are arrays, it uses the arrayMerge strategy.
• If both are objects, it recursively merges their properties.
• If the types of target and source do not match (e.g., one is an array and the other is an object), it returns a clone of the source.

By default, the function performs a deep clone of properties to prevent mutation of the original objects, unless options.clone is set to false.

The deepmerge.all(array, [options]) function takes an array of objects and merges them sequentially into a single object. The merge starts with an empty object {} as the initial accumulator.

Note: The first argument must be an array; otherwise, it throws an error: Error: first argument should be an array.

You can pass an options object to deepmerge() or deepmerge.all() to customize the merging behavior. Supported options include:

• arrayMerge: A function to define how arrays are merged. Defaults to defaultArrayMerge (concatenation). Signature: (target, source, options) => Array.
• isMergeableObject: A function to determine if a value should be treated as a mergeable object. Defaults to the is-mergeable-object package.
• customMerge: A function that receives the current key and returns either a custom merge function for that key or deepmerge to use the default behavior. Signature: (key) => (target, source, options) => any.
• clone: A boolean. If false, it prevents deep cloning of properties during the merge process.