Skip to documentation

package

@stackline/deepmerge 1.1.2 — installation and API

Drop-in replacement for deepmerge 4 with CVE-2026-93753 fixed, cycle support, opt-in hardening, Map and Set merging, and array strategies. Zero dependencies; ESM, CommonJS, TypeScript, and browsers

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 deepmerge 4 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 strict preset, Map and Set merging, skipUndefined, array strategies (replace, by index, by key, unique), class-instance preservation, and richer customMerge hooks. 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

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

MIT. See LICENSE and NOTICE.

@stackline/deepmerge is an independent project and is not affiliated with or endorsed by the maintainers of the deepmerge package.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

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 example

Examples load only when requested. They have their own runtime and are separate from this reference.

Benchmark Methodology — @stackline/deepmerge

Compatibility — @stackline/deepmerge

Upstream issues and pull requests — @stackline/deepmerge