Demystifying Temporal

Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API
Demystifying Temporal
A Deep Dive Into JavaScript’s
New Temporal API
Photo by Steve Johnson on Unsplash
Aditi Singh,
Igalia 2023

What is Temporal?
● Provides easy-to-use APIs for date and time computations
● Supports all time zones, including DST-safe arithmetic
● Provides features to support both common and complex use cases
● Strongly typed, Immutable
● Highly customizable and extensible

Why do we Need Temporal?
But…

Well… The Date API is terrible
1. No support for time zones other than the user’s local time and UTC
2. Parser behavior so unreliable it is unusable
3. Date object is mutable
4. DST behavior is unpredictable
5. Computation APIs are unwieldy
6. No support for non-Gregorian calendars
Original blog post: https://maggiepint.com/2017/04/09/ﬁxing-javascript-date-getting-started/

Types in Temporal
Photo by Lucian Alexe on Unsplash Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

Type Relationships

Temporal.Instant
● An exact moment in time*
● No time zone, no daylight saving
● No calendar, location
● Represented as elapsed nanoseconds since midnight UTC, Jan. 1, 1970
● Can be converted to other types
*disregarding leap seconds, though

Plain Types
● Temporal.PlainDateTime : “The meeting is at 16:00 on September 16th, 2023”
● Temporal.PlainDate : “The conference session on September 15th, 2023”
● Temporal.PlainTime : “The break is at 12:05”
● Temporal.PlainYearMonth : “The September 2023 meeting”
● Temporal.PlainMonthDay : “My birthday is December 15th”

Temporal.ZonedDateTime
● Like Temporal.Instant, an exact time
● But also with a calendar and time zone
● Correctly accounts for the time zone's daylight saving rules

Other Types
● Temporal.Duration
○ returned from other types' since() and until() methods
○ passed to their add() and subtract() methods
● Temporal.TimeZone
○ contains rules for UTC o set changes in a particular time zone
○ converts between Instant and PlainDateTime
● Temporal.Calendar
○ contains rules for converting dates from a particular calendar to ISO 8601
and back

Code Examples
Photo by Alexander Sinn on Unsplash

Get a Unix Timestamp in ms

Temporal.Now
● A namespace with functions that give you Temporal objects representing the current date, time, or
time zone
● Shortcuts if you are using the ISO 8601 calendar
○ Temporal.Now.instant()
○ Temporal.Now.timeZone()
○ Temporal.Now.zonedDateTime(calendar)
○ Temporal.Now.zonedDateTimeISO()
○ Temporal.Now.plainDateTime(calendar)
○ Temporal.Now.plainDateTimeISO()
○ Temporal.Now.plainDate(calendar)
○ Temporal.Now.plainDateISO()
○ Temporal.Now.plainTimeISO()

Properties
● Each Temporal object has read-only properties
● year, month, monthCode, day, hour, minute, second, millisecond, microsecond,
nanosecond, calendar, timeZone, offset, era, eraYear, dayOfWeek, dayOfYear,
weekOfYear, daysInWeek, daysInMonth, daysInYear, monthsInYear, inLeapYear,
hoursInDay, startOfDay, offsetNanoseconds, epochSeconds, epochMilliseconds,
epochMicroseconds, epochNanoseconds
● Only ZonedDateTime has all these at once, the others have subsets

Get a Unix Timestamp in ms
> Temporal.Now.instant().epochMilliseconds
1694534288427

Let’s mix things up a little,

What is the date one month from today?

Duration Arithmetic
● add()/subtract() take a Temporal.Duration and return a new
Temporal object of the same type, that far in the future or the past
● since()/until() take another Temporal object of the same type and
return a Temporal.Duration representing the amount of time that
elapsed from one to the other
●
> const monthLater = date.add({ months: 1 })

More About Calendars
● The standard machine calendar is the ISO 8601 calendar
● Human readable calendars are common in user-facing use cases
● Much of the world uses the Gregorian calendar
● Can print non-ISO dates with toLocaleString(), but that is not good
enough

What is the date one month from today?
> today = Temporal.PlainDate.from('2023-09-15')
> today.toLocaleString('en', { calendar: 'hebrew' });
'29 Elul 5783'
> nextMonth = today.add({ months: 1 });
> nextMonth.toLocaleString('en', { calendar: 'hebrew' });
'30 Tishri 5784' // WRONG!

The Right Way
const calendar = Temporal.Calendar.from(“hebrew”);
// choose the appropriate calendar
const today = Temporal.Now.plainDate(calendar);
console.log(today.add({ months: 1 }).toLocaleString('en', {
calendar: 'hebrew' }));
// 28 Tishri 5784

When will we be able to use Temporal?
● Temporal is at Stage 3 of TC39 proposal process
● Browser Implementations
○ V8
○ Spidermonkey
○ JSC
● Polyﬁlls
○ https://github.com/tc39/proposal-temporal/blob/main/README.md#polyﬁlls
● Playground:
○ Reference documentation: https://tc39.es/proposal-temporal/docs/index.html

QR Codes
Maggie Pint’s Blog Temporal Repository Temporal Docs

Thank You

Demystifying Temporal

More Related Content

Similar to Demystifying Temporal

More from Igalia

Recently uploaded

Demystifying Temporal