Proposal-temporal: "Which Temporal type do I use" flowchart

[ptomato]

It would be useful to have a "Which Temporal type do I use" flowchart in the documentation, similar to "Which STL container do I use"

[justingrant]

Not exactly a flowchart, but I built a visual "which Temporal type to use when parsing from a string?" graphic for https://github.com/tc39/proposal-temporal/issues/716#issuecomment-669736392. I built it in PowerPoint because I was too lazy to make it into an SVG, but it's probably pretty easy to turn into an SVG for easier inclusion in the docs if an image is not good enough.

A more complete version of this image would include a bracket for TimeZone (once we agree about whether an offset is a time zone or not!) and Calendar. And perhaps Duration and Now shown sitting off to the side, lonely and disconnected like Alaska and Hawaii in US maps. ;-)

Temporal Type to ISO Strings.pptx

[ljharb]

@justingrant this is amazing, and I would strongly encourage this diagram to actually be part of the spec text itself (there's a few existing diagrams).

(if so, please include editable source so future changes can be easily made)

[jasonwilliams]

I agree with @ljharb including this would be useful. However i think this may serve a _different_ purpose to what a flow chart may serve. I can see this being useful for mentally mapping an ISO string back to Temporal types (especially for those who aren't used to ISO strings)

As well as the useful breaking-down of a full ISO date, I would still like to see a flowchart. A flowchart can serve a great purpose for users who don't know where to begin and need a starting point.

[acutmore]

The RxJs docs used to have a nice flow chart mechanism with their docs. I believe it was generated from these pages:
https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/which-static.md
https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/which-instance.md
Can definitely see a similar thing being useful for Temporal.

Tangentially related I made this today:

I'm thinking of doing similar ones for other aspects of Temporal.

[justingrant]

Nice diagram! Note that ISO strings can be parsed into any Temporal type, not only ZonedDateTime and Instant.

Also, take a look at https://tc39.es/proposal-temporal/docs/#object-relationship which is somewhat similar (albeit less detailed and with boxes in different places) than your diagram above.

[acutmore]

Nice diagram! Note that ISO strings can be parsed into any Temporal type, not only ZonedDateTime and Instant.

Thanks @justingrant 😀 I did start adding links from string to all the other Temporal types but ran out of room 😂, but you're 100% right that it makes it look like that is the only type that can be created from the ISO string.

I've updated the diagram to with a catch all *.from(str) similar to the *.toString(options*) link

[justingrant]

@justingrant this is amazing, and I would _strongly_ encourage this diagram to actually be part of the spec text itself (there's a few existing diagrams).

(if so, please include editable source so future changes can be easily made)

@ljharb A later version of this chart was just merged into the docs in #1168. I ported the chart from PowerPoint to cleaned-up SVG to make it easy to embed anywhere and to edit later.

I'd be happy to put it into the spec, but where would you recommend to put it?

[ljharb]

I'm not sure :-) when the spec is ready for review, I'll certainly keep an eye open for a good spot, but for now, probably just pick one.