For analytics applications, particularly ones focused around time series data, there's a significant mismatch between the
realities of time (ie. "it's complicated(tm)") and the
user's mental model of time. The core challenge is that most users think in terms of "local time", but the analytics tools and systems need to work within a more precise time framework. Bridging this gap consumes a great deal of mental effort for developers, and is also a source of a significant number of hard-to-find correctness bugs, based on my experience. Here are a few of the areas related to closing that gap that I didn't see well supported in the proposed API:
Instant Offsets
A specific example, which it looks like someone may have already commented on, is how to get an instant that is X hours back in time from some other instant. Since most users will think about this in local time, and often in their own time zone, computing this accurately across DST or leap boundaries is non-trivial. Based on how you answered that challenge, it seems like it's up to the caller to take the Posix time, add the requisite number of milliseconds, and then convert back into the desired Zone. While a simple transformation, that seems like exactly the sort of detail a Time abstraction should hide from me.
This same question gets even harder, however, when dealing with irregular time units, like Months or Years; getting an instant X months or years back in time, for example. In that case, you can't simply calculate the number of milliseconds to use for the offset because months and years are irregularly sized. At this point, I think it's no longer a good idea to push the responsibility of doing the calculation onto the user of the API, since the calculation requires knowledge of things encoded in the TZ database.
Partial Instants
Another use-case I didn't notice as being supported is the ability to partially specify instants. The toCivil function is along those lines, but in the reverse. The place this comes up is that humans (especially in an analytics app) often want to only specify the Year, or Month, or Week that they are interested in. Fully specifying the instant would be painful. 2017-01-01T00:00:00.000Z, for example, only really cares about the year in the 1st "digit". The rest of it is just noise.
A different way to present this is that humans often think about time at different granularities depending on what they are doing with it, while the API as written doesn't seem to support that very well, requiring consumers to close that gap themselves each time it comes up.
Weeks
While not super common, analytics apps often think in terms of weeks. eg. Week over Week reporting, weekly aggregations, etc. I didn't see any treatment of weeks in any significant way, yet it is a common human abstraction. Additionally, ISO 8601 also has a special section devoted to week representation, so supporting ISO 8601 via this API will be less rich if it doesn't have weeks as a core concept.
Calendars
A final concern that came to mind is representing entirely different calendars, likeHebrew, for instance. I am less familiar with the needs for this, but alternate calendar representation is a core capabilities of well regarded time libraries like JodaTime. I have not dealt with those issues myself, so I cannot speak to their relative merits of inclusion in a core time abstraction, but I had not seen them mentioned yet.
It's been a bit since I've delved into the murky mental depths of this, but I believe the core mismatch is that humans generally think of time in an ISO 8601 way, in terms of years, months, days, hours, etc. while time itself is a continuous dimension. Humans bucket time, turning it into a discrete space (or many discrete spaces of differing granularity), but we often represent it as a continuous thing (ie. a count of milliseconds since some epoch). Bridging that gap, from the human mental model into the reality of continuous time while dealing with the complexities of Zones, etc., is the need a Time API is trying to fill.
Given the complexities and difficulties of dates and times, and how widely the complexity can vary based on the use-cases, the right choice may very well be to keep a very simple representation and API. Since the goal of the new API is to "do what people want", it may not make sense for it to try to do what only advanced analytics applications want. But if that is the chosen path, I think having some disclaimers or "anti-docs" about what the abstraction is known not to do well would go a long way towards setting expectations.
Sorry for the book-length feedback, and for being a bit late to the party, but Time has caused me such pain in the past that I can't help but share my experiences so that others may hopefully benefit. I'm perhaps overly familiar with time-based analytics, and I'm very new to Elm, so please forgive me if I simply misunderstood the API, but those are the concerns and ill-supported use-cases that jumped out at me at 1st glance. Hopefully some of the concerns are mitigated by other aspects of Elm, but I thought it best to call them out since they were non-obvious to me. Admittedly, analytics is not what the majority of applications use Date/Time for, but it is a significant category of interactive applications, so I'd hate to see them stymied due to insufficient Time capabilities.
- Rick