0
# xtend
1

2
xtend is a lightweight utility library for extending JavaScript objects by merging properties from multiple source objects. It provides both immutable and mutable variants of object extension, implementing safe property copying with hasOwnProperty checks to prevent prototype pollution.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const extend = require("xtend");
15
```
16

17
For the mutable variant:
18

19
```javascript
20
const mutableExtend = require("xtend/mutable");
21
```
22

23
## Basic Usage
24

25
```javascript
26
const extend = require("xtend");
27

28
// Immutable extension - creates new object
29
const obj1 = { a: "foo", b: "bar" };
30
const obj2 = { b: "baz", c: "qux" };
31
const result = extend(obj1, obj2);
32
// result: { a: "foo", b: "baz", c: "qux" }
33
// obj1 and obj2 remain unchanged
34

35
// Mutable extension - modifies target object
36
const mutableExtend = require("xtend/mutable");
37
const target = { a: "foo" };
38
mutableExtend(target, { b: "bar" });
39
// target is now: { a: "foo", b: "bar" }
40
```
41

42
## Capabilities
43

44
### Immutable Object Extension
45

46
Creates a new object by merging properties from source objects without modifying the original objects.
47

48
```javascript { .api }
49
/**
50
 * Extends objects immutably by creating a new object with merged properties
51
 * Takes any number of objects as arguments and merges them into a new object
52
 * @param {...Object} sources - Objects to merge properties from (variadic arguments)
53
 * @returns {Object} New object with merged properties from all sources
54
 */
55
function extend() {}
56
```
57

58
**Key features:**
59
- Creates a new target object (immutable operation)
60
- Accepts any number of source objects as arguments using `arguments` object
61
- Right-most property takes precedence on conflicts
62
- Handles null/undefined sources gracefully
63
- Uses hasOwnProperty checks to prevent prototype pollution
64
- Copies only own enumerable properties
65

66
**Usage Examples:**
67

68
```javascript
69
const extend = require("xtend");
70

71
// Basic merging
72
const result = extend({ a: "foo" }, { b: "bar" });
73
// { a: "foo", b: "bar" }
74

75
// Property precedence (rightmost wins)
76
const result = extend({ a: "foo" }, { a: "bar" });
77
// { a: "bar" }
78

79
// Multiple objects
80
const result = extend({ a: 1 }, { b: 2 }, { c: 3 });
81
// { a: 1, b: 2, c: 3 }
82

83
// Handles special values
84
const result = extend({ a: undefined }, { b: 0 }, { c: null });
85
// { a: undefined, b: 0, c: null }
86

87
// Graceful handling of null/undefined
88
const result = extend(null, { a: "foo" }, undefined, { b: "bar" });
89
// { a: "foo", b: "bar" }
90
```
91

92
### Mutable Object Extension
93

94
Modifies the target object in place by copying properties from source objects.
95

96
```javascript { .api }
97
/**
98
 * Extends the target object mutably by copying properties from source objects
99
 * Takes target as first argument, then any number of source objects
100
 * @param {Object} target - Object to modify (receives new properties)
101
 * @param {...Object} sources - Objects to copy properties from (variadic arguments)
102
 * @returns {Object} The modified target object
103
 */
104
function extend(target) {}
105
```
106

107
**Key features:**
108
- Modifies the first argument (target) in place
109
- Accepts target object as first parameter, sources as remaining parameters using `arguments` object
110
- Right-most property takes precedence on conflicts
111
- Handles null/undefined sources gracefully
112
- Uses hasOwnProperty checks to prevent prototype pollution
113
- Copies only own enumerable properties
114
- Returns the modified target object
115

116
**Usage Examples:**
117

118
```javascript
119
const mutableExtend = require("xtend/mutable");
120

121
// Basic mutable extension
122
const target = { a: "foo" };
123
mutableExtend(target, { b: "bar" });
124
console.log(target); // { a: "foo", b: "bar" }
125

126
// Property overwriting
127
const target = { a: "foo" };
128
mutableExtend(target, { a: "bar" });
129
console.log(target); // { a: "bar" }
130

131
// Multiple sources
132
const target = { a: 1 };
133
mutableExtend(target, { b: 2 }, { c: 3 });
134
console.log(target); // { a: 1, b: 2, c: 3 }
135

136
// Return value is the modified target
137
const target = { a: "foo" };
138
const result = mutableExtend(target, { b: "bar" });
139
console.log(result === target); // true
140
```
141

142
## Error Handling
143

144
Both variants handle edge cases gracefully:
145

146
- **Null/undefined sources**: Skipped silently without errors
147
- **Non-object sources**: Properties enumerated if present, skipped if not
148
- **Prototype pollution**: Prevented by hasOwnProperty checks
149
- **Special values**: undefined, null, and 0 values are copied correctly
150

151
The functions do not throw exceptions and handle invalid inputs by skipping them silently.