NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #2657 most downloaded on npm
Deeply merge 2 or more objects respecting type information.
Last release 1 months ago
21 Aug 2026
Ships unpredictably
gaps range from 9 days to 1.5 years
Most releases are documented
notes for 29 of 41 stable releases
4 versions withdrawn
withdrawn after publishing
5 years old
61 releases · first in 2021
One column per quarter.
correct node engine requirement to >=16.9.0
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
### Bug Fixes * merge functions' types
support older module resolutions (063675e), closes #480
handling of partial types (1832bd0), closes #476
Nothing published for this version
deepmergeInto unsafe key value assignment
return type when using empty records (6b4ff3f), closes #465
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
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
Nothing published for this version
Nothing published for this version
Nothing published for this version
export types for module resolution node 16
Nothing published for this version
Nothing published for this version
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
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
allows readonly records in DeepMergeRecordsDefaultHKTInternalPropValueHelper
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
Nothing published for this version
add better support for readonly types
Nothing published for this version
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
### Bug Fixes * deno: deno release fixup
Nothing published for this version
### 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
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →