0
# Moment Creation and Parsing
1

2
Core functionality for creating Moment instances from various input types including strings, dates, numbers, and arrays with flexible parsing options and format specifications.
3

4
## Capabilities
5

6
### Main Constructor
7

8
The primary `moment()` function creates Moment instances from various input types with optional format specification and strict parsing.
9

10
```javascript { .api }
11
/**
12
 * Create a Moment instance from various input types
13
 * @param inp - Input to parse (string, Date, number, array, object, or another Moment)
14
 * @param strict - Enable strict parsing mode (disables fallback to native Date constructor)
15
 * @returns New Moment instance
16
 */
17
function moment(inp?: MomentInput, strict?: boolean): Moment;
18

19
/**
20
 * Create a Moment instance with format specification
21
 * @param inp - Input to parse
22
 * @param format - Format specification string or array of formats
23
 * @param strict - Enable strict parsing (format and input must match exactly)
24
 * @returns New Moment instance
25
 */
26
function moment(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
27

28
/**
29
 * Create a Moment instance with format and locale
30
 * @param inp - Input to parse
31
 * @param format - Format specification
32
 * @param language - Locale string for parsing
33
 * @param strict - Enable strict parsing
34
 * @returns New Moment instance
35
 */
36
function moment(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
37
```
38

39
**Usage Examples:**
40

41
```javascript
42
import moment from "moment";
43

44
// Current date/time
45
const now = moment();
46

47
// From string (ISO 8601)
48
const date1 = moment("2023-12-25");
49
const date2 = moment("2023-12-25T15:30:00Z");
50

51
// From Date object
52
const date3 = moment(new Date());
53

54
// From timestamp (milliseconds)
55
const date4 = moment(1640447400000);
56

57
// From array [year, month, day, hour, minute, second, millisecond]
58
const date5 = moment([2023, 11, 25, 15, 30, 0, 0]); // Note: month is 0-indexed
59

60
// From object
61
const date6 = moment({
62
  year: 2023,
63
  month: 11, // December (0-indexed)
64
  day: 25,
65
  hour: 15,
66
  minute: 30
67
});
68

69
// With format string
70
const date7 = moment("25/12/2023", "DD/MM/YYYY");
71
const date8 = moment("December 25, 2023 3:30 PM", "MMMM DD, YYYY h:mm A");
72

73
// Strict parsing
74
const date9 = moment("2023-12-25", "YYYY-MM-DD", true); // Must match exactly
75
const invalid = moment("2023/12/25", "YYYY-MM-DD", true); // Invalid because format doesn't match
76

77
// Multiple formats
78
const date10 = moment("2023-12-25", ["MM/DD/YYYY", "YYYY-MM-DD"]); // Tries both formats
79

80
// With locale
81
const date11 = moment("25 décembre 2023", "DD MMMM YYYY", "fr");
82
```
83

84
### UTC Constructor
85

86
Creates Moment instances in UTC mode, which affects display formatting and manipulation operations.
87

88
```javascript { .api }
89
/**
90
 * Create a UTC Moment instance
91
 * @param inp - Input to parse
92
 * @param strict - Enable strict parsing mode
93
 * @returns New Moment instance in UTC mode
94
 */
95
function utc(inp?: MomentInput, strict?: boolean): Moment;
96

97
/**
98
 * Create a UTC Moment instance with format specification
99
 * @param inp - Input to parse
100
 * @param format - Format specification
101
 * @param strict - Enable strict parsing
102
 * @returns New Moment instance in UTC mode
103
 */
104
function utc(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
105

106
/**
107
 * Create a UTC Moment instance with format and locale
108
 * @param inp - Input to parse
109
 * @param format - Format specification
110
 * @param language - Locale string
111
 * @param strict - Enable strict parsing
112
 * @returns New Moment instance in UTC mode
113
 */
114
function utc(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
import moment from "moment";
121

122
// Current UTC time
123
const nowUtc = moment.utc();
124

125
// Parse as UTC
126
const utcDate1 = moment.utc("2023-12-25T15:30:00");
127
const utcDate2 = moment.utc("25/12/2023 15:30", "DD/MM/YYYY HH:mm");
128

129
// Compare local vs UTC
130
const local = moment("2023-12-25T15:30:00");
131
const utc = moment.utc("2023-12-25T15:30:00");
132
console.log(local.format()); // Interprets as local time
133
console.log(utc.format());   // Interprets as UTC time
134
```
135

136
### Unix Timestamp Constructor
137

138
Creates Moment instances from Unix timestamps (seconds since epoch).
139

140
```javascript { .api }
141
/**
142
 * Create a Moment instance from Unix timestamp
143
 * @param timestamp - Unix timestamp in seconds (not milliseconds)
144
 * @returns New Moment instance
145
 */
146
function unix(timestamp: number): Moment;
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
import moment from "moment";
153

154
// From Unix timestamp (seconds)
155
const date1 = moment.unix(1640447400); // December 25, 2021 15:30:00 UTC
156

157
// Note: moment() constructor uses milliseconds, unix() uses seconds
158
const date2 = moment(1640447400000); // Same date using milliseconds
159
const date3 = moment.unix(1640447400); // Same date using seconds
160

161
console.log(date2.isSame(date3)); // true
162
```
163

164
### Parse Zone Constructor
165

166
Creates Moment instances while preserving the original timezone information from the input string.
167

168
```javascript { .api }
169
/**
170
 * Parse input while keeping original timezone offset
171
 * @param inp - Input to parse
172
 * @param format - Format specification
173
 * @param strict - Enable strict parsing
174
 * @returns New Moment instance with preserved timezone
175
 */
176
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
177

178
/**
179
 * Parse input with format and locale while keeping timezone
180
 * @param inp - Input to parse  
181
 * @param format - Format specification
182
 * @param language - Locale string
183
 * @param strict - Enable strict parsing
184
 * @returns New Moment instance with preserved timezone
185
 */
186
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
187
```
188

189
**Usage Examples:**
190

191
```javascript
192
import moment from "moment";
193

194
// Parse with timezone preservation
195
const date1 = moment.parseZone("2023-12-25T15:30:00-05:00");
196
const date2 = moment.parseZone("2023-12-25T15:30:00+03:00");
197

198
console.log(date1.format()); // Maintains -05:00 offset
199
console.log(date2.format()); // Maintains +03:00 offset
200

201
// Compare with regular parsing
202
const regular = moment("2023-12-25T15:30:00-05:00"); // Converts to local timezone
203
const parseZone = moment.parseZone("2023-12-25T15:30:00-05:00"); // Keeps original timezone
204

205
console.log(regular.utcOffset()); // Local timezone offset
206
console.log(parseZone.utcOffset()); // -300 (5 hours behind UTC)
207
```
208

209
### Clone Method
210

211
Creates a copy of an existing Moment instance.
212

213
```javascript { .api }
214
/**
215
 * Create a copy of this Moment instance
216
 * @returns New Moment instance with same date/time and settings
217
 */
218
clone(): Moment;
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
import moment from "moment";
225

226
const original = moment("2023-12-25");
227
const copy = original.clone();
228

229
// Modifications to copy don't affect original
230
copy.add(1, "day");
231
console.log(original.format("YYYY-MM-DD")); // "2023-12-25"
232
console.log(copy.format("YYYY-MM-DD"));     // "2023-12-26"
233
```
234

235
## Input Types and Validation
236

237
### Input Type Definition
238

239
```javascript { .api }
240
type MomentInput = Moment | Date | string | number | (number | string)[] | MomentInputObject | void;
241

242
interface MomentInputObject {
243
  years?: numberlike;
244
  year?: numberlike;
245
  y?: numberlike;
246
  months?: numberlike;
247
  month?: numberlike;
248
  M?: numberlike;
249
  days?: numberlike;
250
  day?: numberlike;
251
  d?: numberlike;
252
  dates?: numberlike;
253
  date?: numberlike;
254
  D?: numberlike;
255
  hours?: numberlike;
256
  hour?: numberlike;
257
  h?: numberlike;
258
  minutes?: numberlike;
259
  minute?: numberlike;
260
  m?: numberlike;
261
  seconds?: numberlike;
262
  second?: numberlike;
263
  s?: numberlike;
264
  milliseconds?: numberlike;
265
  millisecond?: numberlike;
266
  ms?: numberlike;
267
}
268

269
type numberlike = number | string;
270
```
271

272
### Format Specification
273

274
```javascript { .api }
275
type MomentFormatSpecification = string | MomentBuiltinFormat | (string | MomentBuiltinFormat)[];
276

277
interface MomentBuiltinFormat {
278
  __momentBuiltinFormatBrand: any;
279
}
280

281
// Built-in format constants
282
const ISO_8601: MomentBuiltinFormat;
283
const RFC_2822: MomentBuiltinFormat;
284
```
285

286
**Common Format Tokens:**
287

288
- `YYYY` - 4-digit year
289
- `MM` - 2-digit month (01-12)
290
- `DD` - 2-digit day (01-31)
291
- `HH` - 2-digit hour (00-23)
292
- `mm` - 2-digit minute (00-59)
293
- `ss` - 2-digit second (00-59)
294
- `SSS` - 3-digit millisecond (000-999)
295
- `Z` - UTC offset (+05:00)
296
- `A` - AM/PM
297
- `MMMM` - Full month name
298
- `MMM` - Short month name
299
- `dddd` - Full day name
300
- `ddd` - Short day name
301

302
### Invalid Moment Creation
303

304
```javascript { .api }
305
/**
306
 * Create an invalid Moment instance with optional parsing flags
307
 * @param flags - Optional parsing flags for debugging
308
 * @returns Invalid Moment instance
309
 */
310
function invalid(flags?: MomentParsingFlagsOpt): Moment;
311

312
interface MomentParsingFlagsOpt {
313
  empty?: boolean;
314
  unusedTokens?: string[];
315
  unusedInput?: string[];
316
  overflow?: number;
317
  charsLeftOver?: number;
318
  nullInput?: boolean;
319
  invalidMonth?: string;
320
  invalidFormat?: boolean;
321
  userInvalidated?: boolean;
322
  iso?: boolean;
323
  parsedDateParts?: any[];
324
  meridiem?: string;
325
}
326
```
327

328
**Usage Examples:**
329

330
```javascript
331
import moment from "moment";
332

333
// Create explicitly invalid moment
334
const invalid = moment.invalid();
335
console.log(invalid.isValid()); // false
336

337
// Invalid parsing results
338
const badDate = moment("not a date");
339
console.log(badDate.isValid()); // false
340
console.log(badDate.format()); // "Invalid date"
341

342
// Strict parsing with invalid input
343
const strictBad = moment("2023/12/25", "YYYY-MM-DD", true);
344
console.log(strictBad.isValid()); // false (format doesn't match)
345
```
346

347
## Parsing Validation
348

349
### Validation Methods
350

351
```javascript { .api }
352
/**
353
 * Check if this Moment instance represents a valid date
354
 * @returns true if valid, false otherwise
355
 */
356
isValid(): boolean;
357

358
/**
359
 * Get index of invalid field (for debugging parsing failures)
360
 * @returns Index of invalid field, or -1 if valid
361
 */
362
invalidAt(): number;
363

364
/**
365
 * Get creation metadata for this Moment instance
366
 * @returns Object containing input, format, locale, and other creation details
367
 */
368
creationData(): MomentCreationData;
369

370
/**
371
 * Get parsing flags for debugging parsing process
372
 * @returns Object containing parsing flags and error information
373
 */
374
parsingFlags(): MomentParsingFlags;
375

376
interface MomentCreationData {
377
  input: MomentInput;
378
  format?: MomentFormatSpecification;
379
  locale: Locale;
380
  isUTC: boolean;
381
  strict?: boolean;
382
}
383

384
interface MomentParsingFlags {
385
  empty: boolean;
386
  unusedTokens: string[];
387
  unusedInput: string[];
388
  overflow: number;
389
  charsLeftOver: number;
390
  nullInput: boolean;
391
  invalidMonth: string | void;
392
  invalidFormat: boolean;
393
  userInvalidated: boolean;
394
  iso: boolean;
395
  parsedDateParts: any[];
396
  meridiem: string | void;
397
}
398
```
399

400
**Usage Examples:**
401

402
```javascript
403
import moment from "moment";
404

405
const date = moment("2023-13-45"); // Invalid date
406
console.log(date.isValid()); // false
407
console.log(date.invalidAt()); // 1 (month field is invalid)
408

409
const flags = date.parsingFlags();
410
console.log(flags.overflow); // 1 (indicates month overflow)
411
console.log(flags.invalidMonth); // null
412

413
const creation = date.creationData();
414
console.log(creation.input); // "2023-13-45"
415
console.log(creation.isUTC); // false
416
```