NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #2657 most downloaded on npm
Deeply merge 2 or more objects respecting type information.
Latest stable
8.0.2
Last release 3 months ago
21 Aug 2026
Ships unpredictably
gaps range from 9 days to 1.5 years
Nearly every release is documented
notes for 43 of 43 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
61 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
correct node engine requirement to >=16.9.0
## 8.0.1 (2026-08-16) ### Bug Fixes * typescript 7 support
Your coding agent can read these notes before it upgrades. Set up the MCP server →
metaMeta parameter is now mergeInfo.
Implementations must update the parameter name accordingly.MetaDataUpdater<M, MI>).DeepMergeIntoFunctionUtils type has been renamed to DeepMergeIntoUtils.`deepmergeInto` no longer leak-mutates the input objects. (As described in Breaking Changes.)
deepmergeCustom({ mergeMaps: false }).DeepMergeMetaMetaData renamed to DeepMergeMergeInfo. A deprecated alias for the old name is still exported for backwards compatibility, but it will be removed in a future major version. The rename better reflects the structure's expanded role, including hierarchy tracking, in custom merging and the metadata passed to custom merge functions. The MetaDataUpdater callback's metaMeta parameter is now mergeInfo, and the MM generic shorthand is now MI.DeepMergeIntoFunctionUtils renamed to DeepMergeIntoUtils. No alias is kept for the old name.deepmergeInto no longer leak-mutates the input objects. Previously deepmergeInto would mutate the first object's nested containers (arrays, Maps, Sets, and objects) in place, potentially corrupting the input. It is now fixed.deepmergeCustom and deepmergeIntoCustom now handle circular references, configurable via a new maxDepth option and a new mergeCircularReferences merge-function option. The merge metadata also now tracks the merge hierarchy.deepmergeFastUnsafe and deepmergeIntoFastUnsafe are drop-in replacements for deepmerge and deepmergeInto with prototype-pollution interception, circular-reference handling, and metadata tracking removed for maximum throughput. They should only be used with trusted data. Each ships with a *Custom constructor (deepmergeFastUnsafeCustom and deepmergeIntoFastUnsafeCustom) for customisation.deepmergeInto no longer leak-mutates the input objects. (As described in Breaking Changes.)Much faster type checking. The following numbers are the type-checking cost, comparing this release against v7.1.6 (measured with TypeScript 5.9.3):
| Scenario | Types | Instantiations | Total time |
|---|---|---|---|
| wide | 256k -> 26k (-90%) | 6.5M -> 83k (-98.7%) | 10.5s -> 0.94s (-91%) |
| deep | 64k -> 26k (-60%) | 438k -> 67k (-85%) | 1.82s -> 0.87s (-52%) |
| optional | 45k -> 27k (-40%) | 172k -> 78k (-55%) | 1.39s -> 0.89s (-36%) |
| unions | 40k -> 26k (-36%) | 118k -> 69k (-42%) | 1.26s -> 0.92s (-27%) |
| collections | 37k -> 26k (-29%) | 95k -> 69k (-28%) | 1.22s -> 1.06s (-13%) |
| custom | 38k -> 26k (-31%) | 100k -> 69k (-31%) | 1.22s -> 1.02s (-16%) |
| into | 35k -> 25k (-27%) | 76k -> 64k (-15%) | 1.20s -> 0.87s (-28%) |
Runtime performance. Compared to v7.1.6, deepmerge-ts v8.0.0 is roughly 40% faster when merging two objects and ~5-10% faster on multi-object merges, while deepmergeInto performs about the same (its leak-mutation fix adds a little clone work). Memory use is markedly lower as well: on the largest benchmark dataset, v7.1.6 runs into Node's default heap limit, whereas the same workload completes with a peak of roughly half a gigabyte.
Compared to other merge libraries we benchmark against.
defu@6.1.7 is the fastest. When merging many objects, deepmerge-ts@8.0.0 is within ~1.5x and merge-anything@6.0.6 close behind; on simple two-object merges defu pulls further ahead (~1.1-2x).deepmerge-ts edges out defu (~1.5x) and is ~2.5x faster than merge-anything.deepmerge-ts is the fastest, roughly 25-35x faster than both defu and merge-anything.ts-deepmerge@8.0.0, mergician@2.0.2, @fastify/deepmerge@3.2.1, deepmerge@4.3.1) fall anywhere from ~100x to ~17,000x behind, largely because they deep-clone the entire input, whereas deepmerge-ts shares references to untouched subtrees.deepmerge-ts merges them deeply, by unioning Set elements and merging Map entries (including their values), while the other libraries simply let one of the values win.For a line-by-line breakdown of every commit, see the CHANGELOG.
preserve known keys when merging objects with index signatures
improve type merging of nested optional properties
apply filtering to types when selecting a leaf node (#526) (6d85163), closes #524
## 7.1.3 (2024-10-08)
use more performant data structures
add explicit return type to speed up types
benchmark: add defu to compare with
## 7.0.3 (2024-06-06) ### Bug Fixes * merge functions' types
support older module resolutions (063675e), closes #480
handling of partial types (1832bd0), closes #476
rename DeepMergeFunctionUtils to DeepMergeUtils
deepmergeInto unsafe key value assignment
return type when using empty records (6b4ff3f), closes #465
type when merging index signatures (5e8b9b6), closes #459
deepmergeCustom
and deepmergeIntoCustom have changed. If you are passing generics
to these functions you need to update them.remove deprecated type DeepMergeLeafHKT
deepmergeCustom
and deepmergeIntoCustom have changed. If you are passing generics
to these functions you need to update them.Nothing published for this version
Nothing published for this version
expose some of the internal utils
use default MM generics (944b428), closes #304
use default MM generics (944b428), closes #304
# 5.0.0-next.3 (2023-03-18) ### Bug Fixes * add missing dev dep
create deepmergeInto function (9c350a0), closes #51
drop support for node 12 and 14
create deepmergeInto function (9c350a0), closes #51
## 4.2.2 (2022-09-19)
## 4.2.1 (2022-06-15) ### Bug Fixes * broken type info path
export types for module resolution node 16
treat module imports as records (20c0dfb), closes #133
drop keys that have no enumerable properties
use explict return types for function that return a HKT (eb4183e), closes #94
protect against prototype pollution
deno: fix broken import in deno dist files
allow for default merging via a special return value
Nothing published for this version
Nothing published for this version
Nothing published for this version
allows readonly records in DeepMergeRecordsDefaultHKTInternalPropValueHelper
deepmergeCustomunrequire unused types and values
deepmergeCustomNothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
## 2.0.1 (2021-12-22)
add better support for readonly types
Nothing published for this version
Nothing published for this version
incorrect resulting type when merging 3+ readonly tuples
convert recursive types to tail-recursive versions
## 1.1.5 (2021-10-18) ### Bug Fixes * deno: deno release fixup
This release has no changes for node uses.
## 1.1.3 (2021-09-21) ### Bug Fixes * order of package exports
current and legacy types trying to using the same file resulting in one being overridden
only merge enumerable properties
# 1.1.0 (2021-09-13) ### Features * add support for custom merging
One column per quarter.