Intl format relative

[tan75]

New Feature

Implement intlFormatDistance for date-fns

[kossnocorp]

Great job, code and tests look good.

Besides review comments I have few requests:

• Please rewrite it to TypeScript. If you never worked with it or just need advice - ping me, I'll help you.

• Let's change the behavior. You can see that our formatDistance picks the most appropriate unit depending on the distance. The less the distance the smaller the unit. Let emulate this algo but allow users pass unit as well. So that we can move unit to options and make it optional.

  Here's the algo I suggest (tell me if you have other ideas)

  • Less than minites: second
  • Less than hour: minute
  • Less than day: hour
  • Less than week: day
  • Less than quarter: month
  • Less than year: quarter
  • More or equal to year: year

• Let's rename the function to intlFormatDistance and make API similar to https://date-fns.org/v2.16.1/docs/formatDistance. Initially, I wanted to keep it similar to Intl API, but realized that it will confuse our users.

• Add a second date argument like in formatDistance and use it in calculations instead of new Date().

• Add another function variation intlFormatDistanceToNow similar to https://date-fns.org/v2.16.1/docs/formatDistanceToNow that uses Date.now() as the second argument.

[tan75]

WIP:

• intlFormatDistanceToNow
• Test Cases

[kossnocorp]

Good progress. Please format the code using Prettier and address my suggestions.

[kossnocorp]

Instead of forcing users to read MDN, we can add either example for each option variant or a table to the description.

[tan75]

WIP

[tan75]

is this ok ?
e.g. "hi": Hindi (language) or "de-AT": German (language) as used in Austria (region)

[robertvanhoesel]

Awesome work! While working on my own implementation I found a gotcha with numeric: 'auto' which might be wise to address (or at least mention in documentation). Because RelativeTimeFormat only takes a value and unit, it has no context/awareness of the actual difference in years.

When I compare two dates, today (Feb 24, 2020) and almost 2 years ago (March 30, 2019).dateFns.differenceInYears will return '-1', which is correct, it is not 2 years ago, just one and a bit.

new Intl.RelativeTimeFormat('en', { 
  numeric: "auto" 
}).format(-1, 'year')
// 'last year'

The majority of Intl implementations will return last year in response to above code, which to humans is just incorrect when we are aware of comparing 2021 and 2019, which was not 'last year'.

https://codesandbox.io/s/musing-river-90m6t?file=/src/index.ts

Since your proposed implementation always takes two dates, you could prevent this error from occurring by having additional checks in the unit resolver that only applies 'auto' when the two compared years differ exactly 1 year, and force 'numeric' in all other cases.

@kossnocorp It occurs to me that maybe this more opinionated/smart logic should be in Intl.RelativeTimeFormat instead? Alongside rounding instead of flooring (i.e. 1 year 9 months becomes 2 years) and optional joining in localized time?

[robertvanhoesel]

Or... split this implementation to:

• intlFormatDistanceStrict which uses numeric: always and takes 'ceil', 'round', 'floor' arguments.
• intlFormatDistance which uses numeric: auto where applicable and generally rounds the years.

My 2cts would be to avoid providing the exact arguments of Intl.RelativeTimeFormat and allow room to algorithmically use the right unit and formatting options.

An other thing to review would be wether outputting 'quarters' by default makes sense to most implementations. Date-fns is slightly opinionated in its other implementations (i.e. when to include time in 'relative' and never returning '4 quarters ago' in formatDistance), providing that as an option to control would make this more useful, otherwise I would find myself going back to first comparing the dates, then calling intlFormatDistance with unit months when I know we're talking about 3-12 months distance.

[kossnocorp]

Some more new comments

[kossnocorp]

@robertvanhoesel, this is an excellent point. Adding special logic for numeric: 'auto' and -1/1/0 makes sense at first glance, not only for year but also month and quarter. However, I'm afraid it's a slippery slope. For instance, this is not a problem for minute and hour in English, but I imagine it might be a case for other languages or Intl implementations or wise versa might not have an issue with year.

Using ceil/floor won't help because rounding 4 months to 0 years while working with December will produce this year and its inaccuracy.

I think instead we can use differenceInCalendarDays, differenceInCalendarWeeks, differenceInCalendarMonths and differenceInCalendarYears unless numeric is set to always. Then with your example, you'll get -2 "2 years ago".

We also should make numeric: 'auto' the default value because such:

new Intl.RelativeTimeFormat('en').format(0, 'year')
//=> "in 0 years"

..it is not a good default option. However, I'm not sure what are side effects of this change. @tan75 could you please explore that?

@robertvanhoesel @tan75 @leshakoss @rikkalo WDYT?

[tan75]

@kossnocorp
If numeric: auto is a default option, then when adding style: short it falls back to numeric: always (if the result is 1 day or 1 month or 1 year) e.g.:

const result = intlFormatDistance(
      new Date(1985, 4, 5, 10, 30, 0),
      new Date(1985, 4, 4, 10, 30, 0),
      { style: 'short' }
) //=> 'in 1 day' instead of 'tomorrow'

however it looks like explicitly adding numeric: auto when calling the function will fix it (even though we know that's the case by default):

    const result = intlFormatDistance(
      new Date(1985, 4, 5, 10, 30, 0),
      new Date(1985, 4, 4, 10, 30, 0),
      { style: 'short', numeric: 'auto' }
   )//=> 'tomorrow'

The same happens to 1 month and 1 year
Test

[tan75]

hi @robertvanhoesel
my tests are failing on this Error

Any ideas why?

[robertvanhoesel]

@tan75 the typescript compiler needs to know that you are using es2020.intl definitions. In .tsconfig you should add es2020 to the target. Also, this is a good case to catch, as older browser will also not know about this constructor and fail.

[robertvanhoesel]

I use the below logic to check wether the API is available in the browser.

const IntlRelativeSupported = typeof Intl.RelativeTimeFormat === 'function';

[tan75]

@tan75 the typescript compiler needs to know that you are using es2020.intl definitions. In .tsconfig you should add es2020 to the target. Also, this is a good case to catch, as older browser will also not know about this constructor and fail.

Thank a lot for your answer! Do you mean tsconfig.json? I added it here
tsconfig
But is it still failing:
Run

[leshakoss]

⭐️

[kossnocorp]

👏

[orhangazi]

Hi, I can't pass this error. I am using react native version is 0.68.2, react version is 17.0.2 and using date-fns version is 2.29.3. Code reference doc here. I am using also intl version is 1.2.5. Maybe this is to cause the error?

I check with this code

const IntlRelativeSupported = typeof Intl.RelativeTimeFormat === 'function'
console.log("IntlRelativeSupported: ", IntlRelativeSupported) --> output: false. what should I do?

Codes:

import { format, formatDistance, formatRelative, subDays, intlFormatDistance } from 'date-fns'
.....
lastMessageDeliveryDate = intlFormatDistance(
			new Date(1986, 3, 4, 11, 30, 0),
			new Date(1986, 3, 4, 10, 30, 0)
		)

I am getting this error:

[hrdyjan1]

Typo - first

[JestemTrzcinska]

Hi, I also encountered this problem. The same result as here.
It works good on newer iOS simulators, but it doesn't on Android simulators and old iPhone simulators like iPhone 6s with iOS 13.7.

Any workaround? I need something exactly like intlFormatDistance with its "... ago" etc.

Making if statement is not good way for me, because I need it to work on every devices.

"date-fns": "^2.29.3",
"react": "18.2.0",
"react-native": "0.71.6",