https://blog.openreplay.com/is-it-time-for-the-javascript-temporal-api/

 
Navigate back to the homepageBLOG
Browse Repo
Copied
Browse Repo
Back

Is It Time for the JavaScript Temporal API?

 
[9k][craig-buck]
Craig Buckler, 
December 26th, 2021 * 3 min read
[vQTVLmqcLG][hero]
Copied

Date handling in JavaScript is ugly. The Date() object has not
changed since the first Java-inspired implementation in 1995. Java
scrapped it but Date() remained in JavaScript for backward browser
compatibility.

Issues with the Date() API include:

  * it's inelegant
  * it only supports UTC and the user's PC time
  * it doesn't support calendars other than Gregorian
  * string to date parsing is error-prone
  * Date objects are mutable -- for example:

Copy 
1const today = new Date();
2const tomorrow = new Date( today.setDate( today.getDate() + 1 ) );
3
4console.log( tomorrow );  // is tomorrow's date
5console.log( today );     // is also tomorrow's date!

Developers often turn to date libraries such as moment.js but it's a
74Kb payload and dates remain mutable. Modern alternatives such as
Day.js and date-fns may be better but should a library necessary when
your app has minimal date-handling requirements?

Browsers must continue to support Date() but a new Temporal static
global date object is at the Stage 3 Candidate Proposal in the TC39
standards approval process (the final stage before implementation).
The API addresses all the issues above and it's coming to the Chrome
browser soon. It's unlikely to have widespread implementation until
late 2022 so be wary that changes could occur.

Current Date and Time

Temporal.Now returns an object representing the current date and
time. Further methods provide information such as:

Copy 
1// time since the Unix epoch on 1 Janary, 1970 UTC
2Temporal.Now.instant().epochSeconds;
3Temporal.Now.instant().epochMilliseconds;
4
5// time in current location
6Temporal.Now.zonedDateTimeISO();
7
8// current time zone
9Temporal.Now.timeZone();
10
11// current time in another time zone
12Temporal.Now.zonedDateTimeISO('Europe/London');

Instant Dates and Times

Temporal.Instant returns an object representing a date and time to
the nearest nanosecond according to an ISO 8601 formatted string:

Temporal date time string

Copy 
1Temporal.Instant.from('2022-03-04T05:56:78.999999999+02:00[Europe/Berlin]');
2Temporal.Instant.from('2022-03-04T05:06+07:00');

You can also use an epoch value:

Copy 
1Temporal.Instant.fromEpochSeconds(1.0e8);

Zoned Dates and Times

Temporal.ZonedDateTime returns an object representing a timezone and
calendar-aware date/time at the instant an event occurred (or will
occur) in a particular global location, e.g.

Copy 
1new Temporal.ZonedDateTime(
2  1234567890000, // epoch nanoseconds
3  Temporal.TimeZone.from('Europe/London'), // timezone
4  Temporal.Calendar.from('iso8601') // default calendar
5);
6
7Temporal.ZonedDateTime.from('2025-09-05T02:55:00+02:00[Africa/Cairo]');
8
9Temporal.Instant('2022-08-05T20:06:13+05:45').toZonedDateTime('+05:45');
10
11Temporal.ZonedDateTime.from({
12  timeZone: 'America/New_York'
13  year: 2025,
14  month: 2,
15  day: 28,
16  hour: 10,
17  minute: 15,
18  second: 0,
19  millisecond: 0,
20  microsecond: 0,
21  nanosecond: 0
22});

Plain Dates and Times

Plain dates and times reference simpler calendar events which are not
associated with a specific time zone. The options include:

  * Temporal.PlainTime refers to a specific time, e.g. "the meeting
    occurs at 3pm every weekday":

    Copy 
    1// both are 15:00:00
    2new Temporal.PlainTime(15, 0, 0);
    3Temporal.PlainTime.from('15:00:00');

  * Temporal.PlainDate refers to a specific date, e.g. "your tax
    return is due by January 31, 2022":

    Copy 
    1// both are January 31, 2022
    2new Temporal.PlainDate(2022, 1, 31);
    3Temporal.PlainDate.from('2022-01-31');

  * Temporal.PlainDateTime refers to a date and time without a time
    zone:

    Copy 
    1// both are 4 May 2022 at 10:11am and 12 seconds
    2new Temporal.PlainDateTime(2022, 5, 4, 10, 11, 12);
    3Temporal.PlainDateTime.from('2022-05-04T10:11:12');

  * Temporal.PlainYearMonth refers to a date without a day, e.g. "the
    June 2022 schedule is ready":

    Copy 
    1// both are June 2022
    2new Temporal.PlainYearMonth(2022, 6);
    3Temporal.PlainYearMonth.from('2022-06');

  * Temporal.PlainMonthDay refers to a date without a year, e.g.
    "Star Wars day is on May 4":

    Copy 
    1// both are May 4
    2new Temporal.PlainMonthDay(5, 4);
    3Temporal.PlainMonthDay.from('05-04');

Open Source Session Replay

Debugging a web application in production may be challenging and
time-consuming. OpenReplay is an Open-source alternative to
FullStory, LogRocket and Hotjar. It allows you to monitor and replay
everything your users do and shows how your app behaves for every
issue. It's like having your browser's inspector open while looking
over your user's shoulder. OpenReplay is the only open-source
alternative currently available.

OpenReplay

Happy debugging, for modern frontend teams - Start monitoring your
web app for free.

Date and Time Values

You can extract specific date and time values from a Temporal object.
Assuming the following date and time:

Copy 
1const t1 = Temporal.ZonedDateTime.from('2022-12-07T03:24:30+02:00[Africa/Cairo]');

you can extract:

Copy 
1t1.year;        // returns 2022
2t1.month;       // 12
3t1.day;         // 7
4t1.hour;        // 3
5t1.minute;      // 24
6t1.second;      // 30
7t1.millisecond; // 0
8t1.microsecond; // 0
9t1.nanosecond;  // 0

Other useful properties include:

  * dayOfWeek -- returns 1 for Monday to 7 for Sunday
  * dayOfYear -- returns 1 to 365 or 366 on leap years
  * weekOfYear -- returns 1 to 52 or 53
  * daysInMonth -- returns 28, 29, 30, or 31
  * daysInYear -- returns 365 or 366
  * inLeapYear -- returns true for a leap year or false when not

Comparing and Sorting Dates and Times

All Temporal objects have a .compare(date1, date2) method which
returns:

  * 0 when date1 and date2 are the same
  * 1 when date1 occurs after date2, or
  * -1 when date1 occurs before date2

For example:

Copy 
1const
2  date1 = Temporal.Now,
3  date2 = Temporal.PlainDateTime.from('2022-05-04');
4
5Temporal.ZonedDateTime.compare(date1, date2);
6// returns 1 when May 4, 2022 arrives

You can pass the compare() method as an Array sort() function to
arrange dates into ascending chronological order (earliest to
latest):

Copy 
1const t = [
2
3    '2022-01-01T00:00:00+00:00[Europe/London]',
4    '2022-01-01T00:00:00+00:00[Africa/Cairo]',
5    '2022-01-01T00:00:00+00:00[America/New_York]'
6
7  ].map( d => Temporal.ZonedDateTime.from(d) )
8  .sort( Temporal.ZonedDateTime.compare );

Date and Time Calculations

All Temporal objects offer math methods to add(), subtract(), or
round() to a duration.

You can define a duration as a Temporal.Duration object which sets a
period in years, months, weeks, days, hours, minutes, seconds,
milliseconds, microseconds, and nanoseconds as well as a sign for -1
negative or 1 positive durations. However, all these methods accept a
duration-like value without the need to create a specific object.
Examples:

Copy 
1const t1 = Temporal.ZonedDateTime.from('2022-05-04T00:00:00+00:00[Europe/London]');
2
3// add 8 hours 59 minutes
4t1.add({ hours: 8, minutes: 59 }); // or
5t1.add(Temporal.Duration.from({ hours: 8, minutes: 59 }));
6
7// subtract 2 weeks
8t1.subtract({ weeks: 2 }); // or
9t1.add({ weeks: 2, sign: -1 });
10
11// round to nearest month
12t1.round({ smallestUnit: 'month' });

Plain dates and times can wrap so adding 24 hours to a PlainTime
returns a new Temporal object with an identical value.

The until() and since() methods return a Temporal.Duration object
describing the time until or since a specific date and time based on
the current date/time, e.g.

Copy 
1// months to t1
2t1.until().months;
3
4// days to t2
5t2.until().days;
6
7// weeks since t3
8t3.since().weeks;

The equals() method also determines whether two date/time values are
identical:

Copy 
1const
2  d1 = Temporal.PlainDate.from('2022-01-31');
3  d2 = Temporal.PlainDate.from('2023-01-31');
4
5d1.equals(d2); // false

Formatting Date and Time Strings

All Temporal objects have a string representation returned when using
the .toString() method, e.g. Temporal.Now.toString():

Copy 
12022-09-05T02:55:00+02:00[Europe/London]

This is not user friendly but the Internationalization API offers a
better alternative with localisation options. For example:

Copy 
1// define a date
2const d = new Temporal.PlainDate(2022, 3, 14);
3
4// US date format: 3/14/2022
5new Intl.DateTimeFormat('en-US').format(d);
6
7// UK date format: 14/03/2022
8new Intl.DateTimeFormat('en-GB').format(d);
9
10// Spanish long date format: miercoles, 14 de abril de 2022
11new Intl.DateTimeFormat('es-ES', { dateStyle: 'full' }).format(d);

This is not part of the Temporal API and there's no guarantee the
Intl (Internationalization) API will support Temporal as well as Date
objects -- although there would be a developer outcry if it didn't!

Temporal Time

We've accepted the dodgy Date() since day one but Temporal gives
JavaScript developers something to look forward to. The days of
resorting to a date library are nearly over.

For further information, refer to:

 1. The Temporal proposal
 2. The Temporal documentation
 3. The Temporal cookbook examples

Share:
Share the selected text
Share the selected text

More articles from OpenReplay Blog

 
[rSGpFqUdyh][hero]

React Architecture Patterns for Your Projects

Use these React patterns to structure your project and scale them as
much as you need

December 22nd, 2021 * 6 min read
 
[AIDtUlsOMn][hero]

5 Projects You Need to Build to Get Started with Reactjs

Learn the basics to start working with React through these 5
tutorials

December 20th, 2021 * 4 min read
(c) 2021 OpenReplay Blog
Link to $https://twitter.com/OpenReplayHQLink to $https://github.com/
openreplay/openreplayLink to $https://www.linkedin.com/company/
18257552