Normative: Temporal stage 4 by ptomato · Pull Request #3759 · tc39/ecma262

ptomato · 2026-02-16T23:53:01Z

Stage 4 PR for Temporal.

Draft 2026-02-16: This currently includes only the changes to ECMA-262 that would need to be made if putting Temporal in a separate document. It does not yet include the Temporal Object itself. I've posted this for early feedback since I expect these parts will be what attracts the most review comments anyway. I'll update this later on to include the rest of the proposal.

2026-02-20: This now includes the rest of the Temporal proposal.

ptomato

Self-reviewing to point out places where you might particularly have questions/comments and places where the one-document approach would simplify things.

We may want to additionally look at https://tc39.es/ecma262/#sec-date-time-string-format. Most likely this can be simplified with Temporal stuff, or turned into a grammar using the building blocks from Temporal's RFC9557 grammar.

spec.html

ptomato · 2026-02-17T00:04:08Z

spec.html

          In time zone aware implementations, a primary time zone identifier is a Zone name, and a non-primary time zone identifier is a Link name, respectively, in the IANA Time Zone Database except as specifically overridden by AvailableNamedTimeZoneIdentifiers as specified in the ECMA-402 specification.
          Implementations that do not support the entire IANA Time Zone Database are still recommended to use IANA Time Zone Database names as identifiers to represent time zones.
        </p>
+        <p>These identifiers are described by the following grammar.</p>


This grammar would be deduplicated into Temporal's RFC 9557 grammar if we go the same-document route.

ptomato · 2026-02-17T00:05:42Z

spec.html

+          UTC offsets that represent offset time zone identifiers, or that are intended for interoperability with ISO 8601, use only hours and minutes and are specified by |UTCOffset[~SubMinutePrecision]|.
+          UTC offsets that represent the offset of a named time zone can be more precise, and are specified by |UTCOffset[+SubMinutePrecision]|.
        </p>
+        <p>These formats are described by the following grammar.</p>


This grammar would also be deduplicated into Temporal's RFC 9557 grammar.

ptomato · 2026-02-17T00:08:37Z

spec.html

+        </emu-clause>
+      </emu-clause>
+
+      <emu-clause id="sec-iso-date-records">


These three sections on ISO Date Records, Time Records, and ISO Date-Time Records would go into a Temporal section if we put Temporal in the same document. But they're needed in ECMA-262 for AOs like GetNamedTimeZoneEpochNanoseconds and GetNamedTimeZoneOffsetNanoseconds.

spec.html

ptomato · 2026-02-17T00:29:38Z

As for the "esmeta yet phrases detection" job there seem to be two main issues:

ESMeta seems not to ignore steps beginning with "NOTE:"
ESMeta seems not to understand "an integer in the inclusive interval from X to Y"

I'm puzzled about that since both constructions seem to be used elsewhere in the spec. Am I doing something wrong here or do I need to add these manually to a skip list?

Once those are resolved I can dig into the remaining items turned up by ESMeta.

This commit makes changes to ECMA-262 AOs that are needed for Temporal regardless of whether it lands in a separate document.

This adds the rest of the Temporal proposal, organizing it into the "Numbers and Dates" section. Some of the sections added in the previous commit are moved into Temporal sections. The existing section on "Time Zone Identifiers", used both by Date and Temporal, is moved into its own section under "Numbers and Dates". Most of the proposal is kept in separate temporal/*.emu files, included with `<emu-import>` tags. This is an arbitrary choice and can be done differently if so desired.

ptomato

More self-review with comments on things you may want to look at. I'm planning to join the editor call on Monday 23 Feb, so we can talk through this PR live.

Additional comments not tied to a particular place in the PR:

We may want to refactor/rewrite 21.4.1.32 Date Time String Format to use the new grammar.
Probably one of the main things to talk about in the editor call is "how to structure the sections". I've put most everything as subsections of the "Numbers and Dates" section. Maybe it makes sense to split that up into two toplevel sections, "Numbers" and "Dates"? Here's what the second-level outline looks like now:

ptomato · 2026-02-20T19:08:22Z

temporal/abstractops.emu

+    <emu-clause id="sec-canonicalizeuvalue" type="abstract operation">
+      <h1>
+        CanonicalizeUValue (
+          _ukey_: a Unicode locale extension sequence key defined in <a href="https://unicode.org/reports/tr35/#Key_And_Type_Definitions_">Unicode Technical Standard #35 Part 1 Core Section 3.6.1 Key and Type Definitions</a>,
+          _uvalue_: a String,
+        ): a String
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>The returned String is the canonical and case-regularized form of _uvalue_ as a value of _ukey_.</dd>
+      </dl>
+      <emu-alg>
+        1. Let _lowerValue_ be the ASCII-lowercase of _uvalue_.
+        1. Let _canonicalized_ be the String value resulting from canonicalizing _lowerValue_ as a value of key _ukey_ per <a href="https://unicode.org/reports/tr35/#processing-localeids">Unicode Technical Standard #35 Part 1 Core, Annex C LocaleId Canonicalization Section 5 Canonicalizing Syntax, Processing LocaleIds</a>.
+        1. NOTE: It is recommended that implementations use the 'u' extension data in <code>common/bcp47</code> provided by the Common Locale Data Repository (available at <a href="https://cldr.unicode.org/">https://cldr.unicode.org/</a>).
+        1. Return _canonicalized_.
+      </emu-alg>
+    </emu-clause>


CanonicalizeUValue is debatable whether it should be included here. It's moved from ECMA-402 into here, but is only used for CanonicalizeCalendar, to show that if the implementation supports multiple calendars, their identifiers should be canonicalized in the way specified in UTS#35.

An alternative would be to override CanonicalizeCalendar in ECMA-402 instead, and provide a skeleton CanonicalizeCalendar here which does something like "If id is some case-insensitive form of "iso8601", return "iso8601", else throw".

I've included what this would look like, in an additional commit named "(optional) Change approach for specifying CanonicalizeCalendar".

spec.html

temporal/abstractops.emu

Jack-Works · 2026-02-21T17:07:53Z

Hi! I'm implementing Temporal in engine262. I'd like to know if all changes made here will be synced to the Temporal repo, or if the repo will be stale and all new changes will be made here.

ptomato · 2026-02-23T17:23:16Z

I'm not planning to sync changes back to the Temporal repo, unless someone really wants that.

github-actions · 2026-02-23T22:21:07Z

The rendered spec for this PR is available as a single page at https://tc39.es/ecma262/pr/3759 and as multiple pages at https://tc39.es/ecma262/pr/3759/multipage .

bakkot · 2026-02-23T23:20:22Z

Notes from editor call:

let's put Dates+Temporal in their own section, and reduce the current Numbers and Dates section to just Number/BigInt/Math
Date.parse is no longer strictly a simplification of ISO 8601 as 8601 no longer allows "24" for hours; as this PR is updating the referenced version of 8601, we should add some wording to that effect
GetOption is overkill, at least for base64, and it can probably be inlined into all of its callsites in Temporal
[[EpochNanoseconds]] should be a mathematical value instead of a BigInt, both as a matter of convention and because implementations are likely to use a different type than their internal bigint type
the algorithm in AddTimeDurationToEpochNanoseconds is written with the values backwards from the order in which they appear as parameters, which is confusing even though it doesn't actually affect anything
don't worry about esmeta for now
we are undecided on how to handle CanonicalizeCalendar (personally I am fine with the current approach, or for doing something like we do for timezones, as in, we can say here's the implementation if you only support iso8601, otherwise you must use the implementation from 402)

Split the "Numbers and Dates" section into "Numbers and Mathematical Functions" and "Dates and Temporal".

…rmat 24:00 is not supported in the current (2019) edition of ISO 8601, unlike the 2004 edition which we previously cited in the bibliography. Also update the note about a standard for time zone names not existing; this exists now with RFC 9557.

temporal/grammar.emu

The desired convention going forward ("Stop Coercing Things") is too different from the ECMA-402 options conventions, so it doesn't make sense to share GetOption with ECMA-402. The reversion of base64 changes can be squashed with "Normative: Temporal stage 4, part 1"

Minor editorial point, reads better when the operands are in the same order as the AO's arguments.

[[EpochNanoseconds]] should be a mathematical value instead of a BigInt, both as a matter of convention and because implementations are likely to use a different type than their internal BigInt type. Bikeshedding welcome on the type name. I went with "An epoch nanoseconds value", but "an exact time", "an epoch time", etc., are possibilities.

Can be squashed with "Normative: Temporal stage 4, part 2"

…rings Instead of |DateYear| and |DateDay|. Naming the parse node one level down from the goal may make it easier to understand what needs to be implemented.

As discussed during the editors meeting, this commit shows what it'd look like if we changed AvailableCalendars and CanonicalizeCalendar to work more like time zones, where we give the specification assuming that only the minimum is supported. CanonicalizeUValue would then stay in ECMA-402 where it originated, and ECMA-402 would gain an override of CanonicalizeCalendar (it already has one for AvailableCalendars).

ptomato · 2026-02-25T18:36:24Z

I've added commits addressing all the things we discussed in Monday's editor call. (To make it easy to see what changed, I'll refrain from squashing or force-pushing until it comes time to merge.)

I tried to request another preview but the job failed with a 403 on npm ci, so not sure what's going on there.

ptomato · 2026-02-25T18:36:24Z

I've added commits addressing all the things we discussed in Monday's editor call. (To make it easy to see what changed, I'll refrain from squashing or force-pushing until it comes time to merge.)

I tried to request another preview but the job failed with a 403 on npm ci, so not sure what's going on there.

…ndar See the commit named "(optional) Change approach for specifying CanonicalizeCalendar" in tc39/ecma262#3759 - pending discussion with the ECMA-262 editors.

See the commit named "(review) Express epoch nanoseconds in mathematical values" in tc39/ecma262#3759 - this change is based on feedback from the ECMA-262 editors that epoch time should be specified as mathematical values.

gibson042

Partial review, mostly just spec.html.

@bakkot Note that ISO 8601 does allow "24" for hours again as of 2022.

spec.html

gibson042 · 2026-02-26T19:29:02Z

spec.html

          <dl class="header">
            <dt>description</dt>
-            <dd>The return value indicates whether _offsetString_ conforms to the grammar given by |UTCOffset|.</dd>
+            <dd>The return value indicates whether _offsetString_ conforms to the grammar given by |UTCOffset[~SubMinutePrecision]|.</dd>


This restriction is technically a breaking change, although I think we failed to find any implementation for which SystemTimeZoneIdentifier returned an offset string with sub-minute precision. So I don't know whether or not a mention belongs in Annex F.

Alternatively we could just make this |UTCString[+SubMinutePrecision]| here, although we'd have to check callers of the operation to see if any further validation was needed.

spec.html

temporal/abstractops.emu

Review suggestion from Richard.

The ISO 8601-1:2019/Amd.1:2022 amendment added back support for 24:00, this time even as an instant in time and not just the end of a duration.

(And, while here, fix the descriptions at the very top of each section --- these were seriously outdated)

Not sure why I thought this was supposed to be alphabetized; the other sections aren't.

Review comment from Richard.

spec.html

Review suggestion from Michael Dyck.

This was a confusion on my part because in implementations you can optimize out the weeks and days parameters entirely. h/t Jack Works

ptomato · 2026-03-05T23:06:41Z

Pushed another commit addressing a comment from @Jack-Works (tc39/proposal-temporal#3290)

gibson042 · 2026-03-06T16:43:38Z

temporal/grammar.emu

+    <emu-clause id="sec-rfc9557grammar-static-semantics-early-errors">
+      <h1>Static Semantics: Early Errors</h1>


I think we're missing a syntax error for |TimeZoneIANAName| productions when |TimeZoneIANANameComponent| is "." or "..", which should be added for alignment with RFC 9557.

I don't think it matters that much, since an annotation like [../../Foobar] will throw a RangeError anyway when given to Instant.from() or ZonedDateTime.from(), because there won't be an IANA time zone with that name.

But note that it would technically be a normative change to make it into a syntax error, because Temporal.PlainDate.from('2026-03-06T15[../../Foobar]') would throw an error instead of ignoring the annotation (as it would with an otherwise syntactically valid annotation such as Temporal.PlainDate.from('2026-03-06T15[Europe/Custom]')).

I've pushed a commit marked "(optional)" implementing this, if we choose to go ahead with it. But I'd personally recommend against at this point.

I'd prefer you not include that commit in this PR unless you're planning to ask for consensus for the normative change.

Review suggestion from Richard.

ptomato marked this pull request as draft February 16, 2026 23:53

ptomato commented Feb 17, 2026

View reviewed changes

ptomato force-pushed the temporal-stage-4 branch 2 times, most recently from b7627f5 to 283e9b8 Compare February 17, 2026 00:25

michaelficarra added the editor call to be discussed in the next editor call label Feb 17, 2026

Normative: Temporal stage 4, part 1

ccbb91e

This commit makes changes to ECMA-262 AOs that are needed for Temporal regardless of whether it lands in a separate document.

ptomato force-pushed the temporal-stage-4 branch from 283e9b8 to ccbb91e Compare February 17, 2026 18:52

ptomato commented Feb 20, 2026

View reviewed changes

ptomato marked this pull request as ready for review February 20, 2026 19:20

bakkot added the request preview ask the bot to trigger a PR preview label Feb 23, 2026

github-actions bot removed the request preview ask the bot to trigger a PR preview label Feb 23, 2026

ptomato added 2 commits February 24, 2026 17:26

(review) Split "Numbers and Dates"

0002680

Split the "Numbers and Dates" section into "Numbers and Mathematical Functions" and "Dates and Temporal".

Jack-Works reviewed Feb 25, 2026

View reviewed changes

temporal/grammar.emu Outdated Show resolved Hide resolved

Jack-Works reviewed Feb 25, 2026

View reviewed changes

temporal/grammar.emu Outdated Show resolved Hide resolved

ptomato added 6 commits February 25, 2026 09:51

(review) Reverse order of addition in AddTimeDurationToEpochNanoseconds

af202e7

Minor editorial point, reads better when the operands are in the same order as the AO's arguments.

(fixup) Remove accidental 402 language from AvailableCalendars

855c8f6

Can be squashed with "Normative: Temporal stage 4, part 2"

ptomato added the request preview ask the bot to trigger a PR preview label Feb 25, 2026

github-actions bot removed the request preview ask the bot to trigger a PR preview label Feb 25, 2026

gibson042 added the request preview ask the bot to trigger a PR preview label Feb 26, 2026

github-actions bot removed the request preview ask the bot to trigger a PR preview label Feb 26, 2026

gibson042 reviewed Feb 26, 2026

View reviewed changes

ptomato added 5 commits February 26, 2026 15:46

(fixup) Remove duplicate "defined in" xref for |SourceCharacter|

c4fc6d2

Review suggestion from Richard.

(fixup) Update notes about 24:00 again

1ff830f

The ISO 8601-1:2019/Amd.1:2022 amendment added back support for 24:00, this time even as an instant in time and not just the end of a duration.

(fixup) DFN elements for "Temporal.___" and "%Temporal.___%"

ab5ad47

(And, while here, fix the descriptions at the very top of each section --- these were seriously outdated)

(fixup) Reorder grammar annex to match order given in grammar

75a075b

Not sure why I thought this was supposed to be alphabetized; the other sections aren't.

(fixup) Adjust reference to UTS35 and add to normative references

d0f1150

Review comment from Richard.

ptomato changed the title ~~Draft: Normative: Temporal stage 4~~ Normative: Temporal stage 4 Feb 27, 2026

jmdyck reviewed Mar 4, 2026

View reviewed changes

spec.html Outdated Show resolved Hide resolved

(fixup) oldids punctuation

94011c7

Review suggestion from Michael Dyck.

michaelficarra added the request preview ask the bot to trigger a PR preview label Mar 5, 2026

github-actions bot removed the request preview ask the bot to trigger a PR preview label Mar 5, 2026

(fixup) Address tc39/proposal-temporal#3290

cfde6e4

This was a confusion on my part because in implementations you can optimize out the weeks and days parameters entirely. h/t Jack Works

gibson042 reviewed Mar 6, 2026

View reviewed changes

(optional) Disallow TimeZoneIANANameComponent of "." or ".."

4b0645e

Review suggestion from Richard.

		<emu-clause id="sec-rfc9557grammar-static-semantics-early-errors">
		<h1>Static Semantics: Early Errors</h1>

Conversation

ptomato commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ptomato left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ptomato commented Feb 17, 2026

Uh oh!

ptomato left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Jack-Works commented Feb 21, 2026

Uh oh!

ptomato commented Feb 23, 2026

Uh oh!

github-actions bot commented Feb 23, 2026

Uh oh!

bakkot commented Feb 23, 2026

Uh oh!

Uh oh!

Uh oh!

ptomato commented Feb 25, 2026

Uh oh!

ptomato commented Feb 25, 2026

Uh oh!

gibson042 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ptomato commented Mar 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ptomato commented Feb 16, 2026 •

edited

Loading

gibson042 left a comment •

edited

Loading