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
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.
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.
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.
🔍 Search Terms
function documentation jsdoc NOT-FOUND
✅ Viability Checklist
⭐ Suggestion
The documentation of
String.indexOfshould 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
To get more useful information from the language server while writing TS, which reduces interruptions / context switching, allowing the user to be more productive.
The user has to stop and think about the not found case. Users coming from other languages might expect the
indexOffunction to maybe returnnullorundefinedor throw an exception when the substring is not found.In cases where I've personally been faced with this issue in the past, I quickly used a js console to check the behaviour.