The Temporal API has made great progress since I wrote my article on it, The Temporal API Is Awesome.

The major milestones have been:

• The TC39 proposal has made a huge leap forward.
• Deno added first-party support for it in its 1.40 release.

What does this mean and why is this important?

Standards

Last time we explored this, we saw that, for the TC39 proposal to reach stage 4, there were two main outstanding issues:

• Acceptance of the IETF proposal to standardize string formats used for calendar and time zone annotations¹.
• Merging and reviewing normative changes.

There's only 1 issue left now! As of 2023-10-27² the IETF proposal has been accepted and is now a standard.

One down, one to go. And that last issue is mostly done, too.

Things are looking good over here :)

Deno

Deno has added first-class support for it³ in its 1.40.0 release. This is yet another major player in the JS world showing great interest in this API moving forward.

But it also adds immediate value to devs. The Temporal API was already available in Deno before 1.40.0 —since Deno uses V8 under the hood— behind a V8-specific feature flag: --v8-flags=--harmony-temporal. You could do this:

$ deno repl --v8-flags=--harmony-temporal
Deno 1.39.0
exit using ctrl+d, ctrl+c, or close()
> Temporal.Now.instant().toString()

"2024-02-10T16:52:04.823920896Z"

You can now do this:

$ deno repl --unstable-temporal
Deno 1.39.0
exit using ctrl+d, ctrl+c, or close()
> Temporal.Now.instant().toString()

"2024-02-10T16:52:51.623122944Z"

So we --unstable-temporal instead of --v8-flags=--harmony-temporal. Big deal.

But wait — there's more under the hood. Looking at the relevant PR⁴, the main changes to Deno's codebase are:

• It now has its own test suite for the Temporal API, which adds more stability to the API,
• and, most interesting to us, Deno now has .d.ts types for the Temporal API out of the box.

Alright, let's give this a try.

First, let's move on from the repl and write an actual file, deno.ts:

console.log('🕜', 'Instant as string')
const instantAsString: string = Temporal.Now.instant().toString()
console.log(instantAsString)

console.log()
console.log('🕞', 'Instant as Instant — inferred')
const instantAsInstantInferred = Temporal.Now.instant()
console.log('Run-time type:', Object.getPrototypeOf(instantAsInstantInferred))
console.log(instantAsInstantInferred)

console.log()
console.log('🕣', 'Instant as Instant — explicitly typed')
const instantAsInstant: Temporal.Instant = Temporal.Now.instant()
console.log('Run-time type:', Object.getPrototypeOf(instantAsInstant))
console.log(instantAsInstant)

console.log()
console.log('🕟', 'Instant as boolean — this should blow up')
const instantAsBoolean: boolean = Temporal.Now.instant()
console.log('Run-time type:', Object.getPrototypeOf(instantAsBoolean))
console.log(instantAsBoolean)

And let's run it with version 1.39.0

$ deno --version
deno 1.39.0 (release, x86_64-unknown-linux-gnu)
v8 12.0.267.8
typescript 5.3.3

$ deno run --v8-flags=--harmony-temporal deno.ts
🕜 Instant as string
2024-02-10T17:57:43.596431872Z

🕞 Instant as Instant — inferred
Run-time type: Object [Temporal.Instant] {}
Instant [Temporal.Instant] {}

🕣 Instant as Instant — explicitly typed
Run-time type: Object [Temporal.Instant] {}
Instant [Temporal.Instant] {}

🕟 Instant as boolean — this should blow up
Run-time type: Object [Temporal.Instant] {}
Instant [Temporal.Instant] {}

So far, so good. But take a look at the last test:

console.log('🕟', 'Instant as boolean — this should blow up')
const instantAsBoolean: boolean = Temporal.Now.instant()

Indeed, this should blow up. We're trying to assign an Instant to a boolean, but nothing's complaining about this. We actually need to deno check to type-check our code:

$ deno check deno.ts 
Check file:///.../deno.ts
error: TS2304 [ERROR]: Cannot find name 'Temporal'.
const instantAsString: string = Temporal.Now.instant().toString()
                                ~~~~~~~~
    at file:///.../deno.ts:2:33

TS2304 [ERROR]: Cannot find name 'Temporal'.
const instantAsInstantInferred = Temporal.Now.instant()
                                 ~~~~~~~~
    at file:///.../deno.ts:7:34

TS2503 [ERROR]: Cannot find namespace 'Temporal'.
const instantAsInstant: Temporal.Instant = Temporal.Now.instant()
                        ~~~~~~~~
    at file:///.../deno.ts:13:25

TS2304 [ERROR]: Cannot find name 'Temporal'.
const instantAsInstant: Temporal.Instant = Temporal.Now.instant()
                                           ~~~~~~~~
    at file:///.../deno.ts:13:44

TS2304 [ERROR]: Cannot find name 'Temporal'.
const instantAsBoolean: boolean = Temporal.Now.instant()
                                  ~~~~~~~~
    at file:///.../deno.ts:19:35

Found 5 errors.

Kaboom it went, but not only where we expected it to — everything blew up! Dang, this isn't very helpful. Let's try this again, but with 1.40.0 instead:

$ deno --version
deno 1.40.0 (release, x86_64-unknown-linux-gnu)
v8 12.1.285.6
typescript 5.3.3

$ deno --unstable-temporal run deno.ts
# Same output as with 1.39.0. as before. Omitting it here to reduce noise.

$ deno check deno.ts
Check file:///.../deno.ts
error: TS2322 [ERROR]: Type 'Instant' is not assignable to type 'boolean'.
const instantAsBoolean: boolean = Temporal.Now.instant()
      ~~~~~~~~~~~~~~~~
    at file:///.../deno.ts:19:7 

Now would you look at that! This is some actually useful feedback.

If you're curious, these types exist in tsc/dts/lib.deno.unstable.d.ts. And that file is over 4200 lines long! Sure comes in handy not to have to deal with that ourselves.

Final Words

I'm not usually so inclined to provide updates on things, as there are a bunch of newsletters out there already that do a great job at this; but I've grown a strong interest in the evolution of JavaScript over the years and am particularly passionate about some emerging html, css and js standards — specially understanding them in depth rather than just the "hey this is out there" or "this has happened".

I believe there's value in sharing these in-depth articles here, but am not sure about whether sending updates such as this one in the newsletter would be useful to you. Do you think it would be? Do you think it wouldn't? I'd love to hear your feedback! You can reach out to me at hey@taro.codes.

And if you liked what you read, subscribe to my newsletter :)

Next up in my list is an article exploring Web Components and paraphernalia (omg this stuff is awesome), a piece with some strong opinions on unit and integration testing and quite possible one on MongoDB.