Deep Merge

Utility to perform a deep merge of two or more Objects or Arrays.

Environment support

| Node | CLI | UMD | ES Module | Browser | | :--: | :-: | :-: | :-------: | :-----: | | ✔ | x | ✔ | ✔ | ✔ |

Install

npm install @brikcss/merge --save-dev

Setup

Node:

const merge = require('@brikcss/merge');

JS Modules:

import merge from '@brikcss/merge';

Browser:

const merge = window.brikcss.merge;

Usage

Pass list of objects (or arrays) directly to the merge function:

merge(...objects);

To use with options, set 1st argument as an Array of objects (or arrays) and set 2nd argument as options Object:

merge([...objects], options);

Note:

Merge works similarly to the Object.assign() method in that the first object is set as the merge target and will mutate with each merged object. If you wish to do a full clone, simply pass an empty Object (or Array) as the first object:

merge({}, obj1, obj2);
// Or with options:
merge([{}, obj1, obj2], options);

API

Merge(...objects) or Merge([...objects], options)

A container function to merge either Objects or Arrays. Any number of Objects or Arrays can be merged, but they all need to be either Objects or Arrays, not a mix of both.

If only two arguments exist, and the 1st argument is an Array and the 2nd is an Object, Merge will merge the items in the Array and treat the Object as options.

Merge.objects(target, source, options)

Returns the target Object, which is now merged with the source Object.

• target {Object} Target to merge to.
• source {Object} Object to merge with target.
• options {Object} Configuration options.

Merge.arrays(target, source, options)

Returns the target Array, which is now merged with the source Array.

• target {Array} Target to merge to.
• source {Array} Array to merge with target.
• options {Object} Configuration options.

Options

arrayStrategy {String}

• unique (default): Concatenate arrays and remove duplicates.
• merge: Same as unique, except nested objects and arrays are merged.
• concat: Concatenate arrays, but do not remove duplicates.
• overwrite: Overwrite target array with source.

ignore {String[]}

Array of string paths to ignore, or not merge. Use object key names and/or array index values to specify values to ignore. For example: ignore: ['key', '1', 'a.b.c.d'] will ignore the object key key, the 2nd item an array, and the d property in the path a.b.c.d.