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/

[jakearchibald]

I don’t think my proposed solution is right, as it’d cause TypeScript to reject things like this:

const doubler = (n: number) => n * 2;
const mappedArray = numberArray.map(doubler);
const nextFrame = new Promise(requestAnimationFrame);

Line 2 is fine, because doubler is designed to be a callback to array.map, whereas line 3 is bad because requestAnimationFrame isn’t designed to be a callback to new Promise. However, in both cases there’s a function being called with an incorrect number of arguments.

Maybe this isn’t a typing problem, but I’ll leave this open in case anyone thinks of a better solution.

Edit: I’ve changed the solution in the OP.

[RyanCavanaugh]

most folks consider this to be a backwards compatible change:

I don’t know what to say except that those people are, factually, wrong. If a library author wants to keep the door open for adding parameters in the future in a way that isn’t a breaking change, they need to throw today if the incoming arity is too high.

By way of analogy, most library authors don’t treat “adding” a return value (e.g. going from implicit undefined to number) to be a breaking change, but if tomorrow console.log starts returning the number of characters printed like Array#push does, then this will break code like foo(console.log(x) || x). TypeScript stops you from doing that because we think the console.log return value is incidentally undefined (i.e., void) rather than intentionally undefined, and we get bug reports about this because people think it’s safe to rely on that function always producing a falsy value, and I think on balance they’re correct and we should change console.log’s return type to be undefined because that’s what’s in the spec today and, barring evidence to the contrary, the spec for any given function isn’t likely to change.

Ultimately the entire surface API of anything is subject to Hyrum’s law and I’m struggling to draw a bright line where things “could plausibly change” and “couldn’t plausibly change” in a way that doesn’t require arguing about thousands of different functions in the DOM and core lib to represent this. Do we think Array#forEach’s callback could ever gain an additional arg? Why / why not? How do I apply that logic elsewhere?