Options objects should ideally be eager-parsed lazy-validated

[Manishearth]

I discussed this a bit in the Matrix room first to get a temperature check. Apologies in advance for the large pile of text

Background

temporal_rs

I've been implementing Temporal in V8, using the temporal_rs library, used by boa. Most of the implementation concerns here pertain to both V8 and Boa.

temporal_rs is a library whose API can be tweaked if necessary¹, but overall I think its API is a good example of an attempt to split surface-level "JS interaction" code from the underlying spec logic/algorithms². I think that this type of implementation hygeine is worth supporting as a specification, and if temporal_rs' model is incompatible with the spec, it's potentially a sign for a spec change.

WebIDL

(This section is not really a motivation, but is an attempt to explain the type of validation/parsing model I am aiming for)

I like the model WebIDL presents, providing a very clear distinction between "JS interaction" code and the underlying spec logic. Specifications using WebIDL seldom have to explicitly interact with JS beyond throwing errors; the JS layer is basically handled by the structure provided by WebIDL itself.

For example, Instant.since() would typically have the "input types" all clearly specified in WebIDL, which would imply a bunch of pre-parsing and type validation and the actual specification would do things like validating whether the settings are compatible (e.g. Instant.since() doesn't want you to use "day" units) and then performing the actual algorithm.

An example `Instant.since()` in WebIDL

typedef (Instant or string) InstantLike;

enum Unit {
   "auto",
   "years",
   ....
   "nanoseconds",
};

enum RoundingMode {
    "ceil",
    ...
    "halfEven",
}

struct DifferenceSettings {
    Unit? largestUnit;
    Unit? smallestUnit;
    long? roundingIncrement;
    RoundingMode? roundingMode;
}

interface Instant {
   Duration since(InstantLike other, DifferenceSetting settings);
}

In the runtime, all of this validation would be deterministically performed at the boundary of since (throwing any errors necessary), and only then would the spec code run.

I do not wish to suggest this specification move over to WebIDL: I'm using WebIDL to illustrate a good way of thinking about the JS-to-spec layer that is consistently used in Web specifications.

A different perspective on all of this is separating out "type validation" from "value validation", though that usage of terminology may be too ambiguous to usefully convey an idea.

Options loading and observability

By and large, all of this is mostly relevant to the part of the spec that deals with options loading, like GetDifferenceSettings and GetTemporalUnitValuedOption.

The order in which operations are performed does matter; it is observable to external code if e.g. smallestUnit is read before largestUnit, or if smallestUnit and largestUnit are read before validating their values in case, say, smallestUnit has an invalid value for the context (you could notice using a proxy or custom getter that largestUnit was still read before the routine raised an exception).

The current specification mixes up options loading and validation. For example, in GetDifferenceSettings, the steps are:

Step 1: not a step
Step 2: get field (unit)
Step 3: validate
Step 4-5: get field
Step 6: independent of other steps
Step 7: get field (unit)
Step 8: validate
Step 9-10: resolve defaults/auto
Step 11-13: validate

Furthermore, each "get field (unit)" performs unit group validation and default resolution on top of parsing. This is a fair amount of validation overall.

Status quo in different implementations

Firefox matches the current spec exactly. Boa uses temporal_rs and batches up "get field" and option variant parsing (into typed values), but defers further validation to later; as such it is currently spec non compliant.

I am working on the V8 implementation and it does a bit of both, but I'm rapidly hitting a hard tradeoff. If I eagerly validate as the spec wants me to, I end up doing a bunch of operations twice (since temporal_rs will do them again), AND I risk performing non-idempotent operations multiple times (e.g. Instant.prototype.since "inverts" the rounding mode, which you don't want to do twice). If I lazily validate, it is far easier and more efficient, but I am not spec compliant.

The "non idempotent operations get performed multiple times" is by far the largest risk in my view. Performance hits are suboptimal, as is the maintenance burden of more complex validation code being carried in two places, but the issue with non idempotent options can easily cause subtle bugs.

Proposal

I haven't fully investigated the situations where Temporal performs interspersed loading and validation, but my understanding is that it's basically around all of the options bags (there aren't too many of those) and some select enumerated options like "unit". They show up a lot, but it's all shared code.

I'd like to propose that we move in the direction of consistently performing load-and-parse operations (GetOption) first, to get the entire options bag, and any further validation can be performed after the full options bag has been loaded.

This would mean e.g. GetTemporalUnitValuedOption would become a simple three-line GetOption call like GetTemporalOverflowOption. Potentially with default-handling like GetTemporalOffsetOption. There can be a separate ValidateTemporalUnitValuedOption that does unit group validation/etc.

This would also mean that GetDifferenceSettings would call GetFooOption for each object field first, and only then perform parsing and default resolution steps.

I don't necessarily want to turn this into some type of blocker where the Temporal team must agree to fully change everything in this spec, I'm mostly looking for general assent that this is a good direction to move in, and individual PRs could be approved on their merits. I don't think this is a large endeavor, but I don't want to commit the Temporal team to this endeavor, especially in case I'm wrong about the size.

I suspect what will end up happening is that I will discover these cases during the process of implementation, and while doing so open PRs to the Temporal repo, but I am open to other ideas.

There's also probably some leeway on how things are sliced in individual cases; e.g. Unit could still be validated into unit groups by "splitting" it into a timeunit and dayunit set of types. I don't think that's necessary, people may disagree.

Footnotes

1. Not that I claim to speak for the Boa/temporal_rs team here! They may have a certain plan for how it is designed and not wish to change it in certain directions. ↩

2. I think there are, really, three layers to this, not just two. You have very surface level "JS interaction" code (going from JS types into algorithm types), then you have "orientation" where you're validating and just generally figuring out what you've been asked, and then you have the underlying algorithm. servo-media and webxr draw the line between the second two. temporal_rs draws the line between the first two. ↩

[Manishearth]

I was asked to provide more background on the risks for implementors here if the spec remains unchanged.

There are a couple options moving forward, for boa and v8.

Do not change temporal_rs, be spec noncompliant

This is by far the least work involved for everyone. Of course, it is spec-noncompliant, has (minor) interop risks, and is a bad sign for the spec.

This is the status quo for boa (though I cannot claim to speak with their plans around this). While I'm working on the V8 implementation I'm somewhat doing this, but if the spec stays the same I will likely switch to a different strategy eventually. This will likely delay implementation, though.

Do not change temporal_rs, comply with the spec

This would essentially mean that engines and temporal_rs would inefficiently perform validation and defaults resolution multiple times. In V8; this would mean performing all of the validation steps in V8 C++, and then performing them again in temporal_rs Rust code.

Some checks could be skipped in V8 C++ if it's clear that there is no further user-observable steps after them. Determining that is not always easy and it's easy to make mistakes.

Some steps will have to be skipped: for example GetDifferenceSettings "inverts" the rounding mode based on the operation being performed. It's important that this isn't done twice.

For GetDifferenceSettings, the end result would be code that:

1. Performs steps 1-5 in C++
2. Skips step 6 in C++ (idempotency)
3. Performs step 7 in C++
4. Perform step 8-14 in C++.
5. Later on, in Rust code for e.g. Instant.since(), perform steps 1-14 in Rust.

It would be nice if steps 8-14 could be deferred to the Rust code: they happen after all user-visible gets in GetDifferenceSettings. However, they do not happen after user-visible error cases in callers of GetDifferenceSettings. It's fine in DifferenceTemporalInstant: there's no additional steps. But DifferenceTemporalPlainDate does many further steps which can error.

Overall, this is inefficient, and extra maintainence burden on the engines.

Change temporal_rs to deal with "resolved" options, comply with the spec

temporal_rs could be tweaked to publicly accept "resolved" options, where all of these validation and transformation steps have already been applied. A separate API could be provided to go from specified to resolved options.

This is doable, but it further splits the spec across the library and the engine.

Furthermore, temporal_rs would then have to determine what to do when fed inconsistent options. It is good practice for libraries to validate their inputs, and either it has to re-perform validation, or it has to forgo it. A different way to do it would be to split up the types into differently validated types; so you might have a TimeUnit, DateTimeUnit, and DateUnit enum, but this would need to also account for types like TimeAndDay, DateTimeAndAuto, etc. This quickly explodes the number of types in play.

Finally, this diminishes temporal_rs' utility as a general purpose Rust library that has an API similar to Temporal (a well designed datetime library), since all of its endpoints will be lower level ones pulled from the bowels of the spec.

I think if forced to choose I would prefer to have the previous inefficient option over this behavior; I'd rather not make temporal_rs less useful to others.

[ptomato]

We should discuss this in the following Temporal meeting. I'll summarize my opinion that I already communicated in the Matrix room.

I am strongly against this change. It would involve a lot of churn in the proposal, potentially introducing new bugs, while the benefit to JS programmers would be nonexistent or negligible (because all it would do is shuffle the order in which getters would be called.)

We have continued to make a few normative changes — against my better judgement, and each time using up patience from TC39 and from stakeholders funding the work — but those changes have all been at most a handful of lines, and actually solving a problem that would affect JS programmers and/or their users. I do not think "an implementation changed their underlying tech stack and now the code is a little ugly" is anywhere near sufficient motivation for a change of this scope. The time for that was 2 years ago.

I think it's fine for temporal_rs to either revalidate the arguments (how many extra CPU cycles does it cost to check something like unit != YEAR anyway) or lean on use of extra types like TimeOrDayUnit (which costs nothing at runtime).

[Manishearth]

I accept that it might be too big a change, but I want to respond specifically to this point, because I think it is phrased too strongly or leaves me confused as to what the ECMA process is.

I do not think "an implementation changed their underlying tech stack and now the code is a little ugly" is anywhere near sufficient motivation for a change of this scope. The time for that was 2 years ago.

We are currently in the stage of the process where it gets implemented and it gets iterated on due to feedback from implementors. As an implementor I am left confused as to what you mean to say here.

If this feedback is something the team finds too big to act on, that is fine, but if you wanted this feedback earlier I don't see how that could happen. I don't think it's fair for spec authors of a Stage 3 proposal to tell implementors that their feedback is "too late", it's a bait and switch when it comes to the ECMA process, or at least what I understand of it.

I'd also hope that this feedback nudges future ECMA API work to consider WebIDL-like load-and-parse-first models.

Also it's not just about ugly code, it's about correctness; not all of these steps are idempotent.

It would involve a lot of churn in the proposal, potentially introducing new bugs, while the benefit to JS programmers would be nonexistent or negligible (because all it would do is shuffle the order in which getters would be called.)

I'll note: I think the spec spends a lot of extra effort carefully doing options getting in alphabetic order while there is no benefit to JS programmers either. Sure, this change does not benefit JS programmers, but the spec is already spending a lot of effort into choices that do not benefit JS programmers. (Those are some of the choices I'd like to undo if possible, too, but it doesn't sound like that's happening)

I'll also argue that something that hampers implementation also indirectly hurts JS programmers: this issue is perhaps the one with the potential to most drastically change the amount of work involved in V8 spec compliance, which means that V8 will either ship noncompliant¹, or ship later, both of which hurt JS programmers.

Footnotes

1. This is an option I am seriously considering leaving on the table: it is not my decision, but as the immediate implementor it may not be work I have time to do, unless Boa is also interested in full spec compliance when it comes to observable options getters and is able to help. ↩

[nekevss]

Just going to leave a couple comments since this has partially been around temporal_rs.

It would involve a lot of churn in the proposal, potentially introducing new bugs, while the benefit to JS programmers would be nonexistent or negligible (because all it would do is shuffle the order in which getters would be called.)

I could be misunderstanding the exact scope of Manish's proposal above, but I don't think the proposal, at least with GetDifferenceSettings, is to change the order of the options getters. Technically, everything can be left in the same order. It is primarily to separate the concerns of calling getters and algorithm specific validation of those getters to two separate abstract ops.

The reason why this came up is that in order to address the GetDifferenceSettings, the getters and validation were separated with the ordering of the operations preserved, which is not technically spec conformant but it is, as of right now, test262 conformant.

Which leads to a second point.

We have continued to make a few normative changes

I will acknowledge that it would technically be a normative change, but it is a change that is not currently tested in test262. Boa is currently 100% conformant on Temporal difference operations because there are no tests about throwing in the middle of order of operations.

Beyond the above, this may be worth further consideration because the above approach mirrors the general approach to PrepareCalendarFields and CalendarResolveFields. Primarily, these abstract ops act in two different steps to parse and validate an object to a calendar fields record object, which is then later resolved via algorithm specific validation.

[ptomato]

We discussed this in the Temporal meeting today (2025-06-26), but didn't have enough of a quorum to make a decision. Something that would be helpful, but not required, to move the discussion forward, would be a spec PR that shows the scope of what's being proposed for change.

(I'll respond to some of the above questions with my opinion-based answers in a separate post)