Namespace, Primitive, Method

    mergician

    1.0.3 • Public • Published

    Mergician

    NPM GitHub Workflow Status (main) Codacy code quality License: MIT jsDelivr Tweet

    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.

    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

    License

    This project is licensed under the MIT license.

    Copyright (c) John Hildenbiddle (@jhildenbiddle)

    Install

    npm i mergician

    DownloadsWeekly Downloads

    737

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    82.2 kB

    Total Files

    9

    Last publish

    Collaborators

    • jhildenbiddle