merge-professor

Advanced recursive merge utility for JavaScript objects and arrays.

Features

• Supports multiple objects or arrays to merge in single function call.
• Merges objects recursively.
• Allows to merge object items of arrays by specified identifier fields.
• Has an option to merge properties existing only in first object.
• Free to use. :)

Installation

npm install merge-professor --save

Usage

• require with Node.js:

  var merge = require('merge-professor');

• in browser include dist/merge.js or dist/merge.min.js script:

  var merge = window.mergeProfessor;

and then

var o = merge({ a: 1 }, { b: 2 });                        // { a: 1, b: 2 }
var a = merge([1, 2, 3], ['one', 'two', 'three']);        // [1, 2, 3, 'one', 'two', 'three']

Examples

• merge plain objects and arrays:

  var o = merge({ a: 1 }, { b: 2 });                    // { a: 1, b: 2 }
  var a = merge([1, 2, 3], ['one', 'two', 'three']);    // [1, 2, 3, 'one', 'two', 'three']

• merge objects recursively:

  var o1 = {
      language: {
          en: 'English',
          ru: 'Русский'
      },
      sidebarPanelId: 'satellite'
  };
  
  var o2 = {
      language: {
          ru: 'Russian',
          de: 'German'
      },
      sidebarPanelId: 'geocoding'
  };
  
  var o = merge(o1, o2);    // {
                            //     language: {
                            //         en: 'English',
                            //         ru: 'Russian',
                            //         de: 'German'
                            //     },
                            //     sidebarPanelId: 'geocoding'
                            // }

• merge arrays uniting their object items by specified identifier field:

  var a1 = [
      { id: 25994, name: 'Terra', visible: true },
      { id: 27424, name: 'Aqua', visible: false }
  ];
  
  var a2 = [
      { id: 27424, name: 'AQUA' },
      { id: 25994, visible: false }
  ];
  
  var a = merge(a1, a2, 'id');    // [
                                  //     { id: 25994, name: 'Terra', visible: false },
                                  //     { id: 27424, name: 'AQUA', visible: false }
                                  // ]

  or even objects with nested arrays uniting their object items by more than single identifier field:

  var o1 = {
      satellites: [
          { id: 25994, name: 'Terra', visible: true },
          { id: 27424, name: 'Aqua', visible: false }
      ]
  };
  
  var o2 = {
      satellites: [
          { id: 27424, name: 'AQUA', visible: true },
          { id: 40069, name: 'Terra' }
      ]
  };
    
  var o = merge(o1, o2, 'id', 'name');    // {
                                          //     satellites: [
                                          //         { id: 40069, name: 'Terra', visible: true },
                                          //         { id: 27424, name: 'AQUA', visible: true }
                                          //     ]
                                          // }

• merge properties existing only in first object:

  var o1 = { id: 25994, name: 'Terra', visible: false };
  var o2 = { sidebarPanelId: 'satellite', visible: true };
  
  var o = merge(o1, o2, true);    // { id: 25994, name: 'Terra', visible: true });

• merge with all available options:

  var o1 = {
      satellites: [
          { id: 25994, name: 'Terra', visible: true },
          { id: 27424, name: 'Aqua', visible: false }
      ]
  };
  
  var o2 = {
      satellites: [
          { id: 25994, visible: false },
          { id: 40069, name: 'Meteor-M №2', visible: true }
      ]
  };
  
  var o = merge(o1, o2, 'id', true);    // {
                                        //     satellites: [
                                        //         { id: 25994, name: 'Terra', visible: false },
                                        //         { id: 27424, name: 'Aqua', visible: false }
                                        //     ]
                                        // }

Building

In order to build library run:

npm run build

Testing

Run unit tests:

npm test

In order to run tests with Coveralls locally you have to provide COVERALLS_REPO_TOKEN:

COVERALLS_REPO_TOKEN=<token> npm run test:coverage

Contribution

Before making a pull request, please, be sure that your changes are rebased to dev branch.

License

MIT