Temporal proposal

[littledan]

Bonjour TAG,

I'm requesting a TAG review of:

• Name: Temporal proposal
• Specification URL: https://tc39.github.io/proposal-temporal/spec-rendered
• Explainer, Requirements Doc, or Example code: https://github.com/tc39/proposal-temporal
• Tests: https://github.com/pipobscure/tc39-proposal-temporal/tree/master/test
• Primary contacts: @maggiepint @pipobscure @mj1856

Further details (optional):

• Relevant time constraints or deadlines: Feedback is requested before this feature is proposed for Stage 3. We don't have a solid timeline for proposing for Stage 3, but the soonest possible time would be in the January 2019 meeting (and likely later).
• I have read and filled out the Self-Review Questionnare on Security and Privacy. The answer to all questions is "no"--the only possible security-related concern was related to the possibility of adding more precise Date.now()-like functionality, which this proposal currently omits.
• I have reviewed the TAG's API Design Principles

You should also know that...

It would be helpful to get feedback on which date/time units are useful/needed for web APIs (e.g., this proposal omits a duration type). The date/time types here may enable changes in the TAG's API Design Principles, c.f., w3ctag/design-principles#101

We'd prefer the TAG provide feedback as (please select one):

• open issues in our Github repo for each point of feedback
• open a single issue in our Github repo for the entire review
• leave review feedback as a comment in this issue and @-notify [github usernames]

[slightlyoff]

Stream of consciousness before we take this up properly:

• Is there a way to represent a time delta in this API?
• What is the type relationship between Instant and DOMHighResTimeStamp/DOMTimeStamp? Do you envision those DOM types subclassing the new ones? Should they be convertable? Has there been a dicsussion about how IDL will translate them?
• Has TC39 thought about HTMLTimeElement integration? Or how this can work with <input type="time">?
• I don't think anyone is happy with the current processing model in HTML which is Gregorian-only (uggh) and which seems to include custom parsers. We'd love your thoughts on how to join these up.
• Instant's constructor appears to rely on BigInt. Does DOM integration for Instant and related classes require WebIDL extensions?

[annevk]

What is wrong with Gregorian-only for non-user-facing date handling?

[cynthia]

Is there a way to represent a time delta in this API?

I was wondering the same.

[littledan]

Does DOM integration for Instant and related classes require WebIDL extensions?

I have a PR out for review at WebIDL to add BigInt support, but it's waiting for use cases to be articulated. I'm not sure if we'd need BigInt in WebIDL just to support Instant being used in DOM, though.

Is there a way to represent a time delta in this API?

Could you say more about use cases for a time delta representation?

[cynthia]

Example would be something like this:

if (date1 - date2 > date3 - date4) {
  // do something
}

(Although this proposal doesn't include a operator overloaded syntax, this is just an example of a use case.)

[pipobscure]

Re: time-delta

This is actually a fair bit more complicated than that. For one thing, the delta depends on TimeZones which may not be available.

So the approach we have chosen for temporal is to be explicit. So for Instant you'd do

if (instant1.milliseconds - instant2.milliseconds > instant3.milliseconds - instant4.milliseconds) {
  // do something
}

If you assume CivilDate then date1 - date2 will never give you a result that can in any way be relied upon to be correct. So being more explicit ensures that the result will actually be what you'd expect.