Deepmerge Custom

deepmergeCustom allows you to customize the deepmerge function. It is a higher-order function; that is to say it returns a new customized deepmerge function.

Merge Functions

The signature of merging functions looks like this:

(values: Ts, utils: U, meta: M | undefined) => unknown;

Simply return the merged value.

Special Actions

We provide a couple of special actions under utils.actions that you can use to simplify your custom merge functions.

Skipping a Property (`utils.actions.skip`)

If you want to skip a property from being included in the result of a merge based on its value or metadata, you can easily do so with this action.

For example, skipping all properties under the key "skipme" of type Date:

const customizedDeepmerge = deepmergeCustom({
  mergeOthers: (values, utils, meta) => {
    if (meta?.key === "skipme") {
      const nonDateValues = values.filter((value) => !(value instanceof Date));
      if (nonDateValues.length === 0) {
        return utils.actions.skip; // Completely skip this property
      }

      // Don't skip the property completely if a non-Date value was found.
      return utils.defaultMergeFunctions.mergeOthers(nonDateValues);
    }

    // Perform the default merging (see below).
    return utils.actions.defaultMerge;
  },
});

To do this without any special actions would require using a custom mergeRecords which would be a bit more complicated.

Default Merging (`utils.actions.defaultMerge`)

If you do not want to have to explicitly call the default merging function in your custom merge function; you can just return utils.actions.defaultMerge. This will automatically apply the default merging strategy.

For example, the following customizedDeepmerge functions are equivalent:

const customizedDeepmerge = deepmergeCustom({
  mergeOthers: (value, utils) => {
    if (someCondition) {
      return someCustomValue;
    }
    return utils.defaultMergeFunctions.mergeOthers(values);
  },
});

const customizedDeepmerge = deepmergeCustom({
  mergeOthers: (value, utils) => {
    if (someCondition) {
      return someCustomValue;
    }
    return utils.actions.defaultMerge;
  },
});

Note: When using this action, you cannot change the values upon which the default merging will apply.

Implicit Default Merging

You can alternatively set the option enableImplicitDefaultMerging to true to make it so that if any of your custom merge functions return undefined, then the default merging strategy will automatically be applied.

For example, the following customizedDeepmerge function is equivalent to the two above:

const customizedDeepmerge = deepmergeCustom({
  enableImplicitDefaultMerging: true, // enable implicit default merging
  mergeOthers: (value, utils) => {
    if (someCondition) {
      return someCustomValue;
    }
    // implicitly return undefined
  },
});

Restricting the Parameter Types

By default, anything can be passed into a deepmerge function. If your custom version relies on certain input types, you can restrict the parameters that can be passed. This is done with the first generic that can be passed into deepmergeCustom.

For example:

import { deepmergeCustom } from "deepmerge-ts";

type Foo = {
  foo: {
    bar: string;
    baz?: number;
  };
};

const customDeepmerge = deepmergeCustom<Foo>({}); // <-- Only parameters of type Foo to be passed into the function.

const x = { foo: { bar: "bar-1", baz: 3 } };
const y = { foo: { bar: "bar-2" } };

customDeepmerge(x, y); // => { foo: { bar: "bar-2", baz: 3 } }

const z = { bar: "bar" };

customDeepmerge(x, z); // Argument of type '{ bar: string; }' is not assignable to parameter of type 'Foo'.

Customizing the Return Type

If you want to customize the deepmerge function, you probably also want the return type of the result to be correct too.
Unfortunately however, due to TypeScript limitations, we can not automatically infer this. In order to get the correct return type, you need to provide us with type information about how you have customized the function (we do the very same to define the default configuration).

We need to use HKTs (higher-kinded types) in order to generate the right output type. But again, unfortunately, TypeScript does not support HKTs. Luckily however, there is a workaround.
To use HKTs, we alias the type to a string type (a URI) and simply refer to that type by its alias until we need to resolve it.

Here’s a simple example that creates a custom deepmerge function that does not merge arrays.

import { type DeepMergeLeafURI, deepmergeCustom } from "deepmerge-ts";

const customDeepmerge = deepmergeCustom<
  unknown, // <-- Types that can be passed into the function.
  {
    DeepMergeArraysURI: DeepMergeLeafURI; // <-- Needed for correct output type.
  }
>({
  mergeArrays: false,
});

const x = { foo: [1, 2], bar: [3, 4] };
const y = { foo: [5, 6] };

customDeepmerge(x, y); // => { foo: [5, 6], bar: [3, 4] }

When resolving a HKT, we use a lookup inside an interface called DeepMergeFunctionURItoKind. This interface needs to contain all the mappings of the URIs to their actual type.

When defining your own HKT for use with deepmerge, you need to extend this interface with your mapping. This can be done using Declaration Merging by declaring a module block for this library and defining the same interface.

declare module "deepmerge-ts" {
  interface DeepMergeFunctionURItoKind<
    Ts extends ReadonlyArray<unknown>,
    Fs extends DeepMergeFunctionsURIs,
    M,
  > {
    readonly MyCustomMergeURI: MyValue;
  }
}

Here’s an example of creating a custom deepmerge function that amalgamates dates into an array.

import {
  type DeepMergeFunctionURItoKind,
  type DeepMergeFunctionsURIs,
  type DeepMergeLeaf,
  deepmergeCustom,
} from "deepmerge-ts";

const customizedDeepmerge = deepmergeCustom<
  unknown, // <-- Types that can be passed into the function.
  {
    DeepMergeOthersURI: "MyDeepMergeDatesURI"; // <-- Needed for correct output type.
  }
>({
  mergeOthers: (values, utils, meta) => {
    // If every value is a date, the return the amalgamated array.
    if (values.every((value) => value instanceof Date)) {
      return values;
    }
    // Otherwise, use the default merging strategy.
    return utils.defaultMergeFunctions.mergeOthers(values);
  },
});

const x = { foo: new Date("2020-01-01") };
const y = { foo: new Date("2021-02-02") };
const z = { foo: new Date("2022-03-03") };

customDeepmerge(x, y, z); // => { foo: [Date, Date, Date] }

declare module "deepmerge-ts" {
  interface DeepMergeFunctionURItoKind<
    Ts extends ReadonlyArray<unknown>,
    Fs extends DeepMergeFunctionsURIs,
    M,
  > {
    readonly MyDeepMergeDatesURI: EveryIsDate<Ts> extends true
      ? Ts
      : DeepMergeLeaf<Ts>;
  }
}

type EveryIsDate<Ts extends ReadonlyArray<unknown>> = Ts extends readonly [
  infer Head,
  ...infer Rest,
]
  ? Head extends Date
    ? EveryIsDate<Rest>
    : false
  : true;

Note: If you want to use HKTs in your own project, not related to deepmerge-ts, we recommend checking out fp-ts.

Filtering Values

You can filter the values before they are merged by using the filterValues option. By default, we filter out all undefined values.

If you don’t want to filter out any values, you can set the filterValues option to false. Be sure to also set the DeepMergeFilterValuesURI to DeepMergeNoFilteringURI to ensure correct return types.

import {
  type DeepMergeFunctionURItoKind,
  type DeepMergeFunctionsURIs,
  type DeepMergeNoFilteringURI,
  deepmergeCustom,
} from "deepmerge-ts";

const customizedDeepmerge = deepmergeCustom<
  unknown,
  {
    DeepMergeFilterValuesURI: DeepMergeNoFilteringURI;
  }
>({
  filterValues: false,
});

const x = { key1: { subkey1: `one` } };
const y = { key1: undefined };
const z = { key1: { subkey2: `two` } };

customizedDeepmerge(x, y, z); // => { key1: { subkey2: `two` } }

Here’s an example that creates a custom deepmerge function that filters out all null values instead of undefined.

import {
  type DeepMergeFunctionURItoKind,
  type DeepMergeFunctionsURIs,
  type FilterOut,
  deepmergeCustom,
} from "deepmerge-ts";

const customizedDeepmerge = deepmergeCustom<
  unknown,
  {
    DeepMergeFilterValuesURI: "FilterNullValues";
  }
>({
  filterValues(values, meta) {
    return values.filter((value) => value !== null);
  },
});

const x = { key1: { subkey1: `one` } };
const y = { key1: null };
const z = { key1: { subkey2: `two` } };

customizedDeepmerge(x, y, z); // => { key1: { subkey1: `one`, subkey2: `two` } }

declare module "deepmerge-ts" {
  interface DeepMergeFunctionURItoKind<
    Ts extends Readonly<ReadonlyArray<unknown>>,
    Fs extends DeepMergeFunctionsURIs,
    M,
  > {
    readonly FilterNullValues: FilterOut<Ts, null>;
  }
}

Meta Data

We provide a simple object of meta data that states the key that the values being merged were under.

Here’s an example that creates a custom deepmerge function that merges numbers differently based on the key they were under.

import {
  type DeepMergeFunctionURItoKind,
  type DeepMergeFunctionsURIs,
  type DeepMergeLeaf,
  deepmergeCustom,
} from "deepmerge-ts";

const customizedDeepmerge = deepmergeCustom({
  mergeOthers: (values, utils, meta) => {
    if (meta !== undefined && areAllNumbers(values)) {
      const { key } = meta;
      const numbers: ReadonlyArray<number> = values;

      if (key === "sum") {
        return numbers.reduce((sum, value) => sum + value);
      }
      if (key === "product") {
        return numbers.reduce((prod, value) => prod * value);
      }
      if (key === "mean") {
        return numbers.reduce((sum, value) => sum + value) / numbers.length;
      }
    }

    return utils.defaultMergeFunctions.mergeOthers(values);
  },
});

function areAllNumbers(
  values: ReadonlyArray<unknown>,
): values is ReadonlyArray<number> {
  return values.every((value) => typeof value === "number");
}

const v = { sum: 1, product: 2, mean: 3 };
const x = { sum: 4, product: 5, mean: 6 };
const y = { sum: 7, product: 8, mean: 9 };
const z = { sum: 10, product: 11, mean: 12 };

customizedDeepmerge(v, x, y, z); // => { sum: 22, product: 880, mean: 7.5 }

Customizing the Meta Data

You can customize the meta data that is passed to the merge functions by providing a metaDataUpdater function.

Here’s an example that uses custom metadata that accumulates the full key path.

import {
  type DeepMergeFunctionURItoKind,
  type DeepMergeFunctionsURIs,
  type DeepMergeLeaf,
  deepmergeCustom,
} from "deepmerge-ts";

const customizedDeepmerge = deepmergeCustom<
  // Allow any value to be passed into the function.
  unknown,
  // Change the return type of `mergeOthers`.
  {
    DeepMergeOthersURI: "KeyPathBasedMerge";
  },
  // Change the meta data type.
  {
    keyPath: ReadonlyArray<PropertyKey>;
  }
>({
  // Customize what the actual meta data.
  metaDataUpdater: (previousMeta, metaMeta) => {
    if (previousMeta === undefined) {
      if (metaMeta.key === undefined) {
        return { keyPath: [] };
      }
      return { keyPath: [metaMeta.key] };
    }
    if (metaMeta.key === undefined) {
      return previousMeta;
    }
    return {
      ...metaMeta,
      keyPath: [...previousMeta.keyPath, metaMeta.key],
    };
  },
  // Use the meta data when merging others.
  mergeOthers: (values, utils, meta) => {
    if (
      meta !== undefined &&
      meta.keyPath.length >= 2 &&
      meta.keyPath.at(-2) === "bar" &&
      meta.keyPath.at(-1) === "baz"
    ) {
      return "special merge";
    }

    return utils.defaultMergeFunctions.mergeOthers(values);
  },
});

const x = {
  foo: { bar: { baz: 1, qux: 2 } },
  bar: { baz: 3, qux: 4 },
};
const y = {
  foo: { bar: { baz: 5, bar: { baz: 6, qux: 7 } } },
  bar: { baz: 8, qux: 9 },
};

customizedDeepmerge(x, y); // => { foo: { bar: { baz: "special merge", bar: { baz: 6, qux: 7 }, qux: 2 } }, bar: { baz: "special merge", qux: 9 }, }

declare module "deepmerge-ts" {
  interface DeepMergeFunctionURItoKind<
    Ts extends Readonly<ReadonlyArray<unknown>>,
    Fs extends DeepMergeFunctionsURIs,
    M, // This is the meta data type
  > {
    readonly KeyPathBasedMerge: Ts[number] extends number
      ? Ts[number] | string
      : DeepMergeLeaf<Ts>;
  }
}

API

See deepmerge custom API.

Deepmerge Into Custom

deepmergeIntoCustom as the name suggests, works just like deepmergeCustom, only for deepmergeInto instead of deepmerge. But there are some differences to be aware of.

Merge Functions

The signature of merging functions for deepmergeIntoCustom looks like this:

(
  target: DeepMergeValueReference<T>,
  values: Ts,
  utils: U,
  meta: M | undefined,
) => symbol | undefined;

Instead of returning a value like with deepmergeCustom’s merge functions, mutations should be made to target.value.
You can however still return an action.

Note: values includes all the values, including the target’s value (if there is one).

Special Actions

No Skip Action (`utils.actions.skip`)

This action doesn’t make sense with in the context of merging into a target. Use delete target.value[key] instead if you don’t want the property to exists on the target.

No Implicit Default Merging

It doesn’t make sense to have implicit default merging here as all merge functions should return undefined (if not returning an action).

Customizing the Return Type

The return type of a custom deepmergeInto should be void, so you don’t need to customize it’s return type like you would with a regular custom deepmerge function.

However, you may want to use an assertion function if the target’s type is not the same as the inputs. This is by no means required though. But if you want to do this then you’ll simply need to explicity declare a type annotation for your customized deepmergeInto function that makes such an assertion.

Here’s an example:

type CustomizedDeepmergeInto = <
  Target extends object,
  Ts extends ReadonlyArray<object>,
>(
  target: Target,
  ...objects: Ts
) => asserts target is Target & // Intercepting with `Target` is essentially required to make TypeScript happy.
  DeepMergeHKT<
    [Target, ...Ts], // Don't forget to pass the `Target` type here too.
    {
      DeepMergeRecordsURI: DeepMergeFunctionsDefaultURIs["DeepMergeRecordsURI"]; // Use default behavior.
      DeepMergeArraysURI: DeepMergeFunctionsDefaultURIs["DeepMergeArraysURI"]; // Use default behavior.
      DeepMergeSetsURI: DeepMergeFunctionsDefaultURIs["DeepMergeSetsURI"]; // Use default behavior.
      DeepMergeMapsURI: DeepMergeFunctionsDefaultURIs["DeepMergeMapsURI"]; // Use default behavior.
      DeepMergeOthersURI: "CustomDeepMergeOthersURI"; // Use custom behavior (see deepmergeCustom's docs above for details).
    },
    DeepMergeBuiltInMetaData // Use default meta data.
  >;

export const customizedDeepmergeInto: CustomizedDeepmergeInto =
  deepmergeIntoCustom({
    mergeOthers: (source, values, utils, meta) => {
      /* ... */
    },
  });

API

See deepmerge into custom API.

Deepmerge Custom

Merge Functions

Special Actions

Skipping a Property (utils.actions.skip)

Default Merging (utils.actions.defaultMerge)

Implicit Default Merging

Restricting the Parameter Types

Customizing the Return Type

Filtering Values

Meta Data

Customizing the Meta Data

API

Deepmerge Into Custom

Merge Functions

Special Actions

No Skip Action (utils.actions.skip)

No Implicit Default Merging

Customizing the Return Type

API

Skipping a Property (`utils.actions.skip`)

Default Merging (`utils.actions.defaultMerge`)

No Skip Action (`utils.actions.skip`)