Install @stackline/deepmerge
npm install @stackline/[email protected]Package version: 1.1.2. Metadata verified: 2026-11-12. This is separate from the framework version and demonstration runtime.
- Node.js requirement
- {"node": ">=14.17.0"}
- Accepted peer dependencies (declared ranges)
- {}
Tested environments are described in the versioned README and linked source checks. A declared peer range is not evidence that every version in it was tested.
Practical guides
Versioned reference
This reference comes from the published @stackline/[email protected] README. Its upstream attribution and license remain with the source. Benchmark and security statements describe the cited tests and advisories, not a guarantee for every application.
@stackline/deepmerge
Drop-in replacement for
deepmerge4 that fixes CVE-2026-93753 and circular-reference crashes, with opt-in hardening and the most requested upstream features. Zero dependencies; ESM, CommonJS, TypeScript, and browsers.
Documentation | npm | Issues | Repository
Current package version: 1.1.2
Why this package?
Run application compatibility tests before replacing a dependency. Review the version-specific behavior and limits below.
[email protected] is the latest upstream release. It was last published in
March 2023, it is affected by
CVE-2026-93753 (a __proto__
key can replace the prototype of the merged object), it overflows the stack on
circular references, and dozens of community requests remain open.
@stackline/deepmerge is built for the swap:
- Same results. Without options, every value, key order, prototype,
property descriptor, and copy matches
[email protected]. A differential suite compares complete output graphs on every test run, and deepmerge's own test suite passes against this package. - Fixed by default.
__proto__is dropped at every depth, cycles are reproduced instead of crashing, frozen options work, and React 19 elements stay intact. - Opt-in improvements. A hardened
strictpreset,MapandSetmerging,skipUndefined, array strategies (replace, by index, by key, unique), class-instance preservation, and richercustomMergehooks. See how every upstream issue is handled. - Faster. About 30% more operations per second than
[email protected]on the included benchmark. - Modern packaging. Native ESM, callable CommonJS, a browser global, and TypeScript declarations tested from 3.9 through 7.0. Zero runtime dependencies.
Trust and maintenance
- No runtime dependencies.
- Every release is built from the public repository.
- CI validates behavior, types, package exports, clean installs, and supported runtimes.
- Security reports have a dedicated private process in SECURITY.md.
- Release history is recorded in CHANGELOG.md.
Compatibility
| Item | Value |
|---|---|
| Package | @stackline/[email protected] |
| Replaces | [email protected] |
| Node.js runtime | >=14.17.0 |
| CommonJS / primary entry | ./dist/index.cjs |
| ES module entry | ./dist/index.js |
| Type declarations | ./dist/index.d.ts |
Installation
Replace deepmerge without changing application imports:
npm install deepmerge@npm:@stackline/deepmerge
Or install under the package's public name:
npm install @stackline/deepmerge
Usage
Existing code keeps working unchanged:
import merge from 'deepmerge';
const config = merge(defaults, environment);
Quick start
import merge from '@stackline/deepmerge';
const defaults = {
server: { port: 3000, headers: { accept: 'application/json' } },
plugins: ['core']
};
const production = {
server: { port: 8080, headers: { authorization: 'Bearer token' } },
plugins: ['metrics']
};
const config = merge(defaults, production);
// {
// server: {
// port: 8080,
// headers: {
// accept: 'application/json',
// authorization: 'Bearer token'
// }
// },
// plugins: ['core', 'metrics']
// }
Neither input is mutated.
Features and Integrations
API compatibility
merge(target, source, options?)
Returns a new merged value. Objects merge recursively. Arrays concatenate by default. When an array and an object occupy the same position, the source wins. Keys keep the target order, and new source keys are appended.
merge.all(objects, options?)
const config = merge.all([
{ logging: { level: 'info' } },
{ logging: { format: 'json' } },
{ region: 'ca-central-1' }
]);
deepmerge 4 options
| Option | Default | Purpose |
|---|---|---|
arrayMerge(target, source, options) |
concatenate | Replace or customize array behavior |
clone |
true |
Set false to keep nested input references |
customMerge(key, options, context) |
none | Return a merge function for a property |
isMergeableObject(value) |
built in | Decide which values are traversed |
customMerge is consulted only when the key exists in the target and the
source value is mergeable, exactly like deepmerge 4. Return undefined to use
the default merge. The callback options include cloneUnlessOtherwiseSpecified,
matching the deepmerge 4 hook shape. Falsy options and hooks fall back to the
defaults, as in deepmerge 4.
Opt-in options
| Option | Default | Purpose |
|---|---|---|
unsafeKeys |
'compatible' |
'strict' also drops constructor and prototype at every depth |
onUnsafeKey |
'skip' |
'throw' rejects the whole merge; setting it selects the strict key policy |
maxDepth |
unlimited | Bound nesting depth |
maxKeys |
unlimited | Bound the keys read in one merge |
skipUndefined |
false |
undefined source values do not replace existing target values |
mergeCollections |
false |
Deep merge Map entries and union Set values |
customMergeScope |
'objects' |
'all' also consults customMerge for primitive values |
Exports
import merge, {
DeepMergeLimitError,
UnsafeKeyError,
all,
concatUniqueArrays,
createDeepmerge,
deepmerge,
isMergeableObject,
isPlainMergeableObject,
mergeArraysByIndex,
mergeArraysByKey,
overwriteArrays,
strict,
strictOptions
} from '@stackline/deepmerge';
Every export is also a static property of the default export, so
merge.all(...) and merge.strict(...) work in ESM, CommonJS, and the browser.
CommonJS remains callable:
const merge = require('@stackline/deepmerge');
merge({ left: true }, { right: true });
merge.all([{ one: 1 }, { two: 2 }]);
Hardened mode
strict applies unsafeKeys: 'strict', onUnsafeKey: 'throw',
maxDepth: 1000, and maxKeys: 100000. Per-call options override the preset:
import { strict } from '@stackline/deepmerge';
const config = strict(defaults, JSON.parse(requestBody));
const lenient = strict(defaults, input, { onUnsafeKey: 'skip' });
createDeepmerge(defaults) builds the same kind of function from your own
defaults, for one consistent merge across an application:
import { createDeepmerge, overwriteArrays } from '@stackline/deepmerge';
const mergeConfig = createDeepmerge({ arrayMerge: overwriteArrays, skipUndefined: true });
mergeConfig(base, override);
mergeConfig.all([base, environment, cli]);
Array strategies
import merge, {
concatUniqueArrays,
mergeArraysByIndex,
mergeArraysByKey,
overwriteArrays
} from '@stackline/deepmerge';
merge({ list: [1, 2] }, { list: [3] }, { arrayMerge: overwriteArrays });
// { list: [3] }
merge({ list: [{ a: 1 }, 'x'] }, { list: [{ b: 2 }] }, { arrayMerge: mergeArraysByIndex });
// { list: [{ a: 1, b: 2 }, 'x'] }
merge(
{ plugins: [{ name: 'core', retries: 1 }] },
{ plugins: [{ name: 'metrics' }, { name: 'core', timeout: 5 }] },
{ arrayMerge: mergeArraysByKey('name') }
);
// { plugins: [{ name: 'core', retries: 1, timeout: 5 }, { name: 'metrics' }] }
merge({ tags: ['a', 'b'] }, { tags: ['b', 'c'] }, { arrayMerge: concatUniqueArrays });
// { tags: ['a', 'b', 'c'] }
mergeArraysByKey also accepts a function, such as
mergeArraysByKey((item) => item.id.toLowerCase()). Items without an
identifier are appended. All strategies also work as arrayMerge hooks for
deepmerge 4 itself.
Class instances, Map, and Set
deepmerge 4 traverses every non-null object, so class instances become plain
objects and Map or Set values become {}. That remains the default. Opt in
to keep them:
import merge, { isPlainMergeableObject } from '@stackline/deepmerge';
// Class instances, Map, Set, and other built-ins are copied by reference.
merge(target, source, { isMergeableObject: isPlainMergeableObject });
// Map entries are deep merged and Set values are unioned into new collections.
merge(
{ limits: new Map([['api', { rps: 10 }]]), tags: new Set(['a']) },
{ limits: new Map([['api', { burst: 20 }]]), tags: new Set(['b']) },
{ mergeCollections: true }
);
// { limits: Map { 'api' => { rps: 10, burst: 20 } }, tags: Set { 'a', 'b' } }
Custom merge context
customMerge receives a third argument with the property path and both
values:
merge(target, source, {
customMerge(key, options, { path, target, source }) {
if (Array.isArray(target) !== Array.isArray(source)) {
throw new TypeError(`Type mismatch at ${path.join('.')}`);
}
return undefined;
}
});
With customMergeScope: 'all', customMerge also handles primitive values,
for example to add counters:
merge({ stats: { visits: 3 } }, { stats: { visits: 2 } }, {
customMergeScope: 'all',
customMerge: (key) => (key === 'visits' ? (left, right) => left + right : undefined)
});
// { stats: { visits: 5 } }
Cycles and shared references
deepmerge 4 overflows the stack on circular input. This package reproduces the cycle in the result instead:
const source = { name: 'root' };
source.self = source;
const result = merge({}, source);
result.self === result; // true
Repeated references that are not cycles become independent copies, exactly as in deepmerge 4:
const shared = { enabled: true };
const result = merge({}, { first: shared, second: shared });
result.first === result.second; // false
TypeScript
The package ships declaration files for modern ESM, CommonJS, and older TypeScript resolvers. Return types recursively combine the target and source.
import merge from '@stackline/deepmerge';
const result = merge(
{ service: { port: 3000 } },
{ service: { secure: true } }
);
result.service.port; // number
result.service.secure; // boolean
Code typed against the upstream deepmerge declarations, such as
deepmerge.Options or deepmerge.all<T>(), compiles unchanged. The release
matrix tests TypeScript 3.9, 4.7, 4.9, 5.9, 6.0, and 7.0. The
JavaScript runtime supports Node.js 14.17 and newer.
Browser
Use the ESM build with a bundler, or load the browser global directly (about 10 KB minified, 4 KB gzipped):
<script src="https://unpkg.com/@stackline/deepmerge@1/dist/index.min.js"></script>
<script>
const merged = StacklineDeepmerge(
{ theme: { contrast: 'normal' } },
{ theme: { motion: 'reduced' } }
);
</script>
Migration from deepmerge
The lowest-change migration uses an npm alias:
npm uninstall deepmerge
npm install deepmerge@npm:@stackline/deepmerge
Results differ from [email protected] only where deepmerge 4 crashes or
returns an unsafe result:
__proto__keys are dropped instead of replacing the result's prototype (CVE-2026-93753);- circular references are reproduced instead of overflowing the stack;
- frozen options objects work instead of throwing;
- React 19 elements are kept intact instead of having their props merged;
- the options object you pass is never mutated.
See Compatibility for the full contract and how it is verified, and Upstream issues for every upstream issue, pull request, and fork.
Performance
The included benchmark merges the same nested configuration with both packages in one process:
npm run benchmark
On Node.js 24.20, this release measured about 200,000 operations per second,
against about 150,000 for [email protected]. Use benchmark results as
regression signals, not universal claims. Runtime, CPU, input shape, and
custom callbacks materially affect throughput.
Adoption resources
- Direct install and drop-in alias guide
- Compatibility contract
- Upstream issues, pull requests, and forks
- Reproducible benchmark methodology
- Executable examples
- Stackline open-source catalog
The examples are included in the npm tarball and run against the package's public exports. They cover hostile configuration input, array strategies, cycles, and a configured merge with collections and class instances.
Security
Secure by default
__proto__ is dropped from both inputs at every depth, before its value is
read, so the merged object can never inherit attacker-controlled properties:
import merge from '@stackline/deepmerge';
const payload = JSON.parse('{ "session": { "__proto__": { "isAdmin": true } } }');
const result = merge({ session: null }, payload);
result.session.isAdmin; // undefined (true with deepmerge 4.3.1)
Object.prototype.isAdmin; // undefined
constructor and prototype are handled exactly like deepmerge 4: a source
key that only exists on the target's prototype chain is skipped, so the classic
{ "constructor": { "prototype": ... } } payload never reaches the result when
merged into a plain object. Accepted keys are always written as own data
properties, never through setters.
Strict input handling
Use the strict key policy and limits at untrusted boundaries:
import { strict } from '@stackline/deepmerge';
strict({}, JSON.parse('{ "profile": { "constructor": {} } }'));
// UnsafeKeyError: Refusing to merge unsafe key constructor at
// <root>.profile.constructor
Or pick the pieces you need:
merge(target, source, {
unsafeKeys: 'strict',
onUnsafeKey: 'skip',
maxDepth: 64,
maxKeys: 10000
});
Local Development
git clone https://github.com/alexandroit/stackline-deepmerge.git
cd stackline-deepmerge
npm ci
npm run test
Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.
Contributing
Read CONTRIBUTING.md before opening a pull request. Changes to compatibility or security behavior require focused regression tests.
Consumer Smoke Test
Run the repository's existing consumer/package check after installing development dependencies:
npm run test:install
Release Checklist
Run npm run test and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.
License
@stackline/deepmerge is an independent project and is not affiliated with or
endorsed by the maintainers of the deepmerge package.
Credits and original authors
- Alexandro Paixao Marques.
- Copyright (c) 2026 Alexandro Paixao Marques and contributors.
- Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.
Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.
Community and Links
Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.
Examples and compatibility
The original example runtime is preserved. Its build is identified by source commit 198e0c26ac419009c4f2b5ee3dfa566346baa820. Package version and runtime version must be checked independently.
Open the original exampleExamples load only when requested. They have their own runtime and are separate from this reference.
Benchmark Methodology — @stackline/deepmerge