Styjun

Is there a way to properly tell flow that I'm returning a function with the same signature as the function I'm passed, but not exactly the same function ?

This is an example of a "once" wrapper which prevents a function from being called multiple times, it works but uses an any-cast internally to make flow give up, I'd like to get rid of that cast and have 100% coverage:

module.exports.once = /*::<F:Function>*/(f /*:F*/) /*:F*/ => 
 let guard = false;
 return ((function () 
 if (guard) return; 
 guard = true;
 return f.apply(null, arguments);
 /*:any*/) /*:F*/);
;

Okay, first things first.

Your return value can currently never match F without your casting through any because the signature of the function you're returning is not the same because it can return undefined where the original may not.

(comment syntax removed for readability)

module.exports.once = <F: Function>(f: F): F => 
 let guard = false;
 return ((function () // this function returns the return value of F or void
 if (guard) return; // returning void
 guard = true;
 return f.apply(null, arguments);
 : any): F);
;

But to start typing this, we're gonna need to break down that function generic a little bit.

First of all, let's not use Function as it's generally better if we don't:

However, if you need to opt-out of the type checker, and don’t want to go all the way to any, you can instead use Function. Function is unsafe and should be avoided.

Also, we're going to extract the types of the arguments and the return value so we can manipulate them independently and construct a return type. We'll call them Args and Return so they're easy to follow.

module.exports.once = <Args, Return, F: (...Array<Args>) => Return>(
 f: F
) ((...Array<Args>) => Return | void) => void`
 let guard = false;
 return function () 
 if (guard) return; 
 guard = true;
 return f.apply(null, arguments);
 ;
;

Now that we're taking into account that our new function might return void everything type checks fine. But of course, the return type of our once function will no longer match the type of the passed function.

type Func = (number) => string;

const func: Func = (n) => n.toString();

const onceFunc: Func = module.exports.once(func); // error!
 // Cannot assign `module.exports.once(...)` to `onceFunc` because
 // undefined [1] is incompatible with string [2] in the return value.

Makes sense, right?

So, let's discuss the signature of this function. We want our return value to have the same signature as the function we pass in. Currently it doesn't because we're adding void to the signature. Do we need to? Why are we returning undefined? How can we always return the same type from our onced function? Well, one option would be to store the return value from the single call to the function and always return the stored return value for subsequent calls. This would kind of make sense because the whole point is to allow multiple calls but not perform any of the functions effects. So this way we can avoid changing the interface of the function, so we really don't need to know whether or not the function has been called before.

module.exports.once = <Args, Return, F: (...Array<Args>) => Return>(
 f: F
): ((...Array<Args>) => Return) => 
 let guard = false;
 let returnValue: Return;
 return function () 
 if (guard) return returnValue; 
 guard = true;
 returnValue = f.apply(null, arguments);
 return returnValue;
 ;
;


type Func = (number) => string;

const func: Func = (n) => n.toString();

const onceFunc: Func = module.exports.once2(func);

One good question to ask at this point would be, why do the types match even if we're not technically returning exactly F? The answer to that is because functions in flow are structurally typed. So if they have the same arguments and return value, their types match.