Why not `reflect`? about proposal-promise-allsettled

[benjamingr]

@ljharb I am not too concerned about the name itself. It can be .settle on the promise. It's also not about it being a prototype method. It's more about it acting on a single promise rather than an array of promises.

[domenic]

Very interesting issue. My intuition is that allSettled is still useful and convenient, even if we additionally added reflect() or similar as a lower-level primitive with slightly broader applicability. But, the fact that Bluebird deprecated their allSettled counterpart is concerning. @benjamingr, could you say more about this?

Champions, I think this is worth raising for committee discussion when transitioning to stage 3. As I said, I'd be supportive of moving ahead with allSettled and considering this an add-on, but it'd be good to ensure the committee agrees.

[benjamingr]

@rpamely sorry, I missed your comment there. Basically, you would reflect whenever an API you are calling failing something does not necessarily mean failure.

Here are some examples and use cases:

// network request
const hostReachability = await fetch('http://might-not-be-reachable.com').reflect();
const isHostReachable = hostReachability.status === 'fulfilled';

// timer that might be cancelled
const timerDone = await setTimeout(4000, token).reflect();
if (timerDone.status === 'rejected') { // cancelled, but not an error

}

// in Node.
const safeExists = await fs.readFile('./mightNotExist').reflect();
if (safeExists.status === 'fulfilled') { // the file existed and I read it

} else { // file not in cache

}

Of course all of these can be handled with writing our own reflect (it's a 2 LoC polyfill already) or by wrapping allSettled and destructuring the array - again, not a huge deal - just a worse off API. After all .allSettled is a 2 line polyfill itself anyway.

[rpamely]

Thanks a lot for this @benjamingr. This has given me a much clearer understanding of when reflect is useful. I agree with you that there is place for both of these features. I think allSettled is a common enough case that it deserves its own function.

[benjamingr]

Sure, having co-maintained the most popular promise library I have several. You're also welcome to check the threads from bluebird discussing this and why we deprecated .settle in favor of reflect.

[benjamingr]

I see the meeting notes mention less adoption. I have actually seen some adoption of reflect over .settle in multiple places. I'm not sure how common it is but the three other common ones I've seen are:

• raceSettled where we want to await the first from an array of promises and not look at it as a rejection.
• propsSettled where we want to wait for properties of an object.
• .reflect() to protect against throwing APIs.

There are more common ones - but these were the most common I saw.

---

I actually don't feel too strongly about it to be honest. It just seems odd to pick the less composing abstraction and to have to do .allSettled([p]).then(([v]) => v) in order to do it for a single promise.

[benjamingr]

@ljharb it most certainly didn't originate in bluebird - I'm just sad you're considering the API we moved away from

[benjamingr]

And to be extra clear - I'm not sure we shouldn't do allSettled. I can't block this proposal, but if I could I still wouldn't. Spec work is full of compromises and I wouldn't be too bothered by a language that does modulu between strings containing a 'slightly worse off' primitive.

Promises themselves were full of compromises and were still a huge win for the language.

[mathiasbynens]

At today’s TC39 meeting, there was consensus to proceed with Promise.allSettled since it carries its own weight, regardless of whether or not we decide to add reflect as a separate proposal.

[benjamingr]

The decision process wasn't so thorough but we always liked that decision petkaantonov/bluebird#346 (comment)

[ljharb]

Reflect is a place methods matching Proxy traps are stored; I’m not sure the name makes sense given the builtin.

Are you suggesting a prototype method in general, that gives a promise for the result object?

[rpamely]

@benjamingr do you have realistic use cases for the above scenarios you listed?

[alexweej]

I think this is also useful for e.g. Array#map. A function call may "result" in a thrown exception, or a return value. I don't like naming this specific to Promise personally. Consider {throw: any} | {return: any} instead? This generalises it for use in any monad, not just Promise.

function f(x) {
    if (x) {
        throw new Error();
    } else {
        return "foo";
    }
}

capture(() => f(true))
🠚 {throw: theErrorObject}

capture(() => f(false))
🠚 {return: "foo"}

[benjamingr]

It seems like this is moving forward as allSettled, it's not a huge shame - but it is still a shame to see others repeating our mistakes.

[ljharb]

@benjamingr i don't think the term "settled" originates in Bluebird, fwiw.

[benjamingr]

@domenic honestly this isn't a huge deal - there are many cases where reflect applies and allSettled doesn't - similarly to how we had Promise.map in libraries but people just do Promise.all with array#map.

I think it's generally preferable to add things that compose well with each other - I'm sure we'll see Promise.allSettled([p]).then(([result]) => ... which is just a worse API.

[rpamely]

Passing one item to allSettled will mean you will immediately have to branch on the status for one item to read the value. Why not just use .then().catch() in this case? Same for raceSettled. When the result is one item I don't see what you would need reflect for. Would you mind elaborating please @benjamingr?

[samson-sham]

@domenic honestly this isn't a huge deal - there are many cases where reflect applies and allSettled doesn't - similarly to how we had Promise.map in libraries but people just do Promise.all with array#map.

I think it's generally preferable to add things that compose well with each other - I'm sure we'll see Promise.allSettled([p]).then(([result]) => ... which is just a worse API.

I disagree with your example of Promise.map(), people don't use Promise.map may just because it is not an ECMA standard making it hard to switch between libraries, or many other reasons, which doesn't apply to current matter of Promise.allSettled().

Other than that, I don't see why we can't have both, .allSettled() and .reflect().