JSON Deep Merge: Why Shallow Merge Fails and How to Fix It

The term shallow merge refers to the fact that Object.assign and the spread operator only copy properties at the top level of an object. When both the target and the source have a property with the same name whose value is itself an object, the source's version of that nested object completely replaces the target's version. None of the target's nested properties survive — not even ones that the source did not set.

This behavior is often surprising because the top-level merge looks correct. If you merge { color: 'red', size: 'large' } onto { color: 'blue', weight: 10 }, you get the right result: { color: 'red', weight: 10, size: 'large' }. The merge works because all values are primitives — strings and numbers — which are copied by value. The problem emerges as soon as any value is an object or array, because object references are copied, not the objects themselves.

Consider two configuration objects, each with a server property that is itself an object with host, port, and timeout. When you shallow merge the user config onto the defaults, the user config's server object reference replaces the defaults' server object reference entirely. Even if the user config only specified a port, the result's server property points to the user config's server object — an object that only has port. The host and timeout from defaults are not present in that object and are therefore inaccessible in the merged result.

This is not a bug in Object.assign or the spread operator — it is their defined behavior, and it is correct for use cases where you want the source to completely replace any conflicting top-level values. The mismatch between expected and actual behavior arises when developers reach for these tools expecting recursive combination rather than top-level replacement. Recognizing when your data is nested and when a recursive merge is actually needed is the core diagnostic skill for this class of problem.

The most reliable way to diagnose whether your merge is behaving shallowly is to inspect the nested properties of the merged result directly after the merge operation. Do not inspect only the top-level keys — they will look correct in both a shallow and a deep merge. Instead, access a nested key that exists only in the target but not in the source, and check whether it appears in the merged output.

For configuration objects, a good test is to log a nested property that you expect to be preserved from the default: mergedConfig.server.host or mergedConfig.database.poolSize. If that value is undefined in the result despite being present in the defaults, the merge is shallow and the nested defaults are being dropped.

Node.js's util.inspect with depth: null produces a complete recursive view of an object with no truncation, which is helpful for comparing deeply nested structures. In a browser console, console.dir(obj) expands the object interactively. For automated tests, using a deep equality assertion such as toEqual in Jest or deepStrictEqual in Node's assert module will fail if a nested property is missing, immediately surfacing the problem.

When using lodash.merge, a common diagnostic confusion is that lodash.merge mutates its first argument. If you call lodash.merge(defaultConfig, userConfig) and then later call lodash.merge(defaultConfig, anotherConfig), the defaultConfig you are starting from has already been mutated by the first call. Logging defaultConfig after the first merge will show a value that is no longer the original defaults, which can make subsequent merges produce unexpected results. Always pass an empty object as the first argument — lodash.merge({}, defaultConfig, userConfig) — so the defaults remain pristine.

A correct recursive deep merge function follows a straightforward algorithm: for each key in the source, if both the source value and the target value for that key are plain objects, recurse into them; otherwise, use the source value directly. This algorithm correctly handles any depth of nesting and produces a new object at every level, so neither the original target nor the original source is mutated.

The most important implementation detail is the isPlainObject check. Both null and arrays have typeof 'object' in JavaScript, so a naive check for typeof value === 'object' will incorrectly try to recurse into arrays and will throw when trying to recurse into null. A robust check is: val !== null and typeof val === 'object' and !Array.isArray(val). Some implementations also check that the object's prototype is Object.prototype to exclude class instances, which prevents accidentally recursing into Date, Map, or custom objects that happen to have enumerable own properties.

For arrays, the most common default behavior in a deep merge is for the source array to replace the target array entirely, the same way a primitive value would. This is the behavior of lodash.merge for arrays. If your use case requires merging arrays rather than replacing them — for example, concatenating a default middleware list with a user-supplied middleware list — you need to handle arrays explicitly in your merge function, applying the appropriate strategy before falling through to the default recursive or replace logic.

When using npm packages, lodash.merge is the most widely adopted option and has been battle-tested across millions of projects. For TypeScript projects, deepmerge and ts-deepmerge provide type-safe alternatives with customizable merge behavior. If your project already imports lodash for other utilities, using lodash.merge adds no additional bundle weight. For browser applications concerned about bundle size, a small hand-written recursive merge of ten to fifteen lines is a reasonable alternative to importing a library.

Arrays are the most contentious part of deep merge because there is no single obviously correct behavior. The right strategy depends entirely on what the array represents in your data model. Configuration arrays where each element is a standalone value — for example, a list of allowed hostnames — usually call for replacement: the user's list replaces the default list entirely. Arrays where each element is a record with a unique identifier — for example, a list of middleware plugins with names — might call for a union strategy that merges by identifier.

Replacement is the simplest strategy and the default in most deep merge libraries including lodash.merge. When the source has an array for a key, the target's array for that key is completely discarded. This is predictable and easy to reason about, and it means users have full control over the merged result for any array-valued key.

Concatenation combines both arrays into one. This makes sense for additive configurations, such as a list of plugins where both the defaults and the user additions should be active simultaneously. The merged result is [...targetArray, ...sourceArray]. One risk is duplicate values if both arrays contain the same element, which can be addressed by deduplication using a Set for primitive arrays or a discriminator function for object arrays.

Union merge deduplicates after concatenation. For primitive arrays, this is straightforward: new Set([...targetArray, ...sourceArray]). For object arrays, you need a key function that identifies which property serves as the unique identifier, then merge objects with the same key and keep objects with unique keys. This is the most complex strategy and usually needs to be implemented per-array rather than as a universal behavior, because different arrays in the same document may need different discriminator keys.

The cleanest approach for complex documents is to write a merge function that accepts an options object where callers specify the strategy for each array path using a path descriptor or a per-path callback. This avoids trying to infer the correct strategy from the data itself.

Prototype pollution is a security vulnerability that occurs when a merge function processes the __proto__ key as a regular object property. In JavaScript, every object has a prototype chain, and Object.prototype is the root of that chain for all plain objects. If an attacker can get your merge function to assign properties to Object.prototype — by passing a JSON payload containing a __proto__ key — those properties become visible on every plain object in the process, even objects created before the merge happened.

This is not a theoretical concern. Multiple production npm packages have received security disclosures for prototype pollution vulnerabilities in their merge implementations. The attack is particularly effective in server-side Node.js applications that accept JSON from untrusted clients and merge it with application state, because a successful pollution affects all subsequent request handling in the same process.

The root cause is using for...in or direct bracket notation assignment without filtering dangerous keys. The for...in loop iterates inherited properties in addition to own properties, which means __proto__ can appear in the iteration. Even with Object.keys(), which only returns own enumerable properties, JSON.parse on a string containing __proto__ does create an own property with that name on the parsed object — the JSON spec does not prohibit it, and the parser creates it literally.

The fix has two components. First, use Object.keys() rather than for...in to iterate source properties. Second, maintain an explicit deny-list of dangerous keys including __proto__, constructor, and prototype, and skip those keys before any merge logic. Additionally, starting each merge level with Object.assign({}, target) rather than mutating the target in place prevents the recursive call from ever touching the prototype directly through assignment. For untrusted user input, validate the JSON against a schema before merging it — schema validation can reject documents containing unexpected keys at the top level or in nested positions.

Configuration management is the most common real-world application of deep merge, and it has well-established patterns that are worth following. The typical pattern is a cascade of sources in increasing priority order: built-in defaults, then a configuration file, then environment variables, then command-line arguments. Each higher-priority source is deep-merged onto the accumulated result from lower-priority sources, so that each source only needs to specify the values it intends to override.

Always treat the base defaults as immutable. Pass an empty object as the first argument to lodash.merge or your recursive merge function, so the output is a fresh object and the defaults object is never modified. This matters in long-running server processes where multiple requests might trigger configuration reloading: if the defaults object accumulates changes from previous merges, the baseline shifts in unpredictable ways.

When serializing and restoring configuration — for example, caching a merged config object to Redis — use JSON.stringify and JSON.parse, but be aware that any undefined values in the merged result will be stripped. If your merge algorithm ever sets a key to undefined to signal deletion of a default, that signal will not survive serialization. Use a sentinel value like null, or explicitly delete the key before serializing, to ensure the intent is preserved across the serialize-parse cycle.

Document the merge semantics for your configuration system so that contributors understand what they can control. If your merge function replaces arrays, document that a user must specify the entire array to override even a single element. If it concatenates, document that users cannot remove default array elements by omitting them. These behaviors are not obvious from the API surface alone, and misunderstandings lead to configuration mistakes that are difficult to debug because the code works correctly — it just does not do what the user intended.