Temporal/Joda concept breakdown

So, you really want to get off of the deprecated MomentJS library and you're excited about the new JavaScript proposal for Temporal . This article is designed to help you get familiar with the types for Temporal. Given that Temporal has not been accepted by browsers yet, I'm including the https://js-joda.github.io/js-joda/ types since they are 99.99% the same. Sure, the APIs for JsJoda are different, but you can use JsJoda while you wait for Temporal to be adopted.

LocalDate / PlainDate

( JsJoda docs | Temporal RFC docs )

represents a calendar date that is not associated with a particular time or time zone, e.g. August 24th, 2006.

Note, Temporal calls this PlainDate and Joda calls this LocalDate.

Stringified version:

"2022-04-28"

Real World examples:

• the day you were born
• the day you first tried icecream

ZonedDateTime

( JsJoda docs | Temporal RFC docs )

A date-time with a time-zone in the ISO-8601 calendar system, such as 2007-12-03T10:15:30+01:00 Europe/Paris.

Stringified version:

"2022-04-28T11:49:57.999-04:00[America/New_York]"

Real World Examples of ZonedDateTime:

• "When will we be landing in New York City?"
  • The person asking this likely wants to know what the time is relative to that offset (note timezones and offsets are different). Like does the asker want to know what time it is in New York City? Or do they want to know what time it is on their not-automatically-updating wrist watch since that's what is going to help them understand when they need to get sleep?
• "What time did your car get hit by another car?"
  • the insurance claims adjuster probably wants to know what time of the day it was in that area so they can determine what time of the day in Philadelphia has the most traffic accidents. It would be very hard to determine that if all you had was an Instant since Instants do not have timezone/offset information.

Instant

( JsJoda docs | Temporal RFC docs )

A Temporal.Instant is a single point in time (called "exact time"), with a precision in nanoseconds. No time zone or calendar information is present. To obtain local date/time units like year, month, day, or hour, a Temporal.Instant must be combined with a Temporal.TimeZone instance or a time zone string.

Stringified version:

"2022-04-28T15:49:57.999Z"

Real World Examples of Instant:

• Instant (in my experience) is pretty much exclusively used for sending a datetime string over HTTP. Some times you just don't need to store the offset, so that's why Instant is helpful.
  • If you do need to store the offset, ZonedDateTime since that will keep the offset.

LocalTime / PlainTime

( JsJoda docs | Temporal RFC docs )

represents a wall-clock time that is not associated with a particular date or time zone, e.g. 11:49 AM

Stringified version:

"11:49:57.999"

Real World Example:

• What you would answer with if a friend (who lives in the same town) asks "What time do you want to meet at the restaurant?"

Other types

Joda and Temporal both have many other types that you might need to help with conversions between the above concepts.

For instance, LocalDateTime (or Temporal's PlainDateTime) is a type I can't imagine every using in the real world. Why would I want to know the date and time but without the timezone? Because with LocalDateTime you don't even know if the time is relative to Zulu/GMT or if the moment occurred is in New York City.

Personally, I have found that when you need to know about these more rare types (like LocalDateTime or OffsetDateTime), you'll have end up naturally discovering them through StackOverflow or through the library docs when you're looking up how to accomplish something. For now, get familiar with the types above and the rest you'll learn as you go.

Visual Depictions

When you see the types here, you realize two things:

• The people behind the Temporal spec didn't like the word "Local"
• We should have had these terms at the start of Javascript!