0
# Date & Time
1

2
Comprehensive date manipulation, formatting, and calculation utilities. Supports custom formats, internationalization, and complex date arithmetic. Essential for applications dealing with date display, scheduling, and temporal calculations.
3

4
## Capabilities
5

6
### Date Creation & Parsing
7

8
Utilities for creating and parsing dates from various string formats.
9

10
```javascript { .api }
11
/**
12
 * Parse string to Date object with format support
13
 * @param str - Date string to parse
14
 * @param formats - Array of format strings to try
15
 * @returns Parsed Date object or Invalid Date
16
 */
17
function toStringDate(str: string, formats?: string[]): Date;
18

19
/**
20
 * Get current timestamp
21
 * @returns Current timestamp in milliseconds
22
 */
23
function now(): number;
24

25
/**
26
 * Convert date to timestamp
27
 * @param date - Date to convert
28
 * @param format - Optional format for parsing string dates
29
 * @returns Timestamp in milliseconds
30
 */
31
function timestamp(date?: Date | string | number, format?: string): number;
32
```
33

34
### Date Formatting
35

36
Advanced date formatting with extensive format options and customization.
37

38
```javascript { .api }
39
/**
40
 * Format date to string with custom format
41
 * @param date - Date to format
42
 * @param format - Format string (default: 'yyyy-MM-dd HH:mm:ss.SSS')
43
 * @param options - Formatting options
44
 * @returns Formatted date string
45
 */
46
function toDateString(
47
  date: Date | string | number, 
48
  format?: string, 
49
  options?: ToDateStringOptions
50
): string;
51

52
interface ToDateStringOptions {
53
  /** Starting day of week (0=Sunday, 1=Monday, etc.) */
54
  firstDay?: number;
55
  /** Custom format templates */
56
  formats?: {
57
    /** Quarter formatting */
58
    q?: string[] | ((value: any, match: string, date: Date) => string);
59
    /** Day of week formatting */
60
    E?: string[] | ((value: any, match: string, date: Date) => string);
61
  };
62
}
63
```
64

65
**Format Tokens:**
66
- `yyyy` - 4-digit year
67
- `yy` - 2-digit year  
68
- `MM` - 2-digit month (01-12)
69
- `M` - Month (1-12)
70
- `dd` - 2-digit day (01-31)
71
- `d` - Day (1-31)
72
- `HH` - 2-digit hour 24h (00-23)
73
- `H` - Hour 24h (0-23)
74
- `hh` - 2-digit hour 12h (01-12)
75
- `h` - Hour 12h (1-12)
76
- `mm` - 2-digit minutes (00-59)
77
- `m` - Minutes (0-59)
78
- `ss` - 2-digit seconds (00-59)
79
- `s` - Seconds (0-59)
80
- `SSS` - 3-digit milliseconds (000-999)
81
- `S` - Milliseconds (0-999)
82
- `a` - am/pm
83
- `A` - AM/PM
84
- `e` - Day of week (0-6)
85
- `E` - Day of week (customizable)
86
- `q` - Quarter (1-4, customizable)
87
- `D` - Day of year (1-366)
88
- `W` - Week of year (1-53)
89
- `Z` - Timezone offset (+08:00)
90
- `ZZ` - Timezone offset (+0800)
91

92
### Date Validation
93

94
Functions for validating dates and checking date properties.
95

96
```javascript { .api }
97
/**
98
 * Check if date is valid
99
 * @param date - Date to validate
100
 * @returns True if date is valid
101
 */
102
function isValidDate(date: any): boolean;
103

104
/**
105
 * Check if two dates are the same based on format
106
 * @param date1 - First date
107
 * @param date2 - Second date
108
 * @param format - Format to compare (default: full date)
109
 * @returns True if dates are same according to format
110
 */
111
function isDateSame(date1: Date, date2: Date, format?: string): boolean;
112
```
113

114
### Date Component Extraction
115

116
Functions for extracting specific components from dates.
117

118
```javascript { .api }
119
/**
120
 * Get year from date
121
 * @param date - Date to analyze
122
 * @param startDay - Starting day for year calculation
123
 * @returns Year number
124
 */
125
function getWhatYear(date: Date, startDay?: number): number;
126

127
/**
128
 * Get quarter from date (1-4)
129
 * @param date - Date to analyze
130
 * @param startDay - Starting day for quarter calculation
131
 * @returns Quarter number (1-4)
132
 */
133
function getWhatQuarter(date: Date, startDay?: number): number;
134

135
/**
136
 * Get month from date (0-11)
137
 * @param date - Date to analyze
138
 * @param startDay - Starting day for month calculation
139
 * @returns Month number (0-11)
140
 */
141
function getWhatMonth(date: Date, startDay?: number): number;
142

143
/**
144
 * Get week number from date
145
 * @param date - Date to analyze
146
 * @param startDay - Starting day of week (0=Sunday, 1=Monday)
147
 * @returns Week number
148
 */
149
function getWhatWeek(date: Date, startDay?: number): number;
150

151
/**
152
 * Get day from date
153
 * @param date - Date to analyze
154
 * @param startDay - Starting day for day calculation
155
 * @returns Day number
156
 */
157
function getWhatDay(date: Date, startDay?: number): number;
158
```
159

160
### Date Calculations
161

162
Advanced date calculation functions for various time periods.
163

164
```javascript { .api }
165
/**
166
 * Get day of year (1-366)
167
 * @param date - Date to analyze
168
 * @returns Day of year
169
 */
170
function getYearDay(date: Date): number;
171

172
/**
173
 * Get day of year alias
174
 * @param date - Date to analyze
175
 * @returns Day of year
176
 */
177
function getDayOfYear(date: Date): number;
178

179
/**
180
 * Get day of month (1-31)
181
 * @param date - Date to analyze
182
 * @returns Day of month
183
 */
184
function getDayOfMonth(date: Date): number;
185

186
/**
187
 * Get week of year (1-53)
188
 * @param date - Date to analyze
189
 * @param startDay - Starting day of week
190
 * @returns Week of year
191
 */
192
function getYearWeek(date: Date, startDay?: number): number;
193

194
/**
195
 * Get week of month (1-6)
196
 * @param date - Date to analyze
197
 * @param startDay - Starting day of week
198
 * @returns Week of month
199
 */
200
function getMonthWeek(date: Date, startDay?: number): number;
201
```
202

203
### Date Differences
204

205
Calculate differences between dates in various units.
206

207
```javascript { .api }
208
/**
209
 * Calculate difference between dates
210
 * @param startDate - Start date
211
 * @param endDate - End date
212
 * @param unit - Unit for difference calculation
213
 * @returns Difference in specified unit
214
 */
215
function getDateDiff(
216
  startDate: Date | string | number, 
217
  endDate: Date | string | number, 
218
  unit?: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
219
): number;
220
```
221

222
**Usage Examples:**
223

224
```javascript
225
import { 
226
  toDateString, toStringDate, now, getDateDiff, 
227
  getWhatQuarter, getYearDay, isValidDate 
228
} from 'xe-utils';
229

230
// Current time
231
const currentTime = now();
232
console.log(currentTime); // 1672531200000
233

234
// Date formatting
235
const date = new Date();
236
console.log(toDateString(date)); // '2023-01-01 00:00:00.000'
237
console.log(toDateString(date, 'yyyy-MM-dd')); // '2023-01-01'
238
console.log(toDateString(date, 'MM/dd/yyyy HH:mm')); // '01/01/2023 00:00'
239

240
// Custom formatting
241
console.log(toDateString(date, 'yyyy年MM月dd日')); // '2023年01月01日'
242
console.log(toDateString(date, 'EEEE, MMMM dd, yyyy')); // Custom day/month names
243

244
// Date parsing
245
const parsed1 = toStringDate('2023-01-15');
246
const parsed2 = toStringDate('01/15/2023', ['MM/dd/yyyy']);
247
const parsed3 = toStringDate('15-01-2023', ['dd-MM-yyyy']);
248

249
// Date validation
250
console.log(isValidDate(new Date())); // true
251
console.log(isValidDate('invalid')); // false
252
console.log(isValidDate(new Date('2023-02-30'))); // false
253

254
// Date components
255
const testDate = new Date('2023-06-15');
256
console.log(getWhatQuarter(testDate)); // 2 (Q2)
257
console.log(getYearDay(testDate)); // 166 (166th day of year)
258

259
// Date differences
260
const start = new Date('2023-01-01');
261
const end = new Date('2023-12-31');
262

263
console.log(getDateDiff(start, end, 'day')); // 364
264
console.log(getDateDiff(start, end, 'month')); // 11
265
console.log(getDateDiff(start, end, 'year')); // 0
266

267
// Relative date calculations
268
const birthday = new Date('1990-05-15');
269
const today = new Date();
270
const age = getDateDiff(birthday, today, 'year');
271
console.log(`Age: ${age} years`);
272

273
// Scheduling example
274
function getNextMeeting(lastMeeting, intervalDays) {
275
  const next = new Date(lastMeeting);
276
  next.setDate(next.getDate() + intervalDays);
277
  return toDateString(next, 'yyyy-MM-dd');
278
}
279

280
const lastMeeting = new Date('2023-06-01');
281
console.log(getNextMeeting(lastMeeting, 14)); // '2023-06-15'
282

283
// International formatting
284
const options = {
285
  formats: {
286
    E: ['日', '一', '二', '三', '四', '五', '六'],
287
    q: ['第一季度', '第二季度', '第三季度', '第四季度']
288
  }
289
};
290

291
console.log(toDateString(testDate, 'EEEE', options)); // Chinese day names
292
console.log(toDateString(testDate, 'q季度', options)); // Chinese quarter names
293
```