https://github.com/forcir/object-deep-merge
Strongly-typed deep and recursive object merging with support for all value types.
https://github.com/forcir/object-deep-merge
deep-merge deep-merge-object deep-merge-objects deep-merging merge-object merge-objects merge-options object-deep-merge object-deep-merging object-merge object-merging type-safe typesafe typescript typescript-library
Last synced: about 1 year ago
JSON representation
Strongly-typed deep and recursive object merging with support for all value types.
- Host: GitHub
- URL: https://github.com/forcir/object-deep-merge
- Owner: forcir
- License: mit
- Created: 2023-07-19T06:13:00.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-11-13T03:06:35.000Z (over 2 years ago)
- Last Synced: 2025-04-27T15:48:43.897Z (about 1 year ago)
- Topics: deep-merge, deep-merge-object, deep-merge-objects, deep-merging, merge-object, merge-objects, merge-options, object-deep-merge, object-deep-merging, object-merge, object-merging, type-safe, typesafe, typescript, typescript-library
- Language: TypeScript
- Homepage: https://npmjs.com/object-deep-merge
- Size: 364 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Strongly-typed deep and recursive object merging with support for all value types.
## Install
```bash
pnpm add object-deep-merge
```
```bash
yarn add object-deep-merge
```
```bash
npm install object-deep-merge
```
## Basic Usage
```ts
import { merge } from "object-deep-merge";
```
### Simply merge two objects, with no nested properties
```ts
const merged = merge({ foo: false }, { bar: true });
console.log({ merged });
```
Output
```json
{
"merged": {
"foo": false,
"bar": true
}
}
```
## Typed Usage
### `merge` Type Signature
The `merge` function accepts two optional type generics. `TData` and `TResult`.
```ts
function merge(
source: TData,
target: TData,
...targets: Array
): TResult;
```
> [!IMPORTANT]
> The [`Merge`](https://github.com/sindresorhus/type-fest/blob/main/source/merge.d.ts) and [`MergeDeep`](https://github.com/sindresorhus/type-fest/blob/main/source/merge-deep.d.ts) types from [`type-fest`](https://github.com/sindresorhus/type-fest) are shipped from this library as a convenience. It is not unreasonable to use those types directly instead.
Without explicitly passing in types the function will infer the shape of the object(s) passed in.
- Passing in `TData` will validate the shape of the objects passed in.
- Passing in `TResult` will override the output type. While this should be used sparingly, it provides a convenient approach for correctly typing partial types into complete types.
### Simple Example w/o Generics
```ts
type Data = {
name: string;
description: string;
};
const base: Data = { name: "object-deep-merge", description: "merge objects" };
const overrides: Partial = { description: "merge objects, deeply" };
const merged = merge(base, overrides);
// Type is inferred so the signature becomes:
// function merge, Partial>(source: Partial, target: Partial, ...targets: Partial[]): Partial
// TData = Partial
// TResult = Data
console.log({ merged });
```
Output
```json
{
"merged": {
"name": "object-deep-merge",
"description": "merge objects, deeply"
}
}
```
### Simple Example w/ `TData` Generic
> [!NOTE]
> Passing in TData will validate the shape of the objects passed in.
```ts
type Data = {
name: string;
description: string;
};
const base: Data = { name: "object-deep-merge", description: "merge objects" };
const overrides: Partial = { description: "merge objects, deeply" };
const merged: Partial = merge>(base, overrides);
// TData = Partial
// TResult = Data
console.log({ merged });
```
Output
```json
{
"merged": {
"name": "object-deep-merge",
"description": "merge objects, deeply"
}
}
```
### Simple Example w/ `TData` and `TResult` Generics
> [!NOTE]
> Passing in `TResult` will override the output type. While this should be used sparingly, it provides a convenient approach for correctly typing partial types into complete types.
```ts
type Data = {
name: string;
description: string;
};
const base: Data = { name: "object-deep-merge", description: "merge objects" };
const overrides: Partial = { description: "merge objects, deeply" };
const merged: Data = merge, Data>(base, overrides);
// TData = Partial
// TResult = Data
console.log({ merged });
```
Output
```json
{
"merged": {
"name": "object-deep-merge",
"description": "merge objects, deeply"
}
}
```