Merge
Merge and extend objects.
Installation
$ npm install utils-merge2
Usage
var merge = ;
merge( target, source1[, source2[,...,sourceN]] )
Merges and extends a target object
.
var target ='a': 'beep';var source ='a': 'boop''b': 'bap';var out = ;/* returns{'a': 'boop','b': 'bap'}*/
The function
supports merging multiple source objects
.
var target ='a': 'beep';var source1 ='b': 'boop';var source2 ='c': 'cat';var out = ;/* returns{'a': 'beep','b': 'boop','c': 'cat'}*/
merge.factory( options )
Returns a custom merge function
for merging and extending objects
.
var factory = factory;var opts ='level': 100'copy': true'override': true'extend': true;var merge = ;
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 sourceobject
mutation. Default:true
. - override: defines the merge strategy. If
true
, sourceobject
values will always override targetobject
values. Iffalse
, source values never override target values (useful for adding, but not overwriting, properties). To define a custom merge strategy, provide afunction
. Default:true
. - extend:
boolean
indicating whether new properties can be added to the targetobject
. Iffalse
, only shared properties are merged. Default:true
.
The default merge is a deep (recursive) merge.
var target ='a':'b':'c': 5'd': 'beep';var source ='a':'b':'c': 10;var out = ;/* returns{'a': {'b': {'c': 10},'d': 'beep'}}*/
To limit the merge depth, set the level
option.
var merge =;var target ='1':'a': 'beep''2':'3': null'b': 5 6 7;var source ='1':'b': 'boop''2':'3': 1 2 3;var out = ;/* returns{'1': {'a': 'beep','b': 'boop','2': {'3': [ 1, 2, 3 ]}}}*/
By default, merged values are deep copied.
var target ='a': null;var source ='a':'b': 1 2 3;var out = ;console;// returns false
To allow shared references, set the copy
option to false
.
var merge =;var target = {};var source ='a': 1 2 3;var out = ;var bool = outa === sourcea ;// returns true
To prevent existing properties from being overridden, set the override
option to false
.
var merge =;var target ='a': 'beep''b': 'boop';var source ='a': null'c': 'bop';var out = ;/* returns{'a': 'beep','b': 'boop','c': 'bop'}*/
Alternatively, to define a custom merge strategy, set the override
option to a function
.
{// a => target value// b => source value// key => object keyif key === 'a'return b;if key === 'b'return a;return 'bebop';}var merge =;var target ='a': 'beep''b': 'boop''c': 1234;var source ='a': null'b': {}'c': 'bop';var out = ;/* returns{'a': null,'b': 'boop','c': 'bebop'}*/
To prevent non-existent properties from being added to the target object
, set the extend
option to false
.
var merge =;var target ='a': 'beep''b': 'boop';var source ='b': 'hello''c': 'world';var out = ;/* returns{'a': 'beep','b': 'hello'}*/
Notes
-
The target
object
is mutated.var target ='a': 'beep';var source ='b': 'boop';var out = ;console;// returns trueconsole;// returns 'boop'To return a new
object
, provide an emptyobject
as the first argument.var target ='a': 'beep';var source ='b': 'boop';var out = ;console;// 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
, orBoolean
objects are merged as primitives. -
Functions are not deep copied.
Examples
var merge = ;var target;var source;var out;target ='a': 'beep''b': 'boop''c':'c1': 'woot''c2': false'c3':'c3a': 1 2'c3b': null'd': 1 2 3;source ='b': MathPI'c':'c1': 'bap''c3':'c3b': 5'c3c': 'bop''c4': 1337'c5':'d': 4 5 6'e': true;out = ;consoledir out ;/* returns{'a': 'beep','b': 3.141592653589793,'c': {'c1': 'bap','c2': false,'c3': {'c3a': [ 1, 2 ],'c3b': 5,'c3c': 'bop'},'c4': 1337,'c5': <Date>},'d': [ 4, 5, 6 ],'e': true}*/
To run the example code from the top-level application directory,
$ 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:
$ 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:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ 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:
$ make test-browsers
To view the tests in a local web browser,
$ make view-browser-tests
License
Copyright
Copyright © 2015-2016. Athan Reines.