ariatemplates/noder-js — pull request #8 by divdavem (2014-04-15 17:06:05+00:00)
Title: Clarifying the promise API (non-backward compatible).

This pull request introduces a clear (non-backward compatible) distinction between a defer and a promise in the promise API of noder-js, similar to what already exists in other promise libraries like [q](https://github.com/kriskowal/q).

Here was the previous way of using the promise library (before this pull request):

```js
var promise = require("noder-js/promise");
var myTimeout = function (delay) {
var defer = promise(); // this promise function actually returns a defer
// which can also be used as a promise
var res = defer.promise(); // and this promise method returns the true promise out of the defer
setTimeout(function () {
defer.resolve();
}, delay);
return res;
};
```

In the previous example, `defer` and `res` are very similar objects. The only difference is that `res` does not have the `resolve` and `reject` methods. Both `defer` and `res` are usable as promise objects, but `defer` should not be used as a promise, as it would expose the `resolve` and `reject` methods which are not supposed to be exposed. But it is easy to forget to call `defer.promise()` and to return `defer` instead, by mistake.

This commit removes most of the methods of the `defer` object, so that it can no longer be used as a promise. It now only has the `resolve` and `reject` methods along with a `promise` property containing the object to be used as a promise, so that it is mandatory to use the real promise object. Also, the method to create a defer is now called `promise.defer()` instead of `promise()`.

Here is the new way of using the promise library (starting with this pull request):

```js
var promise = require("noder-js/promise");
var myTimeout = function (delay) {
var defer = promise.defer(); // promise is no longer a function
var res = defer.promise; // promise is no longer a method on the defer object
setTimeout(function () {
defer.resolve();
}, delay);
return res;
};
```

This pull request also removes some non-standard methods on promise objects, such as:
`done`, `fail`, `doneSync`, `failSync` and `state`.

The remaining methods are the following ones:
`then`, `thenSync`, `always`, `end` and `result`

This pull request also adds the following methods on promise objects (to replace the `state` method which was removed):
`isResolved` and `isRejected`