Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@toolsycc/json-merge

sebog3310MIT0.1.0TypeScript support: included

A utility to deeply and safely merge JSON objects, with full TypeScript support.

toolsy, json, merge, deep merge, merge objects, immutable, typescript

readme

@toolsycc/json-merge

A flexible and immutable JSON object merger — perfect for config files, runtime overrides or structured data.
✅ Fully typed, lightweight and easy to use in both TypeScript and JavaScript (ESM & CommonJS).

Features

  • Deep recursive merge
  • Optional array merging (replace or concat)
  • Ignore keys from merge
  • Custom merge logic per key
  • Merge depth limit
  • Date handling strategies
  • Falsy overwrite toggle
  • Clone or mutate input objects
  • Merge multiple objects via mergeMany

Install

pnpm add @toolsycc/json-merge

Or with npm:

npm install @toolsycc/json-merge

Example usage

import { deepMerge } from '@toolsycc/json-merge'

const base = { user: { name: "Seb", roles: ["admin"] } }
const override = { user: { age: 42, roles: ["editor"] } }

const result = deepMerge(base, override, { arrayStrategy: 'concat' })
// → { user: { name: "Seb", age: 42, roles: ["admin", "editor"] } }

API

deepMerge(obj1, obj2, options?)

Option Type Default Description
arrayStrategy "replace" | "concat" "replace" How to merge arrays
depthLimit number Infinity Max depth of recursion
ignoreKeys string[] [] Keys to skip
preserveUndefined boolean false Keeps undefined keys
customMerge (key, val1, val2) => any undefined Custom logic per key
dateStrategy "copy" | "stringify" | "timestamp" "copy" How to handle Dates
overwriteFalsy boolean true Whether to overwrite with falsy values (null, false, etc.)
cloneInputs boolean true If false, mutates target object

mergeMany(objects: object[], options?)

Merges all objects left-to-right using deepMerge.

mergeMany([{ a: 1 }, { b: 2 }, { a: 3 }])
// → { a: 3, b: 2 }

License

MIT