Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Semantic Merge

NPM Version Build Status Coverage Status Documentation Status Built with GNU Make

A merging utility that is self-descriptive and makes sense.


Code should be self-descriptive - you should not need to go hunting for API docs just to understand how a particular function or method works. Ever seen this?

const result = merge({prop: 'some value' }, { prop: 'another value' })

It's obvious the merge function merges two objects, but in what order? And does it modify one of the original objects or does it create new one? You cannot really tell unless you go check the utility's API documentation. And even then you are likely to forget in a matter of days.

What about this?

const result = merge({prop: 'some value' }).into({ prop: 'another value' })

Now it's obvious - the properties of the first object get merged into the second object, overwriting existing values. No need to check the docs and no need to remember anything.

Detailed examples

As usual, you start by requiring the module:

const merge = require('semantic-merge')

To perform a shallow merge of one object into another:

// src and target are objects defined somewhere in the current scope
const result = merge(src).into(target)
// Since we are merging into target, we do not need to capture
// the return value:

To perform a recursive (deep) merge of one object into another:


To merge src into target and create a new object without modifying target:

// You are always explicit about what should be the merge target
// You can chain as many .and() calls as you like - they will be merged
// into the target from right to left, so target first, then src.
const result = merge(src).and(target).into({})


Documentation, including several tutorials, is available here.

To generate documentation locally, run make docs from the repository's root.


This software is licensed under the BSD-3-Clause License. See the LICENSE file for more information.


A merging utility that is self-descriptive and makes sense.




No packages published
You can’t perform that action at this time.