putil-merge

A 'swiss army knife' solution for merging two or more objects. It supports deep merge, cloning properties, copying descriptors and filtering.

Installation

$ npm install putil-merge --save

Table of contents

• merge()
• merge.all()

Merge

merge(target, source[, options])

• target:object:
• source:object:
• options:object
  • deep:boolean (optional): If true, it performs deep merge operation. Default: false
  • clone:boolean (optional): If true, clones object properties rather than assigning references. Default: false
  • adjunct:boolean(optional): If true, it copies only non-existing properties. Default: false
  • descriptor:boolean(optional): If true, copies property descriptors. Default: false
  • filter:function (optional): A callback function to test if source property will be merged to target.
  • arrayMerge:boolean|function (optional): If true, it combines array values. It this is a function, result of call will be assigned to target.

Copying source properties to target object

1const a = {x: 1, y: 2};
2const b = {x: {}, z: [1, 2, 3, 4]};
3const merged = merge(a, b);
4assert(merged.x===b.x); // References copied
5assert(merged.z===b.z); // References copied

Cloning source properties to target object

1const a = {x: 1, y: 2};
2const b = {x: {}, z: [1, 2, 3, 4]};
3const merged = merge(a, b, {clone: true});
4assert(merged.x!==b.x); // Object cloned
5assert(merged.z!==b.z); // Array cloned

Applying filter while merge

1const a = {x: 1, y: 2};
2const b = {x: {}, z: [1, 2, 3, 4]};
3const merged = merge(a, b, {filter: (src, key)=>key!=='z'});
4assert(!merged.z); // Z will not be merged

Copying descriptors

1const b = {};
2Object.defineProperty(b, 'foo', {
3  enumerable: false
4});
5const merged = merge({}, b, {descriptor: true});
6assert.strictEqual(Object.getOwnPropertyDescriptor(merged, 'foo').enumerable, false);

Copying getters and setters

1const b = {
2  bar: 1,
3  get foo(){
4    return this.bar; 
5  }
6};
7const merged = merge({}, b, {descriptor: true});
8assert.strictEqual(merged.foo, 1);

Copying function properties

1const b = {
2  bar: 1,
3  getFoo(){
4    return this.bar; 
5  }
6};
7const merged = merge({}, b, {descriptor: true});
8assert.strictEqual(merged.getFoo(), 1);

Merge.all()

Performs merge with more than two objects.

merge.all(arrayOfObjects[, options])

• arrayOfObjects:Array<object>:
• options:object
  • deep:boolean (optional): If true, it performs deep merge operation. Default: false
  • clone:boolean (optional): If true, clones object properties rather than assigning references. Default: false
  • combine:boolean(optional): If true, it copies only non-existing properties. Default: false
  • descriptor:boolean(optional): If true, copies property descriptors. Default: false
  • filter:function (optional): A callback function to test if source property will be merged to target.
  • arrayMerge:boolean|function (optional): If true, it combines array values. It this is a function, result of call will be assigned to target.

Node Compatibility

• node >= 6.0;

License

MIT