Search jQuery

jQuery Forum

.promise() violates documented behaviour

in Developing jQuery Core • 10 years ago

Due to the documentation of .promise() the created Deferred object will resolve when all actions bound to the collection have ended.

jQuery's implementation does not behave like that! (version 1.6 up to 1.8.2)

The documentation still leaves space for two possible interpretations. Both are violated.

Interpretation #1: For multiple elements the .promise() object resolves once all elements are not being animated at the same time.

The minimal counter example for that meaning is:

$('#foo').fadeOut(100);
var deferred = $('#foo, #bar').promise();
$('#bar').fadeOut(200);

In this example the Deferred is resolved after 100ms. Due to interpretation #1 it must resolve after 200ms.

So let's come to the second possible interpretation.

Interpretation #2: The .promise()-created object resolves once all currently queued animations have ended.

The minimal counter example is:

$('#foo').fadeOut(100);
var deferred = $('#foo').promise();
$('#foo').fadeIn(200);

In this example the Deferred is resolved after 300ms. Due to interpretation #2 it must resolve after 100ms already.

As we see that both interpretations are wrong - which is the right one?

Or can we modify the documentation to explain it with more details?

Peter

Replies(4)

jsclark

Re: .promise() violates documented behaviour

10 years ago

The second example on the .promise() documentation describes the behavior in your second example pretty clearly (http://api.jquery.com/promise/#example-1) :

Resolve the returned Promise when all animations have ended (including those initiated in the animation callback or added later on)
...

You started an animation on an element, got a promise object for the element being animated, then added another animation. The promise was resolved when the element's animation queue was empty, i.e. after both animations completed.

The explanation for the behavior of your first example is that the returned promise only applies to elements that currently have an animation queued. In you example, at the time of calling .promise(), #foo is included because it has an active animation queue, and #bar isn't included because it does not.

This is not explicitly covered in the documentation, but it becomes apparent when looking at the implementation of $.fn.promise (line 1964 in 1.8.2), provided you have a understanding of the animation queue system.

creativec..

Re: Re: .promise() violates documented behaviour

10 years ago

Thanks for the explanation. So I am fine with the implementation.

But I still wonder how we could modify the documentation to cover the implemented behavior.

I came up with that question when I was working on the documentation for my plugin jquery-timing. There I tried to describe what exactly happens as clear as possible. At the end I found that I didn't know it either.

Maybe we can say something like: "... resolves when all elements have reached an empty animation queue at least once."

It still doesn't sound sexy. Do you have a better idea?

Best regards,

Peter

jaubourg

Re: .promise() violates documented behaviour

10 years ago

jsclark is perfectly right. Handling potential future queue creations would require some very nasty and convoluted logic.

I'm unsure how to document this without being too technical.

creativec..

Re: Re: .promise() violates documented behaviour

10 years ago

Hi jaubourg,

the implementation of such an enhanced promise feature is not that complicated:

$.fn.enhancedPromise = function(type){
var ctx = this, ret = $.Deferred();
function checkResolved() {
var promise = ctx.promise(type);
if (promise.state() == "resolved") {
ret.resolveWith(ctx);
} else {
promise.done(checkResolved);
}
}
checkResolved();
return ret;
};

This .enhancedPromise() method in fact gives a deferred object which is resolved once all elements are not being animated at the same time.

But to come back to the original problem, we could change the documentation of the existing .promise([type][,target]) the following way:

Return a Promise object to observe when for all selected elements the actions of a certain type, queued or not, have finished once.

The .promise() method returns a dynamically generated Promise that is resolved when for all elements from the collection all actions of a certain type, queued or not, have ended once.

What do you think?

Top Reply

Response title

Attachments

jQuery Forum

.promise() violates documented behaviour

Replies(4)

Re: .promise() violates documented behaviour

Resolve the returned Promise when all animations have ended (including those initiated in the animation callback or added later on)

...

Re: Re: .promise() violates documented behaviour

Re: .promise() violates documented behaviour

Re: Re: .promise() violates documented behaviour

Statistics

Tags

Actions

Related Posts