Like lodash's _.defaultsDeep, but with array preservation
npm install @phun-ky/defaults-deep   !npm version !issues !license !size !npm !GitHub Repo stars  
Similar to lodash's defaultsDeep, but without mutating the source object, and no merging of arrays, and no lodash as dependency!
- @phun-ky/defaults-deep
- About
- Table of Contents- defaults-deep
- Installation
- Usage
- ESM
- CommonJS
- API
- Parameters
- Returns
- Examples
- Differences from lodash (_.defaultsDeep / _.mergeWith pattern)
- Notice
- Contributing
- License
- Changelog
- Sponsor me
Install the package via npm:
``bash`
npm i --save @phun-ky/defaults-deep
`bash`
import defaultsDeep from "@phun-ky/defaults-deep";
`
const defaultsDeep = require("@phun-ky/defaults-deep");
`ts`
function defaultsDeep(...args): Record
Deeply applies "defaults" from right-to-left sources into a new object, while preserving arrays.
This function mimics the common lodash pattern:
_.toArray(arguments).reverse().forEach(x => _.mergeWith(output, x, customizer)),
but implemented in vanilla TypeScript with a small, predictable merge core.
Key behaviours
- Returns a new object (the returned object is created inside the function).
- Sources are processed right-to-left (reverse()), meaning earlier arguments win:isObjectLoose
values from the first argument are treated as "defaults" that should _not_ be overwritten
by later arguments (because later arguments are merged first).
- Only object-like sources participate in merging. Non-objects are skipped via .
- Uses mergeWith for the deep merge logic.
- Arrays are preserved by replacement: if a source value is an array, it replaces the
destination value at that key (rather than being merged element-by-element).
| Parameter | Type | Description |
| --------- | ------------ | ------------------------------------------------------------------------- |
| ...args | unknown\[] | A list of potential default/source values. Non-object values are ignored. |
Record<PropertyKey, unknown>
A new object containing the merged result.
`ts`
defaultsDeep(
{ a: 1, nested: { x: 1 }, list: [1] },
{ a: 2, nested: { y: 2 }, list: [2] }
);
// => { a: 1, nested: { x: 1, y: 2 }, list: [1] }
// (earlier args win; arrays preserved by replacement)
`ts`
defaultsDeep({ opts: { retry: 3 } }, null, { opts: { timeout: 1000 } });
// => { opts: { retry: 3, timeout: 1000 } }
// (non-object sources are ignored)
/ _.mergeWith pattern)This package is inspired by lodash's common _.defaultsDeep approach (often implemented as _.toArray(arguments).reverse() + _.mergeWith(...)), but it is not a drop-in, byte-for-byte compatible clone. The goal here is to cover the common "configuration defaults" use case with a much smaller, dependency-free implementation. For typical plain objects (JSON-like data) and arrays, the results should match what you expect from the lodash approach.
The biggest difference is the underlying merge engine. Lodash's mergeWith` is a mature, highly general deep-merge with lots of special-case behaviour for many JavaScript value types and edge cases. This implementation intentionally keeps the default rules conservative: it only deep-merges plain objects and treats most other things as replace-by-assignment. That means values like arrays, dates, maps/sets, functions, class instances, and other non-plain objects are not recursively merged unless you explicitly handle them via a customizer.
Array behaviour is also deliberately simpler and more explicit. Lodash's merge behaviour around arrays can be nuanced depending on the function and scenario; in this implementation, arrays are preserved by replacement (the source array overwrites the destination array) rather than being merged element-by-element. This matches the "array preservation" intent for defaults/config objects, but if you expect lodash-style index-wise array merging or concatenation in some cases, you'll need to provide your own customizer.
Another difference is how non-object inputs are treated. Lodash tends to be extremely permissive about odd inputs and will try hard to produce "something reasonable" even when sources are primitives or exotic objects. This implementation focuses on predictable behaviour for configuration merging: non-object sources are typically ignored (or treated as simple replacements at a property level), and only "object-like" values participate meaningfully in deep merging. If you pass primitives/functions as top-level sources, don't expect identical behaviour to lodash across all cases.
Finally, because this package is written in TypeScript with a strict API surface, you may notice differences at compile time even when runtime behaviour is similar. The functions lean on explicit type guards and object-shape constraints rather than lodash's "accept almost anything" philosophy. The payoff is a smaller dependency footprint and clearer semantics for the common defaults use case, at the cost of not matching lodash's full breadth of type handling and edge-case compatibility.
This project is a fork of
Want to contribute? Please read the CONTRIBUTING.md and CODE_OF_CONDUCT.md
This project is maintained by Alexander Vassbotn Røyne-Helgesen and is based on original work by Drew Llewellyn (
See the CHANGELOG.md for details on the latest updates.
I'm an Open Source evangelist, creating stuff that does not exist yet to help get rid of secondary activities and to enhance systems already in place, be it documentation or web sites.
The sponsorship is an unique opportunity to alleviate more hours for me to maintain my projects, create new ones and contribute to the large community we're all part of :)
Support me on GitHub Sponsors.
p.s. Ukraine is still under brutal Russian invasion. A lot of Ukrainian people are hurt, without shelter and need help. You can help in various ways, for instance, directly helping refugees, spreading awareness, putting pressure on your local government or companies. You can also support Ukraine by donating e.g. to Red Cross, Ukraine humanitarian organisation or donate Ambulances for Ukraine.