Consider bringing back old parse

[nfantone]

Hi all!

Today I tried the latest 2.0.0-alpha release and started updating a project we have. Unfortunately for us, the new API of parse didn't fit any of the use cases we have and couldn't find a way of emulating existing behavior.

I'm sure there are plenty of reasoning behind the change, but for all the pleasant updates we've found (fp module is a huge plus one!), this one really let us down. So much so that we are considering reverting and sticking to v1.

• The ability to "guess" the format pattern is quintessential:
  • if parsing dates coming from clients that you cannot truly trust on sending compliant data.
  • while defining generic/multi-purpose types of data (think GraphQL types/resolvers).
• Many popular libraries out there perform pattern discovery (like DateJS or moment). Not even Date.parse requires an explicit pattern.
• IMHO, the vast majority of the time, a developer would not have an idea as to what to define as baseDate. We have several instances of parse being used throughout our project and we always ended up writing new Date(), as the doc suggested. We found its usefulness somewhat dubious and, in our experience, undesired most of the time. Maybe it could be optional/defaulted?
• We found throwing because the length of arguments does not match the expected number to be a rather aggresive form of validation. Specially since date-fns/fp/parse and date-fns/parse are both named exactly the same (both in docs and the exported module) and it's an invitation to confusion:

Default module:

const { parse } = require('date-fns');
parse(new Date()); // <- Throws `TypeError: 3 arguments required, but only 1 present`

FP module:

const { parse } = require('date-fns/fp');
parse(new Date()); // <- Returns a curried function

With all that being said, we'd really like to continue using, testing and supporting next date-fns releases. Could someone give some advice on how to migrate from one version to the other while minimizing impact on projects? Any arguments that we could be passing to parse that would more closely resemble v1?

[leshakoss]

@nfantone
Hello, and thank you for your feedback!
Old parse was renamed to toDate

[nfantone]

@leshakoss Hi and many thanks for your fast response!

Very glad to read that you kept the functionality. May I ask the reason behind the name swapping? Wouldn't it have been easier (as far as API understanding and easiness of migration go) to keep parse the same and give the new parse a different name instead?

[nfantone]

@leshakoss Another conspicuous detail that we found are the new pattern tokens. Docs for v1 mention format defaults to YYYY-MM-DDTHH:mm:ss.SSSZ. But T, on v2, outputs milliseconds.

// v1
format(new Date('2018-01-01'));
// > '2018-01-01T00:00:00.000+00:00'

// v2
format('YYYY-MM-DDTHH:mm:ss.SSSZ')(new Date('2018-01-01'))
// > '2018-01-01151476480000000:00:00.000Z'

What should the corresponding pattern be now?

[leshakoss]

@nfantone I am inclined to reply "for historical reasons" because it was decided two years ago, but it would be unfair to say that about a not yet released version. But it certainly feels like ancient history for me by now :-)

Basically, parse sounds like an antonym of format so for v2 we decided to name that the function that does the opposite of what format does. Sadly, what was parse before had to be renamed to something else. Internally, we use the old parse to convert the date arguments to the instance of Date: https://github.com/date-fns/date-fns/blob/master/src/addDays/index.js#L29 so it makes sense to rename it to something like toDate.

In a lot of aspects, v2 is what date-fns was supposed to be from the start, which means that we made a lot of breaking changes while ignoring the old API in favour of cleanliness and self-consistency of the new API. We are working on v2 for a quite a long time, and we decided that we don't want to carry the old API mistakes over to the new version.

For your second question, the pattern would be "yyyy-MM-dd'T'HH:mm:ss.SSSXXX". Note the lower case of yyyy — it is important. Sorry for the confusion. It is definitely a blind spot of out documentation and we're trying to find a way to fix it before the stable release.

[kossnocorp]

@nfantone I hope @leshakoss did address your questions. If you still have some more — don't hesitate to ask. Also, thank you for trying v2, it's much appreciated.

[green-arrow]

@leshakoss - It looks like toDate in v2 doesn't take a string, and recommends using parseISO for strings. The problem is that client input will most likely not be in ISO format. I don't see a function that takes in an arbitrary string and guesses the input and returns a Date. Am I missing something or is there another recommended approach for parsing client input as a Date?

[dkozickis]

@green-arrow you can just use parse

[green-arrow]

@dkozickis - The parse method requires a format to be passed in. Since this is client input, I have no known format, so parse will not work.

It doesn't appear that there are any public methods in date-fns that will attempt to parse an arbitrary user input into a Date

function parseArbitraryString(value: string): Date

[kossnocorp]

@green-arrow the old parse essentially equals new Date or Date.parse, so you can keep using those.

[Qvatra]

@kossnocorp

@green-arrow the old parse essentially equals new Date or Date.parse, so you can keep using those.

that is not crossbrowser solution as new Date or Date.parse work differently per browser.
for example Date.parse('1986-03-05 10:12:05') will not be parsed in safari but will be parsed in chrome

so latest versions of date-fns in my opinion missing important parse functionality.

does anyone know a working workarounds (except using version < v2)?

[leshakoss]

I feel like you are talking about two different things in this thread 🙂

• old parse is now parseISO
• parse of arbitrary strings is not yet implemented, and it's probably another issue 😀

[randomhash]

@leshakoss
I think he speaks about the same topic
you can simply check description for old function and new ones to see the problem
https://date-fns.org/v2.14.0/docs/parse
https://date-fns.org/v1.30.1/docs/parse

[nfantone]

@leshakoss

old parse is now parseISO

Except it's not. I've read this several times in this thread now and I believe it's misleading people. Old parse would support many patterns and inputs the new parseISO does not.

• date-fns@1.30.1

const parse = require("date-fns/parse")
parse('2020/05/05'); // Tue May 05 2020 00:00:00 GMT+0100

• date-fns@2

const parse = require("date-fns/parseISO")
parse('2020/05/05'); // Invalid Date

It was also stated before that "old parse is now toDate" or that it is "essentially Date.parse". Both of those statements are equally untrue as some others have found and pointed out.

⚠️ As of v2.17.0, there is no drop-in replacement for old parse.

parse of arbitrary strings is not yet implemented

Well - it was implemented before. Despite its shortcomings, it was old parse. From its original docs:

If an argument is a string, the function tries to parse it.

Which sounds exactly what people seem to be requesting.

[kossnocorp]

@nfantone the things are much more straightforward than discussed in the thread. Sorry for the confusion.

Simply use new Date() or Date.parse() to parse free-form strings. This is how old parse worked and unless you know why you need parse/parseISO/parseJSON/etc, you should not use any of that.

new Date('2020/05/05')
//=> Tue May 05 2020 00:00:00 GMT+0800 (Singapore Standard Time)

Date.parse('2020/05/05')
//=> 1588608000000

As @Qvatra noted, this is not consistent across browsers (but will work for you example) and v1 didn't fix that, and this is why we removed it in the first place. It's impossible to write a universal string parser and this inconsistency is the evidence of that.

If you have to parse something like 1986-03-05 10:12:05 (I highly recommend using ISO 8601 or any other standard to store dates as strings), you can do it with help of parse or even better simple custom regexp like /(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})/.

[nfantone]

I understand where you are coming from. I do believe, however, that nobody is expecting date-fns (or any library, for that matter) to provide a "universal string date parser".

You mentioned "storing dates" - as I see it, that's not the actual focus here. The main issue is about being able to interpret strings that may come from unpredictable sources, typically user input. In the past (or if using some other popular libraries, like moment), you'd be able to use parse (or wrap it in moment) just for that. While not perfect, you could rely on having something to delegate parsing to. With latest versions of date-fns, we've lost that ability. I, personally, find myself writing over and over more or less the same kind of logic, wrapping date-fns functions, to get somewhere close to where old parse would leave me.

Simply use new Date() or Date.parse() to parse free-form strings. This is how old parse worked.

Apologies for being repetitive here, but I'd like to raise this once more for people coming into this discussion: old parse did not work like new Date() or Date.parse - that's very easily shown.

const parse = require("date-fns/parse"); // v1.30.1
parse('20141001'); // Wed Oct 01 2014 00:00:00 GMT+0100

Date.parse('20141001'); // NaN
new Date('20141001'); // Invalid Date

In addition, old parse,

• offers a single API for numbers and strings;
• would normalize output by always returning Date instances;
• would accept skipping digits in an input through options.additionalDigits;
• would account for parsing timezone if present;
• had a curried version.

Not sure why the insistence on the point of substituting date-fns~parse with Date.parse or new Date, when the mechanics are simply not the same.

[green-arrow]

I understand where you are coming from. I do believe, however, that nobody is expecting date-fns (or any library, for that matter) to provide a "universal string date parser".

fwiw, this is one of the big reasons we used this library and haven’t upgraded to the latest version. I’m not interested in bringing in another library (ramda) to get back functionality that already existed.

Is it not possible to add in a tryParse method that takes care of this? The code existed at one point, and I don’t understand why that functionality is no longer desired in the library. Was it too much code for not enough worth? Too difficult to maintain?

[nfantone]

I’m not interested in bringing in another library (ramda) to get back functionality that already existed.

There's absolutely no need for bringing ramda, or anything other than date-fns, to implement what you need.

[joshuat]

@kossnocorp Can we remove this as the selected answer since, as shown by @nfantone above, old parse does not work like new Date() or Date.parse?

[nfantone]

I'd like to share my approach to replacing (and even go beyond) the functionality that previous date-fns~parse version offered. This is what I find myself using most of the time when I cannot reliably trust the source of a date string. It uses ramda for laying out the logic, but I believe it's pretty readable as-is.

/**
 * Tries to parse the given input as a `Date`.
 * - If the input is a numerical string (`[0-9]` digits only), it'll be coerced into a number
 * and treated as milliseconds since the epoch.
 * - If the input is a non-numerical `String`, `date-fns~parseJson` will be used to parse it as an ISO 8601 date.
 * - If the input is a non-numerical `String` and `date-fns~parseJson` fails, a series of supported format
 * strings will be attempted until one results in a valid `Date` (or non succeed).
 * - If the input is a `Number`, it'll be passed as-is to the `Date` constructor.
 * - If the input is already a `Date`, it'll be returned without modifications.
 * - Otherwise, `Invalid date` is returned.
 *
 * @function
 * @param {string|number|Date} dt The value to parse.
 * @returns {Date} The parsed date.
 */
const tryParseJson = cond([
  [isNumber, ms => new Date(ms)],
  [
    isString,
    ifElse(
      // Is it a numerical string?
      test(/^\s*\d+\s*$/),
      compose(ms => new Date(ms), Number, trim),
      // Replace any `/` with `-` to improve `date-fns~parseJson` chances of
      // successfully parsing the date
      compose(dt => tryParseDate(dt), replace(/\s*\/+\s*/g, '-'))
    )
  ],
  [instanceOf(Date), identity],
  [T, () => new Date(NaN)]
]);

The private tryParseDate function just folds the input by attempting to apply different supported format patterns and returning the first that yields a valid Date.

/**
 * Supported `date-fns/parse` format strings. Patterns will be attempted sequentially
 * until one of them returns a valid `Date` or all were exhausted. ISO 8610 format is always
 * included (i.e.: there's no need to explicitly add it below as a supported format string).
 *
 * @type {string[]}
 */
const patterns = Object.freeze(['MM-dd-yyyy']);

[nonbob]

I'm in a similar spot. date-fns is a good match for everything we're doing except free-form date parsing. After some poking around, I've settled on any-date-parser as the tool for this - it seems to be popular, flexible, well-designed and well-maintained.