parseJSON - minimal implementation for parsing JSON dates from an API

[marnusw]

The ISO date parsing previously done in toDate was moved into parseISO to keep the minimal build size low when string date manipulation is not required (#1016). The problem is that any application that retrieves a date from an API will parse some form of serialized date string before passing it to other functions. The following is typical example:

const output = format(addDays(parseISO(dateFromAPI), 1), 'yyyy-MM-dd')

As soon as parseISO is used in this way the benefit of removing toDate has been negated. The parseISO and parse functions are still around 7000 and 8000 bytes respectively. The proposed parseUTC function is only ~520 bytes in size and sufficient to parse the standard JSON serialized date string formats of most server-side languages.

Aside from complete ISO dates and the input types accepted by toDate the function returns an Invalid Date. The intention of this function will not be to parse user input, for this parse would still be needed, but it permits convenient parsing of date strings from an API with a known ISO format.

This is a proposed compromise/solution for the issue I raised here, and something I have used in a couple of projects recently to good effect.

I am still undecided about the best name for this function. My initial thought was parseJSONDate, but then I realized only UTC dates are supported and calling it parseUTC might be more generic and describe the function more specifically.

I would like to propose this function for inclusion in the core date-fns library, however, if it is deemed not a good fit I can also add it to date-fns-tz.

[kossnocorp]

I love it! However, I think the name is confusing. I like parseJSON more because it's date string formatted by date.toJSON, and I believe that the fact that only UTC dates are supported is an implementation detail.

[marnusw]

Thanks for the feedback. I agree calling it parseJSON makes sense after all and it has been renamed.

[kossnocorp]

Great work, thank you a lot! Besides the small issue with the function name, the PR is ready to go.

[kossnocorp]

Please add /* eslint-env mocha */ to the top of the test.js to make ESLint happy.

[marnusw]

Thank you for reviewing and accepting this @kossnocorp! The remaining issues have been fixed.

[kossnocorp]

Thank you! I'll ship it with the next release.

[kossnocorp]

👍

[TrySound]

Yay, we have this in a few places in our app

[kossnocorp]

I've shipped the PR with 2.6.0: https://github.com/date-fns/date-fns/releases/tag/v2.6.0

[alexdilley]

Is there an argument against simply using the parsing capabilities built into JS's Date type? i.e.

new Date('2000-03-15T05:20:10.123Z')

Is it a matter of trust in the format supplied by the (commonly) API that would necessitate using a library-supplied function such as this?

[marnusw]

@alexdilley yes it is simply about trust in the underlying implementation of different browsers. These days that might not be as relevant as it once was, but using this function leaves no room for doubt.