Extend documentation of String.indexOf to mention what happens when substring is not found

[Pascal-So]

🔍 Search Terms

function documentation
jsdoc
NOT-FOUND

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

The documentation of String.indexOf should mention that -1 is returned when the substring is not found.

📃 Motivating Example

The documentation for indexOf on arrays already mentioned that the method returns -1 when the value is not found:

But for strings, this information was missing thus far:

Of course the user would have been able to puzzle this together by seeing that the return type is just number, not something like number | undefined, thus allowing them to figure out that the sentinel value probably must be -1. Nevertheless, having to stop and think about this is unnecessary friction for people who don't remember this fact by heart, for example people who jump between programming languages a lot.

💻 Use Cases

1. What do you want to use this for?

To get more useful information from the language server while writing TS, which reduces interruptions / context switching, allowing the user to be more productive.

2. What shortcomings exist with current approaches?

The user has to stop and think about the not found case. Users coming from other languages might expect the indexOf function to maybe return null or undefined or throw an exception when the substring is not found.

3. What workarounds are you using in the meantime?

In cases where I've personally been faced with this issue in the past, I quickly used a js console to check the behaviour.