defu

You can install defu using any of the following package managers:

# yarn
yarn add defu

# npm
npm install defu

# pnpm
pnpm install defu

defuArrayFn is similar to defuFn, but the functions provided are only applied to array values defined in the defaults.

Note: The function is called only if the value defined in the defaults is an array.

import { defuArrayFn } from "defu";

defuArrayFn(
  {
    ignore: (val) => val.filter((i) => i !== "dist"),
    count: () => 20,
  },
  {
    ignore: ["node_modules", "dist"],
    count: 10,
  },
);
/*
  {
    ignore: ['node_modules'],
    count: () => 20
  }
*/

The defu function assigns default properties to a destination object recursively. The leftmost arguments have the highest priority.

Note:

• object and defaults are not modified.
• Nullish values (null and undefined) are skipped.
• __proto__ and constructor keys are skipped to prevent object pollution.
• Array values are concatenated if the property is defined in the defaults.

import { defu } from "defu";

const options = defu(object, ...defaults);

import { defu } from "defu";

console.log(defu({ a: { b: 2 } }, { a: { b: 1, c: 3 } }));
// => { a: { b: 2, c: 3 } }

defuFn allows you to provide a function for specific keys. If a function is provided in the first argument, it will be called with the default value instead of performing a standard merge. This is useful for manipulating default values (e.g., filtering arrays or transforming numbers).

Note: If the default value is not defined, the function will not be called and the value will be kept as is.

import { defuFn } from "defu";

defuFn(
  {
    ignore: (val) => val.filter((item) => item !== "dist"),
    count: (count) => count + 20,
  },
  {
    ignore: ["node_modules", "dist"],
    count: 10,
  },
);
/*
 {
    ignore: ['node_modules'],
    count: 30
  }
 */

If you are using CommonJS, you can import defu using require:

const { defu } = require("defu");

If the default merging strategy is not suitable, use createDefu to create a custom instance. The custom merger function accepts obj (the source object), key, and value (the current value). It should return true if the custom merging was applied.

import { createDefu } from "defu";

const ext = createDefu((obj, key, value) => {
  if (typeof obj[key] === "number" && typeof value === "number") {
    obj[key] += value;
    return true;
  }
});

ext({ cost: 15 }, { cost: 10 }); // { cost: 25 }

The defu function is the standard utility for merging objects with defaults. It performs a deep merge where properties from the first argument (baseObject) overwrite properties in the second argument (defaults).

Key behaviors:

• Deep Merging: Nested plain objects are merged recursively.
• Array Concatenation: If both the base value and the default value are arrays, they are concatenated ([...base, ...defaults]).
• Safety: It ignores __proto__ and constructor keys to prevent prototype pollution.
• Multi-argument support: You can pass multiple objects to be merged sequentially.

The defuProxy function acts as a namespace providing several utilities for advanced merging scenarios:

• defuProxy.fn: A DefuFn utility.
• defuProxy.arrayFn: An arrayFn utility for array-specific merging.
• defuProxy.defuFn: A DefuFn utility.
• defuProxy.defuArrayFn: A defuArrayFn utility.
• defuProxy.createDefu: A function to create new defu instances.
• defuProxy.extend(merger): Returns a DefuFn configured with a custom merger function.
• defuProxy.defu: The default instance.
• defuProxy.default: An alias for the default instance.

The CommonJS entrypoint provides access to the following functions via named exports:

• defu: The core merging function.
• createDefu: A utility to create a custom defu instance.
• defuFn: A utility for merging functions.
• defuArrayFn: A utility for merging arrays of functions.