Annotate immediately-invoked functions for inlining flow control analysis

[RyanCavanaugh]

Per #9998 and its many offshoots, we have problems analyzing code like this

let x: string | number = "OK";
mystery(() => {
 x = 10;
});
if (x === 10) { // Error, we believe this to be impossible 
}

The problem is that we don't know if mystery invokes its argument "now" or "later" (or possibly even never!).

The converse problem appears during reads:

let x: string | number = ...;
if (typeof x === 'string') {
 // Error, toLowerCase doesn't exist on string | number
 let arr = [1, 2, 3].map(n => x.toLowerCase());
}

Proposal is to allow some form of indicating that the function is invoked immediately, e.g.

declare function mystery(arg: immediate () => void): void;

This would "inline" the function body for the purposes of flow control analysis

[tinganho]

I suggested something similar in #7770 (comment).

Though after thinking about it, I thought it was better to annotate callbacks as non-immediate #10180 (comment):

Immediate case:

function doSomething(callback: () => any) {
 callback();
}

function fn(x: number|string) {
 if (typeof x === 'number') {
 doSomething(() => x.toFixed()); // No error.
 }
}

Non-immediate case:

function doSomething(callback: async () => any) {
 setTimeout(callback, 0);
}

function fn(x: number|string) {
 if (typeof x === 'number') {
 doSomething(() => x.toFixed()); // Error x is 'number|string'
 }
}

Sync callbacks is only assignable to sync callbacks and vice versa for Async callbacks:

function doSomething(callback: () => any) {
 setTimeout(callback, 0); // Error a sync callback is not assignable to an async one.
}

function doSomething1(callback: () => any) {
 callback();
}
function doSomething2(callback: () => any) {
 doSomething1(callback); // No error
}

Though re-using async keyword as a type annotation might conflict with the meaning of async declarations in async/await which makes a function returning a promise. An alternative is to use nonimmediate, though I think that keyword is too long.
.

[yortus]

For reference, there was also some discussion of deferred and immediate modifiers in #9757.

[yortus]

Ryan Cavanaugh (@RyanCavanaugh) you commented here that implementing this kind of type modifier would require a massive architectural change. Is that still the case?

[kitsonk]

For completeness #11463 proposed an alternative solution for this problem. Since that was just an "escape hatch" and this is an instruction to CFA to better understand the code, I would prefer this.

The use case where we have run into this is converting a Promise into a deferral and having to generate a noop function to get around strict null checks:

const noop = () => { };

function createDeferral() {
 let complete = noop;
 let cancel = noop;
 const promise = new Promise<void>((resolve, reject) => {
 complete = resolve;
 cancel = reject;
 });

 return { complete, cancel, promise };
}

const deferral = createDeferral();

Though after thinking about it, I thought it was better to annotate callbacks as non-immediate

While it is more "burden" on the developer, in the sense of "strictness" I still think it is safer to assume the worst (that it might not be immediate). Like with strictNullChecks overall, so I would be only in favour of an annotation that indicates that it is immediate.

[kitsonk]

Also 🚲 🏠 while it might be a tad bit confusing, why not sync to be a counter to async:

interface PromiseConstructor {
 new <T>(executor: sync (resolve: (value?: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void): Promise<T>;
}

[tinganho]

I forgot to mention my points on why I think annotating it as async rather sync.

1. Annotating it as immediate or sync means nearly all callbacks needs to be annotated, assuming most callbacks is sync. Async is the exception, sync is the rule.
2. We already annotate async functions(as in async/await) as async. Sync functions has no annotations. So to keep consistent with the current design we should not annotate with immediate.

Maybe to minimize confusion that async only accept a Promise returning callback, a deferred keyword might be more desirable.

[yortus]

I think to cover all cases of "used before assigned" checks you would need both a deferred and an immediate modifier.

The deferred modifier would be needed in cases like Kitson Kelly (@kitsonk) reported here where a non-immediately invoked callback references a variable that is initialized later in the calling scope (i.e. lexically later but temporally earlier). immediate wouldn't help with that (unless the compiler assumes that an un-annotated callback must be deferred).

[yortus]

What about the interplay between immediate vs deferred invocation and synchronous vs asynchronous functions, which can occur in any combination?

function invokeImmediately<R>(cb: () => R) {
 return cb();
}

let p = invokeImmediately(async () => {
 console.log(1);
 await null;
 console.log(2);
});

console.log(3);

p.then(() => {
 console.log(4);
});

// Output:
// 1
// 3
// 2
// 4

Here we have immediate invocation of an asynchronous function (fairly common in real code). As shown by the output, the async function executes synchronously until it either awaits or returns. Then the rest of the function is deferred to another tick.

It would be pretty hard to do accurate CFA in this case with types and assignments involved, since some of the callback happens 'in line' with the surrounding code and some execution is deferred until later.

[novemberborn]

Tingan Ho (@tinganho),

Annotating it as immediate or sync means nearly all callbacks needs to be annotated, assuming most callbacks is sync. Async is the exception, sync is the rule.

In the new Promise() example, the executor function implements the Revealing Constructor Pattern. I wouldn't classify it as a callback — the constructor guarantees it's invoked immediately. Callbacks are often invoked in a future turn.

Troy Gerwien (@yortus),

Here we have immediate invocation of an asynchronous function (fairly common in real code). As shown by the output, the async function executes synchronously until it either awaits or returns. Then the rest of the function is deferred to another tick.

It would be pretty hard to do accurate CFA in this case with types and assignments involved, since some of the callback happens 'in line' with the surrounding code and some execution is deferred until later.

Not knowing anything about how CFA is actually implemented, presumably it could still make a prediction up until the first await statement?

For both your points it would seem that sync doesn't quite cover the nuance of immediate invocation, so immediate may be a better keyword.

[tinganho]

Mark Wubben (@novemberborn) I'm assuming though no annotation is immediate?

[novemberborn]

Tingan Ho (@tinganho),

I'm assuming though no annotation is immediate?

How do you mean?

[kitsonk]

Still think it would be dangerous to have implicit immediate. There are many callbacks where it doesn't matter and if it does matter, the developer should be explicit in order for CFA not to make assumptions.