0
# Base Utilities
1

2
Core utilities for iteration, property access, cloning, and general object/array operations. These foundation methods are used throughout applications for common programming tasks like data manipulation, property access, and collection processing.
3

4
## Capabilities
5

6
### Universal Iteration
7

8
Universal iteration methods that work with both objects and arrays.
9

10
```javascript { .api }
11
/**
12
 * Universal iterator for objects and arrays
13
 * @param obj - Object or array to iterate
14
 * @param iterate - Iterator function receiving (value, key/index, obj)
15
 * @param context - Optional context for iterator
16
 */
17
function each<T, C = any>(
18
  obj: T[] | T, 
19
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
20
  context?: C
21
): void;
22

23
/**
24
 * For-of style iteration
25
 * @param obj - Object or array to iterate
26
 * @param iterate - Iterator function
27
 * @param context - Optional context
28
 */
29
function forOf<T, C = any>(
30
  obj: T[] | T, 
31
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
32
  context?: C
33
): void;
34

35
/**
36
 * Reverse iteration
37
 * @param obj - Object or array to iterate
38
 * @param iterate - Iterator function
39
 * @param context - Optional context
40
 */
41
function lastEach<T, C = any>(
42
  obj: T[] | T, 
43
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => void, 
44
  context?: C
45
): void;
46
```
47

48
### Property Access
49

50
Safe property access methods for nested object properties.
51

52
```javascript { .api }
53
/**
54
 * Get value at object path
55
 * @param obj - Object to access
56
 * @param path - Property path (string or array)
57
 * @param defaultValue - Default value if path doesn't exist
58
 * @returns Value at path or default value
59
 */
60
function get(obj: any, path: string | string[], defaultValue?: any): any;
61

62
/**
63
 * Set value at object path
64
 * @param obj - Object to modify
65
 * @param path - Property path (string or array)
66
 * @param value - Value to set
67
 * @returns Modified object
68
 */
69
function set(obj: any, path: string | string[], value: any): any;
70

71
/**
72
 * Check if object has property at path
73
 * @param obj - Object to check
74
 * @param path - Property path
75
 * @returns True if path exists
76
 */
77
function has(obj: any, path: string | string[]): boolean;
78

79
/**
80
 * Check if object has own property (not inherited)
81
 * @param obj - Object to check
82
 * @param key - Property key
83
 * @returns True if object has own property
84
 */
85
function hasOwnProp(obj: any, key: string): boolean;
86
```
87

88
### Object Property Operations
89

90
Methods for working with object keys, values, and entries.
91

92
```javascript { .api }
93
/**
94
 * Get object keys
95
 * @param obj - Object to get keys from
96
 * @returns Array of object keys
97
 */
98
function keys(obj: any): string[];
99

100
/**
101
 * Get object values
102
 * @param obj - Object to get values from
103
 * @returns Array of object values
104
 */
105
function values(obj: any): any[];
106

107
/**
108
 * Get object entries as key-value pairs
109
 * @param obj - Object to get entries from
110
 * @returns Array of [key, value] pairs
111
 */
112
function entries(obj: any): [string, any][];
113

114
/**
115
 * Pick specified properties from object
116
 * @param obj - Source object
117
 * @param keys - Keys to pick (array or multiple arguments)
118
 * @returns New object with picked properties
119
 */
120
function pick(obj: any, keys: string[] | string): any;
121

122
/**
123
 * Omit specified properties from object
124
 * @param obj - Source object
125
 * @param keys - Keys to omit (array or multiple arguments)
126
 * @returns New object without omitted properties
127
 */
128
function omit(obj: any, keys: string[] | string): any;
129
```
130

131
### Cloning & Copying
132

133
Object and array cloning utilities with support for both shallow and deep copying.
134

135
```javascript { .api }
136
/**
137
 * Clone object or array
138
 * @param obj - Object to clone
139
 * @param deep - Whether to perform deep clone (default: shallow)
140
 * @returns Cloned object
141
 */
142
function clone<T>(obj: T, deep?: boolean): T;
143

144
/**
145
 * Clear object or array properties
146
 * @param obj - Object to clear
147
 * @param defs - Default values to set
148
 * @param assigns - Additional values to assign
149
 * @returns Cleared object
150
 */
151
function clear(obj: any, defs?: any, assigns?: any): any;
152
```
153

154
### Collection Utilities
155

156
Utilities for working with collections (objects and arrays).
157

158
```javascript { .api }
159
/**
160
 * Get size/length of collection
161
 * @param obj - Collection to measure
162
 * @returns Size of collection
163
 */
164
function getSize(obj: any): number;
165

166
/**
167
 * Remove elements from collection
168
 * @param obj - Collection to modify
169
 * @param iterate - Predicate function for removal
170
 * @param context - Optional context
171
 * @returns Modified collection
172
 */
173
function remove<T, C = any>(
174
  obj: T[] | T, 
175
  iterate: (this: C, value: any, key: string | number, obj: T[] | T) => boolean, 
176
  context?: C
177
): T[] | T;
178

179
/**
180
 * Group array elements by computed key
181
 * @param array - Array to group
182
 * @param iterate - Function to compute grouping key
183
 * @param context - Optional context for iterator
184
 * @returns Object with grouped elements
185
 */
186
function groupBy<T, C = any>(
187
  array: T[], 
188
  iterate: (this: C, item: T) => string | number, 
189
  context?: C
190
): { [key: string]: T[] };
191

192
/**
193
 * Count array elements by computed key
194
 * @param array - Array to count
195
 * @param iterate - Function to compute counting key
196
 * @param context - Optional context for iterator
197
 * @returns Object with counts for each key
198
 */
199
function countBy<T, C = any>(
200
  array: T[], 
201
  iterate: (this: C, item: T) => string | number, 
202
  context?: C
203
): { [key: string]: number };
204
```
205

206
### Search & Index Operations
207

208
Methods for finding elements and their positions.
209

210
```javascript { .api }
211
/**
212
 * Find index of element using predicate
213
 * @param array - Array to search
214
 * @param iterate - Predicate function
215
 * @param context - Optional context
216
 * @returns Index of matching element or -1
217
 */
218
function findIndexOf<T, C = any>(
219
  array: T[], 
220
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
221
  context?: C
222
): number;
223

224
/**
225
 * Find last index of element using predicate
226
 * @param array - Array to search
227
 * @param iterate - Predicate function
228
 * @param context - Optional context
229
 * @returns Last index of matching element or -1
230
 */
231
function findLastIndexOf<T, C = any>(
232
  array: T[], 
233
  iterate: (this: C, item: T, index: number, array: T[]) => boolean, 
234
  context?: C
235
): number;
236

237
/**
238
 * Find index of element
239
 * @param array - Array to search
240
 * @param searchElement - Element to find
241
 * @param fromIndex - Starting index
242
 * @returns Index of element or -1
243
 */
244
function indexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;
245

246
/**
247
 * Find last index of element
248
 * @param array - Array to search
249
 * @param searchElement - Element to find
250
 * @param fromIndex - Starting index for reverse search
251
 * @returns Last index of element or -1
252
 */
253
function lastIndexOf<T>(array: T[], searchElement: T, fromIndex?: number): number;
254
```
255

256
### Array Access Helpers
257

258
Convenient methods for accessing array elements.
259

260
```javascript { .api }
261
/**
262
 * Get first element of array
263
 * @param array - Array to access
264
 * @returns First element or undefined
265
 */
266
function first<T>(array: T[]): T | undefined;
267

268
/**
269
 * Get last element of array
270
 * @param array - Array to access
271
 * @returns Last element or undefined
272
 */
273
function last<T>(array: T[]): T | undefined;
274
```
275

276
### Data Conversion
277

278
Methods for converting between different data formats.
279

280
```javascript { .api }
281
/**
282
 * Convert value to JSON string
283
 * @param obj - Value to convert
284
 * @returns JSON string representation
285
 */
286
function toStringJSON(obj: any): string;
287

288
/**
289
 * Convert value to JSON string (alias for toStringJSON)
290
 * @param obj - Value to convert
291
 * @returns JSON string representation
292
 */
293
function toJSONString(obj: any): string;
294
```
295

296
### Utility Generation
297

298
Utility functions for generating IDs and ranges.
299

300
```javascript { .api }
301
/**
302
 * Generate unique ID
303
 * @param prefix - Optional prefix for ID
304
 * @returns Unique ID string
305
 */
306
function uniqueId(prefix?: string): string;
307

308
/**
309
 * Generate range of numbers
310
 * @param start - Start number (or count if only parameter)
311
 * @param stop - End number
312
 * @param step - Step increment (default: 1)
313
 * @returns Array of numbers in range
314
 */
315
function range(start: number, stop?: number, step?: number): number[];
316
```
317

318
### Object Destructuring
319

320
Advanced object manipulation utilities.
321

322
```javascript { .api }
323
/**
324
 * Destructure object properties to destination
325
 * @param destination - Destination object
326
 * @param source - Source object
327
 * @param keys - Keys to destructure
328
 * @returns Destination object with destructured properties
329
 */
330
function destructuring(destination: any, source: any, ...keys: string[]): any;
331
```
332

333
**Usage Examples:**
334

335
```javascript
336
import { 
337
  each, get, set, has, clone, keys, values, 
338
  pick, omit, first, last, range, uniqueId 
339
} from 'xe-utils';
340

341
// Universal iteration
342
const data = { a: 1, b: 2, c: 3 };
343
each(data, (value, key) => {
344
  console.log(`${key}: ${value}`);
345
});
346

347
// Safe property access
348
const user = {
349
  profile: {
350
    personal: {
351
      name: 'Alice',
352
      age: 25
353
    }
354
  }
355
};
356

357
const name = get(user, 'profile.personal.name'); // 'Alice'
358
const email = get(user, 'profile.contact.email', 'No email'); // 'No email'
359

360
set(user, 'profile.contact.email', 'alice@example.com');
361
console.log(has(user, 'profile.contact.email')); // true
362

363
// Object manipulation
364
const original = { a: 1, b: 2, c: 3, d: 4 };
365
const picked = pick(original, ['a', 'c']); // { a: 1, c: 3 }
366
const omitted = omit(original, ['b', 'd']); // { a: 1, c: 3 }
367

368
console.log(keys(original)); // ['a', 'b', 'c', 'd']
369
console.log(values(original)); // [1, 2, 3, 4]
370

371
// Cloning
372
const deepObject = { user: { name: 'Alice', scores: [1, 2, 3] } };
373
const shallowCopy = clone(deepObject); // Shallow clone
374
const deepCopy = clone(deepObject, true); // Deep clone
375

376
// Array utilities
377
const numbers = [10, 20, 30, 40, 50];
378
console.log(first(numbers)); // 10
379
console.log(last(numbers)); // 50
380

381
// Generate utilities
382
const id1 = uniqueId(); // 'xe-123456'
383
const id2 = uniqueId('user-'); // 'user-123457'
384

385
const sequence = range(1, 6); // [1, 2, 3, 4, 5]
386
const steps = range(0, 10, 2); // [0, 2, 4, 6, 8]
387
```