Demystifying Temporal

The talk is about the upcoming major update in JS - Temporal proposal.

It'll cover fundamental principles that drive Temporal's functionality. It
would include essential concepts like immutable objects, extended range and
precision, and improved time zone support. Also, including details about all
different data types you can find in the API, when and how to use them,
essentially setting the stage for seamless integration of Temporal into your
codebase.


(c) CityJS India 2023
September 15 - 16, 2023
New Delhi, India
https://india.cityjsconf.org/
https://www.youtube.com/@cityjsconf

1. 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

2. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

3. Why do we Need Temporal?
But…
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

4. 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/fixing-javascript-date-getting-started/
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

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

6. Type Relationships
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

7. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

8. 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”

Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

9. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

10. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

11. Code Examples
Photo by Alexander Sinn on Unsplash

12. Get a Unix Timestamp in ms
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

13. 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()
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

14. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

15. Get a Unix Timestamp in ms
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API


> Temporal.Now.instant().epochMilliseconds
1694534288427

16. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

Let’s mix things up a little,

17. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

What is the date one month from today?
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

18. 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
●
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

> const monthLater = date.add({ months: 1 })

19. 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
Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

20. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

What is the date one month from today?

Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

> 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!

21. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

The Right Way

Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

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

22. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

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

23. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

QR Codes
Maggie Pint’s Blog Temporal Repository Temporal Docs

24. Demystifying Temporal: A Deep Dive Into JavaScript’s New Temporal API

Thank You