Re: [w3ctag/design-reviews] Temporal proposal (#311)

Hi TAG! First of all I apologize for not responding sooner. Through my own fault I wasn't subscribed to this thread until two weeks ago, and at that point all my time was taken up with preparing for the TC39 plenary, and later recovering from it. Thanks for taking the time to review the proposal. I have some responses below to Lea's and Sangwhan's messages.

> Since there is no explainer but only documentation & the spec, we missed a list of user needs, which would facilitate review.

I've been looking over the [requirements for an explainer](https://w3ctag.github.io/explainers) and while it's true that we don't have a document that follows this format, we did intend our [documentation](https://tc39.es/proposal-temporal/docs/) and [cookbook](https://tc39.es/proposal-temporal/docs/cookbook.html) to fulfill roughly the same function, of describing the rationale for the proposal, the user needs motivating it, and showing samples of how users would solve problems using it. I'd be interested in hearing more about what was missing from these resources which would have helped with your review, so we can improve this going forward.

> One source of cognitive overhead is the deep hierarchy of objects, the distinction between which is based on what information is available (e.g. day+month vs day+month+year vs month+year or types without a timezone and types with a timezone). [...] We were wondering about the reasoning behind this decision, compared to a single object, with some of its information undefined or null.

I can give the rationale for having multiple classes in the proposal. (There is more background in https://github.com/tc39/proposal-temporal/issues/927 and https://github.com/tc39/proposal-temporal/issues/51 if you want to read more about it.) Having strong types is a design decision that was made to avoid bugs that might occur if developers had only one class to work with and had to fill in arbitrary values for missing data, and then decipher what that meant.

For example, "00:00:00" might be a common interpretation of null hour/minute/second fields, but until recently Brazil had their DST transitions at midnight, so for one day every year, that time would not exist, leading to unexpected and hard-to-track-down bugs. The "correct" workaround, to use noon rather than midnight as the missing-time value, is not well-known to most web developers.

In fact the [question](https://github.com/w3ctag/design-reviews/issues/311#issuecomment-434843730) about [HTMLTimeElement integration](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTimeElement/dateTime) from the previous review that the TAG did a couple of years ago was part of the motivation for adding the PlainYearMonth and PlainMonthDay types.

I do want to acknowledge that this is a matter of taste. While we've gotten some feedback that many developers seem to understand and agree with the idea of representing your data more precisely with strong types, certainly plenty of developers would be happier with a single, more generic class as you suggested. If they wanted to, these developers could use Temporal.ZonedDateTime as an "everything" class, but in the documentation and cookbook we don't currently encourage it to be used that way, since it could lead to the type of bugs mentioned above.

In any case, the decision to have multiple classes is foundational to the proposal and I don't believe it would be possible to change it at this point, unless we started over with a different proposal altogether. But I hope that this response helps mitigate the concerns you mentioned, certainly legitimate ones, about cognitive overhead.

> Hopefully there will be some libraries that make this API easier to use for average users.

I'm hopeful that using Temporal.ZonedDateTime for everything would be at least as good of a solution as relying on a wrapper library. That said, if someone does make some sort of a "simplified Temporal" library, I wouldn't be overly sad, as Temporal gives better tools for doing this than the Date object ever did, and avoids the need for that wrapper library to contain a copy of the time zone database which users need to download over and over again.

> it also forces the API to promote factory methods for object creation which need to be learned separately, as opposed to constructors.

I'm not certain of the link that you mentioned between multiple classes and factory methods; that is also a design decision that's a matter of taste, but I do think it's a separate one from the decision to have multiple classes. Speaking personally, I also prefer constructors above factory methods, but it's my understanding that that's not a universal opinion, and I think the current split between low-level constructors related directly to the data model, and high-level factory methods accepting more kinds of input, is a good compromise. We did have an [earlier thread](https://github.com/tc39/proposal-temporal/issues/761) with Lea about this.

> While reviewing, we also spotted a typo in your documentation: in the example here the unit is probably "seconds", not "minutes".

I think this has been fixed in the meantime, thanks!

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/311#issuecomment-804496493