0
# Moment.js
1

2
Moment.js is a comprehensive JavaScript library for parsing, validating, manipulating, and formatting dates and times. It provides a rich API with over 100 locales, flexible parsing from various date formats, intuitive methods for date arithmetic, and powerful formatting capabilities.
3

4
**Note**: Moment.js is now in maintenance mode with the project status indicating it's a legacy library. New projects should consider alternatives like Day.js, date-fns, or Luxon.
5

6
## Package Information
7

8
- **Package Name**: moment
9
- **Package Type**: npm
10
- **Language**: JavaScript (with TypeScript definitions)
11
- **Installation**: `npm install moment`
12
- **CDN**: Available via CDN for browser usage
13

14
## Core Imports
15

16
ES6 Modules:
17
```javascript
18
import moment from "moment";
19
// or
20
import * as moment from "moment";
21
```
22

23
CommonJS:
24
```javascript
25
const moment = require("moment");
26
```
27

28
Browser (Global):
29
```html
30
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.30.1/moment.min.js"></script>
31
<script>
32
  // moment is available globally
33
</script>
34
```
35

36
## Basic Usage
37

38
```javascript
39
import moment from "moment";
40

41
// Create moments
42
const now = moment(); // Current date/time
43
const birthday = moment("1990-06-15"); // Parse date string
44
const specific = moment("2023-12-25 15:30", "YYYY-MM-DD HH:mm"); // With format
45

46
// Display
47
console.log(now.format()); // ISO 8601 string
48
console.log(birthday.format("MMMM Do, YYYY")); // "June 15th, 1990"
49
console.log(specific.fromNow()); // "2 months ago" (relative)
50

51
// Manipulate
52
const nextWeek = moment().add(7, "days");
53
const startOfDay = moment().startOf("day");
54
const endOfMonth = moment().endOf("month");
55

56
// Validate and compare
57
console.log(moment("invalid").isValid()); // false
58
console.log(birthday.isBefore(now)); // true
59
console.log(nextWeek.diff(now, "days")); // 7
60
```
61

62
## Architecture
63

64
Moment.js is built around several key components:
65

66
- **Core Constructor**: Main `moment()` function with multiple parsing modes and format support
67
- **Instance Methods**: Rich API for manipulation, formatting, and comparison on Moment instances
68
- **Static Methods**: Utility functions for creation, validation, and global configuration
69
- **Duration API**: Separate system for working with time durations and intervals
70
- **Locale System**: Internationalization support with 100+ locales and locale management
71
- **Timezone Handling**: UTC conversion, offset management, and timezone-aware operations
72

73
## Capabilities
74

75
### Moment Creation and Parsing
76

77
Core functionality for creating Moment instances from various input types including strings, dates, numbers, and arrays with flexible parsing options.
78

79
```javascript { .api }
80
// Main constructor (overloaded)
81
function moment(inp?: MomentInput, strict?: boolean): Moment;
82
function moment(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
83
function moment(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
84

85
// UTC constructor
86
function utc(inp?: MomentInput, strict?: boolean): Moment;
87
function utc(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
88
function utc(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
89

90
// Unix timestamp constructor
91
function unix(timestamp: number): Moment;
92

93
// Timezone-aware parsing
94
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;
95
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;
96
```
97

98
[Moment Creation and Parsing](./creation-parsing.md)
99

100
### Display and Formatting
101

102
Comprehensive formatting system with customizable format strings, relative time display, calendar formatting, and localized output.
103

104
```javascript { .api }
105
// Formatting methods on Moment instances
106
format(format?: string): string;
107
toString(): string;
108
toISOString(keepOffset?: boolean): string;
109
toJSON(): string;
110

111
// Relative time formatting
112
fromNow(withoutSuffix?: boolean): string;
113
toNow(withoutPrefix?: boolean): string;
114
from(inp: MomentInput, suffix?: boolean): string;
115
to(inp: MomentInput, suffix?: boolean): string;
116

117
// Calendar formatting
118
calendar(): string;
119
calendar(formats: CalendarSpec): string;
120
calendar(time: MomentInput, formats?: CalendarSpec): string;
121
```
122

123
[Display and Formatting](./display-formatting.md)
124

125
### Manipulation and Arithmetic
126

127
Date manipulation methods for adding/subtracting time, setting specific values, and navigating to specific time boundaries.
128

129
```javascript { .api }
130
// Arithmetic operations
131
add(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
132
subtract(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
133

134
// Boundary operations
135
startOf(unitOfTime: unitOfTime.StartOf): Moment;
136
endOf(unitOfTime: unitOfTime.StartOf): Moment;
137

138
// Timezone manipulation
139
local(keepLocalTime?: boolean): Moment;
140
utc(keepLocalTime?: boolean): Moment;
141
utcOffset(): number;
142
utcOffset(b: number|string, keepLocalTime?: boolean): Moment;
143
```
144

145
[Manipulation and Arithmetic](./manipulation.md)
146

147
### Getters and Setters
148

149
Dual-purpose methods for reading and writing specific date/time components with support for all time units.
150

151
```javascript { .api }
152
// Dual-purpose getter/setter methods
153
year(): number;
154
year(y: number): Moment;
155
month(): number;
156
month(M: number|string): Moment;
157
date(): number;
158
date(d: number): Moment;
159
hour(): number;
160
hour(h: number): Moment;
161
minute(): number;
162
minute(m: number): Moment;
163
second(): number;
164
second(s: number): Moment;
165

166
// Generic getter/setter
167
get(unit: unitOfTime.All): number;
168
set(unit: unitOfTime.All, value: number): Moment;
169
set(objectLiteral: MomentSetObject): Moment;
170
```
171

172
[Getters and Setters](./getters-setters.md)
173

174
### Comparison and Validation
175

176
Methods for comparing Moment instances, validating dates, and determining relationships between different time points.
177

178
```javascript { .api }
179
// Comparison methods
180
isBefore(inp?: MomentInput, granularity?: unitOfTime.StartOf): boolean;
181
isAfter(inp?: MomentInput, granularity?: unitOfTime.StartOf): boolean;
182
isSame(inp?: MomentInput, granularity?: unitOfTime.StartOf): boolean;
183
isSameOrAfter(inp?: MomentInput, granularity?: unitOfTime.StartOf): boolean;
184
isSameOrBefore(inp?: MomentInput, granularity?: unitOfTime.StartOf): boolean;
185
isBetween(a: MomentInput, b: MomentInput, granularity?: unitOfTime.StartOf, inclusivity?: "()" | "[)" | "(]" | "[]"): boolean;
186

187
// Difference calculation
188
diff(b: MomentInput, unitOfTime?: unitOfTime.Diff, precise?: boolean): number;
189

190
// Validation
191
isValid(): boolean;
192
invalidAt(): number;
193
```
194

195
[Comparison and Validation](./comparison-validation.md)
196

197
### Duration Operations
198

199
Complete duration system for working with time intervals, performing duration arithmetic, and formatting duration output.
200

201
```javascript { .api }
202
// Duration constructor
203
function duration(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
204

205
// Duration interface methods
206
interface Duration {
207
  clone(): Duration;
208
  humanize(argWithSuffix?: boolean, argThresholds?: argThresholdOpts): string;
209
  abs(): Duration;
210
  as(units: unitOfTime.Base): number;
211
  get(units: unitOfTime.Base): number;
212
  add(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
213
  subtract(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;
214
  toISOString(): string;
215
  isValid(): boolean;
216
}
217
```
218

219
[Duration Operations](./duration.md)
220

221
### Locale and Internationalization
222

223
Comprehensive internationalization system with support for 100+ locales, custom locale definitions, and locale-aware formatting.
224

225
```javascript { .api }
226
// Global locale management
227
function locale(language?: string): string;
228
function locale(language?: string[], definition?: LocaleSpecification): string;
229
function defineLocale(language: string, localeSpec: LocaleSpecification): Locale;
230
function updateLocale(language: string, localeSpec: LocaleSpecification): Locale;
231
function locales(): string[];
232

233
// Instance locale methods
234
locale(): string;
235
locale(locale: LocaleSpecifier): Moment;
236
localeData(): Locale;
237

238
// Display name functions
239
function months(): string[];
240
function monthsShort(): string[];
241
function weekdays(): string[];
242
function weekdaysShort(): string[];
243
function weekdaysMin(): string[];
244
```
245

246
[Locale and Internationalization](./locale.md)
247

248
### Utility and Static Methods
249

250
Static utility functions for type checking, min/max operations, normalization, and global configuration.
251

252
```javascript { .api }
253
// Type checking
254
function isMoment(m: any): m is Moment;
255
function isDate(m: any): m is Date;
256
function isDuration(d: any): d is Duration;
257

258
// Min/max operations
259
function min(moments: Moment[]): Moment;
260
function max(moments: Moment[]): Moment;
261

262
// Utility functions
263
function now(): number;
264
function invalid(flags?: MomentParsingFlagsOpt): Moment;
265
function normalizeUnits(unit: unitOfTime.All): string;
266

267
// Configuration
268
function relativeTimeThreshold(threshold: string): number | boolean;
269
function relativeTimeThreshold(threshold: string, limit: number): boolean;
270
function relativeTimeRounding(fn: (num: number) => number): boolean;
271
```
272

273
[Utility and Static Methods](./utilities.md)
274

275
## Core Types
276

277
```javascript { .api }
278
// Main interfaces
279
interface Moment {
280
  // Full interface definition available in sub-docs
281
}
282

283
interface Duration {
284
  // Full interface definition available in sub-docs  
285
}
286

287
interface Locale {
288
  // Full interface definition available in sub-docs
289
}
290

291
// Input types
292
type MomentInput = Moment | Date | string | number | (number | string)[] | MomentInputObject | void;
293
type LocaleSpecifier = string | Moment | Duration | string[] | boolean;
294
type MomentFormatSpecification = string | MomentBuiltinFormat | (string | MomentBuiltinFormat)[];
295

296
// Utility types
297
type numberlike = number | string;
298
type MomentBuiltinFormat = string;
299

300
// Configuration objects
301
interface MomentInputObject {
302
  years?: numberlike;
303
  months?: numberlike;
304
  days?: numberlike;
305
  hours?: numberlike;
306
  minutes?: numberlike;
307
  seconds?: numberlike;
308
  milliseconds?: numberlike;
309
}
310

311
interface MomentSetObject extends MomentInputObject {
312
  quarters?: numberlike;
313
  weeks?: numberlike;
314
  weekYear?: numberlike;
315
  isoWeekYear?: numberlike;
316
  dayOfYear?: numberlike;
317
  weekday?: numberlike;
318
  isoWeekday?: numberlike;
319
}
320
```
321

322
## Constants
323

324
```javascript { .api }
325
// Version information
326
const version: string; // "2.30.1"
327

328
// Built-in format constants
329
const ISO_8601: MomentBuiltinFormat;
330
const RFC_2822: MomentBuiltinFormat;
331

332
// HTML5 input formats
333
const HTML5_FMT: {
334
  DATETIME_LOCAL: string;        // "YYYY-MM-DDTHH:mm"
335
  DATETIME_LOCAL_SECONDS: string; // "YYYY-MM-DDTHH:mm:ss"
336
  DATETIME_LOCAL_MS: string;     // "YYYY-MM-DDTHH:mm:ss.SSS"
337
  DATE: string;                  // "YYYY-MM-DD"
338
  TIME: string;                  // "HH:mm"
339
  TIME_SECONDS: string;          // "HH:mm:ss"
340
  TIME_MS: string;              // "HH:mm:ss.SSS"
341
  WEEK: string;                 // "GGGG-[W]WW"
342
  MONTH: string;                // "YYYY-MM"
343
};
344

345
// Configuration
346
let defaultFormat: string;
347
let defaultFormatUtc: string;
348
let suppressDeprecationWarnings: boolean;
349
let deprecationHandler: ((name: string | void, msg: string) => void) | void;
350
```