ut-function.merge

Advanced merge handler

Installation

npm i ut-function.merge

Usage examples

const merge = require('ut-function.merge');
const x = {
    foo: 'fooX'
};
const y = {
    foo: 'fooY',
    bar: 'true',
    baz: [{x: 'xX'}, {y:'xY'}]
};
const z = {
    foo: 'fooZ',
    baz: [{y:'xZ'}, {z: 'zZ'}]
};

const output = merge(x, y, z);

/* output will be:
{
    "foo": "fooZ",
    "bar": "true",
    "baz": [
        {
            "y": "xZ"
        },
        {
            "z": "zZ"
        }
    ]
}
*/

For more advanced scenarios ut-function.merge provides an alternative method signature

merge(objects, options);

Where

• objects (required) - an array of objects to be merged
• options (optional) - an object with options
  • options.convert - whether to convert strings to boolean, null or number where applicable. Note that if a given key appears in the target object only, the conversion will not be applied.
  • options.mergeStrategies - whether to apply different merge strategies for Arrays located under the same paths. Strategies are defined as key value pairs where the key is the path to the array and the value is a string representing the merge strategy itself. The merge strategies currently available are:
    • combine - will concatenate both arrays and filter repeating elements
    • override - will override target with source
    • index - will apply lodash.mergeWith default strategy

Here is how to achieve the same result as with the example above based on this alternative signature:

// ...
const output = merge([x, y, z]);

In this case merge options were not provided.

if you need to automatically convert strings to boolean, null or number where applicable, pass the convert option:

const merge = require('ut-function.merge');
const x = {
    foo: 'fooX'
};
const y = {
    foo: 'fooY',
    bar: 'true',
    baz: [{x: 'xX'}, {y:'xY'}]
};
const z = {
    foo: 'fooZ',
    baz: [{y:'xZ'}, {z: 'zZ'}]
};

const output = merge([x, y, z], {convert: true});

/* output will be:
{
    "foo": "fooZ",
    "bar": true,
    "baz": [
        {
            "y": "xZ"
        },
        {
            "z": "zZ"
        }
    ]
}
*/

Note that in this case "bar" become a boolean

Example for applying a different merge strategy:

const merge = require('ut-function.merge');
const x = {
    foo: 'fooX'
};
const y = {
    foo: 'fooY',
    bar: 'true',
    baz: [{x: 'xX'}, {y:'xY'}]
};
const z = {
    foo: 'fooZ',
    baz: [{y:'xZ'}, {z: 'zZ'}]
};

const output = merge([x, y, z], {
    convert: true,
    mergeStrategies: {
        'baz': 'combine'
    }
});

/* output will be:
{
    "foo": "fooZ",
    "bar": true,
    "baz": [
        {
            "x": "xX"
        },
        {
            "y": "xY"
        },
        {
            "y": "xZ"
        },
        {
            "z": "zZ"
        }
    ]
}
*/

This works for nested properties also. Just provide the correct path to the array.

const merge = require('ut-function.merge');
const x = {
    foo: 'fooX'
};
const y = {
    foo: 'fooY',
    bar: 'true',
    baz: {
        test: [{x: 'xX'}, {y:'xY'}, {test: true}]
    }
};
const z = {
    foo: 'fooZ',
    baz: {
        test: [{y:'xZ'}, {z: 'zZ'}, {test: true}]
    }
};

const output = merge([x, y, z], {
    convert: true,
    mergeStrategies: {
        'baz.test': 'combine'
    }
});

/* output will be:
{
    "foo": "fooZ",
    "bar": true,
    "baz": {
        "test": [
            {
                "x": "xX"
            },
            {
                "y": "xY"
            },
            {
                "test": true
            },
            {
                "y": "xZ"
            },
            {
                "z": "zZ"
            }
        ]
    }
}
*/

Note that {"test": true} appears just once as it was recognized as a duplication.