Mergician

Mergician is a uniquely flexible and light-weight utility for deep (recursive) merging/cloning of JavaScript objects.

Unlike native methods and other merge/clone utilities, Mergician provides advanced options for customizing the merge/clone process. These options make it easy to filter properties, inspect and modify properties before/after merging, merge and sort arrays, and remove duplicate array items. Property accessors and descriptors are also handled properly, ensuring that getter/setter functions are retained and descriptor values are defined on the newly merged object.

• Documentation & Demos

Examples

Basic object cloning using default options:

// ES module shown. CommonJS module also available (see below).
import mergician from 'mergician';

const obj1 = { a: [1, 1], b: { c: 1, d: 1 } };
const clonedObj = mergician({}, obj1);

// Results
console.log(clonedObj); // { a: [1, 1], b: { c: 1, d: 1 } }
console.log(clonedObj === obj1); // false
console.log(clonedObj.a === obj1.a); // false
console.log(clonedObj.b === obj1.b); // false

Advanced object merging using custom options:

// ES module shown. CommonJS module also available (see below).
import mergician from 'mergician';

const obj1 = { a: [1, 1], b: { c: 1, d: 1 } };
const obj2 = { a: [2, 2], b: { c: 2 } };
const obj3 = { e: 3 };

const mergedObj = mergician({
    skipKeys: ['d'],
    appendArrays: true,
    dedupArrays: true,
    filter({ depth, key, srcObj, srcVal, targetObj, targetVal }) {
        if (key === 'e') {
            targetObj['hello'] = 'world';
            console.log(targetObj);
            return false;
        }
    }
})(obj1, obj2, obj3);

// Results
console.log(mergedObj); // { a: [1, 2], b: { c: 2 }, hello: 'world' }

Features

• Deep merge/clone JavaScript objects
• Filter properties
• Inspect and modify properties
• Merge arrays
• Sort arrays
• Remove duplicate array items ("dedup")
• Properly handle property accessors (getters/setters) and descriptors
• Returns new object without modifying source objects (immutable)
• Lightweight (1.5k min+gzip) and dependency-free

Platform Support

Node 10+
Chrome 61+
Edge 16+
Firefox 60+
Safari 10.1+

Installation

NPM

npm install mergician

// ES module
import mergician from 'mergician';

// CommonJS module
const mergician = require('mergician');

CDN

Available on jsdelivr (below), unpkg, and other CDN services that auto-publish npm packages.

// ES module @ latest v1.x.x (see @ version in URL)
import mergician from 'https://cdn.jsdelivr.net/npm/mergician@1/dist/mergician.min.mjs';

<!-- Global "mergician" @ latest v1.x.x (see @ version in URL) -->
<script src="https://cdn.jsdelivr.net/npm/mergician@1/dist/mergician.min.js">

💡 Note the @ version lock in the URLs above. This prevents breaking changes in future releases from affecting your project and is therefore the safest method of loading dependencies from a CDN. When a new major version is released, you will need to manually update your CDN URLs by changing the version after the @ symbol.

Usage & Options

See the documentation site for details.

Contact & Support

• Create a Github issue for bug reports, feature requests, or questions
• Follow @jhildenbiddle for announcements
• Add a ⭐️ star on GitHub or 🐦 tweet to spread the word and support the project!

License

This project is licensed under the MIT license.

Copyright (c) John Hildenbiddle (@jhildenbiddle)