Web Fundamentals: Avoid These JavaScript Date Object Pitfalls

The JavaScript Date object is notoriously broken. Until it is replaced with a modern alternative, frontend developers have to deal with its quirks. This post explains two quirks that every frontend developer should know even if you are using TypeScript and a date utility library like date-fns, zod, or Day.js.

tldr;

• new Date(null) returns the Unix epoch 1970-01-01T00:00:00.000Z ;
• When parsing a value to a date, consider manually checking whether value === null before passing the value to library like date-fns or zod
• Here is a repo with safe parse examples in (i) plain TypeScript, (ii) date-fns, and (iii) zod
• Avoid one gotcha when using zod to parse ISO 8601 Date strings

1. new Date(null) Unexpectedly Returns a Valid Date

In JavaScript, creating a Date by passing null to the constructor generates the Unix epoch zoned to your local timezone:

You might think to yourself, “I’m not worried about this because I use TypeScript!” And to an extent you’d be right. If you’re using TypeScript with “strict” set to true you’ll get a compilation error when creating a date with new Date(null).

However, there’s still a lingering problem. Because new Date(null) returns a valid date, libraries like zod coerce it to a Date even if your project uses TypeScript:

i. The Solution

So what is a frontend developer to do?

One solution is to filter null values before they get to date utilities. Here’s an example that wraps zod’s parsing method and filters null and undefined:

This is a repository I created with similar date parsing examples using plain TypeScript and date-fns. The repo also includes a Jest test suite if you want to check your own date parse methods.

2. Bonus: Watch Out For ‘YYYY-MM-DD’ Date Strings When Using Zod

Below is a short example showing one ‘gotcha’ when using zod to parse date strings:

The gotcha is that, unlike the date-fns parseISO method, zod does not automatically parse ISO Dates to local timezones.

The ECMAScript standard for parsing ISO 8601 Date strings (’2023-01-01’) is flawed:

• The ECMAScript standard provides that such strings default to UTC.
• However, the actual ISO 8601 standard specifies that absent a timezone such strings should default to local timezone.

Why does ECMAScript work this way? The t39 committee’s original specification was flawed and they couldn’t revise it before it became a ‘Web Reality’.

This issue is well known and date utility libraries like date-fns provide utility methods that automatically parse ISO Date strings to your local timezone. If you’re used to this convenience from your date utility library, just be warned that zod does not currently take care of this for you.

Finally, here is a cheat sheet for Date strings in JavaScript:

‍

Conclusion

Thank you for reading my post about Dates in JavaScript. To recap, watch out for null constructor values when dealing with Dates and pay special attention to date strings in this format: ‘YYYY-MM-DD’. Date utility libraries and schema validators are excellent tools, but there are still rough edges that warrant special attention.

‍