JavaScript Object Spread Overwrites Nested Objects: Merge Each Level

Find the level that was overwritten#

MDN documents that the last assignment wins for repeated property names. With defaults.retry = { attempts: 3, delayMs: 1000 } and patch.retry = { attempts: 0 }, the outer object has one property named retry. Its last supplied value is the patch’s entire object.

Reversing the spreads restores the default object but discards the requested retry count. That changes precedence; it does not solve nested merging. Likewise, putting retry: { ...defaults.retry, ...patch.retry } before ...patch lets the later spread overwrite the reconstruction again.

The ECMAScript CopyDataProperties operation copies enumerable own property values. It does not recursively combine objects stored in those values. When a copied value is an object, the new property still refers to that object.

Check both the outgoing shape and references. A missing delayMs diagnoses replacement; result.retry === patch.retry identifies the shared object. A new outer wrapper alone does not establish independent nested settings.

Reproduce replacement and verify a settings policy#

Save this fixture as merge-settings.mjs, then run node merge-settings.mjs. It was executed during article preparation on macOS with Node.js 24.13.0 on October 18, 2026. No package, network service, or framework is required.

The helper implements one small application contract: a boolean flag, nonnegative safe-integer retry values, and a dense list of strings. The caller supplies validated plain data records and a valid base configuration. The helper selects known output fields and validates their values; it is not a general validator for arbitrary JavaScript objects.

1
import assert from 'node:assert/strict';
2

3
const defaults = {
4
  enabled: true,
5
  retry: { attempts: 3, delayMs: 1000 },
6
  servers: ['primary', 'backup'],
7
};
8
const patch = { retry: { attempts: 0 }, servers: ['local'] };
9
const shallow = { ...defaults, ...patch };
10
assert.deepEqual(shallow.retry, { attempts: 0 });
11
assert.equal(Object.hasOwn(shallow.retry, 'delayMs'), false);
12
assert.equal(shallow.retry, patch.retry);
13
console.log(`shallow retry: ${JSON.stringify(shallow.retry)}`);
14

15
const reversed = { ...patch, ...defaults };
16
assert.equal(reversed.retry.attempts, 3);
17
console.log(`reversed attempts: ${reversed.retry.attempts}`);
18

19
// Contract: validated plain records; absent/undefined means keep default.
20
// null is invalid; servers replaces the list, including an empty list.
21
function mergeSettings(base, update) {
22
  if (update === null || typeof update !== 'object' || Array.isArray(update)) {
23
    throw new TypeError('update must be a record');
24
  }
25
  if (update.retry !== undefined &&
26
      (update.retry === null || typeof update.retry !== 'object' ||
27
       Array.isArray(update.retry))) {
28
    throw new TypeError('retry must be a record');
29
  }
30
  const retry = update.retry ?? {};
31
  const enabled = update.enabled === undefined ? base.enabled : update.enabled;
32
  const attempts = retry.attempts === undefined ? base.retry.attempts : retry.attempts;
33
  const delayMs = retry.delayMs === undefined ? base.retry.delayMs : retry.delayMs;
34
  const servers = update.servers === undefined ? base.servers : update.servers;
35
  if (typeof enabled !== 'boolean' ||
36
      !Number.isSafeInteger(attempts) || attempts < 0 ||
37
      !Number.isSafeInteger(delayMs) || delayMs < 0 ||
38
      !Array.isArray(servers) ||
39
      !Array.from(servers).every(value => typeof value === 'string')) {
40
    throw new TypeError('invalid settings');
41
  }
42
  return { enabled, retry: { attempts, delayMs }, servers: [...servers] };
43
}
44

45
const merged = mergeSettings(defaults, patch);
46
assert.deepEqual(merged, {
47
  enabled: true, retry: { attempts: 0, delayMs: 1000 }, servers: ['local'],
48
});
49
assert.notEqual(merged.retry, defaults.retry);
50
assert.notEqual(merged.retry, patch.retry);
51
assert.notEqual(merged.servers, patch.servers);
52
merged.retry.attempts = 9;
53
merged.servers.push('extra');
54
assert.equal(defaults.retry.attempts, 3);
55
assert.equal(patch.retry.attempts, 0);
56
assert.deepEqual(patch.servers, ['local']);
57
console.log('merged: default delay retained; source records and list unchanged');
58

59
for (const [label, update, expected] of [
60
  ['omitted', {}, defaults],
61
  ['undefined', { retry: undefined, servers: undefined }, defaults],
62
  ['leaf undefined', { retry: { attempts: undefined } }, defaults],
63
  ['zero and false', { enabled: false, retry: { attempts: 0 } },
64
    { enabled: false, retry: { attempts: 0, delayMs: 1000 }, servers: defaults.servers }],
65
  ['empty list', { servers: [] }, { ...defaults, servers: [] }],
66
]) {
67
  assert.deepEqual(mergeSettings(defaults, update), expected);
68
  console.log(`policy: ${label} passed`);
69
}
70
for (const update of [null, { retry: null }, { retry: [] },
71
  { retry: { attempts: null } }, { servers: null }, { servers: [, 'backup'] }]) {
72
  assert.throws(() => mergeSettings(defaults, update), TypeError);
73
}
74
const wrapper = { ...defaults };
75
assert.equal(wrapper.retry, defaults.retry);
76
assert.equal(wrapper.servers, defaults.servers);
77
console.log('invalid inputs rejected; top-level copy still shares children');
78
console.log('all assertions passed');

Expected output:

1
shallow retry: {"attempts":0}
2
reversed attempts: 3
3
merged: default delay retained; source records and list unchanged
4
policy: omitted passed
5
policy: undefined passed
6
policy: leaf undefined passed
7
policy: zero and false passed
8
policy: empty list passed
9
invalid inputs rejected; top-level copy still shares children
10
all assertions passed

The mutation checks are separate from the merge checks. The helper creates a new retry record and copies the selected servers array. Because that array accepts strings only, copying its entries does not retain mutable element objects. The assertions then change the result and confirm that the patch and default retry counts and patch list remain intact.

Choose missing-value and array semantics explicitly#

The helper uses field selection rather than a generic recursive merge. Its policy is deliberate and exercised above:

A nested spread by itself would retain a leaf property explicitly set to undefined, replacing the default. The helper instead tests === undefined at each selected field. It also avoids value || default, which would discard the accepted zero and false values.

Spreading null or undefined into an object contributes no properties, as specified by CopyDataProperties. Therefore { ...base.retry, ...update.retry } would not reject retry: null on its own. The helper checks null first because its schema rejects it. If your application uses null to clear a section, implement that as a separate branch and change the expected output accordingly.

For JSON request bodies, remember that undefined object fields disappear during serialization. The in-memory distinction exercised here may no longer exist after transport. Define the update contract at the boundary where the patch is received.

Keep the fix limited to the shape you own#

Use explicit nested reconstruction for a small, known object whose leaf values already meet the contract. Use a field-specific helper when omission, clearing, list replacement, and validation need different rules. Adding another nested section means defining that section’s policy too; this helper intentionally drops unselected fields instead of copying them through.

A deep copy is a different operation from combining defaults and updates. If independent data copying is the actual requirement, see the separate structuredClone diagnosis and data-only payload example. Cloning the patch alone would still not supply its missing default delay.

The published checks cover ordinary data records, primitive leaf values, string arrays, and the listed invalid inputs. They do not establish behavior for getters, proxies, class instances, cyclic graphs, framework reactive objects, or untrusted objects with executable property access. Parse and validate external input before calling this helper, and reproduce framework behavior in that framework’s runtime.

For the lost-setting symptom, assert the nested fields after applying the patch. For independence, assert references and mutate the result in a disposable fixture. Those checks answer different questions, and both are needed when the resulting settings will be changed later.

References:

• ECMAScript: CopyDataProperties
• MDN: Spread syntax