0
# node.extend
1

2
node.extend is a faithful port of jQuery's extend functionality for Node.js environments. It provides deep and shallow object cloning/merging capabilities with proper handling of edge cases, arrays, nested objects, and circular reference prevention.
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
ESM:
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 - modifies target object
29
const target = { a: 1 };
30
const source = { b: 2, c: 3 };
31
const result = extend(target, source);
32
// result and target are both { a: 1, b: 2, c: 3 }
33

34
// Deep merge - creates new object
35
const deepTarget = extend(true, {}, {
36
  user: { name: 'Alice', settings: { theme: 'dark' } }
37
}, {
38
  user: { age: 25, settings: { language: 'en' } }
39
});
40
// Result: { user: { name: 'Alice', age: 25, settings: { theme: 'dark', language: 'en' } } }
41
```
42

43
## Capabilities
44

45
### Object Extension
46

47
The main extend function performs object merging with support for both shallow and deep merge operations.
48

49
```javascript { .api }
50
/**
51
 * Merge properties from source objects into target object
52
 * @param {boolean} [deep] - When true, performs deep/recursive merge
53
 * @param {Object} target - The target object to extend (will be modified)
54
 * @param {...Object} sources - Source objects whose properties will be merged into target
55
 * @returns {Object} The extended target object
56
 */
57
function extend([deep], target, ...sources);
58
```
59

60
**Parameters:**
61
- `deep` (optional): Boolean - When `true`, performs recursive deep merge of nested objects and arrays
62
- `target`: Object - The target object that will be modified and returned  
63
- `sources`: Object(s) - One or more source objects whose properties will be copied to target
64

65
**Return Value:** Object - The modified target object
66

67
**Behavior:**
68
- **Shallow merge**: `extend(target, source)` - Copies enumerable properties from source to target
69
- **Deep merge**: `extend(true, target, source)` - Recursively merges nested objects and arrays
70
- **Multiple sources**: Later sources override earlier ones for the same property names
71
- **Type handling**: Non-object targets are converted to empty objects
72
- **String conversion**: String arguments are converted to character array objects
73
- **Circular reference prevention**: Automatically detects and prevents infinite loops
74
- **Array merging**: In deep mode, arrays are merged by index (source elements overwrite target at same indices)
75
- **Undefined skipping**: Undefined values in sources are not copied to target
76

77
**Usage Examples:**
78

79
```javascript
80
const extend = require('node.extend');
81

82
// Basic shallow merge
83
const user = extend({ name: 'Alice' }, { age: 25 }, { active: true });
84
// Result: { name: 'Alice', age: 25, active: true }
85

86
// Create new object without modifying original
87
const newObj = extend({}, originalObj, modifications);
88

89
// Deep merge with nested objects
90
const config = extend(true, {
91
  server: { port: 3000, host: 'localhost' },
92
  features: { auth: true }
93
}, {
94
  server: { port: 8080 }, // port overrides, host remains 'localhost'
95
  features: { logging: true } // logging added, auth remains true
96
});
97

98
// Array merging in deep mode
99
const arrays = extend(true, { nums: [1, 2, 3] }, { nums: ['a', 'b'] });
100
// Result: { nums: ['a', 'b', 3] }
101

102
// String to object conversion
103
const strResult = extend({}, 'hello');
104
// Result: { 0: 'h', 1: 'e', 2: 'l', 3: 'l', 4: 'o' }
105
```
106

107
### Version Information
108

109
Access to the library version for compatibility checking.
110

111
```javascript { .api }
112
/**
113
 * Version string of the extend library
114
 * @type {string}
115
 */
116
extend.version;
117
```
118

119
**Usage Example:**
120

121
```javascript
122
const extend = require('node.extend');
123
console.log('Using node.extend version:', extend.version);
124
// Output: "Using node.extend version: 1.1.7"
125
```
126

127
**Note**: The `extend.version` property returns "1.1.7" even though the package version is 1.1.8, due to a version mismatch in the source code.
128

129
## Edge Cases and Special Handling
130

131
### __proto__ Property Handling
132

133
The library safely handles `__proto__` properties by defining them as enumerable own properties rather than affecting the prototype chain.
134

135
```javascript
136
const target = {};
137
const source = { __proto__: { customProp: 'value' } };
138
extend(target, source);
139
// target.__proto__ is set as an own property, not affecting the prototype
140
```
141

142
### Circular Reference Prevention
143

144
Automatically detects when the target object appears in the source chain to prevent infinite recursion.
145

146
```javascript
147
const obj = { a: 1 };
148
obj.self = obj; // circular reference
149
const result = extend(true, {}, obj); // Safely handled, no infinite loop
150
```
151

152
### Type Coercion Behavior
153

154
- **Non-object targets**: Converted to `{}` 
155
- **String sources**: Split into character arrays
156
- **Number sources**: Ignored (results in empty object)
157
- **Date sources**: Handled as objects with enumerable properties
158
- **Array sources**: Treated as objects with numeric indices