0
# Date Formatting and Processing
1

2
Comprehensive date formatting utilities with multiple output formats, timezone support, caching for performance, and timestamp conversion operations optimized for logging and data processing.
3

4
## Capabilities
5

6
### Log Date Formatting
7

8
Primary date formatting function for logging with millisecond precision and customizable separators.
9

10
```typescript { .api }
11
/**
12
 * Normal log format date with milliseconds
13
 * @param d - Date object, string separator, or null (defaults to current date)
14
 * @param msSep - Millisecond separator (defaults to '.')
15
 * @returns Formatted date string: "YYYY-MM-DD HH:mm:ss.SSS"
16
 */
17
function logDate(d?: Date | string | null, msSep?: string): string;
18

19
// Alias for logDate
20
const YYYYMMDDHHmmssSSS = logDate;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { logDate, YYYYMMDDHHmmssSSS } from "utility";
27

28
// Current timestamp with default formatting
29
const now = logDate();
30
// Result: "2025-09-06 12:05:30.123"
31

32
// Custom date with default formatting
33
const custom = logDate(new Date('2025-01-01T10:30:45.678Z'));
34
// Result: "2025-01-01 10:30:45.678"
35

36
// Custom millisecond separator
37
const customSep = logDate(new Date(), ',');
38
// Result: "2025-09-06 12:05:30,123"
39

40
// Using string parameter as separator
41
const strSep = logDate(':');
42
// Result: "2025-09-06 12:05:30:123"
43

44
// Using alias
45
const aliased = YYYYMMDDHHmmssSSS();
46
```
47

48
### Standard Date-Time Formatting
49

50
Date-time formatting without milliseconds with customizable separators.
51

52
```typescript { .api }
53
/**
54
 * YYYY-MM-DD HH:mm:ss format date string
55
 * @param d - Date, string, or number (defaults to current date)
56
 * @param options - Formatting options for separators
57
 * @returns Formatted date string
58
 */
59
function YYYYMMDDHHmmss(d?: Date | string | number, options?: YYYYMMDDHHmmssOptions): string;
60

61
interface YYYYMMDDHHmmssOptions {
62
  dateSep?: string;
63
  timeSep?: string;
64
}
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
import { YYYYMMDDHHmmss } from "utility";
71

72
// Default formatting
73
const standard = YYYYMMDDHHmmss();
74
// Result: "2025-09-06 12:05:30"
75

76
// Custom separators
77
const custom = YYYYMMDDHHmmss(new Date(), { dateSep: '/', timeSep: '.' });
78
// Result: "2025/09/06 12.05.30"
79

80
// From timestamp
81
const fromTs = YYYYMMDDHHmmss(1641024000000);
82
// Result: "2022-01-01 10:00:00"
83

84
// From ISO string
85
const fromIso = YYYYMMDDHHmmss('2025-12-25T15:30:45Z');
86
```
87

88
### Date-Only Formatting
89

90
Date-only formatting with customizable separators.
91

92
```typescript { .api }
93
/**
94
 * YYYY-MM-DD format date string
95
 * @param d - Date, string, or separator (defaults to current date)
96
 * @param sep - Date separator (defaults to '-')
97
 * @returns Formatted date string
98
 */
99
function YYYYMMDD(d?: Date | string, sep?: string): string;
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { YYYYMMDD } from "utility";
106

107
// Default formatting
108
const today = YYYYMMDD();
109
// Result: "2025-09-06"
110

111
// Custom separator
112
const slashDate = YYYYMMDD(new Date(), '/');
113
// Result: "2025/09/06"
114

115
// String parameter as separator
116
const dotDate = YYYYMMDD('.');
117
// Result: "2025.09.06"
118

119
// Specific date
120
const specific = YYYYMMDD(new Date('2025-12-25'));
121
// Result: "2025-12-25"
122
```
123

124
### Access Log Formatting
125

126
Apache/Nginx compatible access log date formatting with timezone information.
127

128
```typescript { .api }
129
/**
130
 * Access log format date with timezone
131
 * @param d - Date object (defaults to current date)
132
 * @returns Formatted date string: "DD/MMM/YYYY:HH:mm:ss +ZZZZ"
133
 */
134
function accessLogDate(d?: Date): string;
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
import { accessLogDate } from "utility";
141

142
// Current date in access log format
143
const logEntry = accessLogDate();
144
// Result: "06/Sep/2025:12:05:30 +0000"
145

146
// Specific date
147
const customLog = accessLogDate(new Date('2025-04-16T16:40:09Z'));
148
// Result: "16/Apr/2025:16:40:09 +0000"
149
```
150

151
### Timezone Operations
152

153
Timezone calculation and caching utilities.
154

155
```typescript { .api }
156
/**
157
 * Get timezone string with caching for performance
158
 * @param d - Date object
159
 * @returns Timezone string (e.g., "+0800", "-0500")
160
 */
161
function getTimezone(d: Date): string;
162

163
/**
164
 * Calculate timezone offset for a date
165
 * @param date - Date object
166
 * @returns Timezone string
167
 */
168
function resetTimezone(date: Date): string;
169
```
170

171
### Date Structure Operations
172

173
Date structure utilities for numeric date representations.
174

175
```typescript { .api }
176
/**
177
 * Return datetime structure object
178
 * @param now - Date object (defaults to current date)
179
 * @returns Date structure with numeric representations
180
 */
181
function datestruct(now?: Date): DateStruct;
182

183
interface DateStruct {
184
  YYYYMMDD: number;  // e.g., 20250906
185
  H: number;         // Hour (0-23)
186
}
187
```
188

189
**Usage Examples:**
190

191
```typescript
192
import { datestruct } from "utility";
193

194
// Current date structure
195
const current = datestruct();
196
// Result: { YYYYMMDD: 20250906, H: 12 }
197

198
// Specific date structure
199
const specific = datestruct(new Date('2025-12-25T15:30:00'));
200
// Result: { YYYYMMDD: 20251225, H: 15 }
201
```
202

203
### Timestamp Operations
204

205
Unix timestamp conversion and parsing utilities.
206

207
```typescript { .api }
208
/**
209
 * Get Unix timestamp in seconds or convert timestamp to Date
210
 * @param t - Optional timestamp to convert (10 or 13 digits)
211
 * @returns Current timestamp in seconds, or Date object if input provided
212
 */
213
function timestamp(t?: number | string): number | Date;
214

215
/**
216
 * Parse timestamp to Date object
217
 * @param t - Timestamp in seconds or milliseconds
218
 * @returns Date object
219
 */
220
function parseTimestamp(t: number | string): Date;
221

222
/**
223
 * Convert Date object to Unix timestamp in seconds
224
 * @param date - Date object to convert
225
 * @returns Unix timestamp in seconds
226
 */
227
function dateToUnixTimestamp(date: Date): number;
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
import { timestamp, parseTimestamp, dateToUnixTimestamp } from "utility";
234

235
// Get current timestamp
236
const now = timestamp();
237
// Result: 1693934730 (seconds since epoch)
238

239
// Convert 10-digit timestamp to Date
240
const date10 = timestamp(1693934730);
241
// Result: Date object
242

243
// Convert 13-digit timestamp to Date
244
const date13 = timestamp(1693934730123);
245
// Result: Date object
246

247
// Parse timestamp string
248
const parsed = parseTimestamp('1693934730');
249
// Result: Date object
250

251
// Convert Date to timestamp
252
const ts = dateToUnixTimestamp(new Date());
253
// Result: Unix timestamp in seconds
254
```
255

256
### Millisecond Formatting
257

258
Format dates from millisecond values with various output formats.
259

260
```typescript { .api }
261
/**
262
 * Provide milliseconds, return a formatted string
263
 * @param milliseconds - Milliseconds since epoch
264
 * @param format - Output format enum
265
 * @returns Formatted date string
266
 */
267
function getDateFromMilliseconds(milliseconds: number, format?: DateFormat): string;
268

269
enum DateFormat {
270
  DateTimeWithTimeZone = 'DateTimeWithTimeZone',
271
  DateTimeWithMilliSeconds = 'DateTimeWithMilliSeconds', 
272
  DateTimeWithSeconds = 'DateTimeWithSeconds',
273
  UnixTimestamp = 'UnixTimestamp',
274
}
275
```
276

277
**Usage Examples:**
278

279
```typescript
280
import { getDateFromMilliseconds, DateFormat } from "utility";
281

282
const ms = 1693934730123;
283

284
// Default format (YYYY-MM-DD)
285
const default = getDateFromMilliseconds(ms);
286
// Result: "2023-09-05"
287

288
// With timezone
289
const tz = getDateFromMilliseconds(ms, DateFormat.DateTimeWithTimeZone);
290
// Result: "05/Sep/2023:15:52:10 +0000"
291

292
// With milliseconds
293
const withMs = getDateFromMilliseconds(ms, DateFormat.DateTimeWithMilliSeconds);
294
// Result: "2023-09-05 15:52:10.123"
295

296
// Unix timestamp
297
const unix = getDateFromMilliseconds(ms, DateFormat.UnixTimestamp);
298
// Result: "1693934730"
299
```
300

301
### Date String Parts
302

303
Utility for getting date components as string arrays.
304

305
```typescript { .api }
306
/**
307
 * Return date string parts as array
308
 * @param d - Date object (defaults to current date)
309
 * @param onlyDate - Return only date parts (no time)
310
 * @returns Array of date/time parts as strings
311
 */
312
function getDateStringParts(d?: Date, onlyDate?: boolean): string[];
313
```
314

315
**Usage Examples:**
316

317
```typescript
318
import { getDateStringParts } from "utility";
319

320
// Full date-time parts
321
const fullParts = getDateStringParts(new Date('2025-09-06T12:05:30.123Z'));
322
// Result: ["2025", "09", "06", "12", "05", "30"]
323

324
// Date parts only
325
const dateParts = getDateStringParts(new Date(), true);
326
// Result: ["2025", "09", "06"]
327
```