@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

npm install @vitkuz/deep-merge

Usage

Basic Usage

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

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

Array Merge Strategies

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.

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.

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).

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

createAdapter(config?: DeepMergeConfig)

Creates a new adapter instance.

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

adapter.deepMerge(target, source)

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