0
# Utils Merge
1

2
Utils Merge is a lightweight utility library that provides a simple `merge()` function for merging JavaScript objects. The function copies all enumerable properties from a source object into a destination object, modifying the destination object in place with shallow copying behavior.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const merge = require('utils-merge');
15
```
16

17
For ES modules:
18

19
```javascript
20
import merge from 'utils-merge';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const merge = require('utils-merge');
27

28
// Basic object merging
29
const a = { foo: 'bar' };
30
const b = { bar: 'baz' };
31

32
merge(a, b);
33
console.log(a); // { foo: 'bar', bar: 'baz' }
34

35
// Property overwriting
36
const config = { host: 'localhost', port: 3000 };
37
const userConfig = { port: 8080, ssl: true };
38

39
merge(config, userConfig);
40
console.log(config); // { host: 'localhost', port: 8080, ssl: true }
41
```
42

43
## Capabilities
44

45
### Object Merging
46

47
Merges properties from a source object into a destination object with shallow copying.
48

49
```javascript { .api }
50
/**
51
 * Merge object b with object a.
52
 * Copies all enumerable properties from source object into destination object.
53
 * Modifies the destination object in place and returns it.
54
 * 
55
 * @param {Object|null|undefined} a - Destination object that will be modified
56
 * @param {Object|null|undefined} b - Source object whose properties will be copied
57
 * @return {Object|null|undefined} - Returns the modified destination object (or a if null/undefined)
58
 */
59
function merge(a, b);
60
```
61

62
**Behavior:**
63
- Performs shallow merge - only copies property values, not nested objects
64
- Modifies the destination object `a` in place
65
- Properties in source object `b` overwrite existing properties in destination object `a`
66
- Returns the modified destination object `a`
67
- If source object `b` is undefined or null, destination object `a` is returned unchanged
68
- If destination object `a` is undefined or null, it is returned as-is
69
- Function safely handles null/undefined inputs without throwing errors
70

71
**Usage Examples:**
72

73
```javascript
74
const merge = require('utils-merge');
75

76
// Simple merging
77
const target = { name: 'Alice' };
78
const source = { age: 25, city: 'Boston' };
79
const result = merge(target, source);
80
// target is now { name: 'Alice', age: 25, city: 'Boston' }
81
// result === target (same reference)
82

83
// Property overwriting
84
const defaults = { timeout: 5000, retries: 3 };
85
const options = { timeout: 10000 };
86
merge(defaults, options);
87
// defaults is now { timeout: 10000, retries: 3 }
88

89
// Handling undefined source
90
const obj = { foo: 'bar' };
91
merge(obj, undefined);
92
// obj remains { foo: 'bar' }
93

94
// Configuration merging pattern
95
function createClient(userOptions = {}) {
96
  const defaultOptions = {
97
    host: 'api.example.com',
98
    port: 443,
99
    timeout: 5000,
100
    retries: 3
101
  };
102
  
103
  return merge(defaultOptions, userOptions);
104
}
105

106
const client = createClient({ port: 8080, ssl: false });
107
// Returns: { host: 'api.example.com', port: 8080, timeout: 5000, retries: 3, ssl: false }
108
```