Why does the month argument range from 0 to 11 in JavaScript's Date constructor?

Question

The real answer to this question, is that it was copied from java.util.Date, which also had this quirk. Proof can be found on Twitter from Brendan Eich - the guy who originally implemented JavaScript:

https://twitter.com/BrendanEich/status/481939099138654209

https://twitter.com/BrendanEich/status/771006397886533632

Brendan also indicates that it was Ken Smith of Netscape who did the porting from Java.

https://twitter.com/BrendanEich/status/771006208949891072

This happened in 1995, and JDK 1.0 was in beta. It launched in 1996. In 1997, JDK 1.1 came out which deprecated the vast majority of functions on java.util.Date, moving them over to java.util.Calendar, but even that still had zero-based months. Developers fed-up with this created the Joda-Time library, which ultimately led to java.time package that's baked in to Java 8 (2014).

In short, it took 18 years for Java to get a correctly designed date/time API built-in, but JavaScript is still stuck back in the dark ages. We do indeed have excellent libraries like Luxon Moment.js, date-fns, js-joda, and others. But as of now, there is nothing more than Date built-in to the language. Hopefully this will change in the near future with the TC39 Temporal proposal.

It's an old (probably unfortunate, probably dying) tradition in the programming world, see the old standard (POSIX) localtime C function http://linux.die.net/man/3/localtime

Everything but the day of the month is 0 based, see here for a full list including ranges :)

It's actually the 1 based days that are the oddballs here...oddly enough. Why was this was done? I don't know...but probably happened the same meeting they got plastered and decided semicolons were optional.

In 2021 the real question is:

If Date was broken from JS day one, why after 26 years (25 if you count from zero) it's still here?

JS has a lot of bad parts/quirks and the worst thing is that some of them haven't been fixed in decades (fun fact: we're talking about Date dates).

But we're lucky, it looks like the end of Date is near.

Spoiler

new Temporal.PlainDate(2020, 11, 26); // => 2020-11-26

---

Temporal (proposal)

From the proposal introduction:

Date has been a long-standing pain point in ECMAScript. This is a proposal for Temporal, a global Object that acts as a top-level namespace (like Math), that brings a modern date/time API to the ECMAScript language.

It's based, as reported in docs, "on common use cases we examined" and has a multiple types for different kinds of data:

• Plain types do not have a timezone
• ZonedDateTime types have a timezone
• most types have a calendar
• many useful types: Absolute, DateTime, Date, Time, TimeZone, ...

This is a schema that outline various Temporal types and their relationships

You can read more about them in the available documentation and in the nice cookbook. Or explore current issues for open ones.

When Temporal will be available

Since March '21 it's in Stage 3/Draft (see TC39 stages reference). See TC39 March '21 slides.

Now it can be included in TypeScript soon, since their policy is:

When new features have reached stage 3, then they are ready for inclusion in TypeScript.

Probably for Node and major browsers we'll need to wait more.

Start experimenting today

In the meanwhile you can experiment with it using the Temporal polyfill.

npm install --save proposal-temporal

// temporal-test.js
const { Temporal } = require('proposal-temporal');

// or as an ES module
// import { Temporal } from 'proposal-temporal/lib/index.mjs';

// 11 means November now!
const date = new Temporal.PlainDate(2020, 11, 26); // => 2020-11-26

const sameDate = Temporal.PlainDate.from(
                {year: 2020, month: 11, day: 26}); // => 2020-11-26