Add d.ts for Intl.RelativeTimeFormat

[DmitryMakhnev]

Intl.RelativeTimeFormat proposal was moved to stage 4 and included into ecma402 finished proposals

Fixes part of #29129

[msftclas]

All CLA requirements met.

[orta]

👋 hi, you submitted this just as we were preparing for a release, and we get really slow on 3rd party PRs during that period. We're now on 3.9 for master and I think this looks good. You're welcome to ping me on any Intl PRs you're looking at.

I've only got one request, can you consider adding some JSDoc comments to the user facing parts of the API?

[DmitryMakhnev]

👋@orta
Thank you so much for information! 🙏

Could you give me the rules for these JSDoc comments or link to example of it in the current code base?

[orta]

There aren't any rules - it's just that you see these in your editor, and it's good to provide context for users. For example, I took some of the spec text and applied the useful bits of text to the prominent user-facing parts of the API

interface RelativeTimeFormat {
    /**
     * Formats a value and unit according to the locale and formatting options of this Intl.RelativeTimeFormat object.
     *
     * While this method automatically provides the correct plural forms, the grammatical form is otherwise as neutral as possible. It is the caller's responsibility to handle cut-off logic such as deciding between displaying "in 7 days" or "in 1 week". This API does not support relative dates involving compound units. e.g "in 5 days and 4 hours".
    */
    format(
        value: number,
        unit: RelativeTimeFormatUnit,
    ): string;

    /**
     *  A version of the format method which it returns an array of objects which represent "parts" of the object, separating the formatted number into its constituent parts and separating it from other surrounding text.
     */
    formatToParts(
        value: number,
        unit: RelativeTimeFormatUnit,
    ): RelativeTimeFormatPart[];
    
    resolvedOptions(): ResolvedRelativeTimeFormatOptions;
}

[sandersn]

This PR hasn't seen any activity for quite a while, so I'm going to close it to keep the number of open PRs manageable. Feel free to open a fresh PR or continue the discussion here.

[DmitryMakhnev]

Hi @sandersn. Sorry for big delay. I added docs by @orta's request.
Can you reopen this pull request?

[sandersn]

Sure.

1. @DmitryMakhnev can you merge with master to get rid of the merge conflict?
2. @orta can you review the newly-added documentation?

[orta]

These look great!

[DmitryMakhnev]

@sandersn

1. @DmitryMakhnev can you merge with master to get rid of the merge conflict?

Done.

[DmitryMakhnev]

@sandersn @orta
Should I do anything else for this PR?

[orta]

Nope, this is good to go! Thanks

[kripod]

Whoa, I just checked why Intl.RelativeTimeFormat was throwing an error on me and ended up at this issue right this time. Great job on getting this done, thank you! 🙏

[kwasimensah]

What's the ETA for this being in the published typescript npm package?

[sandersn]

@kwasimensah Should be 4.0. See #38510 for details.

[Licen-it]

@kwasimensah Should be 4.0. See #38510 for details.

@sandersn any news on the ETA for having this published? Just checked latest version and it's still not there.

[barakplasma]

@Licen-it
It's in Typescript 4.0.5 - 4.2.3 already, but you have to update your tsconfig.json to target ES2020. Here's an example:

const timeFormatter = new Intl.RelativeTimeFormat(['en', 'fr', 'es', 'it', 'pt'], { numeric: 'always' });

Playground Link

[Licen-it]

@Licen-it
It's in Typescript 4.0.5 - 4.2.3 already, but you have to update your tsconfig.json to target ES2020. Here's an example:

const timeFormatter = new Intl.RelativeTimeFormat(['en', 'fr', 'es', 'it', 'pt'], { numeric: 'always' });

Playground Link

Thanks...didn't think about changing the target in tsconfig. Thanks