# ut-function.merge

> Advanced merge handler

Latest version **1.5.6** (published 2021-03-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install ut-function.merge
pnpm add ut-function.merge
yarn add ut-function.merge
bun add ut-function.merge
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.5.6 |
| Published | 2021-03-29 |
| First published | 2019-09-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 15.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Maintainers | kalin.krustev |

## Links

- npm: https://www.npmjs.com/package/ut-function.merge
- Repository: https://github.com/softwaregroup-bg/ut-function
- Homepage: https://github.com/softwaregroup-bg/ut-function#readme
- Issues: https://github.com/softwaregroup-bg/ut-function/issues
- npm.io page: https://npm.io/package/ut-function.merge

## Dependencies (2)

- [lodash.mergewith](https://npm.io/package/lodash.mergewith.md) 4.6.2
- [ut-function.equals](https://npm.io/package/ut-function.equals.md) ^1.1.3

## Recent versions

- 1.5.6 (latest) — 2021-03-29
- 1.5.5 — 2020-02-25
- 1.5.4 — 2020-01-20
- 1.5.3 — 2020-01-17
- 1.5.2 — 2020-01-15
- 1.5.1 — 2020-01-15
- 1.5.0 — 2019-12-17
- 1.4.0 — 2019-11-06
- 1.3.0 — 2019-11-05
- 1.2.0 — 2019-09-12
- 1.0.1 — 2019-09-11

## README

# ut-function.merge

Advanced merge handler

## Installation

```sh
npm i ut-function.merge
```

## Usage examples

```js
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

```js
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:

```js
// ...
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:

```js
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:

```js
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.

```js
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.

---
_Source: https://npm.io/package/ut-function.merge · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._