api.jquery.com
api.jquery.com copied to clipboard
jquery
promise method of promise object currently not documented
jaubourg states at http://bugs.jquery.com/ticket/14293#comment:2:
As for determining if an object is a promise... you test for the presence of a method called promise and call it to get the actual promise
The presence of the .promise method on the promise object is currently not documented.
It is missing in two places. One place is http://api.jquery.com/deferred.promise which currently states:
The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, pipe, progress, and state),...
The list of methods should include the promise method (and should not include the deprecated pipe method) and thus should be:
The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state (then, done, fail, always, progress, state and promise),...
It would also be very helpful if http://api.jquery.com/deferred.promise documents the fact that one can/should determine if an object is a promise by testing for the presence of the promise method, as jaubourg described. For example:
To test if an object is a promise, you test for the presence of a method called promise.
Another place is http://api.jquery.com/Types/#Promise which currently states:
This object provides a subset of the methods of the Deferred object (then, done, fail, always, pipe. isResolved, and isRejected) to...
The list of methods should include the promise method. Additionally, the list currently includes deprecated methods. Instead, it should say:
This object provides a subset of the methods of the Deferred object (then, done, fail, always, progress, state and promise) to...
Let's be very precise. You can test if an object is observable through a promise by checking if it has a promise method. To get the promise itself, however, you need to call the method.
And a promise is "observable through a promise" as well since a promise's promise method returns the promise itself.
Are there any objects (created by jquery or a plain object passed to deferred.promise(target)) that have a promise method, but are they themselves NOT an observable (Deferred, Promise, etc.)? Oh, maybe jquery objects are such objects....
And a promise is "observable through a promise" as well since a promise's promise method returns the promise itself.
Exactly. Inception-style ;)
Are there any objects (created by jquery or a plain object passed to deferred.promise(target)) that have a promise method, but are they themselves NOT an observable (Deferred, Promise, etc.)?
By definition, an object that has a promise method is observable. I suppose you meant: "Are there objects that have a promise method but do not implement the promise interface?".
Oh, maybe jquery objects are such objects....
Exactly, jQuery collections are observable but do not implement the promise interface directly.
Well, the term "observable" is not defined or documented on jquery.com either, I think. It could/should be added to the documentation as well, since the term is being used in some places.
The way it is being used, I think I thought it meant an object that implements the promise interface. You are saying, though, that an observable is an object that can provide (through a promise method) an object that implements the promise interface.
E.g., http://api.jquery.com/deferred.then states:
or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status...
I think I read that as indicating that an observable object has a resolved/rejected status itself, i.e. implementing the promise interface.
I know it is a very slight difference to your definition above, though, and I understand your definition. And I think it would be good to add it to the documentation.
And a promise is "observable through a promise" as well since a promise's promise method returns the promise itself.
Exactly. Inception-style ;)
However, if one "makes" an existing object a promise (by deferred.promise(obj)), then currently the promise method of that promise does not return itself. I filed a bug report for that http://bugs.jquery.com/ticket/14483
Looking at the implementation, it appears that perhaps the deferred needs to keep track of which object is its promise - the "internal implementation object" or a target object passed in deferred.promise(obj). But you are the expert in the implementation arena...
