0
# Object Operations
1

2
Core functionality for object manipulation including property copying, merging, iteration, and transformation. These utilities provide reliable object handling with support for deep operations and custom iteration patterns.
3

4
## Capabilities
5

6
### Object Assignment
7

8
Copy properties from source objects to a target object, similar to Object.assign but with additional features.
9

10
```javascript { .api }
11
/**
12
 * Copy properties from source objects to target object
13
 * @param target - Target object to copy properties to
14
 * @param sources - Source objects to copy properties from
15
 * @returns Target object with copied properties
16
 */
17
function assign(target: any, ...sources: any[]): any;
18

19
/**
20
 * Deep copy properties (when first parameter is true)
21
 * @param deep - Set to true for deep copying
22
 * @param target - Target object for deep copy
23
 * @param sources - Source objects to deep copy from
24
 * @returns Target object with deep copied properties
25
 */
26
function assign(deep: true, target: any, ...sources: any[]): any;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import { assign } from 'xe-utils';
33

34
// Basic assignment
35
const target = { a: 1 };
36
const result = assign(target, { b: 2 }, { c: 3 });
37
// Result: { a: 1, b: 2, c: 3 }
38

39
// Deep assignment
40
const deepResult = assign(true, {}, 
41
  { user: { name: 'Alice' } }, 
42
  { user: { age: 25 } }
43
);
44
// Result: { user: { name: 'Alice', age: 25 } }
45
```
46

47
### Object Merging
48

49
Deep merge multiple objects into a target object, recursively combining nested properties.
50

51
```javascript { .api }
52
/**
53
 * Deep merge objects recursively
54
 * @param target - Target object to merge into
55
 * @param sources - Source objects to merge from
56
 * @returns Target object with merged properties
57
 */
58
function merge(target: any, ...sources: any[]): any;
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
import { merge } from 'xe-utils';
65

66
const config = { 
67
  api: { timeout: 5000 }, 
68
  features: { auth: true } 
69
};
70

71
const overrides = { 
72
  api: { retries: 3 }, 
73
  features: { logging: true } 
74
};
75

76
const merged = merge(config, overrides);
77
// Result: {
78
//   api: { timeout: 5000, retries: 3 },
79
//   features: { auth: true, logging: true }
80
// }
81
```
82

83
### Object Iteration
84

85
Iterate over object properties with support for custom contexts and both forward and reverse iteration.
86

87
```javascript { .api }
88
/**
89
 * Iterate over object properties
90
 * @param obj - Object to iterate over
91
 * @param iterate - Iterator function receiving (value, key, obj)
92
 * @param context - Optional context for iterator function
93
 */
94
function objectEach<T, C = any>(
95
  obj: T, 
96
  iterate: (this: C, value: any, key: string, obj: T) => void, 
97
  context?: C
98
): void;
99

100
/**
101
 * Reverse iterate over object properties
102
 * @param obj - Object to iterate over
103
 * @param iterate - Iterator function receiving (value, key, obj)
104
 * @param context - Optional context for iterator function
105
 */
106
function lastObjectEach<T, C = any>(
107
  obj: T, 
108
  iterate: (this: C, value: any, key: string, obj: T) => void, 
109
  context?: C
110
): void;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
import { objectEach, lastObjectEach } from 'xe-utils';
117

118
const user = { name: 'Alice', age: 25, city: 'NYC' };
119

120
// Forward iteration
121
objectEach(user, (value, key) => {
122
  console.log(`${key}: ${value}`);
123
});
124
// Output: name: Alice, age: 25, city: NYC
125

126
// Reverse iteration
127
lastObjectEach(user, (value, key) => {
128
  console.log(`${key}: ${value}`);
129
});
130
// Output: city: NYC, age: 25, name: Alice
131

132
// With context
133
const processor = {
134
  prefix: 'User',
135
  process(value, key) {
136
    console.log(`${this.prefix} ${key}: ${value}`);
137
  }
138
};
139

140
objectEach(user, processor.process, processor);
141
```
142

143
### Object Mapping
144

145
Transform object properties by applying a function to each value, creating a new object with the results.
146

147
```javascript { .api }
148
/**
149
 * Transform object values by applying iterator function
150
 * @param obj - Object to transform
151
 * @param iterate - Iterator function receiving (value, key, obj)
152
 * @param context - Optional context for iterator function
153
 * @returns New object with transformed values
154
 */
155
function objectMap<T, U, C = any>(
156
  obj: T, 
157
  iterate: (this: C, value: any, key: string, obj: T) => U, 
158
  context?: C
159
): { [key: string]: U };
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
import { objectMap } from 'xe-utils';
166

167
const numbers = { a: 1, b: 2, c: 3 };
168

169
// Transform values
170
const doubled = objectMap(numbers, (value) => value * 2);
171
// Result: { a: 2, b: 4, c: 6 }
172

173
// Transform with key information
174
const withKeys = objectMap(numbers, (value, key) => `${key}:${value}`);
175
// Result: { a: 'a:1', b: 'b:2', c: 'c:3' }
176

177
// Complex transformation
178
const users = { 
179
  user1: { name: 'Alice', age: 25 },
180
  user2: { name: 'Bob', age: 30 }
181
};
182

183
const userSummaries = objectMap(users, (user) => ({
184
  display: `${user.name} (${user.age})`,
185
  isAdult: user.age >= 18
186
}));
187
// Result: {
188
//   user1: { display: 'Alice (25)', isAdult: true },
189
//   user2: { display: 'Bob (30)', isAdult: true }
190
// }
191
```