deepmerge

What is deepmerge?

The deepmerge npm package is a library for deep (recursive) merging of Javascript objects. It is useful for combining objects with nested structures, such as configuration settings or state objects in applications.

What are deepmerge's main functionalities?

Merging two objects

This feature allows you to merge two objects deeply. Properties from the second object will be added to the first, and if properties are objects themselves, they will be merged recursively.

{"const merge = require('deepmerge');
const x = { foo: { bar: 3 } };
const y = { foo: { baz: 4 } };
const z = merge(x, y);
console.log(z); // { foo: { bar: 3, baz: 4 } }"}

Merging with array concatenation

This feature allows you to specify how arrays are merged. By default, arrays are merged by concatenation, but you can provide a custom arrayMerge function.

{"const merge = require('deepmerge');
const x = { foo: [1, 2, 3] };
const y = { foo: [4, 5, 6] };
const z = merge(x, y, { arrayMerge: (destinationArray, sourceArray) => destinationArray.concat(sourceArray) });
console.log(z); // { foo: [1, 2, 3, 4, 5, 6] }"}

Merging with array replacement

This feature allows you to replace the destination array with the source array instead of merging or concatenating them.

{"const merge = require('deepmerge');
const x = { foo: [1, 2, 3] };
const y = { foo: [4, 5, 6] };
const z = merge(x, y, { arrayMerge: (destinationArray, sourceArray) => sourceArray });
console.log(z); // { foo: [4, 5, 6] }"}

Merging with custom options

This feature allows you to provide custom merge functions to handle the merging process according to your specific requirements.

{"const merge = require('deepmerge');
const x = { foo: { bar: 3 } };
const y = { foo: { bar: 4, baz: 5 } };
const overwriteMerge = (destinationArray, sourceArray, options) => sourceArray;
const z = merge(x, y, { arrayMerge: overwriteMerge });
console.log(z); // { foo: { bar: 4, baz: 5 } }"}

Other packages similar to deepmerge

lodash.merge

Lodash provides a merge function that can recursively merge own and inherited enumerable string keyed properties of source objects into the destination object. It's similar to deepmerge but is part of the larger lodash utility library.

extend

The extend package is a port of the jQuery.extend method that can deep copy both arrays and objects. It is less specialized than deepmerge and does not provide as many options for customizing the merge behavior.

object-assign-deep

This package offers functionality similar to Object.assign but with deep merging capabilities. It is a smaller and more focused utility compared to deepmerge, but it may not offer the same level of customization for array merging and other specific use cases.

README

deepmerge

Merges the enumerable attributes of two or more objects deeply.

UMD bundle is 567B minified+gzipped

Migration from 1.x to 2.0.0

Check out the changes from version 1.x to 2.0.0

For the legacy array element-merging algorithm, see the arrayMerge option below.

Webpack bug

If you have require('deepmerge') (as opposed to import merge from 'deepmerge') anywhere in your codebase, Webpack 3 and 4 have a bug that breaks bundling.

If you see Error: merge is not a function, add this alias to your Webpack config:

alias: {
	deepmerge$: path.resolve(__dirname, 'node_modules/deepmerge/dist/umd.js'),
}

Getting Started

Example Usage

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

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

var expected = {
	foo: {
		bar: 3,
		baz: 4
	},
	array: [{
		does: 'work',
		too: [ 1, 2, 3 ]
	}, {
		does: 'work',
		too: [ 4, 5, 6 ]
	}, {
		really: 'yes'
	}],
	quux: 5
}

merge(x, y) // => expected

Installation

With npm do:

npm install deepmerge

deepmerge can be used directly in the browser without the use of package managers/bundlers as well: UMD version from unpkg.com.

Includes

CommonJS:

var merge = require('deepmerge')

ES Modules:

import merge from 'deepmerge'

API

merge(x, y, [options])

Merge two objects x and y deeply, returning a new merged object with the elements from both x and y.

If an element at the same key is present for both x and y, the value from y will appear in the result.

Merging creates a new object, so that neither x or y is modified.

merge.all(arrayOfObjects, [options])

Merges any number of objects into a single result object.

var x = { foo: { bar: 3 } }
var y = { foo: { baz: 4 } }
var z = { bar: 'yay!' }

var expected = { foo: { bar: 3, baz: 4 }, bar: 'yay!' }

merge.all([x, y, z]) // => expected

Options

arrayMerge

deepmerge, by default, concatenates arrays and merges array values.

There are however nigh-infinite valid ways to merge arrays, and you may want to supply your own method. You can do this by passing an arrayMerge function as an option.

The options object will include the default isMergeableObject implementation if the top-level consumer didn't pass a custom function in.

Examples

Example of overwriting merge when merging arrays:

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

Example of preventing arrays inside of objects from being merged:

const dontMerge = (destination, source) => source
merge(
	{ coolThing: [1, 2, 3] },
	{ coolThing: ['a', 'b', 'c'] },
	{ arrayMerge: dontMerge }
) // => { coolThing: ['a', 'b', 'c'] }

To use the legacy (pre-version-2.0.0) array merging algorithm, use the following:

const emptyTarget = value => Array.isArray(value) ? [] : {}
const clone = (value, options) => merge(emptyTarget(value), value, options)

function legacyArrayMerge(target, source, options) {
	const destination = target.slice()

	source.forEach(function(e, i) {
		if (typeof destination[i] === 'undefined') {
			const cloneRequested = options.clone !== false
			const shouldClone = cloneRequested && options.isMergeableObject(e)
			destination[i] = shouldClone ? clone(e, options) : e
		} else if (options.isMergeableObject(e)) {
			destination[i] = merge(target[i], e, options)
		} else if (target.indexOf(e) === -1) {
			destination.push(e)
		}
	})
	return destination
}

merge(
	[{ a: true }],
	[{ b: true }, 'ah yup'],
	{ arrayMerge: legacyArrayMerge }
) // => [{ a: true, b: true }, 'ah yup']

isMergeableObject

By default, deepmerge clones every property from almost every kind of object.

You may not want this, if your objects are of special types, and you want to copy the whole object instead of just copying its properties.

You can accomplish this by passing in a function for the isMergeableObject option.

If you only want to clone properties of plain objects, and ignore all "special" kinds of instantiated objects, you probably want to drop in is-plain-object.

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

function SuperSpecial() {
	this.special = 'oh yeah man totally'
}

const instantiatedSpecialObject = new SuperSpecial()

const target = {
	someProperty: {
		cool: 'oh for sure'
	}
}

const source = {
	someProperty: instantiatedSpecialObject
}

const defaultOutput = merge(target, source)

defaultOutput.someProperty.cool // => 'oh for sure'
defaultOutput.someProperty.special // => 'oh yeah man totally'
defaultOutput.someProperty instanceof SuperSpecial // => false

const customMergeOutput = merge(target, source, {
	isMergeableObject: isPlainObject
})

customMergeOutput.someProperty.cool // => undefined
customMergeOutput.someProperty.special // => 'oh yeah man totally'
customMergeOutput.someProperty instanceof SuperSpecial // => true

clone

Deprecated.

Defaults to true.

If clone is false then child objects will be copied directly instead of being cloned. This was the default behavior before version 2.x.

Testing

With npm do:

npm test

License

MIT

Changelog

2.1.1

• documentation: Rename "methods" to "api", note ESM syntax #103
• documentation: Fix grammar #107
• documentation: Restructure headers for clarity + some wording tweaks 108 + 109