Ensure forward-compatibility of callbacks

Suggestion

🔍 Search Terms

strict callback arguments, too many arguments warning, option

✅ Viability Checklist

My suggestion meets these guidelines:

• 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 feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Edit: My original suggestion was unworkable. This is a second attempt.

const nextFrame = new Promise(requestAnimationFrame);

The above results in requestAnimationFrame being called with two arguments rather than the one it accepts. This is fragile, since, in future, a second argument may be added to requestAnimationFrame which makes the above code behave differently.

This problem is worse when it comes to browser-provided functions, as those change with new browser versions, and don't rely on an app redeploy.

This can be worked around using never:

declare function requestAnimationFrame(callback: FrameRequestCallback, _: never): number;

…but it makes for a messy auto-complete, as the 'never' arg shows up.

A solution would be some way to mark a function as "cannot be assigned to a function type with more parameters". This would allow library authors to make this assertion if they want to reserve additional params for future use, and this assertion could be added to DOM functions like requestAnimationFrame.

💻 Use Cases

I wrote a blog post about the risks with this pattern, including a section on how TypeScript doesn't prevent it https://jakearchibald.com/2021/function-callback-risks/

Start with the requestAnimationFrame examples and review the linked TypeScript Design Goals and callback-argument behavior. Compare the never-parameter workaround with the proposed function-type assertion; done would require an agreed design that preserves existing runtime behavior and specifies how library declarations are authored and checked.