Merge branch 'main' into next

.cspell.json

@@ -36,33 +36,34 @@
     "/[A-Za-z0-9]{32,}/"
   ],
   "words": [
+    "bar",
+    "baz",
+    "builtins",
+    "codesandbox",
+    "corge",
+    "customizer",
     "deepmerge",
     "deepmergecustomoptions",
     "deepmergets",
+    "denoify",
+    "foo",
+    "fred",
+    "garply",
+    "grault",
     "HKT",
     "HKTs",
     "kinded",
-    "typeguard",
-    "typeguards",
-    "sonarjs",
-    "denoify",
     "litecoin",
     "monero",
-    "codesandbox",
-    "builtins",
-    "foo",
-    "bar",
-    "baz",
-    "qux",
-    "quux",
-    "corge",
-    "grault",
-    "garply",
-    "waldo",
-    "fred",
     "plugh",
-    "xyzzy",
+    "quux",
+    "qux",
+    "sonarjs",
     "thud",
+    "typeguard",
+    "typeguards",
+    "waldo",
+    "xyzzy"
   ],
   "overrides": [
     {

.eslintrc.json

@@ -31,7 +31,7 @@
     "/**/*.md"
   ],
   "rules": {
-    "import/no-relative-parent-imports": "error",
+    "import/no-relative-parent-imports": "off",
     "node/no-extraneous-import": ["error", {
       "allowModules": ["deepmerge-ts"]
     }],

.markdownlint.json

@@ -38,7 +38,7 @@
   // MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
   "MD024": { "siblings_only": true },
   // MD025/single-title/single-h1 - Multiple top level headings in the same document
-  "MD025": true,
+  "MD025": false,
   // MD026/no-trailing-punctuation - Trailing punctuation in heading
   "MD026": true,
   // MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol

README.md

@@ -114,9 +114,20 @@ console.log(merged);
 
 You can try out this example at [codesandbox.io](https://codesandbox.io/s/deepmerge-ts-example-iltxby?file=/src/example.ts).
 
-### Using customized config
+### Merging into a Target
 
-[See deepmerge custom docs](./docs/deepmergeCustom.md).
+You can use `deepmergeInto` if you want to update a target object with the merge result instead of creating a new object.
+
+This function is best used with objects that are all of the same type.
+
+Note: If the target object's type is different to the input objects, we'll assert that the target's type has changed (this is not done automatically with `deepmergeIntoCustom`).
+
+### Customized the Merging Process
+
+We provide a customizer function for each of our main deepmerge functions: `deepmergeCustom` and `deepmergeIntoCustom`.
+You can use these to customize the details of how values should be merged together.
+
+See [deepmerge custom docs](./docs/deepmergeCustom.md) for more details.
 
 ## Performance
 
@@ -140,4 +151,4 @@ In addition to performance improvements, this strategy merges multiple inputs at
 
 ## API
 
-[See API docs](./docs/API.md).
+See [API docs](./docs/API.md).

docs/API.md

@@ -10,9 +10,13 @@ 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.
+Generate a customized `deepmerge` function using the given options. The returned function works just like `deepmerge` except it uses the customized configuration.
 
 ### options
 
@@ -23,27 +27,27 @@ All these options are optional.
 
 Type: `false | (values: Record<any, unknown>[], utils: DeepMergeMergeFunctionUtils, meta: MetaData) => unknown`
 
-If false, records won't be merged. If set to a function, that function will be used to merge records.
+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: DeepMergeMergeFunctionUtils, meta: MetaData) => unknown`
 
-If false, arrays won't be merged. If set to a function, that function will be used to merge arrays.
+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: DeepMergeMergeFunctionUtils, meta: MetaData) => unknown`
 
-If false, maps won't be merged. If set to a function, that function will be used to merge maps.
+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: DeepMergeMergeFunctionUtils, meta: MetaData) => unknown`
 
-If false, sets won't be merged. If set to a function, that function will be used to merge sets.
+If `false`, sets won't be merged. If set to a function, that function will be used to merge sets.
 
 #### `mergeOthers`
 
@@ -70,10 +74,98 @@ These will be the custom merge functions you gave, or the default merge function
 
 #### `defaultMergeFunctions`
 
-These are all the merge functions that the default, non-customize deepmerge function uses.
+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.
+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: DeepMergeMergeFunctionUtils, 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: DeepMergeMergeIntoFunctionUtils, 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: DeepMergeMergeIntoFunctionUtils, 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: DeepMergeMergeIntoFunctionUtils, 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: DeepMergeMergeIntoFunctionUtils, 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.
+
+### `rootMetaData`
+
+Type: `MetaData`
+
+The given meta data value will be passed to root level merges.
+
+### DeepMergeMergeIntoFunctionUtils
+
+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.