Proposal-temporal: TODO: Scenario-Based Examples

[mj1856]

Previously we had two examples of common scenarios this API could solve. We should add those back, with the appropriate changes, and perhaps add some others.

[domenic]

Really looking forward to these. Right now ZonedInstant's existence is very puzzling to me, but I am not experienced in designing date libraries, so hopefully examples will clear it up.

[apaprocki]

@domenic One common scenario you need the timezone for is for future events. The next TC39 meeting is 2017-07-25 10:00:00 America/Los_Angeles. That is stored in your calendar app. It can't be resolved to an absolute point in UTC and stored because between now and 7/25, the US could decide to abolish DST -- but your meeting will still need to be 10am in local time on that date. So resolution to an absolute point in UTC is done at the presentation layer or when needed "as-of-now", but isn't used to store the actual event (or at least the timezone string must be stored as well). So I think a good scenario to write up is retrieving the next few future TC39 meetings from a hypothetical request and displaying them to a user as absolute as-of-now local datetimes in an arbitrary timezone (say, Asia/Tokyo since there are no meetings there).

[domenic]

That's a great example, thanks! In particular the point about the US abolishing DST and how that would impact things makes it clear why these are important. Let's be sure to emphasize that part.

[maggiepint]

In general, it is impossible to do any date computations in local time without a time zone. If you don't have a time zone, you have no idea what time it will be one hour from now in a given location. It may well be 1 AM again due to a fall back transition!

[gilmoreorless]

I’ve followed this proposal from the start, but I had to ignore it for a while (for reasons unimportant to the issue at hand). I’ve now caught up on everything that’s happened in the past few months, and I have some concerns.

It’s great that the proposal is gaining traction and going through the TC39 process. However, there are still barely any actual use cases listed. This proposal was designed to replace the shortcomings of Date, because Date doesn’t easily handle many real-world scenarios without a fair amount of hackery (such as mis-using the UTC timeline). But if we don’t explicitly list out these scenarios and use cases, how can we be sure that the proposed API is actually covering them?

I notice that this particular issue is still unresolved after 2 years. It’s listed in the “finalize documentation” project, but I’m not sure if that comes before or after “finalize spec text”. I very strongly feel that locking in the API _before_ documenting the use cases is the wrong way around. The README currently (commit 4a0f079c60521666184ee05ee93c634ba286e794 at time of writing) links to examples.md, but that only contains a single scenario, with the rest being API documentation.

Rather than just complaining, I’ll briefly list some scenarios I’ve personally had to deal with in production systems. I can provide more details/clarification if needed, but I want to make sure the expanded information would be useful first. Some of these cases are well-known problems with many library solutions available, but it’s still worth listing them for completeness.

1. Abstract date logic which is not tied to any specific location

_(I’m avoiding the “Local”/“Civil” prefix naming debate here)_

1. Showing a generic calendar control, with any day beyond “today” disabled and not selectable.
2. Simple calculations of “how many days until {future date}”.
3. Integration with wearable devices.
   
   
   
   • e.g. Fitbit always records sleep data in the user’s “local” time, wherever they are in the world. Thus their API returns zoneless datetimes: https://dev.fitbit.com/build/reference/web-api/basics/#time-zones
   
   

2. Dealing with dates and times in a time zone that differs from the user’s browser

1. A graph showing activity for a storage tank in a fixed location. The requirement was to always start the graph at midnight for the tank’s location, regardless of the viewer’s time zone.
2. Calculation of recurring schedules for a specific location.
   
   
   
   • “Email this generated report at 4pm daily, Brisbane time.”
   
   
3. Calculation of how recurring schedules will be affected in other locations.
   
   
   
   • “This meeting is always at 2pm in Sydney. What time will that be for our remote team in Ho Chi Minh City before and after Sydney’s daylight saving shifts?”
   
   
4. Trying to book a meeting or event that works for 4 different time zones, with a display of the relative times in each zone (_à la_ World Time Buddy).

3. Combinations of both

1. Show opening hours for a chain of stores spread across multiple time zones.
   
   
   
   • e.g. The default is for all stores to be open from 8am to 6pm in their respective locations.
   
   
   • Viewing the website for a particular store needs to show if it’s currently open/closed, or closing soon. This means taking the abstract shared closing time and applying it to the time zone of the specific store.
   
   

I don’t want to be the _only_ person providing these, though, as it’s just one person’s perspective. There have been some other examples scattered among various issues that I’ve seen so far:

• @kaizhu256 has provided a use-case in https://github.com/tc39/proposal-temporal/issues/139#issuecomment-510925843 regarding flight durations and take-off/landing times.
• @ljharb recounted a bug with scheduling a future event in https://github.com/tc39/proposal-temporal/issues/78#issuecomment-412254068
• I’m also hopeful that @ljharb could provide some more scenarios based on the things Airbnb have had to deal with.

We could specify a list of chosen scenarios, with examples of how to do them with Temporal vs currently-existing methods (some of which might only be possible with third-party libraries). But first we have to decide on what that list contains.

[littledan]

@gibson042 is working on this.

[jasonwilliams]

This issue can be closed as it’s superseeded by #240
If you have any further comments please raise them there.