javascriptdate-parsingdatetime-parsingecmascript-temporal

Is there one function I can call to parse any string into the appropriate JS Temporal type?

I've got a list of ISO 8601-compatible strings, some of which are dates (like '2022-12-25'), some are date-time values (like '2022-12-25T12:00'), and some have time zone info (like '2022-12-25T12:00-08:00[America/Los_Angeles]'.

Using the new Temporal API that's coming to JavaScript, is there one function I can call to parse all these strings into their corresponding Temporal types like Temporal.PlainDate, Temporal.PlainDateTime, Temporal.ZonedDateTime, etc.?

Solution

  • No, there is not a universal parse-into-any-Temporal-type function that's built into the language.

    This is because the same string can be used to parse many different Temporal types. To parse a string into a Temporal type, you must know ahead of time what type you want.

    For example, 2020-04-25[u-ca=hebrew] can be successfully parsed by Temporal.PlainDate.from, Temporal.PlainMonthDay.from, Temporal.PlainYearMonth.from, or even Temporal.PlainDateTime.from. This ambiguity requires choosing a Temporal type before parsing.

    If you have a list of date/time strings and you don't know what type they are, but you'd like to parse them anyways, then it's fairly straightforward to write a function that calls the from methods of multiple Temporal types and returns the first result that doesn't throw. Just make sure to only include types that contain all the data you require, and make sure to put the types in order from "most data" to "least data" in the string. This will usually be this order:

    1. Temporal.ZonedDateTime

    2. Temporal.Instant

    3. Temporal.PlainDateTime

    4. Temporal.PlainDate

    5. Temporal.PlainTime

    6. Temporal.PlainYearMonth

    7. Temporal.PlainMonthDay

    8. Temporal.Duration (although honestly I doubt that there are many use cases where both duration data and date/time data is combined in the same input!)

    If you're curious about why Temporal doesn't have a Temporal.parse method, more background can be found here: https://tc39.es/proposal-temporal/docs/parse-draft.html (I'm one of the champions of the Temporal proposal since 2020.) Here's one relevant excerpt:

    This is a draft design document for a Temporal.parse API, which is not currently planned to be implemented for several reasons:

    • Temporal's approach to most operations—including parsing—is to encourage strong typing, e.g. Temporal.Instant.from vs. Temporal.PlainDateTime.from. A type-spanning "parse anything" API goes against that strongly-typed model.
    • The main use case beyond type-specific parsing that was identified for a parse API was handling "partially correct" ISO strings, e.g. where only one unit was out of range. Most of these use cases were addressed via the overflow option in the from method of all types which either clamps out-of-range values ('constrain') to the nearest in-range value or throws ('reject') in that case.
    • The final remaining case for a parse API was resolving the case where a time zone and a time zone offset can be in conflict, as would happen for future Temporal.ZonedDateTime values stored before a country permanently abolishes DST. This use case is now handled via the offset option of Temporal.ZonedDateTime.from.