Progress/A+ Draft A — https://github.com/promises-aplus/progress-spec/issues/5

gistfile1.md

Progress/A+

This proposal specifies how progress is triggered and propagated in a Promises/A+ promise library.

Requirements

The then Method

The then method is the same as that specified in the promises-spec except that it also takes a third argument. We'll call that third argument the onProgress:

promise.then(onFulfilled, onRejected, onProgress)

1. onProgress is an optional argument:
   1. If onProgress is not a function, it must be ignored.
2. If onProgress is a function:
   1. It must be called after progress is emitted, with the progress value as its first argument.
   2. The onProgress callback may return a promise.
      1. The callback is not considered complete until the promise is fulfilled.
      2. The fulfillment value of the promise is the value to be propagated.
      3. If the promise is rejected, the rejection reason should be treated as if it was thrown by the callback directly.
   3. Unless the onProgress callback throws an exception with a name property equal to 'StopProgressPropagation', the result of the function is used as the progress value to propagate.
   4. If the onProgress callback throws an exception with a name property equal to 'StopProgressPropagation', then the error is silenced.
   5. onProgress is never called once a promise has already been fulfilled or rejected.

The progress Method

resolver.progress(value)

1. The resolver has a progress method.
   1. It accepts a single value argument, which is the progress value.
   2. If value is a promise, the progress value is the fulfillment value of the progress, and the onProgress callbacks are only triggered when the promise is fulfilled.
2. Calling progress triggers all onProgress callbacks, passing the (fulfilled) progress value.
3. progress returns a promise.
   1. If value was a promise that got rejected, the returned promise is rejected with the rejection reason of that promise.
   2. The returned promise is fulfilled with undefined once all progress callbacks are complete,
   3. or is rejected with the first (non-StopProgressPropagation) exception thrown by the callbacks, if any.