Version 2.0.0 of when.js will be released soon. There are a couple of simple things that you need to be aware of as you get ready.
In preparation for 2.0.0, you can test your code against the
dev-200 branch. If you have any questions about the upcoming 2.0.0 release, please feel free to post questions here!
Deprecated APIs
There are a handful of deprecated APIs that will be removed or renamed in 2.0.0. Here is the full list of current deprecations, with their new 2.0.0 alternatives. You will need to update your code accordingly. If you use when/debug in 1.8.1, it will log obnoxious warnings about these to the console.
* removed deferred.then - use deferred.promise.then
* renamed deferred.progress - use deferred.notify
* renamed deferred.resolver.progress - use deferred.resolver.notify
* removed when/timed - this module only aggregated two other existing modules and provided no additional functionality. Use when/timeout and/or when/delay directly
Asynchronous Resolutions
In versions prior to 2.0.0, when.js allowed promise callbacks to be invoked immediately for a promise that was already fulfilled or rejected. The problem this creates is one of inconsistency. Under some conditions, promise callbacks would be called immediately, and under other conditions, they would be called asynchronously (e.g. in a future event loop turn). Consider the following code:
function doStuff(promise) {
var i = 0;
promise.then(function() {
console.log(i);
});
i++;
}
Admittedly, this is an extremely trivial example, but it illustrates the point. This function accepts a promise, which might still be pending, or might be already fulfilled. The function itself cannot know the state of the promise, and
will behave differently depending on whether the promise is already-fulfilled (doStuff will log 0 immediately) or pending (doStuff will log 1 after promise is fulfilled). One implication of this is that the developer must write unit tests for both the pending and fulfilled cases (and possibly the rejected case as well), and not doing so could lead to errors in production. As you can imagine, with more complex functions in complex software systems, this kind of unpredictability can be very difficult to track down if/when it causes a problem.
In when.js 2.0.0, promise callbacks will never be called immediately. They will always be called asynchronously. This means that the doStuff function above will log 1 regardless of whether promise is already fulfilled or is still pending at the time doStuff executes--it simply cannot log 0. By guaranteeing consistency, we feel when.js reduces possible mistakes and eases the testing burden.