Typescript: Missing specific types in DateTimeFormatOptions

[ksoldau]

TypeScript Version: 3.7.3

Search Terms: Intl.DateTimeFormat, DateTimeFormatOptions, date format types

Code

// A *self-contained* demonstration of the problem follows...
// Test this by running `tsc` on the command-line, rather than through another build tool such as Gulp,
(See below)

DateTimeFormatOptions interface missing specific types.
https://github.com/microsoft/TypeScript/blob/408b17649a1197a52f68fcb49b8c2f1eeac13668/src/lib/es5.d.ts#L4253-L4267

Expected behavior:
I would expect the types to match what's listed here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

  interface DateTimeFormatOptions {
        localeMatcher?: 'lookup' | 'best fit';
        weekday?: 'long' | 'short' | 'narrow';
        era?:  'long' | 'short' | 'narrow';
        year?: 'numeric' | '2-digit';
        month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
        day?: 'numeric' | '2-digit';
        hour?: 'numeric' | '2-digit';
        minute?: 'numeric' | '2-digit';
        second?: 'numeric' | '2-digit';
        timeZoneName?: 'long' | 'short';
        formatMatcher?: 'basic' | 'best fit';
        hour12?: boolean;
        timeZone?: string; // this is more complicated than the others, not sure what I expect here
    }

Actual behavior:

 interface DateTimeFormatOptions {
        localeMatcher?: string;
        weekday?: string;
        era?: string;
        year?: string;
        month?: string;
        day?: string;
        hour?: string;
        minute?: string;
        second?: string;
        timeZoneName?: string;
        formatMatcher?: string;
        hour12?: boolean;
        timeZone?: string;
    }

Playground Link:

Related Issues:
Couldn't find any

[RyanCavanaugh]

Would be a breaking change; we'll have to discuss.

[andreipfeiffer]

I would expect these to break only if you misspelled an option, which won't work anyway.
I'm just curious what other Breaking Changes are you thinking about @RyanCavanaugh .

[johan]

Would be a breaking change; we'll have to discuss.

I'd love to see this discussed, or move forward. To me, moving runtime exceptions out of js into hard compile-time errors in typescript is one of the strongest points of typescript to begin with.

[sandersn]

Here's a breaking change:

function makeOptions(matcher: string): DateTimeFormatOptions {
  return {
    year: 'numeric',
    formatMatcher: matcher
  }
}

The author of makeOptions will have to propagate the stricter type of formatMatcher out, possibly breaking its consumers.

[johan]

So… …is there some process where you tag all PR:s with fixes for under-specified types like this by something like "improvement for next major version bump", so you can land a busload of such fixes in batch whenever you decide that enough of those have piled up since last time, or that you are just about to release a major version bump anyhow, because of some non-type-related fix to typescript itself?

If not, I think it would be a good process to introduce, so we don't get stuck forever with a lot of DOM / TC39 types that are a notch or two better than the any type.

[ShuiRuTian]

Maybe you could write like "x"|"y"|string
And there would be no break changes.
What we need to do is to wait #33471.

[johan]

Maybe you could write like "x"|"y"|string
And there would be no break changes.

Much or most of the value a strict type here brings _is_ in flagging illegal string values as illegal. The documentation aspect of calling out a few explicitly legal values is nice, but we'd miss the catching bugs at compile time aspect for everything else that the browser definitely explodes on.

[mhuggins]

Running into this issue for dateStyle and timeStyle options as well.

[lgrahl]

Running into this issue for dateStyle and timeStyle options as well.

I wonder if these are even related. Should we create a separate issue for that? Because those two properties are just missing entirely.