Why is the new Date() function designed to increment the month by one more than whatever you input?

[ral325]

On the first page of the docs themselves, the site says:

format(new Date(2014, 1, 11), 'MM/dd/yyyy')
//=> '02/11/2014'

My question is... why?? When we input 1 for the month, why doesn't it stay as 1 when formatted, and why doesn't it produce January?? What am I missing?

[fturmel]

Very common mistake, the Date constructor takes a month index (0-11), so 1 does represent February.

console.log(new Date(2014, 1, 11).toString()) // Tue Feb 11 2014 00:00:00 GMT-0500 (Eastern Standard Time)

[ral325]

Sure, I mean I put that together. I guess my question was more meant to be "Why was the date constructor implemented that way?" It seems unnecessarily confusing.

[fturmel]

Some history

The decision goes back to the mid 90s with the first release of JavaScript. The Date object was modeled on Java 1.0's Date, per Wikipedia:

JavaScript was designed with Java's syntax and standard library in mind. In particular, all Java keywords were reserved in original JavaScript, JavaScript's standard library follows Java's naming conventions, and JavaScript's Math and Date objects are based on classes from Java 1.0.

There could be earlier precedents, but you can also see int tm_mon of struct tm in the ANSI C/C89 spec is 0-11, and is defined as "months since January". Java was built in C, so I'm sure there was some influence there.

Why?

Without defending the choice, because ultimately it probably was a mistake, it's most likely because these languages have arrays that start at index 0. In Java, enums are also by default assigned integer values that start at 0.

Just like week days, months are commonly converted back and forth between integers and string representation. It can be practical for the month value to match how you would naturally declare the data structure used for the conversion without having to mutate by one, or to insert an empty value at index 0 (which can create array length and iteration issues).

Illustrated in TypeScript:

enum Month {
  Jan,
  Feb,
  Mar,
  Apr,
  May,
  Jun,
  Jul,
  Aug,
  Sep,
  Oct,
  Nov,
  Dec,
}

const monthNames = [
  'Jan',
  'Feb',
  'Mar',
  'Apr',
  'May',
  'Jun',
  'Jul',
  'Aug',
  'Sep',
  'Oct',
  'Nov',
  'Dec',
]

const d = new Date(2021, Month.Dec, 26)
console.log(d.toString()) // Sun Dec 26 2021 00:00:00 GMT-0500 (Eastern Standard Time)

console.log(monthNames[d.getMonth()]) // Dec
console.log(Month[d.getMonth()]) // Dec

[ral325]

Wow amazing write up thank you!!!