Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/deepmergets/docs/API.md

Deeply merge 2 or more objects respecting type information.
Go to Latest
File

API

deepmerge(x, y, …)

Merges the given inputs together using the default configuration.

deepmerge(…inputs)

Merges the array of inputs together using the default configuration.

Note: If inputs isn’t typed as a tuple then we cannot determine the output type. The output type will simply be unknown.

deepmergeInto(target, value, …)

Mutate the target by merging the other inputs into it using the default configuration.

deepmergeCustom(options[, rootMetaData])

Generate a customized deepmerge function using the given options. The returned function works just like deepmerge except it uses the customized configuration.

options

The following options can be used to customize the deepmerge function.
All these options are optional.

mergeRecords

Type: false | (values: Record<any, unknown>[], utils: DeepMergeUtils, meta: MetaData) => unknown

If false, records won’t be merged. If set to a function, that function will be used to merge records.

Note: Records are “vanilla” objects (e.g. { foo: "hello", bar: "world" }).

mergeArrays

Type: false | (values: unknown[][], utils: DeepMergeUtils, meta: MetaData) => unknown

If false, arrays won’t be merged. If set to a function, that function will be used to merge arrays.

mergeMaps

Type: false | (values: Map<unknown, unknown>[], utils: DeepMergeUtils, meta: MetaData) => unknown

If false, maps won’t be merged. If set to a function, that function will be used to merge maps.

mergeSets

Type: false | (values: Set<unknown>[], utils: DeepMergeUtils, meta: MetaData) => unknown

If false, sets won’t be merged. If set to a function, that function will be used to merge sets.

mergeOthers

Type: (values: unknown[], utils: DeepMergeUtils, meta: MetaData) => unknown

If set to a function, that function will be used to merge everything else.

Note: This includes merging mixed types, such as merging a map with an array.

filterValues

Type: false | (values: unknown[], meta: MetaData) => unknown[]

If false, no values will be filter out. If set to a function, that function will be used to filter values. By default, undefined values will be filtered out (null values will be kept).

rootMetaData

Type: MetaData

The given meta data value will be passed to root level merges.

DeepMergeUtils

This is a set of utility functions that are made available to your custom merge functions.

mergeFunctions

These are all the merge function being used to perform the deepmerge.
These will be the custom merge functions you gave, or the default merge functions for options you didn’t customize.

defaultMergeFunctions

These are all the merge functions that the default, non-customized deepmerge function uses.

metaDataUpdater

This function is used to update the meta data. Call it with the new meta data when/where applicable.

deepmerge

This is your top level customized deepmerge function.

Note: Be careful when calling this as it is really easy to end up in an infinite loop.

useImplicitDefaultMerging

States whether or not implicit default merging is in use.

actions

Contains symbols that can be used to tell deepmerge-ts to perform a special action.

deepmergeIntoCustom(options[, rootMetaData])

Generate a customized deepmergeInto function using the given options. The returned function works just like deepmergeInto except it uses the customized configuration.

options

The following options can be used to customize the deepmerge function.
All these options are optional.

mergeRecords

Type: false | (target: DeepMergeValueReference<Record<PropertyKey, unknown>>, values: Record<any, unknown>[], utils: DeepMergeUtils, meta: MetaData) => void | symbol

If false, records won’t be merged. If set to a function, that function will be used to merge records by mutating target.value.

Note: Records are “vanilla” objects (e.g. { foo: "hello", bar: "world" }).

mergeArrays

Type: false | (target: DeepMergeValueReference<unknown[]>, values: unknown[][], utils: DeepMergeIntoFunctionUtils, meta: MetaData) => void | symbol

If false, arrays won’t be merged. If set to a function, that function will be used to merge arrays by mutating target.value.

mergeMaps

Type: false | (target: DeepMergeValueReference<Map<unknown, unknown>>, values: Map<unknown, unknown>[], utils: DeepMergeIntoFunctionUtils, meta: MetaData) => void | symbol

If false, maps won’t be merged. If set to a function, that function will be used to merge maps by mutating target.value.

mergeSets

Type: false | (target: DeepMergeValueReference<Set<unknown>>, values: Set<unknown>[], utils: DeepMergeIntoFunctionUtils, meta: MetaData) => void | symbol

If false, sets won’t be merged. If set to a function, that function will be used to merge sets by mutating target.value.

mergeOthers

Type: (target: DeepMergeValueReference<unknown>, values: unknown[], utils: DeepMergeIntoFunctionUtils, meta: MetaData) => void | symbol

If set to a function, that function will be used to merge everything else by mutating target.value.

Note: This includes merging mixed types, such as merging a map with an array.

filterValues

Type: false | (values: unknown[], meta: MetaData) => unknown[]

If false, no values will be filter out. If set to a function, that function will be used to filter values. By default, undefined values will be filtered out (null values will be kept).

rootMetaData

Type: MetaData

The given meta data value will be passed to root level merges.

DeepMergeIntoFunctionUtils

This is a set of utility functions that are made available to your custom merge functions.

mergeFunctions

These are all the merge function being used to perform the deepmerge.
These will be the custom merge functions you gave, or the default merge functions for options you didn’t customize.

defaultMergeFunctions

These are all the merge functions that the default, non-customized deepmerge function uses.

metaDataUpdater

This function is used to update the meta data. Call it with the new meta data when/where applicable.

deepmergeInto

This is your top level customized deepmergeInto function.

Note: Be careful when calling this as it is really easy to end up in an infinite loop.

actions

Contains symbols that can be used to tell deepmerge-ts to perform a special action.