A calendar is a way to organize days, typically into periods of weeks, months, years, and eras. Most of the world uses the Gregorian calendar, but there are many other calendars in use, especially in religious and cultural contexts. By default, all calendar-aware Temporal objects use the ISO 8601 calendar system, which is based on the Gregorian calendar and defines additional week-numbering rules. Intl.supportedValuesOf() lists most of the calendars likely to be supported by browsers. Here we provide a brief overview of how calendar systems are formed to help you internalize what factors may vary between calendars.
There are three prominent periodic events on Earth: its rotation around the sun (365.242 days for one revolution), the moon's rotation around the Earth (29.53 days from new moon to new moon), and its rotation around its axis (24 hours from sunrise to sunrise). Every culture has the same measure of a "day", which is 24 hours. Occasional changes such as daylight saving time are not part of the calendar, but are part of the time zone's information.
- Some calendars primarily define one year as 365.242 days on average, by defining years to have 365 days, and adding an extra day, the leap day, about every 4 years. Then, the year may be further divided into parts called months. These calendars are called solar calendars. The Gregorian calendar and the Solar Hijri calendar are solar calendars.
- Some calendars primarily define one month as 29.5 days on average, by defining months to alternate between 29 and 30 days. Then, 12 months may be grouped into a year of 354 days. These calendars are called lunar calendars. The Islamic calendar is a lunar calendar. Because a lunar year is artificial and does not correlate with the season cycle, lunar calendars are generally rarer.
- Some calendars also primarily define months based on lunar cycles, like lunar calendars. Then, to compensate for the 11-day discrepancy with the solar year, an extra month, the leap month, is added about every 3 years. These calendars are called lunisolar calendars. The Hebrew calendar and the Chinese calendar are lunisolar calendars.
In Temporal, every date under one calendar system is uniquely identified by three components: year, month, and day. While year is typically a positive integer, it may also be zero or negative, and increases monotonically with time. The year 1 (or 0, if it exists) is known as the calendar epoch, and is arbitrary for each calendar. month is a positive integer that increments by 1 every time, starting at 1 and ending at date.monthsInYear, then resetting back to 1 as the year advances. day is also a positive integer, but it may not start at 1 or increment by 1 every time, because political changes may cause days to be skipped or repeated. But in general, day monotonically increases and resets as the month advances.
In addition to year, a year can also be uniquely identified by the combination of era and eraYear, for calendars that use eras. For example, the Gregorian calendar uses the era "CE" (Common Era) and "BCE" (Before Common Era), and the year -1 is the same as { era: "bce", eraYear: 1 }. era is a lowercase string, and eraYear is an arbitrary integer that may be zero or negative, or even decrease with time (usually for the oldest era).
Note:
Always use era and eraYear as a pair; don't use one property without also using the other. In addition, to avoid conflicts, don't combine year and era/eraYear when designating a year. Pick one year representation and use it consistently.
Be careful of the following incorrect assumptions about years:
- Don't assume that
era and eraYear are always present; they may be undefined.
- Don't assume that
era is a user-friendly string; use toLocaleString() to format your date instead.
- Don't assume that two
year values from different calendars are comparable; use the compare() static method instead.
- Don't assume that years have 365/366 days and 12 months; use
daysInYear and monthsInYear instead.
- Don't assume that leap years (
inLeapYear is true) have one extra day; they may have an extra month.
In addition to month, a month in a year can also be uniquely identified by the monthCode. monthCode usually maps to the month's name, but month does not. For example, in the case of lunisolar calendars, two months with the same monthCode, where one belongs to a leap year and the other one does not, will have different month values if they come after the leap month, due to the insertion of an extra month.
Note:
To avoid conflicts, don't combine month and monthCode when designating a month. Pick one month representation and use it consistently. month is more useful if you need the order of months in a year (e.g., when looping through the months), while monthCode is more useful if you need the name of the month (e.g., when storing birthdays).
Be careful of the following incorrect assumptions about months:
- Don't assume that
monthCode and month always correspond.
- Don't assume the number of days in a month; use
daysInMonth instead.
- Don't assume that
monthCode is a user-friendly string; use toLocaleString() to format your date instead.
- Generally, don't cache the name of months in an array or object. Even though
monthCode usually maps to the month's name within one calendar, we recommend always computing the month's name using, for example, date.toLocaleString("en-US", { calendar: date.calendarId, month: "long" }).
In addition to day (which is a month-based index), a day in a year can also be uniquely identified by the dayOfYear. dayOfYear is a positive integer that increments by 1 every time, starting at 1 and ending at date.daysInYear.
The concept of a "week" is not connected with any astronomical event, but is a cultural construct. While the most common length is 7 days, weeks can also have 4, 5, 6, 8, or more days — or even lack a fixed number of days altogether. To get the specific number of days of the week of a date, use the date's daysInWeek. Temporal identifies weeks by the combination of weekOfYear and yearOfWeek. weekOfYear is a positive integer that increments by 1 every time, starting at 1, then resetting back to 1 as the year advances. yearOfWeek is generally the same as year, but may be different at the start or end of each year, because one week may cross two years, and yearOfWeek picks one of the two years based on the calendar's rules.
Note:
Always use weekOfYear and yearOfWeek as a pair; don't use weekOfYear and year.
Be careful of the following incorrect assumptions about weeks:
- Don't assume that
weekOfYear and yearOfWeek are always present; they may be undefined.
- Don't assume that weeks are always 7 days long; use
daysInWeek instead.
- Note that the current
Temporal API does not support year-week dates, so you can't construct dates using these properties or serialize dates to year-week representations. They are only informational properties.