utils-merge2

    2.0.0 • Public • Published

    Merge

    NPM version Build Status Coverage Status Dependencies

    Merge and extend objects.

    Installation

    $ npm install utils-merge2

    Usage

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

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

    Merges and extends a target object.

    var target = {
        'a': 'beep'
    };
    var source = {
        'a': 'boop',
        'b': 'bap'
    };
     
    var out = merge( target, source );
    /* 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 = merge( target, source1, source2 );
    /* returns
        {
            'a': 'beep',
            'b': 'boop',
            'c': 'cat'
        }
    */

    merge.factory( options )

    Returns a custom merge function for merging and extending objects.

    var factory = require( 'utils-merge2' ).factory;
     
    var opts = {
        'level': 100,
        'copy': true,
        'override': true,
        'extend': true    
    };
     
    var 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.

    var target = {
        'a': {
            'b': {
                'c': 5
            },
            'd': 'beep'
        }
    };
    var source = {
        'a': {
            'b': {
                'c': 10
            }
        }
    };
     
    var out = merge( target, source );
    /* returns
        {
            'a': {
                'b': {
                    'c': 10
                },
                'd': 'beep'
            }
        }
    */

    To limit the merge depth, set the level option.

    var merge = factory({
        'level': 2
    });
     
    var target = {
        '1': {
            'a': 'beep',
            '2': {
                '3': null,
                'b': [ 5, 6, 7 ]
            }
        }
    };
     
    var source = {
        '1': {
            'b': 'boop',
            '2': {
                '3': [ 1, 2, 3 ]
            }
        }
    };
     
    var out = merge( target, source );
    /* 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 = merge( target, source );
     
    console.log( out.a.b === source.a.b );
    // returns false

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

    var merge = factory({
        'copy': false
    });
     
    var target = {};
     
    var source = {
        'a': [ 1, 2, 3 ]
    };
     
    var out = merge( target, source );
     
    var bool = ( out.a === source.a );
    // returns true

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

    var merge = factory({
        'override': false
    });
     
    var target = {
        'a': 'beep',
        'b': 'boop'
    };
     
    var source = {
        'a': null,
        'c': 'bop'
    };
     
    var out = merge( target, source );
    /* returns
        {
            'a': 'beep',
            'b': 'boop',
            'c': 'bop'
        }
    */

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

    function strategy( a, b, key ) {
        // a => target value
        // b => source value
        // key => object key
        if ( key === 'a' ) {
            return b;
        }
        if ( key === 'b' ) {
            return a;
        }
        return 'bebop';
    }
     
    var merge = factory({
        'override': strategy
    });
     
    var target = {
        'a': 'beep',
        'b': 'boop',
        'c': 1234
    };
     
    var source = {
        'a': null,
        'b': {},
        'c': 'bop'
    };
     
    var out = merge( target, source );
    /* 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 = factory({
        'extend': false
    });
     
    var target = {
        'a': 'beep',
        'b': 'boop'
    };
     
    var source = {
        'b': 'hello',
        'c': 'world'
    };
     
    var out = merge( target, source );
    /* returns
        {
            'a': 'beep',
            'b': 'hello'
        }
    */

    Notes

    • The target object is mutated.

      var target = {
          'a': 'beep'
      };
      var source = {
          'b': 'boop'
      };
       
      var out = merge( target, source );
       
      console.log( out === target );
      // returns true
       
      console.log( target.b );
      // returns 'boop'

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

      var target = {
          'a': 'beep'
      };
      var source = {
          'b': 'boop'
      };
       
      var out = merge( {}, target, source );
       
      console.log( out === target );
      // 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

    var merge = require( 'utils-merge2' );
     
    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': Math.PI,
        'c': {
            'c1': 'bap',
            'c3': {
                'c3b': 5,
                'c3c': 'bop'
            },
            'c4': 1337,
            'c5': new Date()
        },
        'd': [ 4, 5, 6 ],
        'e': true
    };
     
    out = merge( {}, target, source );
     
    console.dir( 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

    MIT license.

    Copyright

    Copyright © 2015-2016. Athan Reines.

    Install

    npm i utils-merge2

    DownloadsWeekly Downloads

    51

    Version

    2.0.0

    License

    MIT

    Last publish

    Collaborators

    • kgryte