0
# xe-utils
1

2
xe-utils is a comprehensive JavaScript utility library providing 150+ utility functions organized into 9 functional categories. It offers precise implementations for common programming tasks including object manipulation, array operations, string processing, date handling, number formatting, URL operations, and web-related functionality. The library is designed for maximum flexibility with tree-shaking support and works in both browser and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: xe-utils
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install xe-utils`
10

11
## Core Imports
12

13
```javascript
14
import XEUtils from 'xe-utils';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const XEUtils = require('xe-utils');
21
```
22

23
Individual function imports for tree-shaking:
24

25
```javascript
26
import each from 'xe-utils/each';
27
import toDateString from 'xe-utils/toDateString';
28
import isArray from 'xe-utils/isArray';
29
```
30

31
Category-based imports:
32

33
```javascript
34
import XEUtils from 'xe-utils/ctor';
35
import objectMethods from 'xe-utils/object';
36
import arrayMethods from 'xe-utils/array';
37
import baseMethods from 'xe-utils/base';
38
```
39

40
## Basic Usage
41

42
```javascript
43
import XEUtils from 'xe-utils';
44

45
// Object operations
46
const merged = XEUtils.merge({ a: 1 }, { b: 2 });
47
XEUtils.each(merged, (value, key) => console.log(key, value));
48

49
// Array operations
50
const users = [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }];
51
const names = XEUtils.pluck(users, 'name'); // ['Alice', 'Bob']
52
const adults = XEUtils.filter(users, user => user.age >= 18);
53

54
// Date formatting
55
const formatted = XEUtils.toDateString(new Date(), 'yyyy-MM-dd HH:mm:ss');
56

57
// Number operations with precision
58
const sum = XEUtils.add(0.1, 0.2); // Precise arithmetic: 0.3
59

60
// String operations
61
const camelCased = XEUtils.camelCase('hello-world'); // 'helloWorld'
62
```
63

64
## Architecture
65

66
xe-utils is built around several key design principles:
67

68
- **Modular Design**: Each function is a separate module that can be imported individually
69
- **Universal Compatibility**: Works in browser (IE7+) and Node.js environments
70
- **Type Safety**: Full TypeScript definitions with generic type preservation
71
- **Precision Arithmetic**: Special handling for floating-point precision issues
72
- **Extensible Core**: Mixin system allows adding custom utilities to the main object
73
- **Configuration**: Global configuration system for customizing behavior
74

75
## Capabilities
76

77
### Object Operations
78

79
Core functionality for object manipulation including property copying, merging, and iteration. Essential for data transformation and object utilities.
80

81
```javascript { .api }
82
function assign(target: any, ...sources: any[]): any;
83
function merge(target: any, ...sources: any[]): any;
84
function objectEach<T>(obj: T, iterate: (value: any, key: string) => void): void;
85
function objectMap<T, U>(obj: T, iterate: (value: any, key: string) => U): { [key: string]: U };
86
```
87

88
[Object Operations](./object-operations.md)
89

90
### Array Operations
91

92
Comprehensive array manipulation including functional programming methods, sorting, grouping, and tree operations. Perfect for data processing pipelines.
93

94
```javascript { .api }
95
function map<T, U>(array: T[], iterate: (item: T, index: number) => U): U[];
96
function filter<T>(array: T[], iterate: (item: T, index: number) => boolean): T[];
97
function uniq<T>(array: T[]): T[];
98
function sortBy<T>(array: T[], iterate: (item: T) => any): T[];
99
function chunk<T>(array: T[], size: number): T[][];
100
function flatten<T>(array: any[], deep?: boolean): T[];
101
function zip<T>(...arrays: T[][]): T[][];
102
function arrayEach<T>(array: T[], iterate: (item: T, index: number) => void): void;
103
function some<T>(array: T[], iterate: (item: T, index: number) => boolean): boolean;
104
function every<T>(array: T[], iterate: (item: T, index: number) => boolean): boolean;
105
```
106

107
[Array Operations](./array-operations.md)
108

109
### Type Checking & Validation
110

111
Comprehensive type checking utilities for runtime validation and type guards. Includes checks for all JavaScript types plus DOM and web API types.
112

113
```javascript { .api }
114
function isArray(val: any): val is any[];
115
function isObject(val: any): val is object;
116
function isString(val: any): val is string;
117
function isNumber(val: any): val is number;
118
function isFunction(val: any): val is Function;
119
function isEmpty(val: any): boolean;
120
function isEqual(val1: any, val2: any): boolean;
121
```
122

123
[Type Checking & Validation](./type-checking.md)
124

125
### Base Utilities
126

127
Core utilities for iteration, property access, cloning, and general object/array operations. Foundation methods used throughout applications.
128

129
```javascript { .api }
130
function each<T>(obj: T[] | T, iterate: (item: any, key: string | number) => void): void;
131
function clone<T>(obj: T, deep?: boolean): T;
132
function get(obj: any, path: string | string[], defaultValue?: any): any;
133
function set(obj: any, path: string | string[], value: any): void;
134
function keys(obj: any): string[];
135
function values(obj: any): any[];
136
function groupBy<T>(array: T[], iterate: (item: T) => string | number): { [key: string]: T[] };
137
function countBy<T>(array: T[], iterate: (item: T) => string | number): { [key: string]: number };
138
```
139

140
[Base Utilities](./base-utilities.md)
141

142
### Number Operations
143

144
Precise arithmetic operations and number formatting utilities. Solves JavaScript's floating-point precision issues and provides advanced number formatting.
145

146
```javascript { .api }
147
function add(num1: number, num2: number): number;
148
function subtract(num1: number, num2: number): number;
149
function multiply(num1: number, num2: number): number;
150
function divide(num1: number, num2: number): number;
151
function round(num: number, digits?: number): number;
152
function commafy(num: number | string, options?: CommafyOptions): string;
153
```
154

155
[Number Operations](./number-operations.md)
156

157
### Date & Time
158

159
Comprehensive date manipulation, formatting, and calculation utilities. Supports custom formats, internationalization, and complex date arithmetic.
160

161
```javascript { .api }
162
function toDateString(date: Date | string | number, format?: string, options?: ToDateStringOptions): string;
163
function toStringDate(str: string, formats?: string[]): Date;
164
function getDateDiff(startDate: Date, endDate: Date, unit?: DateUnit): number;
165
function isValidDate(date: any): boolean;
166
function getWhatWeek(date: Date, startDay?: number): number;
167
```
168

169
[Date & Time](./date-time.md)
170

171
### String Processing
172

173
String manipulation utilities including case conversion, padding, trimming, templating, and HTML escaping. Essential for text processing and formatting.
174

175
```javascript { .api }
176
function camelCase(str: string): string;
177
function kebabCase(str: string): string;
178
function padStart(str: string, targetLength: number, padString?: string): string;
179
function trim(str: string, chars?: string): string;
180
function template(str: string, obj: any, options?: TemplateOptions): string;
181
```
182

183
[String Processing](./string-processing.md)
184

185
### Function Utilities
186

187
Function manipulation utilities including binding, throttling, debouncing, and execution control. Perfect for event handling and performance optimization.
188

189
```javascript { .api }
190
function throttle<T extends (...args: any[]) => any>(fn: T, wait: number, options?: ThrottleOptions): T;
191
function debounce<T extends (...args: any[]) => any>(fn: T, wait: number, options?: DebounceOptions): T;
192
function once<T extends (...args: any[]) => any>(fn: T): T;
193
function bind(fn: Function, thisArg: any, ...args: any[]): Function;
194
```
195

196
[Function Utilities](./function-utilities.md)
197

198
### Web & Browser
199

200
Browser-specific utilities for URL parsing, cookie management, navigation, and browser detection. Essential for web development and browser compatibility.
201

202
```javascript { .api }
203
function parseUrl(url: string): ParsedUrl;
204
function serialize(obj: any, options?: SerializeOptions): string;
205
function cookie(name?: string, value?: any, options?: CookieOptions): any;
206
function browse(): BrowserInfo;
207
```
208

209
[Web & Browser](./web-browser.md)
210

211
## Core Types
212

213
```javascript { .api }
214
interface XEUtilsMethods {
215
  version: string;
216
  mixin(...methods: { [key: string]: any }[]): void;
217
  setup(options: any): any;
218
  getConfig(): any;
219

220
  // All utility methods are available as properties
221
  [key: string]: any;
222
}
223

224
interface CommafyOptions {
225
  separator?: string;
226
  fixed?: number;
227
  rounding?: boolean;
228
}
229

230
interface ToDateStringOptions {
231
  firstDay?: number;
232
  formats?: {
233
    q?: string[] | ((value: any, match: string, date: Date) => string);
234
    E?: string[] | ((value: any, match: string, date: Date) => string);
235
  };
236
}
237

238
interface TemplateOptions {
239
  tmplRE?: RegExp;
240
  escape?: boolean;
241
}
242

243
interface ThrottleOptions {
244
  leading?: boolean;
245
  trailing?: boolean;
246
}
247

248
interface DebounceOptions {
249
  leading?: boolean;
250
  trailing?: boolean;
251
}
252
```