A battle of wits with datetime (part 2)

In part one, we explained several time representation notions and showed the problems that DST (Daylight Saving Time) can cause. To solve those issues, we researched the best libraries to use in the TypeScript ecosystem. We hope that the knowledge we gathered will help you avoid our mistakes.

How to handle datetime in the TypeScript ecosystem

Faced with the calculation of time, we usually use the following tools / libraries:

• Date: the most basic date tool

  • JS native type

  • Provides some very basic methods, can’t cope with date calculation and other work

     

• Moment.js: preferred for back-end projects. If you need to calculate the time before 1970 and after 2039 with DST, remember to calculate and append DST data

  • long-lived date tool library, well-functioning & API friendly

  • Provides perfect unit test to ensure accuracy of calculation

  • Requires that you generate timezone data before 1970 and after 2039

  • Weak automatic string parsing ability. You need to manually provide format when parsing.

  • Large data package, full version not suitable for front-end projects

  • Currently maintenance only

     

• Day.js: great choice if you don’t need to calculate across time zones / DST

  • Relatively popular date tool library, providing the API of Moment.js

  • Unlike Moment.js, provides immutable instance objects

  • When the system time zone has DST, it can lead to date calculation bugs and incorrect timezone conversions

     

• Spacetime: lightweight time tool, currently buggy but has potential

  • Excellent automatic string parsing ability

  • More accurate cross-time zone / DST conversion and calculation

  • DST data isn’t rigorous enough (for example, Sydney time zone is hardcoded to switch every April 3 and October 3, which is inaccurate)

  • Some other minor issues that can be worked around

     

• Other available date tools

  • fns-date

  • Luxon

The challenges of a Datetime Utils

Looking at these libraries, it looks like the TypeScript ecosystem is so poor that it can’t even provide a good datetime tool. In fact, neither the ecosystem nor its developers are to blame. The development of a tool that can be used with confidence with worldwide time zones while maintaining accuracy of the calculation is simply too difficult! How hard is it? Why not use our human brains to try to solve the following problems:

• 02/01/2021 means which day of the year?

• If it’s 6pm on October 30, 1999 in Sydney, what time will it be 12 hours later?

• Is it daylight saving time (AEDT) or standard time (AEST) on April 2, 2051 in Sydney?

• What is the UTC time in Sydney on April 3, 2021 at 2:30 AM?

• When we talk about adding a year, how many days do we mean exactly?

• What month and day is February 29, 2020 plus one year in 2021? How many days are added each year?

• When I ask about adding a month, how many days do I mean exactly?

• What day of the month is January 31 plus one month later? How many days are added per month?

• How many months are there between January 31 and February 15? Can you express it as a decimal?

   

These are only some of the tricky questions we encountered in our project. Several of them caused bugs due to calculation errors.

We can see that a Datetime Utils will encounter the following challenges:

• Date format

• Calendar

• Temporary adjustment

• DST

• Human habits

• Data updating

• Time zone data acquisition

• Test cases

   

After working on packaging our own Datetime utils, we have the following suggestions:

• Choose the right three-part library for the usage scenario. There is no “best,” only “best suited.”

• Centralize the management of time calculation logic in the application. There must be a team consensus on the time calculation logic within the project. Implement it uniformly and encapsulate it in one place to ensure consistent project behavior.

• Extensive coverage of unit tests (hard to practice, e.g. moment.js provides 160531 test cases).

• Use timestamp/UTC ISO transmission time, as most computing tools/libraries use similar logic to parse the time in this format so that no ambiguity will arise.

• Server-side calculations are better when it comes to time and time sensitive calculations.

Conclusion

DST is more prone to problems due to the irregular modification of "global variables," which caused a lot of software problems in the US in 2007 due to the updated DST rules.

Instead of adjusting clocks, it would be more practical to just adjust work hours to save energy. As a matter of fact, both the European Union and the United States have recently made proposals to abolish seasonal time changes.