Merge

Merge and extend objects.

Installation

1$ npm install utils-merge2

Usage

1var merge = require( 'utils-merge2' );

merge( target, source1[, source2[,...,sourceN]] )

Merges and extends a target object.

1var target = {
2    'a': 'beep'
3};
4var source = {
5    'a': 'boop',
6    'b': 'bap'
7};
8
9var out = merge( target, source );
10/* returns
11    {
12        'a': 'boop',
13        'b': 'bap'
14    }
15*/

The function supports merging multiple source objects.

1var target = {
2    'a': 'beep'
3};
4var source1 = {
5    'b': 'boop'
6};
7var source2 = {
8    'c': 'cat'
9};
10
11var out = merge( target, source1, source2 );
12/* returns
13    {
14        'a': 'beep',
15        'b': 'boop',
16        'c': 'cat'
17    }
18*/

merge.factory( options )

Returns a custom merge function for merging and extending objects.

1var factory = require( 'utils-merge2' ).factory;
2
3var opts = {
4    'level': 100,
5    'copy': true,
6    'override': true,
7    'extend': true    
8};
9
10var merge = factory( opts );

The function accepts the following options:

• level: limits the merge depth. The default merge strategy is a deep (recursive) merge. Default: level = +infinity.
• copy: boolean indicating whether to deep copy merged values. Deep copying prevents shared references and source object mutation. Default: true.
• override: defines the merge strategy. If true, source object values will always override target object values. If false, source values never override target values (useful for adding, but not overwriting, properties). To define a custom merge strategy, provide a function. Default: true.
• extend: boolean indicating whether new properties can be added to the target object. If false, only shared properties are merged. Default: true.

The default merge is a deep (recursive) merge.

1var target = {
2    'a': {
3        'b': {
4            'c': 5
5        },
6        'd': 'beep'
7    }
8};
9var source = {
10    'a': {
11        'b': {
12            'c': 10
13        }
14    }
15};
16
17var out = merge( target, source );
18/* returns
19    {
20        'a': {
21            'b': {
22                'c': 10
23            },
24            'd': 'beep'
25        }
26    }
27*/

To limit the merge depth, set the level option.

1var merge = factory({
2    'level': 2
3});
4
5var target = {
6    '1': {
7        'a': 'beep',
8        '2': {
9            '3': null,
10            'b': [ 5, 6, 7 ]
11        }
12    }
13};
14
15var source = {
16    '1': {
17        'b': 'boop',
18        '2': {
19            '3': [ 1, 2, 3 ]
20        }
21    }
22};
23
24var out = merge( target, source );
25/* returns
26    {
27        '1': {
28            'a': 'beep',
29            'b': 'boop',
30            '2': {
31                '3': [ 1, 2, 3 ]
32            }
33        }
34    }
35*/

By default, merged values are deep copied.

1var target = {
2    'a': null
3};
4var source = {
5    'a': {
6        'b': [ 1, 2, 3 ]
7    }
8};
9
10var out = merge( target, source );
11
12console.log( out.a.b === source.a.b );
13// returns false

To allow shared references, set the copy option to false.

1var merge = factory({
2    'copy': false
3});
4
5var target = {};
6
7var source = {
8    'a': [ 1, 2, 3 ]
9};
10
11var out = merge( target, source );
12
13var bool = ( out.a === source.a );
14// returns true

To prevent existing properties from being overridden, set the override option to false.

1var merge = factory({
2    'override': false
3});
4
5var target = {
6    'a': 'beep',
7    'b': 'boop'
8};
9
10var source = {
11    'a': null,
12    'c': 'bop'
13};
14
15var out = merge( target, source );
16/* returns
17    {
18        'a': 'beep',
19        'b': 'boop',
20        'c': 'bop'
21    }
22*/

Alternatively, to define a custom merge strategy, set the override option to a function.

1function strategy( a, b, key ) {
2    // a => target value
3    // b => source value
4    // key => object key
5    if ( key === 'a' ) {
6        return b;
7    }
8    if ( key === 'b' ) {
9        return a;
10    }
11    return 'bebop';
12}
13
14var merge = factory({
15    'override': strategy
16});
17
18var target = {
19    'a': 'beep',
20    'b': 'boop',
21    'c': 1234
22};
23
24var source = {
25    'a': null,
26    'b': {},
27    'c': 'bop'
28};
29
30var out = merge( target, source );
31/* returns
32    {
33        'a': null,
34        'b': 'boop',
35        'c': 'bebop'
36    }
37*/

To prevent non-existent properties from being added to the target object, set the extend option to false.

1var merge = factory({
2    'extend': false
3});
4
5var target = {
6    'a': 'beep',
7    'b': 'boop'
8};
9
10var source = {
11    'b': 'hello',
12    'c': 'world'
13};
14
15var out = merge( target, source );
16/* returns
17    {
18        'a': 'beep',
19        'b': 'hello'
20    }
21*/

---

Notes

• The target object is mutated.

  1var target = {
  2    'a': 'beep'
  3};
  4var source = {
  5    'b': 'boop'
  6};
  7
  8var out = merge( target, source );
  9
  10console.log( out === target );
  11// returns true
  12
  13console.log( target.b );
  14// returns 'boop'

  To return a new object, provide an empty object as the first argument.

  1var target = {
  2    'a': 'beep'
  3};
  4var source = {
  5    'b': 'boop'
  6};
  7
  8var out = merge( {}, target, source );
  9
  10console.log( out === target );
  11// returns false

• Only plain JavaScript objects are merged and extended. The following values/types are either deep copied or assigned:

  • Boolean
  • String
  • Number
  • Date
  • RegExp
  • Array
  • Int8Array
  • Uint8Array
  • Uint8ClampedArray
  • Init16Array
  • Uint16Array
  • Int32Array
  • Uint32Array
  • Float32Array
  • Float64Array
  • Buffer (Node.js)
  • Set
  • Map
  • Error
  • URIError
  • ReferenceError
  • SyntaxError
  • RangeError

• Support for deep merging class instances is inherently fragile.

• Number, String, or Boolean objects are merged as primitives.

• Functions are not deep copied.

---

Examples

1var merge = require( 'utils-merge2' );
2
3var target;
4var source;
5var out;
6
7target = {
8    'a': 'beep',
9    'b': 'boop',
10    'c': {
11        'c1': 'woot',
12        'c2': false,
13        'c3': {
14            'c3a': [ 1, 2 ],
15            'c3b': null
16        }
17    },
18    'd': [ 1, 2, 3 ]
19};
20
21source = {
22    'b': Math.PI,
23    'c': {
24        'c1': 'bap',
25        'c3': {
26            'c3b': 5,
27            'c3c': 'bop'
28        },
29        'c4': 1337,
30        'c5': new Date()
31    },
32    'd': [ 4, 5, 6 ],
33    'e': true
34};
35
36out = merge( {}, target, source );
37
38console.dir( out );
39/* returns
40    {
41        'a': 'beep',
42        'b': 3.141592653589793,
43        'c': { 
44            'c1': 'bap',
45            'c2': false,
46            'c3': { 
47                'c3a': [ 1, 2 ],
48                'c3b': 5,
49                'c3c': 'bop'
50            },
51            'c4': 1337,
52            'c5': <Date>
53        },
54        'd': [ 4, 5, 6 ],
55        'e': true
56    }
57*/

To run the example code from the top-level application directory,

1$ node ./examples/index.js

---

Tests

Unit

This repository uses tape for unit tests. To run the tests, execute the following command in the top-level application directory:

1$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

1$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

1$ make view-cov

Browser Support

This repository uses Testling for browser testing. To run the tests in a (headless) local web browser, execute the following command in the top-level application directory:

1$ make test-browsers

To view the tests in a local web browser,

1$ make view-browser-tests

---

License

MIT license.

Copyright

Copyright © 2015-2016. Athan Reines.