@litert/utils

Appearance

Function deepMerge ​

Source: DeepMerge.ts

Recursively merges two objects and returns a new merged object. Neither input is modified. When a key exists in both objects, the value from the second object takes precedence; for nested objects and arrays, the merge is applied recursively.

Import ​

ts
import { deepMerge } from '@litert/utils-object';

Signature ​

ts
function deepMerge<T1 extends IObject, T2 extends IObject>(
    obj1: T1,
    obj2: T2,
    opts?: IDeepMergeOptions,
): IMergeObject<T1, T2>;

Parameters ​

  • Parameter obj1: T1

    The base object. Its keys and values form the starting point of the merge.

  • Parameter obj2: T2

    The override object. Its values take precedence over obj1 when conflicts occur.

  • Parameter opts?: IDeepMergeOptions

    Optional tuning options. See IDeepMergeOptions.

Return Value ​

A new IMergeObject<T1, T2> object. The original objects are not mutated.

Examples ​

ts
import { deepMerge } from '@litert/utils-object';

const base = { a: 1, b: { x: 10, y: 20 }, c: [1, 2, 3] };
const patch = { b: { y: 99, z: 30 }, c: [4, 5] };

const result = deepMerge(base, patch);
// {
//   a: 1,
//   b: { x: 10, y: 99, z: 30 },  ← merged recursively
//   c: [4, 5, 3]                  ← merged element-by-element
// }

Using arrayAsValue ​

ts
const result = deepMerge(base, patch, { arrayAsValue: true });
// c: [4, 5]  ← patch replaces base entirely

Using nullAsEmptyObject ​

ts
const result = deepMerge({ settings: { theme: 'dark' } }, { settings: null }, { nullAsEmptyObject: true });
// settings: { theme: 'dark' }  ← null treated as {}, not overwriting