Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    object-mergepublic

    object-merge

    Merges JavaScript objects recursively without altering the objects merged.

    Installation

    npm install object-merge
    

    https://npmjs.org/package/object-merge Source code available at: https://github.com/matthewkastor/object-merge/

    Usage

    In Node:

    var objectMerge = require('object-merge');
    var x = {
        a : 'a',
        b : 'b',
        c : {
            d : 'd',
            e : 'e',
            f : {
                g : 'g'
            }
        }
    };
    var y = {
        a : '`a',
        b : '`b',
        c : {
            d : '`d'
        }
    };
    var z = {
        a : {
            b : '``b'
        },
        fun : function foo () {
            return 'foo';
        },
        aps : Array.prototype.slice
    };
    var out = objectMerge(x, y, z);
    // out.a will be {
    //         b : '``b'
    //     }
    // out.b will be '`b'
    // out.c will be {
    //         d : '`d',
    //         e : 'e',
    //         f : {
    //             g : 'g'
    //         }
    //     }
    // out.fun will be a clone of z.fun
    // out.aps will be equal to z.aps
    

    Merging arrays is not the same as concat. When they're merged the arrays are handled as objects. This means that indexes are object properties with numeric names. Merging ['a'] with ['b'] will give you ['b'] because the two arrays both have a property 0 and the last one in overrides the first. However, merging arr1['a', 'b'] with arr2[1] = 'override' will give you ['a', 'override'] because arr1 has properties 0 and 1, while arr2 only has the property 1 which overrides arr1[1] in the output.

    Merging functions will cause the output function to be a clone of the last function merged and it will have all the properties of the merged functions recursively merged together. So something like:

    var func = function () {
        return null;
    };
    var func2 = function () {
        return 'hello';
    };
    func.wohoo = 'wohoo';
    func.obj = {a:'a'};
    func2.wee = 'wee';
    func2.obj = {b:'b'};
    func2.obj2 = {a:'a'};
    var out = objectMerge(func, func2);
    

    will give you a function out that is a clone of func2's function definition but has the properties: wohoo, obj, wee, and obj2. out.obj will have the properties a and b because the properties of func and func2 are merged recursively.

    Options

    Options exist to do things like limit the depth of object traversal and disable errors on detection of circular references. In order to specify the options you must create an options object using the provided method createOptions, a normal object just won't work.

    var objectMerge = require('object-merge');
    var a = {
        'a1' : {
            'a2' : {
                'a3' : {}
            }
        }
    };
    var b = {
        'b1' : {
            'b2' : {
                'b3' : {}
            }
        }
    };
    var opts = objectMerge.createOptions({depth : 2});
    var res = objectMerge(opts, a, b);
    // res will be
    // {
    //     'a1' : {
    //         'a2' : {}
    //     },
    //     'b1' : {
    //         'b2' : {}
    //     }
    // }
    

    See the tests in browser/tests for more examples and expected outputs.

    In the browser, include ./browser/object-merge_web.js in your page. objectMerge will be available in your page.

    For full documentation see the docs folder.

    Tests

    Tests can be run from the root of this package with

    npm test
    

    There are also browser tests available in the browser directory.

    Hacking

    There are several other scripts listed in package.json for development and hacking on this module. They can be run with npm run-script followed by the scripts property corresponding to the script you want to run. For example, given a script called buildDocs, it could be run from the package root by:

    npm run-script buildDocs
    

    Author

    Matthew Kastor matthewkastor@gmail.com https://plus.google.com/100898583798552211130

    License

    gpl-3.0 http://www.gnu.org/licenses/gpl-3.0-standalone.html

    Keywords

    none

    install

    npm i object-merge

    Downloadsweekly downloads

    9,050

    version

    2.5.1

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar