Now, what is it?
If we take the Introductionary information that they provide,
Datehas been a long-standing pain point in ECMAScript. This is a proposal for
Temporal, a global
Object'that acts as a top-level namespace (likeMath
Why would you want to use it?
Well, there are a couple of reasons, such as:
- A more straightforward API to work with, both for time, as well as for dates
- Intuitive naming convention (
Zoned, depending on your need for timezone agnosticism or not)
- Ease of extracting time/date differences
- Interoperability between string and object formats
- Having to deal only with objects representing time or date
I believe that the new Temporal API provides us with a lot of utility that we previously lacked with JS Dates (which had to be compensated through with libraries such as moment.js or date-fns), and a much nicer way of working with a single, global date object (
Temporal API Data Types
An essential factor to take into consideration when working with Temporal API is that the data types that it provides are split into
Plain, which provides no timezone information
Zoned, which represents a date/time with information tied to a particular timezone; it is best suited for scenarios where you need to deal with a particular time within a particular timezone or if you need to format or do time/date difference/addition operations that take timezone-specific information into account
Some key data types that you will most likely work with:
This is one of the easiest to understand, as it represents a date and time object with no timezone information attached. You can create an instance simply by using the
This method creates a new
PlainDateTime object that uses the local timezone date & time unless no other timezone argument is passed to the method.
This object contains date information with no timezone data attached to it. It’s best suited for situations where there is no need for any time information.
PlainTime object represents a time that has no date or timezone information associated with it. Something to note about this data type is that there is no associated
Temporal.Now.plainTime method, as there cannot be a specific calendar context for a
ZonedDateTime object is a DateTime object packed with all timezone-related information, making it a perfect fit for cases where daylight savings time is required.
Instant object is similar to a
ZonedDateTime object in terms of representing a specific point in time. However, the difference is that it always contains UTC time and doesn’t refer to a particular calendar.
You also cannot pass an object to the
from method (which I will address in a second) for an
Instant; when you pass a string to the
from method, it must include timezone information.
PlainMonthDay is just like a
PlainDate; the only difference is that it does not include any year information. This is especially good when working with holidays (December 25th) that always fall on the same day.
Since this is a less common data type, the only ways to create it are with the
from method and the constructor.
PlainYearMonth object has the same utility, except that you’re dealing with Month & Year this time.
Cool Utility Methods That Temporal API Provides
subtract methods that make it incredibly easy.
Both functions have the same arguments, the only difference being that one adds while the other subtracts.
The easiest way to use these methods is by passing an object to the
subtract method with properties for the changes you want to make.
Another nice thing about these functions is they automatically deal with overflow.
For example, if you try to add one month to the date January 31st, that would result in the date February 31st, which doesn’t exist. By default, these results will be clamped to the nearest valid date so that they will return February 28th.
You can also disable this behavior, though, with a second options argument.
until methods will determine the distance in time between the current temporal date object and another temporal date object.
until methods are opposites of each other and take the same parameters.
The value returned by these methods is a
Temporal.Duration object. Also, you can pass an options argument to these methods to fine-tune how you want the duration calculated.
If you specify the
largestUnit then the duration will be determined using that unit as the largest value instead of the default value.
If you specify the
smallestUnit then the duration will be determined using that unit as the smallest value instead of the default value. This could result in rounding, which can be further customized with the
The last methods were a bit complex so let’s look at a really simple method.
equals method will return true if the two temporal date objects have the same fields. This is needed since, technically, any comparison done with
=== will be false unless the two objects are the same instance.
with method takes in an object of fields to overwrite on the current date object.
Also, something important to know about this method is that it does not actually change the temporal date object it is called on. Instead, it returns a new temporal date object with the changes applied.
Round is a method that returns a new date/time object rounded by a specific unit specified as the argument when called on a Temporal’- like object.
If you want to modify how the rounding is performed, you can instead pass an object that takes
The last method I want to discuss is the
compare method, which is available on the actual data type and not the object instance. This method is pretty much used to make sorting dates easier.
Other Data Types
So far, we’ve looked over the stars of the show, but there are also a couple more data types that, although you might not use as much, would be helpful to be aware of.
We have mentioned the
Duration data type a few times in this article. This data type represents a duration of time and is generally not something you will construct on your own but something you will deal with in the case of comparing dates. If you want, you can create a new Duration with the constructor or the
Similarly to the other aforementioned data types, you can also use the
round methods on durations. There are also a few additional helper methods that you will want to know:
TimeZone data type is used to represent a specific timezone. The most common scenarios you are likely to use it in would be with the
from method or with the
Temporal.Now.timeZone method, but you could also use the constructor.
The most crucial helper functions for this data type are
getPreviousTransition, which will return the date/time of the next/previous daylight savings time transition.
Calendar data type is the last data type you need to know and is probably the least useful. You can create a calendar using the
from method or if you want, use the constructor.
There are no important functions you need to know about this data type, as you’re unlikely to use it that often anyway.
Hopefully, after reading all this, you are excited to start trying out the temporal API. The only bad news is that this API is not yet available as it is still in proposal stage 3. There are currently no browsers with any support for this API, but you can use a polyfill if you want to start using this API today.
There are multiple polyfills available for this API, but I found the @js-temporal/polyfill to be a good one. Once you install this library, you can immediately start using the temporal API.