# left-merge

> Recursively compare object A and B, merge B into A, but discard fields not pre-existed on A

Latest version **1.1.4** (published 2021-11-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install left-merge
pnpm add left-merge
yarn add left-merge
bun add left-merge
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2021-11-07 |
| First published | 2020-02-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ZYinMD |
| Maintainers | zyinmd |
| Keywords | merge, object, objects, localStorage, merge-left, settings |

## Links

- npm: https://www.npmjs.com/package/left-merge
- Repository: https://github.com/ZYinMD/left-merge
- Homepage: https://github.com/ZYinMD/left-merge#readme
- Issues: https://github.com/ZYinMD/left-merge/issues
- npm.io page: https://npm.io/package/left-merge

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 1.1.4 (latest) — 2021-11-07
- 1.1.3 — 2020-04-01
- 1.1.2 — 2020-03-29
- 1.1.1 — 2020-03-09
- 1.1.0 — 2020-02-29
- 1.0.6 — 2020-02-27
- 1.0.5 — 2020-02-27
- 1.0.4 — 2020-02-27
- 1.0.3 — 2020-02-27
- 1.0.2 — 2020-02-27
- 1.0.1 — 2020-02-27
- 1.0.0 — 2020-02-27

## README

# left-merge

```js
const result = leftMerge(left, right);
```

Recursively compare two object, merge `right` into `left`, but maintain the structure of `left`, ignoring redundant fields from `right`. Inspired by "left join" in SQL.

### install:

```
npm i left-merge
```

### when can it be useful:

Imagine `left` is the default preference settings of your app, and `right` is the user's customized settings, which is stored on the client side. But the two have different shapes because the user hasn't logged on for a long time. You don't know what shape or what old version he has, but you want to update him to the latest version, meanwhile preserve his custom settings.

### example:

```js
import { leftMerge } from 'left-merge';
// user's existing preferences:
const userPreferences = {
  language: 'French',
  itemsPerPage: 50,
};
// now you evolved the default settings into a new structure:
const defaultSettings = {
  language: 'Enligsh',
  useDarkMode: false,
};
// on app start, update user preference to the new structure:
let updatedUserPreferences = leftMerge(defaultSettings, userPreferences); /* ->
{
  language: 'French',
  useDarkMode: false,
} */
```

### another example:

```js
const template = {
  species: 'cat',
  color: ['yellow', 'black'],
  stats: { speed: 10 },
};
const modification = {
  species: 'tiger',
  stats: { speed: 25, canFly: true },
};

let result = leftMerge(template, modification); /* ->
{
  species: 'tiger',
  color: ['yellow', 'black'],
  stats: { speed: 25},
} */
```

### Immutability:

Both arguments and their nested children are never mutated, but may be shallow copied when no change is needed.

### null and undefined:

If a field is `null` or `undefined` on the left, it'll be overwritten by the counterpart on the right. If `null` or `undefined` is on the right, it won't overwrite left.

(when these happen, you'll see more detailed reports in the verbose loggings in development)

### type conflicts:

Except `null` and `undefind`, when a field has different types on left and right, right will be ignored.

(when this happens, you'll see more detailed reports in the verbose loggings in development)

### if you're using commonjs `require`:

```js
const { leftMerge } = require('left-merge');
```

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