0
# node.extend
1

2
node.extend is a faithful port of jQuery's extend function that works reliably in Node.js environments. It enables developers to merge and clone JavaScript objects with support for both shallow and deep copying operations, addressing limitations found in other extend implementations available on npm.
3

4
## Package Information
5

6
- **Package Name**: node.extend
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install node.extend`
10

11
## Core Imports
12

13
```javascript
14
const extend = require('node.extend');
15
```
16

17
For ES modules:
18

19
```javascript
20
import extend from 'node.extend';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const extend = require('node.extend');
27

28
// Shallow merge
29
const result = extend({}, { a: 1 }, { b: 2 });
30
// Result: { a: 1, b: 2 }
31

32
// Deep merge
33
const deep = extend(true, {}, { 
34
  nested: { a: 1 } 
35
}, { 
36
  nested: { b: 2 } 
37
});
38
// Result: { nested: { a: 1, b: 2 } }
39

40
// Clone an object
41
const original = { name: 'Alice', age: 30 };
42
const clone = extend({}, original);
43
```
44

45
## Capabilities
46

47
### Object Extend Function
48

49
Merges and clones JavaScript objects with support for shallow and deep copying.
50

51
```javascript { .api }
52
/**
53
 * Extends objects with properties from source objects
54
 * @param {boolean} [deep] - If true, performs deep merge recursively
55
 * @param {any} target - The target object to extend (modified in-place)
56
 * @param {...any} sources - One or more source objects to merge into target
57
 * @returns {any} The modified target object with merged properties
58
 */
59
function extend([deep,] target, ...sources);
60
```
61

62
**Parameters:**
63

64
- **deep** (optional): Boolean - When `true`, performs recursive deep merge of nested objects and arrays
65
- **target**: Any - The target object to extend. Non-object values are converted to empty objects `{}`
66
- **sources**: Any - One or more source objects whose properties will be copied to the target
67

68
**Return Value:**
69

70
Returns the modified target object containing merged properties from all source objects.
71

72
**Behavior Details:**
73

74
1. **Type Coercion**: Non-object targets (strings, numbers, etc.) are converted to empty objects `{}`
75
2. **String Handling**: String sources are converted to object form with numeric keys (e.g., `"abc"` becomes `{0: 'a', 1: 'b', 2: 'c'}`)
76
3. **Array Handling**: Arrays are treated as objects with numeric indices as keys
77
4. **Deep Merge**: When `deep=true`, recursively merges nested objects and arrays
78
5. **Property Safety**: Properly handles the `__proto__` property using `Object.defineProperty` when available
79
6. **Circular Reference Protection**: Prevents infinite loops from objects that reference themselves
80
7. **Undefined Values**: Undefined values from sources are ignored and not copied to the target
81

82
**Usage Examples:**
83

84
```javascript
85
const extend = require('node.extend');
86

87
// Basic shallow merge
88
const user = { name: 'Alice' };
89
const details = { age: 30, city: 'New York' };
90
const result = extend(user, details);
91
// user and result are: { name: 'Alice', age: 30, city: 'New York' }
92

93
// Multiple source objects
94
const config = extend({}, defaults, options, overrides);
95

96
// Deep merge for nested objects
97
const defaultConfig = {
98
  api: { timeout: 5000, retries: 3 },
99
  logging: { level: 'info' }
100
};
101
const userConfig = {
102
  api: { retries: 5 },
103
  logging: { level: 'debug', format: 'json' }
104
};
105
const finalConfig = extend(true, {}, defaultConfig, userConfig);
106
// Result: {
107
//   api: { timeout: 5000, retries: 5 },
108
//   logging: { level: 'debug', format: 'json' }
109
// }
110

111
// Cloning objects (shallow)
112
const original = { items: [1, 2, 3], meta: { count: 3 } };
113
const shallowClone = extend({}, original);
114
// shallowClone.items === original.items (same reference)
115

116
// Cloning objects (deep)
117
const deepClone = extend(true, {}, original);
118
// deepClone.items !== original.items (different reference)
119

120
// Working with arrays
121
const arr1 = [1, 2, 3];
122
const arr2 = ['a', 'b'];
123
const merged = extend(arr1, arr2);
124
// arr1 and merged are: ['a', 'b', 3]
125

126
// String sources are converted to objects
127
const target = extend({}, 'hello');
128
// Result: { 0: 'h', 1: 'e', 2: 'l', 3: 'l', 4: 'o' }
129
```
130

131
**Error Handling:**
132

133
The function gracefully handles edge cases without throwing errors:
134
- `null` or `undefined` sources are ignored
135
- Circular references are detected and prevented
136
- Type coercion ensures consistent behavior across different input types
137

138
**Type Compatibility:**
139

140
The function handles these type combinations:
141
- Object + Object → Merged object
142
- Array + Array → Merged array (properties by index)
143
- String + Any → Object form of string with additional properties
144
- Number + Object → Object (number ignored)
145
- Date + Object → Date with object properties attached
146
- Any + undefined/null → Target unchanged