Promises/A+

promises-a-plus.md

Promises/A+

This proposal attempts to clarify the behavioral clauses of the Promises/A proposal, and to extend it to cover the cases where handlers may return a promise.

This proposal intentionally omits the progress handling portion of Promises/A. In practice it has proven to be underspecified and currently does not have an agreed-upon or defacto behavior within the promise implementor community.

Also intentionally omitted is a requirement for calling fulfill and broken handlers either synchronously or asynchronously [1]. Promises/A itself does not specify, and both synchronous and asynchronous approaches exist in the current landscape of popular implementations.

This specification borrows heavily from the Promises/A proposal by Kris Zyp, as well as the UncommonJS Thenable Promises specification by Kris Kowal. All credit goes to those authors.

As with Promises/A, this proposal does not deal with creation of promises.

Promise

A promise represents a value that may not be available yet. A promise must be one of three states: pending, fulfilled, or broken:

• When in the pending state, a promise may transition to either the fulfilled or broken state.

• When in the fulfilled state, a promise has a value and provides a way to arrange for a function to be called with that value. Once a promise has transitioned to the fulfilled state, it must never transition to any other state.

• When in the broken state, a promise has a reason (an indication of why it was broken) and provides a way to arrange for a function to be called with that reason. Once a promise has transitioned to the broken state, it must never transition to any other state.

Requirements

A promise is an object or function that defines a then method that accepts at least 2 arguments:

promise.then(fulfilled, broken)

• Both fulfilled and broken are optional arguments

• If truthy, fulfilled must be a function that accepts a value as its first argument.

  • When promise is fulfilled, fulfilled will be called with promise's fulfillment value.
  • fulfilled will never be called more than once.
  • fulfilled will never be called if broken has already been called.

• If truthy, broken must be a function that accepts a reason (which must be a value, not a promise) as its first argument.

  • When promise is broken, broken will be called with promise's reason for being broken.
  • broken will never be called more than once.
  • broken will never be called if fulfilled has already been called.

• then may be called any number of times.

• fulfilled and broken supplied in one call to then must never be called after those supplied to a later call to then on the same promise.

• then must return a promise [2]

    var promise2 = promise1.then(fulfilled, broken)
  

  • When promise1 is either fulfilled and fulfilled is called with the fulfillment value, or broken and broken is called with the reason:
    • If either returns a value, promise2 must be fulfilled with that value.
    • If either throws an exception, promise2 must be broken with the thrown exception as the reason.
    • If either returns a promise (call it returnedPromise), promise2 must be placed into the same state as returnedPromise:
      • If returnedPromise is fulfilled, promise2 must be fulfilled with the same fulfillment value.
      • If returnedPromise is broken, promise2 must be broken with the same reason.
      • If returnedPromise is pending, promise2 must also be pending. When returnedPromise is fulfilled, promise2 must be fulfilled with the same fulfillment value. When returnedPromise is broken, promise2 must be broken with the same reason.

Recommendations

1. Each implementation should document whether it calls handlers synchronously or asynchronously.
2. Each implementation should document whether it may produce promise2 === promise1, and if so, under what conditions. It is intentionally not specified as to whether the returned promise may be the same promise, or must be a new promise, i.e. promise2 !== promise1 is not a requirement. An implemention is free to allow promise2 === promise1, provided it can meet the requirements in this section.

Haha I was totally thinking of doing this, with exactly this name too! Glad you are on top of it; it's great to have others sharing the effort :)

---

I actually like some of the terminology things going on here:

• Promises are never resolved; this spec doesn't mention that term. However, deferreds can be resolved. If we use the term "resolved" as a promise state (meaning "non-pending"), it's confusing, since you can resolve a deferred with a pending promise.
• Broken always made more sense to me. If we keep "reject" as the deferred's verb, and adopt "broken" as the promise state, then we've entirely managed to separate the terminology used by promises and deferreds, which helps reduce the confusion.

That is, promises are either pending, fulfilled, or broken. Deferreds can be resolved or rejected. Now we can explain how the latter impacts the former, without being confused by the way that, in the old terminology (pending vs. resolved and fulfilled vs. rejected) "reject" maps rather directly where "resolve" is rather complex.

---

I feel somewhat strongly that async resolution should be required for compliance. It can be turned off for specific libraries as an optional feature, but the default configuration of most libraries should be async. I realize this would be a breaking change for When, requiring users to specify an option to retrieve the old behavior, but I hope that would be OK. Pinging @wycats.

---

You say "must be a function," but that's rather imprecise. Should then throw an early error? Ignore it? Store it in the internal listeners array, then blow up when calling a non-function.

---

Given that the then duck-type test is easy to fool, and has existing landmines in the wild, I'd consider specifying a better method of detection. For example, AMD has something like define.amd. I'd love then.aplus or similar.

You should document the value/reason relaying behavior when fulfilled or broken is not provided. This is especially relevant for middle steps in a promise chain.

+1

Specify behavior for resolvedPromise.then(what, now)

+1; the current "when promise is fulfilled" and "when promise is broken" are not clear enough. (Although, as per my above comment, I recommend doing away with the terminology "resolved promise".)

Specify what happens when fulfilled or broken don't return a value.

+1; amending "returns a value" with "returns a value (including undefined)" should suffice.

Do you know of implementations that produce promise2 === promise1? I can't imagine a use case that would require that behavior. It seems wrong.

domenic/promise-tests#2 discusses this; in particular see this comment.

Maybe better to spec that implementations MAY allow a third argument for progress handler?

Probably a good idea, or something like this. Maybe "if implementations use a third argument, it MUST be a progress handler"? It's nice being able to absorb progress-emitting when promises into Q (via thenable.then(deferred.resolve, deferred.reject, deferred.notify)) without worrying that someone might create a new library that takes as its third parameter something completely different.

---

I also think we should produce Deferreds/A+, but let's leave that discussion for another time.

I don’t have any opinions that have not yet been represented.

1. I, and the experts I learned promises from, feel strongly that sync and async should not be mixed. Since a promise by definition may be async, it follows that they must always be async. when.js is welcome to play with that fire, but I will not be raising my flag on that particular aspect. That said, I would not want to miss an opportunity to converge on all the things we can agree on in terms of terminology and behavior. I propose that Promises/A+ be strictly async, and when.js can emblazon itself as an almost-compliant variant pointing out that caveat.
2. As far as I’m concerned "pending" and "unresolved" are equivalent and opposite to "resolved". "resolved" can mean "fulfilled" or "rejected". Resolvers confuse the issue since "resolve" (in Q terminology) does not imply that the promise becomes "resolved", but I don’t have a good solution to that problem. As far as I’m concerned "reject" and "break" are equivalent, and "rejected" and "broken" are equivalent. I believe ref_send’s Q used "reject" to avoid a collision with the "break" keyword. Going forward, we might revisit that decision.
3. I don’t think we should specify anything more than "then" to identify a compliant library. Anything that has a "then" method that does not pertain to promises should be wrapped. @domenic, we should talk about this more; Q could provide a facility for unconditionally wrapping, possibly through Q.fulfill.
4. Give a mouse a cookie. I think it would be grand if we agreed on this much. It would be a basis for run-time equivalence. It would be even better to agree on the "defer()" -> {resolve, promise} interface too, so libraries could be swapped.
5. Talked a bit to @wycats and managed to articulate that {promise, resolver} might be more appropriate than {promise, resolve}. The {resolver} would be a passable object with all of the state change methods {resolve, reject, notify, cancel}.

I, and the experts I learned promises from, feel strongly that sync and async should not be mixed. Since a promise by definition may be async, it follows that they must always be async. when.js is welcome to play with that fire, but I will not be raising my flag on that particular aspect. That said, I would not want to miss an opportunity to converge on all the things we can agree on in terms of terminology and behavior. I propose that Promises/A+ be strictly async, and when.js can emblazon itself as an almost-compliant variant pointing out that caveat.

Fully agree.

As far as I’m concerned "pending" and "unresolved" are equivalent and opposite to "resolved". "resolved" can mean "fulfilled" or "rejected". Resolvers confuse the issue since "resolve" (in Q terminology) does not imply that the promise becomes "resolved", but I don’t have a good solution to that problem. As far as I’m concerned "reject" and "break" are equivalent, and "rejected" and "broken" are equivalent. I believe ref_send’s Q used "reject" to avoid a collision with the "break" keyword. Going forward, we might revisit that decision.

I like the nomenclature of "promise" and "resolver", but I am not sold on "broken" as a state. It strikes me as too cute. I'm not sure I understand why "rejected" doesn't work as the adjective form of resolver.reject.

I don’t think we should specify anything more than "then" to identify a compliant library. Anything that has a "then" method that does not pertain to promises should be wrapped. @domenic, we should talk about this more; Q could provide a facility for unconditionally wrapping, possibly through Q.fulfill.

In my use cases, it is important to be able to detect whether some object is a promise or not. Some of my APIs support promises as an advanced feature only, allowing users to return regular values in place of promises if desired. A mostly-foolproof way to identify a promise would be great. I like the "branding" approach of `promise.then && promise.then.aplus.

Give a mouse a cookie. I think it would be grand if we agreed on this much. It would be a basis for run-time equivalence. It would be even better to agree on the "defer()" -> {resolve, promise} interface too, so libraries could be swapped.

I really don't like the use of defer here. It's inappropriately a verb. I don't like Foo.deferred() any better, because it creates a new concept ("a deferred"), which the rest of the nomenclature has (thank god) been able to avoid. And while Cocoa folks might like Foo.promiseAndResolverPair(), it's probably too verbose ;)

I'm open to other options.

Talked a bit to @wycats and managed to articulate that {promise, resolver} might be more appropriate than {promise, resolve}. The {resolver} would be a passable object with all of the state change methods {resolve, reject, notify, cancel}.

This seems like another spec? "Promises/A+ Resolvers"? There's a less urgent need for compatibility and more generally evolving state of the art here (e.g. what should happen when a promise is cancelled/aborted), so we can take our time on this one, I'd think.

As far as I’m concerned "pending" and "unresolved" are equivalent and opposite to "resolved". "resolved" can mean "fulfilled" or "rejected". Resolvers confuse the issue since "resolve" (in Q terminology) does not imply that the promise becomes "resolved", but I don’t have a good solution to that problem.

Well, by removing the term "resolved" from promises, I was hoping to solve this problem.

I don’t think we should specify anything more than "then" to identify a compliant library. Anything that has a "then" method that does not pertain to promises should be wrapped. @domenic, we should talk about this more; Q could provide a facility for unconditionally wrapping, possibly through Q.fulfill.

I'm not quite sure I understand what you're suggesting. My use case is to improve this check:

if (typeof assertion._obj.pipe === "function") {
  throw new TypeError("Chai as Promised is incompatible with jQuery's so-called “promises.” Sorry!");
}

If I could replace it with

if (!assertion._obj.then.aplus) {
  throw new TypeError("Chai as Promised only works with Promises/A+ compatible promises. Sorry!");
}

I'd feel much better.

Talked a bit to @wycats and managed to articulate that {promise, resolver} might be more appropriate than {promise, resolve}. The {resolver} would be a passable object with all of the state change methods {resolve, reject, notify, cancel}.

I really like this, actually. It makes the separation I allude to while trying to explain resolution races more apparent.

I'm not sure I understand why "rejected" doesn't work as the adjective form of resolver.reject.

Because "resolved" doesn't work as the adjective form of resolver.resolve.

Because "resolved" doesn't work as the adjective form of resolver.resolve.

Why not reject/rejected and fulfill/fulfilled?

Why not reject/rejected and fulfill/fulfilled?

Because we need a way to say resolver.adoptEventualStateOf(pendingPromise). Currently it's deferred.resolve(pendingPromise).

Wow, I go out for the evening and you guys post all sorts of great feedback :) It'll take me a bit to get through all of this, but I'll try to do so today.

I think we'll probably benefit from the better history, diff, and commenting tools in a full repo, so here we go. I also created this issue where we can continue. Sorry to have to break up the conversation, but I figured may as well do it now than when we've amassed even more comments.