# add

Learn how to add a value to a collection.

This method chains an `add` operation to the patch.

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.add(path: string, element: JsonValue): 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
path.add('searches', 'data science');
```

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

| Current value | Given value | Result            |
| ------------- | ----------- | ----------------- |
| `null`        | `'a'`       | `['a']`           |
| `'a'`         | `null`      | `['a']`           |
| `'a'`         | `'b'`       | `['a', 'b']`      |
| `['a']`       | `null`      | `['a']`           |
| `[]`          | `'a'`       | `['a']`           |
| `['a', 'b']`  | `'a'`       | `['a', 'b', 'a']` |

## Parameters

The following list describes the supported parameters:

- `path`: `string`

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

- `element`: `JSON`

  The element to add to the collection, like `data science`.