0
# Merge
1

2
Merge provides comprehensive object merging utilities for JavaScript and TypeScript applications. It enables developers to merge objects with optional deep cloning and recursive merging capabilities, featuring built-in prototype pollution protection and flexible API patterns.
3

4
## Package Information
5

6
- **Package Name**: merge
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install merge`
10

11
## Core Imports
12

13
```typescript
14
import merge from "merge";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const merge = require("merge");
21
```
22

23
Named imports (alternative approach):
24

25
```typescript
26
import { merge, recursive, clone, isPlainObject } from "merge";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import merge from "merge";
33

34
// Basic shallow merge using default export
35
const result1 = merge({ a: 1 }, { b: 2 });
36
// Result: { a: 1, b: 2 }
37

38
// Merge with cloning (first parameter true)
39
const original = { a: 1 };
40
const result2 = merge(true, original, { b: 2 });
41
// Result: { a: 1, b: 2 }, original unchanged
42

43
// Recursive merge using namespace property
44
const result3 = merge.recursive(
45
  { level: { value: 1 } }, 
46
  { level: { str: 'hello' } }
47
);
48
// Result: { level: { value: 1, str: 'hello' } }
49

50
// Deep clone using namespace property
51
const cloned = merge.clone({ a: { b: 1 } });
52

53
// Alternative: using named imports
54
import { merge as mergeFunc, recursive, clone } from "merge";
55
const result4 = mergeFunc({ a: 1 }, { b: 2 });
56
const result5 = recursive({ a: { b: 1 } }, { a: { c: 2 } });
57
// result4: { a: 1, b: 2 }
58
// result5: { a: { b: 1, c: 2 } }
59
```
60

61
## Capabilities
62

63
### Main Function (Default Export)
64

65
The primary merge function exported as default. Identical to the named `merge` function but also provides namespace access to other functions.
66

67
```typescript { .api }
68
function main(clone: boolean, ...items: any[]): any;
69
function main(...items: any[]): any;
70
```
71

72
When the first parameter is `true`, objects are cloned before merging to prevent mutation of input objects. Otherwise, the first object in the arguments is mutated and returned.
73

74
**Parameters:**
75
- `clone` (boolean, optional): When `true`, clones objects before merging
76
- `...items` (any[]): Objects to merge together
77

78
**Returns:** Merged object
79

80
**Namespace Properties:**
81
- `main.clone` - Reference to clone function
82
- `main.isPlainObject` - Reference to isPlainObject function
83
- `main.recursive` - Reference to recursive function
84

85
### Basic Merge
86

87
Performs shallow merging of objects with optional cloning.
88

89
```typescript { .api }
90
function merge(clone: boolean, ...items: any[]): any;
91
function merge(...items: any[]): any;
92
```
93

94
When the first parameter is `true`, objects are cloned before merging to prevent mutation of input objects. Otherwise, the first object in the arguments is mutated and returned.
95

96
**Parameters:**
97
- `clone` (boolean, optional): When `true`, clones objects before merging
98
- `...items` (any[]): Objects to merge together
99

100
**Returns:** Merged object
101

102
### Recursive Merge
103

104
Performs deep/recursive merging of nested objects with optional cloning. Available as both a named export and as a namespace property on the main function.
105

106
```typescript { .api }
107
function recursive(clone: boolean, ...items: any[]): any;
108
function recursive(...items: any[]): any;
109
```
110

111
Recursively merges nested objects instead of replacing them entirely. Automatically filters dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
112

113
**Parameters:**
114
- `clone` (boolean, optional): When `true`, clones objects before merging
115
- `...items` (any[]): Objects to recursively merge
116

117
**Returns:** Recursively merged object
118

119
### Clone
120

121
Deep clones objects and arrays, preserving nested structures. Available as both a named export and as a namespace property on the main function.
122

123
```typescript { .api }
124
function clone<T>(input: T): T;
125
```
126

127
Creates a deep copy of the input, handling nested objects and arrays recursively. Primitive values are returned as-is.
128

129
**Parameters:**
130
- `input` (any): Object, array, or primitive to clone
131

132
**Returns:** Deep cloned copy of the input
133

134
### Plain Object Check
135

136
Checks if input is a plain object (not array, null, or primitive). Available as both a named export and as a namespace property on the main function.
137

138
```typescript { .api }
139
function isPlainObject(input: any): input is Object;
140
```
141

142
Type predicate function that determines if the input is a plain object suitable for merging operations.
143

144
**Parameters:**
145
- `input` (any): Value to check
146

147
**Returns:** `true` if input is a plain object, `false` otherwise
148

149
## Types
150

151
For TypeScript users, the package includes complete type definitions:
152

153
```typescript { .api }
154
// Main function with overloads
155
declare function main(clone: boolean, ...items: any[]): any;
156
declare function main(...items: any[]): any;
157

158
// Named export functions
159
declare function merge(clone: boolean, ...items: any[]): any;
160
declare function merge(...items: any[]): any;
161
declare function recursive(clone: boolean, ...items: any[]): any;
162
declare function recursive(...items: any[]): any;
163
declare function clone<T>(input: T): T;
164
declare function isPlainObject(input: any): input is Object;
165

166
// Main function namespace properties
167
declare namespace main {
168
  var clone: typeof clone;
169
  var isPlainObject: typeof isPlainObject;
170
  var recursive: typeof recursive;
171
}
172
```
173

174
## Security Features
175

176
The merge package includes built-in protection against prototype pollution attacks:
177

178
- Automatically filters dangerous keys: `__proto__`, `constructor`, `prototype`
179
- Safe for use with user-provided data and JSON payloads
180
- Protection applies to both shallow and recursive merge operations
181

182
## Error Handling
183

184
The package gracefully handles invalid inputs:
185
- Non-objects are filtered out during merging
186
- `null`, `undefined`, arrays, and primitives are ignored
187
- Empty arguments return an empty object `{}`
188
- No exceptions are thrown for invalid inputs