jusimen
MergeKit
Introductory Note
This repository is a fork of mergician with the goal of making it available on npm and updating with new features.
A huge thanks to John Hildenbiddle for creating such a great utility! 🎉
About
mergekit is a uniquely flexible and light-weight utility for cloning and deep (recursive) merging of JavaScript objects.
Unlike native methods and other utilities, mergekit faithfully clones and merges objects by properly handling descriptor values, accessor functions, and prototype properties while offering advanced options for customizing the clone/merge process.
Features
- Deep (recursive) clone/merge JavaScript objects
- Generates new object without modifying source object(s)
- Clone/merge enumerable and non-enumerable properties
- Clone/merge property descriptor values
- Retain, skip, or convert accessor functions to static values
- Inspect, filter, and modify properties
- Merge, skip, or hoist prototype properties
- Merge or skip key intersections, unions, and differences
- Merge, sort, and remove duplicate array items
- IntelliSense / code hinting support
- TypeScript support
- Lightweight (2k min+gzip) and dependency-free
Platform Support
Node 10+
Chrome 61+
Edge 16+
Firefox 60+
Safari 10.1+
Examples
Basic object cloning using default options:
// ES module shown. CommonJS module also available (see below).
import { mergekit } from 'mergekit';
const obj1 = { a: [1, 1], b: { c: 1, d: 1 } };
const clonedObj = mergekit({}, 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); // falseAdvanced object merging using custom options:
// ES module shown. CommonJS module also available (see below).
import { mergekit } from 'mergekit';
const obj1 = { a: [1, 1], b: { c: 1, d: 1 } };
const obj2 = { a: [2, 2], b: { c: 2 } };
const obj3 = { e: 3 };
const mergedObj = mergekit({
skipKeys: ['d'],
appendArrays: true,
dedupArrays: true,
filter({ depth, key, srcObj, srcVal, targetObj, targetVal }) {
if (key === 'e') {
targetObj['hello'] = 'world';
return false;
}
}
})(obj1, obj2, obj3);
// Result
console.log(mergedObj); // { a: [1, 2], b: { c: 2 }, hello: 'world' }Installation
NPM
npm install mergekit// ES module
import { mergekit } from 'mergekit';// CommonJS module
const { mergekit } = require('mergekit');CDN
Available on jsdelivr (below), unpkg, and other CDN services that auto-publish npm packages.
💡 Note the
@version lock in the URLs below. 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.
// ES module @ latest v2.x.x
import { mergekit } from 'https://cdn.jsdelivr.net/npm/mergekit@2';Usage & Options
See the documentation site for details.
Contact & Support
- Follow 👨🏻💻 @jusimen on Twitter and GitHub for announcements
- Create a 💬 GitHub issue for bug reports, feature requests, or questions
- Add a ⭐️ star on GitHub and 🐦 tweet to promote the project
License
This project is licensed under the MIT license.
Copyright (c) Josue "Jusi" Monteiro (@jusimen)