mergeDeepLeft()

mergeDeepLeft<T, U>(left, right): T & U

Recursively merges objects, with left values taking precedence.

remarque

Arrays are replaced, not merged.

---

Type Parameters

T: T extends AnyRecord

The type of the left object.

U: U extends AnyRecord

The type of the right object.

---

Parameters

left: T

The left object (takes precedence).

right: U

The right object (fallback values).

---

Returns: T & U

A new deeply merged object.

---

See Also

mergeDeepRight

---

Since

2.0.0

---

Note

Symbol keys are included via Reflect.ownKeys.

---

Performance

O(n) time & space where n is total number of properties. Early returns for null/undefined/primitives/arrays. Uses spread operator for shallow copy.

---

Example

const left = { user: { name: 'John', age: 30 } };
const right = { user: { name: 'Jane', email: 'jane@example.com' } };

mergeDeepLeft(left, right);
// => { user: { name: 'John', age: 30, email: 'jane@example.com' } }

// Arrays: left wins
mergeDeepLeft({ items: [1, 2] }, { items: [3, 4] });
// => { items: [1, 2] }

---

Use Cases

Merge with default precedence 📌

Merge objects recursively where the first object (left) keeps its values if conflicts occur. Useful for preserving original state while filling in gaps.

#merge#defaults#precedence#left#preserve#recursive

const result = mergeDeepLeft(defaults, overrides);
// defaults are kept, overrides only add new keys

Preserve initialization data

Merge new data into an object, but refuse to overwrite any existing values. Useful for "fill only if empty" logic.

#preserve#initialization#refuse#overwrite#fill#empty

const session = { id: 123 };
const newInfo = { id: 456, name: 'Guest' };
const result = mergeDeepLeft(session, newInfo);
// { id: 123, name: 'Guest' } - id preserved

Fill missing data

Populate a sparse object with data from a complete template. Useful for restoring partial backups or checking schema compliance.

#fill#missing#sparse#template#restore#backup

const complete = mergeDeepLeft(template, partialData);