Narrow unnecessarily ambiguous Date.getMonth return type.

The specified behaviour of Date.getMonth implies that it will always return a number from 0 - 11 inclusive.

Hence annotating the return type (source) as number is unnecessarily ambiguous.

If it would be accepted, I would like to open a PR to narrow the type down to the 12 values from 0 - 11.

🔍 Search Terms

Date
getMonth
ambiguous type
narrowing type

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
  • the set of 0..11 inclusive is also part of the set number. Hence this narrowing is not breaking.
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

If it would be accepted, I would like to open a PR to narrow the type down to the 12 values from 0 - 11.

interface Date {
  getMonth(): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
}

📃 Motivating Example

I think this is a very small and self-explanatory enhancement. The benefit here being that the type better describes the behaviour.

Whereas before "the set of things this function could do" was much wider. Now by reading the type (even if you didn't know the name of the method) you could rest assured that you are handling all cases correctly.

Secondly, by looking at the type, one need not read documentation to know that January is 0, not 1 as many JS developers probably learned the hard way.

💻 Use Cases

Make types represent the behaviour of a function more accurately.

Beginne in lib/lib.es5.d.ts etwa bei Zeile 751, wo die Deklaration von Date.getMonth verknüpft ist. Vergleiche den deklarierten Rückgabetyp mit dem angegebenen Verhalten von 0–11 und prüfe den im Issue vorgeschlagenen Literal-Union-Typ. Als erledigt gilt die Aufgabe, wenn die Deklaration alle möglichen Monatswerte korrekt widerspiegelt und die relevanten TypeScript-Prüfungen erfolgreich sind.