defaults()

defaults<T>(object, ...sources): T

Assigns source properties to destination only where destination is undefined.

💎 Why is this a Hidden Gem?

Safely applies default values only where properties are undefined.

remarque

Only undefined values are replaced. null values are preserved.

---

Type Parameters

T: T extends Record<string, unknown>

The type of the destination object.

---

Parameters

object: T

The destination object.

sources: ...Record<string, unknown>[]

The source objects.

---

Returns: T

A new object with defaults applied (does not mutate original).

---

Since

2.0.0

---

Note

Inherited properties (e.g., from Object.prototype) are not considered undefined.

---

Performance

O(n×m) where n = number of sources, m = average keys per source

---

Also known as

assign (Radashi) · defaults (Lodash, es-toolkit) · mergeRight (Ramda) · ❌ (Remeda, Effect, Modern Dash, Antfu)

---

Example

const target = { a: 1, b: undefined, c: 3 };
const source = { b: 2, c: 4, d: 5 };

defaults(target, source);
// => { a: 1, b: 2, c: 3, d: 5 }

// Original is not mutated
target.b; // => undefined (unchanged)

// null is preserved (not undefined)
defaults({ city: null }, { city: 'Paris' });
// => { city: null }

// Multiple sources (first wins)
defaults({ a: 1 }, { b: 2 }, { b: 3, c: 4 });
// => { a: 1, b: 2, c: 4 }

---

How it works?

Fills in undefined properties with values from source objects. Only undefined values are replaced — null is preserved.

null vs undefined

null is preserved because it's a deliberate value, not absence.

Multiple Sources

First source wins for each key.

---

Use Cases

Initialize configuration options 📌

Apply default settings to a user-provided config object without overwriting explicit nulls. Perfect for library initialization or function parameters.

#initialize#configuration#defaults#options#settings#library

const config = defaults(userOptions, {
  timeout: 5000,
  retries: 3,
  verbose: true
});

Preserve explicit nulls

Ensure that null values provided by the user are respected (not treated as missing). Critical for APIs where null has a specific semantic meaning (e.g., "disable feature").

#preserve#null#semantic#explicit#disable#API

const options = defaults({ cache: null }, { cache: true });
// options.cache is null (user disabled it)

Combine multiple sources

Layer multiple default objects to build a final configuration. Useful for cascading settings (Global -> Project -> User).

#combine#merge#cascade#layering#sources#configuration

const final = defaults(userOpts, projectDefaults, globalDefaults);