MDN: Promise.all() : Information about sync/a-sync resolution possibly irrelevant

NEW
Unassigned

Status

enhancement
P3
normal
Last year
Last year

People

(Reporter: avih, Unassigned)

Tracking

Details

()

The docs for Promise.all(iterable) mention several times and also give examples that if iterable is empty (e.g. the array []) then it resolves synchronously, and if it's not empty but doesn't contain promises (e.g. the array [1,2,3]) then it resolves a-synchronously.

As far as I can tell this info is completely inconsequential, and therefore confusing. I don't think the user can use this info for anything.

For instance, let's say a is an array which is either empty or contains only numbers (without any promises), but the developer doesn't know which is it.

Say they write this code:

Promise.all(a).then(foo, bar);

I assert that whether or not Promise.all(a) resolves sync or a-sync has no impact whatsoever.

The only thing which does have an impact the user might care about is when foo/bar are invoked. However, this is well defined. Because Promise.all returns a Promise, then calling its 'then' method is well defined - foo/bar will be called with "a clean stack" once the current execution context exits.

Whether or not a Promise is "resolved sync" or "resolved async" has no impact because there's no way to inspect its state. This is implementation details which don't affect the user.

Therefore I think that all the places where it mentions that it resolves sync or async should be removed from the docs - it's not information the user can use and doesn't help understand how Promise.all() works.

It's enough to say that it returns a Promise, and that's it.
Also, if you think there is a difference between "resolves sync" and "resolves a-sync" in this context, then I'd appreciate a code example which shows how it behaves differently depending on whether it resolves sync or async.

Here's an example where it _doesn't_ make a difference.

var a = [];
if (Math.random() > 0.5)
    a.push(1);
Promise.all(a).then(() => console.log("Clean stack"));
console.log("Dirty stack");

Which will always print:

Dirty stack
Clean stack

Regardless of whether it was "Resolved sync" or "Resolved async".

So how can a user use this information to their advantage? Are there pitfalls they can use this information to avoid? Is there a way at all (other than logging a Promise object at the console) that it can differentiate between two different ways their code might behave?
Priority: -- → P3
You need to log in before you can comment on or make changes to this bug.