Wondering what’s next for npm?Check out our public roadmap! »

    deep-object-assign-with-reduce

    3.0.2 • Public • Published

    deep-object-assign-with-reduce

    Build Status Downloads

    Introduction

    Deep Object.assign() written with modern, functional JavaScript. Inspired by deep-assign and the need for a deeper Object.assign.

    No dependencies and very tiny - only ~450 bytes gzipped.

    Installation

    Requires Node.js 10+, which comes with npm.

    In your project directory, type:

    npm install deep-object-assign-with-reduce

    or

    yarn add deep-object-assign-with-reduce

    Changelog

    • 3.0.0 - dropped Node 8 and 9 support. Please use 2.x if you wish to use an older version of Node.
    • 2.0.0 - dropped IE 11 support in order to dramatically reduce filesize.
    • 1.2.0 - added deepAssignOptions to give more control over array and object merging
    • 1.1.0 - fixed RegExp as values, Symbols as keys. Moved to Rollup, Jest. Updated Babel.

    Examples

    Merge complex objects

    import { deepAssign } from 'deep-object-assign-with-reduce';
    
    deepAssign({}, { dimensions: { width: 100, height: 100 } }, { dimensions: { width: 200 } });
    // -> { dimensions: { width: 200, height: 100 } }

    Merge arrays

    import { deepAssign } from 'deep-object-assign-with-reduce';
    
    deepAssign({}, { numbers: [1, 2, 3] }, { numbers: [4, 5, 6] });
    // -> { numbers: [1, 2, 3, 4, 5, 6] }

    Custom overwriting behavior

    deepAssign merges objects and arrays by default. If you want to disable this behavior and instead overwrite objects and/or arrays, you can use deepAssignOptions instead, which accepts an options object as the first parameter:

    import { deepAssignOptions } from 'deep-object-assign-with-reduce';
    
    deepAssignOptions({overwriteArrays: true}, {}, { numbers: [1, 2] }, { numbers: [3, 4] });
    // -> { numbers: [3, 4] }
    
    deepAssignOptions({overwriteObjects: true}, {}, { a: { b: 1 } }, { a: { c: 2 } });
    // -> { a: { c: 2 } }

    Why not just use Object.assign() or Object spread?

    Where Object.assign() works fine

    Here's the motivation: the native Object.assign() works great on its own as long as you use simple objects that are one level deep.

    There's a common use case where we have some "defaults" configuration object, in which properties can be selectively overridden while retaining the remaining default properties.

    Say we have some component which has default dimensions, which we want to be able to selectively override:

    // Default properties to "fallback" to.
    const componentDefaults = { width: 100, height: 100 };
    
    // Selectively overrides one property.
    const componentOptions = { width: 200 };
    
    // Constructs the final options object by merging the objects.
    const options = Object.assign({}, componentDefaults, componentOptions);
    // -> { width: 200, height: 100 }

    This works because Object.assign will merge the simple objects together - and if the same property (such as width) appears in a later object, it will override the previous value. In this case the width in componentOptions overrides the previously set default in componentDefaults.

    Where Object.assign() DOESN'T work fine

    If your configuration object is more complicated and contains nested objects, Object.assign() turns out not to work so well:

    const componentDefaults = { dimensions: { width: 100, height: 100 } };
    const componentOptions = { dimensions: { width: 200 } };
    
    const options = Object.assign({}, componentDefaults, componentOptions);
    // -> { dimensions: { width: 200 } }

    What happened to the height property?! It turns out that the previously set dimensions property was completely overwritten, not merged with the new dimensions object.

    Maybe we can use Object spread? But that turns out to have the same limitation with complex objects:

    const objSpreadTest = { ...componentDefaults, ...componentOptions };
    // -> { dimensions: { width: 200 } }

    Testing

    To run the test suite, simply type:

    npm test

    Note that I've used some of the same tests as deep-assign in addition to my own. More contributions are welcome!

    License

    MIT

    Install

    npm i deep-object-assign-with-reduce

    DownloadsWeekly Downloads

    8

    Version

    3.0.2

    License

    MIT

    Unpacked Size

    25.6 kB

    Total Files

    11

    Last publish

    Collaborators

    • avatar