Support promise-like types in contextual return type of async function

[Ron Buckton (rbuckton)]

This changes the contextual type we use for a return expression in an async function. Prior to this change, we would infer {} for the type argument to Promise below:

interface Obj { key: "value"; }

function fn1(): Promise<Obj> {
    // ok: return expression is contextually typed to 'Promise<Obj>' so 'T' in 'Promise<T>' 
    // is contextually typed to 'Obj'.
    return new Promise(resolve => { resolve({ key: "value" }); });
}

async function fn2(): Promise<Obj> {
    // ok: return expression is contextually typed to 'Obj'.
    return { key: "value" }; 
}

async function fn3(): Promise<Obj> {
    // error: '{}' is not assignable to type 'Obj'.
    // return expression is contextually typed to 'Obj' so 'T' in 'Promise<T>' is not
    // contextually typed and becomes '{}'
    return new Promise(resolve => { resolve({ key: "value" }); });
}

This is because we use the "awaited type" Obj for the return type Promise<Obj> as the contextual type. With this change, we use Obj | PromiseLike<Obj> as the contextual type:

interface Obj { key: "value"; }

function fn1(): Promise<Obj> {
    // ok: return expression is contextually typed to 'Promise<Obj>' so 'T' in 'Promise<T>' 
    // is contextually typed to 'Obj'.
    return new Promise(resolve => { resolve({ key: "value" }); });
}

async function fn2(): Promise<Obj> {
    // ok: return expression is contextually typed to 'Obj | PromiseLike<Obj>'.
    return { key: "value" }; 
}

async function fn3(): Promise<Obj> {
    // ok: return expression is contextually typed to 'Obj | PromiseLike<Obj>' so 'T' in 
    // 'Promise<T>' is contextually typed to 'Obj'
    return new Promise(resolve => { resolve({ key: "value" }); });
}

Fixes #24629, #27001

[Ron Buckton (rbuckton)]

Wesley Wigham (@weswigham): I opted to just continue using PromiseLike as opposed to some other construct for the time being.

[Daniel Rosenwasser (DanielRosenwasser)]

Does this fix #27001 too?

[Ron Buckton (rbuckton)]

Daniel Rosenwasser (@DanielRosenwasser): I don't think it does, but I will check that tomorrow.

[Ron Buckton (rbuckton)]

Daniel Rosenwasser (@DanielRosenwasser): It does now, the fix for #27001 was easy to accomplish with the changes in this PR since you need the same behavior (union the awaited type with a PromiseLike of the awaited type).

[Ron Buckton (rbuckton)]

This change is postponed to 3.2, you can find the PR against master here: #27270