yui/yui3 — pull request #757 by juandopazo (2013-05-16 17:36:17+00:00)
Title: Promises extras

This pull request splits the `promise` module into two modules: `promise-core` and `promise-extras`. The `promise` name is still an alias that loads these two new modules. The core module has little changes and the extras module introduces new features.

### Changes from previous version
* Promises now flatten other promises in a resolution procedure located in `resolver.resolve`
* The first argument in the promise initialization is now a reference to `resolver.resolve`
* `promise.getStatus` is now only available when including the `promise-extras` module
* `promise.then` no longer returns an instance of `promise.constructor`. Instead it always return a bare Promise with no subclassing
* `Y.batch` is deprecated in favor of `Y.Promise.every`. Resolves https://github.com/yui/yui3/issues/740
* Resolves https://github.com/yui/yui3/issues/571

### New features
* New method: `promise.done()`. `done` behaves in a simlar way to `then`, but it doesn't return a new promise and it doesn't catch errors to turn them into rejections. `fail is a
* New method `promise.fail()`. A shorthand for `then(null, fn)`, useful for reporting errors at the end of a chain.
* New factory methods `Promise.resolve` and `Promise.reject` for easier creation of already resolved promises
* New combinator methods `Promise.every`, `Promise.any` and `Promise.some`. Resolves https://github.com/yui/yui3/issues/670
* I did not include `Promise.accept` from the DOM standard because it opens the door for promises for promises which I don't think we want unless proven useful. It can be added later.

### Changes in the docs

* Removed all references to `batch` from the docs.
* Removed the "Subclassing promises" example. Subclassing is already covered by the Plugin example and I don't see a simple-to-explain non-hacky way of showing how to write a LazyPromise
* Changed all uses of `Promise(function (fulfill) ...` to using "resolve"

### Promises/A+

* These changes should make our implementation mostly compatible with A+ 1.1. The new A+ version hasn't been ratified yet. There is still the open issue of resolving promises/thenables that are fulfilled with themselves.

### Test results

```
Starting Grover on 2 files with PhantomJS@1.8.1
Running 15 concurrent tests at a time.
OK [Promise core tests]: Passed: 14 Failed: 0 Total: 15 (ignored 1) (0.334 secon
ds) 100%
OK [Promise extras]: Passed: 37 Failed: 0 Total: 37 (ignored 0) (1.108 seconds)
100%

------------------------+-----------+-----------+-----------+-----------+
File | % Stmts |% Branches | % Funcs | % Lines |
------------------------+-----------+-----------+-----------+-----------+
promise-core\ | 100 | 92.86 | 100 | 100 |
promise-core.js | 100 | 92.86 | 100 | 100 |
promise-extras\ | 100 | 100 | 100 | 100 |
promise-extras.js | 100 | 100 | 100 | 100 |
------------------------+-----------+-----------+-----------+-----------+
All files | 100 | 96.77 | 100 | 100 |
------------------------+-----------+-----------+-----------+-----------+
```
I'll work on getting that 100% on branches back.

I created a new branch with no commit history because I went back and forth a bit with some changes and I reached nearly 30 commits.