Type corrections for Promise to adhere to Promises/A+ standard

[TorstenStueber]

The type definition for promises need to be changed in two ways in order to adhere to the Promises A+ specification:

1. The return type of then must be PromiseLike<T|U> (for PromiseLike) and Promise<T|U> (for Promise), respectively. This is due to rule 2.2.7.3 in the spec: if the argument onfulfilled of then is not defined, then the promise returned by then must be fulfilled with the same value as the originating promise – however, this value is of type T.
2. The type of value of the argument onfulfilled of then in the interface PromiseLike must be T | PromiseLike<T> instead of T. This is partially due to rule 2.3.3.3.1 of the spec: the value y can be of type T | PromiseLike<T> instead of T only. Unfortunately, rule 2.3.3.3.1 and the entire Promises A+ standard does not explicitely state that y is also allowed to be a PromiseLike<T>. However, the Promises/A+ Compliance Test Suite will fail if y is assumed to be only of type T and not T | PromiseLike<T> (see test case 'y is a thenable' in https://github.com/promises-aplus/promises-tests/blob/master/lib/tests/2.3.3.js).

Remark: the type of value of the argument onfulfilled of then in the class Promise must be only T, though.

For references see my repository, an implementation of the Promises A+ spec in TypeScript – in this project Promise is named Tomise and PromiseLike is referred to as Thenable.

Fixes #

[msftclas]

Hi @TorstenStueber, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution!

In order for us to evaluate and accept your PR, we ask that you sign a contribution license agreement. It's all electronic and will take just minutes. I promise there's no faxing. https://cla.microsoft.com.

TTYL, MSBOT;

[msftclas]

@TorstenStueber, Thanks for signing the contribution license agreement so quickly! Actual humans will now validate the agreement and then evaluate the PR.

Thanks, MSBOT;

[TorstenStueber]

Obviously CI checks have failed. However, in view of the log message I cannot trace the failed tests back to my changes. I would be thankful for any help.

[mhegazy]

@rbuckton can you take a look.

[mhegazy]

the tests are failing and you need to accept the new baselines. jake baseline-accept

[jwbay]

I'm just curious, what type of code will this enable/fix? From the signatures it almost looks like this is going to require continual casting or explicit annotations as you change the return type while chaining promises. For example, would this still work?

Promise.resolve(42).then(num => {
   return "string";
}).then(str => {
   return [str];
}).then(arr => {
   console.log(arr[0].toLowerCase());
});

[rbuckton]

@TorstenStueber Unfortunately the typings for Promise you provided would make the more common use cases of Promise much harder to use, as @jwbay mentioned above.

The recent additions to the compiler to support non-nullable types would likely be better for your purposes:

    then<TResult>(onfulfilled: null | undefined, onrejected: (reason: any) => TResult | PromiseLike<TResult>): Promise<T | TResult>; 
    then<TResult>(onfulfilled?: (value: T) => TResult | PromiseLike<TResult>, onrejected?: (reason: any) => TResult | PromiseLike<TResult>): Promise<TResult>; 

Also be aware that the interface definition for PromiseLike is used to support async functions, and your proposed change could have an adverse effect on accurate type resolution for await.

[TorstenStueber]

@rbuckton Thanks for your great comment. It just dawned to me this morning as well that one should distinguish between a null or undefined argument onfulfilled and a non-null argument onfulfilled in order to avoid the unfortunate problem that @jwbay mentioned.

Indeed, according to Promises/A+ the return value of then can only be of type Promise<T> if onfulfilled is not provided. One can even distinguish further:

• onfulfilled non-null: result is Promise<TResult>
• onfulfilled null and onrejected non-null: result is Promise<T|TResult>
• onfulfilled null and onrejected null: result is Promise<T>

So out of logic necessity of the Promises/A+ spec and in order to avoid unnecessary type castings I would like to go ahead and change the PR accordingly.

About PromiseLike: this is unfortunate as well. The most correct solution would be to define yet another interface Thenable (that is similar to PromiseLike but contains my change) to be used in the Promise declaration. However, I do not want to complicate matters as this minor correction would only be required for Promise polyfill developers. Hence, I will remove this change from the PR.

[rbuckton]

Keep in mind the Promise/A+ term "thenable" does not mean it's a Promise or "Promise-like", it just means that it is a foreign object with a callable "then" member. { then(){} } is a thenable, but certainly not a Promise.

[Arnavion]

Just FYI - Promise in es2015.promise.d.ts is the ES2015 Promise, not the Promises/A+ Promise, so the spec to reference is http://www.ecma-international.org/ecma-262/6.0/#sec-promise-objects . They have some implementation differences.

[TorstenStueber]

@Arnavion You are right, I should have referred to the ES2015 Promise spec instead of Promises/A+. However, my changes are also required by ES2015 Promises:

1. Section 25.4.5.3.1 of the spec defines the then method of promises: item 3 replaces onFulfilled by "Identity" if not provided. The latter is just the identity function; hence, the Promise returned by then needs to accept values of type T for its [[Resolve]] function.
2. Section 25.4.1.3.2 specifies that resolution is allowed to have a then method and will recursively invoke PromiseResolveThenableJob for further resolution in this case.

[mhegazy]

this should not be not optional, do not think this would compile this way anyways.

[mhegazy]

With the recent updates to the library including #10448, i do not think this is needed. closing.