# merge

Learn how to merge two maps or lists.

This method chains a `merge` operation to the patch, combining entries in maps or appending items to a list.

Non-existent paths and null values are treated as an empty collection.

> **Atomicity**
>
> If the value at the specified path is not a collection, the operation fails and the entire patch is discarded.

## Signature

This method has the following signature:

```ts
patch.merge(path: string, value: JsonArray | JsonMap): Patch
```

The return is the `Patch` instance itself to allow operation chaining.

## Example

Here is a basic example of how to use this method:

```ts
patch.merge('preferences', {color: 'green'});
```

The following table shows how the operation behaves in different scenarios:

| Current value | Given value  | Result                 |
| ------------- | ------------ | ---------------------- |
| `{}`          | `{}`         | `{}`                   |
| `{}`          | `{a: 1}`     | `{a: 1}`               |
| `{a: 1}`      | `{b: 2}`     | `{a: 1, b: 2}`         |
| `{a: 1}`      | `{a: 2}`     | `{a: 2}`               |
| `null`        | `{a: 1}`     | `{a: 1}`               |
| `null`        | `[1]`        | `[1]`                  |
| `1`           | `[2]`        | `[1, 2]`               |
| `[]`          | `[1]`        | `[1]`                  |
| `[1]`         | `[2]`        | `[1, 2]`               |
| `['a', 'b']`  | `['b', 'c']` | `['a', 'b', 'b', 'c']` |

## Parameters

The following list describes the supported parameters:

- `path`: `string`

  The path to the collection in dot notation, like `flags`.

- `value`: `JSON`

  The value to merge with the Current value, like `{'enabled': true}`.