What does the JavaScript Temporal.PlainDate method do

One of the latest additions to the ECMAScript 2024 standard is the Temporal.PlainDate method which is a part of the Temporal API in JavaScript.

The Temporal API is a new date and time API used for handling dates and times more effectively and predictably.

The PlainDate method itself is used to create a simple date object that includes only the year, month and day. It doesn't include time or timezone details, which can help to simplify your logic when you have no need for time measurements.

* Note that this method is relatively new to the standard and as such not all browsers will have full support just yet.

Initializing a PlainDate object

There are 2 ways to generate a Temporal.PlainDate object and the one that you choose really depends on the preferred format of your input. For example, you can instantiate a PlainDate object using its inherent constructor as such:

new Temporal.PlainDate(year, month, day, calendar);

In which case, you would need to supply the desired date parts as parameters. Note that the parameters will also need to be in the proper iso8601 format.

Note that the final 'calendar' parameter will be a string that identifies the type of built-in calendar to use, such as "gregory", "islamic" or "iso8601". This parameter is optional, and by default it will be set to "iso8601".

Also note that the 'month' parameter expects a value from 1-12, which is different than the traditional zero-based month indexing found in the older Date object.

You can also instantiate a PlainDate object by using the static from method that you can reference from PlainDate.

let _date = Temporal.PlainDate.from('2024-07-14');

The benefit of using the from method to instantiate the object instead of the constructor is that you can supply the input in various ways which might be more convenient for your particular use case. In the example above, if you already have a date string, then you won't need to do any kind of parsing in order to instantiate a new object.

Real world use cases

Here are a few examples of when this new method might be the most applicable to your projects.

Scheduling events - There are various types of events in which the time component bares little to no meaning, such as with public holidays or project deadlines and the following:

Birthdays - While birthdays do have birth "hours" typically, this isn't a metric that we observe often times.

Recurrence rules - Often seen with scheduled tasks or with recurring payment options, such as charging a client's credit card on the 1st of the month.

Historical dates - Typically, though not always, historical dates don't include time values.

Any situation where you intend to reference an entire day or a large portion of a day are an ideal candidate for PlainDate.

Benefits

Working with dates and times in any programming language can be a frustrating experience as you typically have to take physical location and time of year into account. For example, being in Los Angeles during Daylight Savings Time is different than being in Australia during DST, because not every region in Australia observes DST, and because you have to ensure that offset's are handled accordingly when they shift from day to day.

But very often, you don't technically care about the time component and you simply default to midnight of that day and then simply ignore that fact. While by itself this isn't a huge problem to have, it can potentially introduce system errors at some point down the line, particularly if a developer is unaware that a date is time agnostic.

The PlainDate object solves that issue by removing the possibility for a misunderstanding within a projects dev circle.

A great new addition to the specification to start using, though be mindful that support is probably still not widespread.