@vitkuz/deep-merge

A lightweight, flexible, and functional deep merge utility for TypeScript/JavaScript objects.

Features

- Deep Merging: Recursively merges nested objects.
- Array Strategies: Choose how arrays are handled (overwrite, concat, unique).
- Functional API: Designed with a functional approach, separating configuration from execution.
- Dual Support: Full CommonJS and ESM support (Node.js and Bundlers).
- TypeScript: Written in TypeScript with full type definitions.

Installation

``bash
npm install @vitkuz/deep-merge
`

Usage

$3

`typescript
import { createAdapter, ArrayMergeStrat } from '@vitkuz/deep-merge';

// 1. Initialize the adapter (default strategy: ArrayMergeStrat.OVERWRITE)
const adapter = createAdapter();
`

$3

You can configure how arrays are merged by passing a config object to createAdapter.

#### 1. Overwrite (Default)

The source array completely replaces the target array.

`typescript
import { createAdapter, ArrayMergeStrat } from '@vitkuz/deep-merge';

const adapter = createAdapter({ arrayMergeStrategy: ArrayMergeStrat.OVERWRITE });

const target = { tags: ['a', 'b'] };
const source = { tags: ['c'] };

const result = adapter.deepMerge(target, source);
// result: { tags: ['c'] }
`

#### 2. Concat

Appends the source array to the target array.

`typescript
const adapter = createAdapter({ arrayMergeStrategy: ArrayMergeStrat.CONCAT });

const target = { tags: ['a', 'b'] };
const source = { tags: ['b', 'c'] };

const result = adapter.deepMerge(target, source);
// result: { tags: ['a', 'b', 'b', 'c'] }
`

#### 3. Unique

Concatenates arrays and removes duplicate primitive values (uses Set).

`typescript
const adapter = createAdapter({ arrayMergeStrategy: ArrayMergeStrat.UNIQUE });

const target = { tags: ['a', 'b'] };
const source = { tags: ['b', 'c'] };

const result = adapter.deepMerge(target, source);
// result: { tags: ['a', 'b', 'c'] }
`

API

$3

Creates a new adapter instance.

- config.arrayMergeStrategy: ArrayMergeStrat (Default: ArrayMergeStrat.OVERWRITE)
- ArrayMergeStrat.OVERWRITE ('overwrite')
- ArrayMergeStrat.CONCAT ('concat')
- ArrayMergeStrat.UNIQUE ('unique')

$3

Merges source into target.

- Returns a new object (immutable input).
- target and source must be objects. If either is not an object, source` is returned.

License

ISC