Background

[ForbesLindesay]

Some of the promises libraries now implement progress. The key thing that has yet to be decided upon is how we should deal with exceptions thrown in progress handdlers.

It has been broadly agreed upon that progress should be a single value (akin to fulfillment and rejection). We have also agreed that the third argument to then should be treated as the progress handler and should also controll propagation of progress.

I'd apreciate it if someone could fill in what the currently in use rules are regarding progress propagation.

[domenic]

Progress propagation: given

var promise2 = promise1.then(undefined, undefined, onProgress1);
var promise3 = promise2.then(undefined, undefined, onProgress2);
promise3.then(undefined, undefined, onProgress3);

• The return value of onProgress1 is passed to the progress handler for onProgress2.
• If onProgress2 is not a function, then the return value of onProgress1 is passed to onProgress3.

---

Other issues: does progress get replayed? What happens if you return a promise as your progress value? How should cases like this be handled?

---

Another piece of background: many people believe progress should not belong to promises at all. E.g. promises should just be event emitters and fire off progress events, or allow them to be dispatched. This introduces two difficulties, in my mind:

1. It fails to separate the "notifier" role from the "listener" role. I.e. it should be the resolver's responsibility to trigger progress events, while it's the promise's responsibility to provide a hook for listening to them. Most event emitter implementations (e.g. EventEmitter in Node or EventTarget in the DOM) conflate the two.
2. It requires manually propagating progress, negating much of the use of promises and leading to ugly code.

If neither point is addressed, it turns code like this (which currently works in Q)

function getUser() {
   return doJsonXhr("/user").then(function (res) {
      return res.user;
   });
}

into this code:

function getUser() {
  var p = doJsonXhr("/user");

  var derived = p.then(function (res) {
    return res.user;
  });

  p.on("progress", function (x) {
    p.emit("progress", x);
  });

  return derived;
}

If only point 1 is addressed, but point 2 is not, the code is much worse than even that.

[ForbesLindesay]

How do you stop progress propagation in your first example? You could deliberately address 2 and not 1 by having a simple method to do straight forward direct propagation within then by passing true as the third argument. You'd then let people do the more complex event emitter stuff when they needed to handle more complex stuff like fast then slow.

[domenic]

To stop progress propagation, add a progress handler that returns undefined.

[domenic]

Hmm, actually, that won't stop propagation, it'll just propagate undefined instead of anything useful. Good point.

[ForbesLindesay]

I'm in favour of also making undefined not propagate. I think it would be nice to have a value that succinctly says "don't propagate"

[domenic]

Reminds me of StopIteration from ES6. Maybe throwing a distinguished error would make more sense there?

[ForbesLindesay]

Yeh, throwing an exception would work, but it may be difficult to distinguish the right exception. An instanceof check would prevent using them interoperably

[briancavalier]

I can't see any reason not to propagate undefined, especially since it propagates like any other value for fulfill/reject. I do see the value in having a StopIteration like value, but I also see the problems around interop there since it's not something that the language can provide right now ... unless we were to actually use StopIteration, which would require a polyfill, and just feels wrong.

Throwing seems reasonable, but raises the question of what to do with the thrown value. It seems like that may be a candidate for a promise debugger hook similar to the stuff we're discussing in unhandled-rejections-spec land

[ForbesLindesay]

How about instead of using instanceof we add a .code property to the error with a value of 'StopProgressPropagation'. By just checking for that would allow all libraries to use other libraries' exceptions interchangeably. Then it could be upgraded to an instanceof check if it gains language support.

[domenic]

@ForbesLindesay or .name, to match existing errors.

[ForbesLindesay]

I'm not at all fussed what we call the property, I thought node.js used .code a lot elsewhere? I'm happy to use .name if people prefer.

[briancavalier]

afaik, .name is what builtins like TypeError use. If we go with a particular exception name, then an implementation will assume that whatever thing it catches is indeed an error, compare it's .name to the "official" name, and if it matches, silently stop progress propagation? That seems reasonable.

Would it also be reasonable to return one of these "stop propagation" objects instead of throwing it?

What about other exceptions? Should we assume that we'll be able to rely on some debug hook? Crash the app with a next-tick throw?

[domenic]

Let's not forget we can open more than one GitHub issue for the separate issues involved ;)