Proposal-temporal: Turn disambiguation into static property

[Ryuno-Ki]

In getInstantWithLocalTimeInZone the parameter disambiguation is introduced for the first time (in the cookbook).

I was wondering, whether it couldn't be a static property on Temporal, so the possible values are defined.
I'm thinking here along the lines of static properties of Math, i.e. properties of Temporal.disambiguation.X.

In TypeScript, I'd model it as Enum, I think. For JavaScript, I often go with a POJO instead.

[ljharb]

Temporal.disambiguations.X makes a lot of sense to me.

[ptomato]

Thanks for the feedback!

Some related discussion is at #607. (Since, currently, not all functions with a disambiguation option accept the same values, it would make sense to have separate enum-like objects)

[justingrant]

It makes sense for long, difficult-to-remember, difficult-to-type numeric constants like Math.PI to be static properties. But string options seems like a different use case.

Are there other examples in JS of exposing string options as static props in this way? Does Intl do this? Do any DOM APIs?

From an ergonomics standpoint, is Temporal.disambiguations.Duration.minus.balanceConstrain better than 'balanceConstrain'? Seems like a lot of extra typing.

If the advantage is that you can autocomplete your way into the correct spelling, users already get IDE autocomplete for the existing string options:

And tooltip help too, showing the string values that can easily be copied to clipboard:

I guess I'd like to understand this proposal better. What are the use cases where this is helpful?

[ljharb]

imo yes; in my codebases i prefer to have a given string (like, a conceptual atom, ie, "foo" might exist twice but not if it represents the same thing) only exist once in the entire application, to avoid trivial mistakes.

[justingrant]

IMHO it seems unlikely that many developers would have the patience to type Temporal.disambiguations.Duration.minus.balanceConstrain every time this option is needed. Autocomplete can make that easier, but if they have autocomplete then they'll probably have autocomplete for the option strings too, right?

Seems more realistic that developers would create their own shorter constants, e.g.

const BALANCE_CONSTRAIN = Temporal.disambiguations.Duration.minus.balanceConstrain;

But at that point, I'm not sure that's better than:

const BALANCE_CONSTRAIN = 'balanceConstrain';

FWIW the trend in TypeScript over the last few years has been to move away from enum objects and towards typed string literals. For example, calling the function below with 'add' or 'minous' will cause a build or lint error:

function doPlusOrMinus(
  op: 'plus' | 'minus',
  durationLike: Temporal.DurationLike,
  options: LocalDateTimeMathOptions | undefined,
  localDateTime: LocalDateTime
): LocalDateTime

That isn't an argument about how pure JS code should evolve, but it does suggest that this problem will be lessened over time, somewhat from TS adoption but perhaps more from tools like ESLint evolving to become better at finding problems like this, esp. given 2-3-ish years before Temporal goes mainstream.

Net-net, I don't think the underlying problem is bad enough to warrant API expansion for it, esp. given that the problem is likely to get less bad in the future.

[Ryuno-Ki]

Some related discussion is at #607. (Since, currently, not all functions with a disambiguation option accept the same values, it would make sense to have separate enum-like objects)

@ptomato Shall we coalesce on #607 then? As in, not having the conversation twice?

From an ergonomics standpoint, is Temporal.disambiguations.Duration.minus.balanceConstrain better than 'balanceConstrain'? Seems like a lot of extra typing.

@justingrant My thinking was rather along the lines of: What values are valid? So I'd go with _semantic_ value instead of ergonomics. I have no strong opinions about where you put those collection of strings.

When I was working with createImageBitmap for a project, I'd wish, that the options parameter would have had a list of valid values - because I'd need to look them up otherwise.

Yes, you can have an IDE autosuggest values for you. But I'd need to have that knowledge in reviews as well. (Plus, I prefer working with Vim as IDEs are often get in my way with their „features”).

const BALANCE_CONSTRAIN = 'balanceConstrain';

What if there was a way to tell, that BALANCE CONSTRAIN is of type Temporal.disambiguations.Duration.minus.balanceConstrain? (Either via TypeScript or as JSDoc annotation)

[ptomato]

Shall we coalesce on #607 then? As in, not having the conversation twice?

I think no need to consolidate those two discussions; that one is about distinguishing disambiguation from overflow, this discussion is about bare strings vs static properties. They are related, but not the same.

[littledan]

I agree with @justingrant 's comment that using strings would follow JS's typical conventions. If we're deviating from those conventions, I'd want to understand if this is establishing a new convention, and if so, what the pattern is exactly.