then/promise — pull request #13 by ForbesLindesay (2013-05-30 05:05:18+00:00)
Title: Add extensions and documentation

I think it's time we thought about some small extensions being built into this library. As it stands it's not really very useful.

## Error Reporting

There needs to be something better for error reporting. `promise.then` results in errors being swallowed, so I think we should add `promise.done`. Virtually all the popular Promises/A+ libraries have promises that work the same way.

## Convenience

I need a way to assimilate promises from broken libraries or create a promise for a value all the time, so I added `Promise.assimilate`.

## Interoperability

Sadly all the node.js APIs are still not compatible with promises, so `Promise.denodeify` is needed to convert those callback functions into functions that return promises.

When I'm creating libraries that aren't directly for manipulating promises I want them to be usable by people who are only using callbacks, otherwise they won't gain popularity. With this in mind I added `promise.nodeify` and `Promise.nodeify`.

## Ease of Use

It can be useful to make functions that just resolve all their arguments so that you can pass promises around as first class values whenever you like. To do this, I created `Promise.promisify`. It's used internally by `Promise.nodeify` and `Promise.denodeify` to make those APIs even more useful. This is the one I'm least sure about because:

a) It's a relatively large amount of code that would be significantly neater if I could depend on `all`
b) It's not something I've actively used in real world applications. All the other extensions listed here are things I've used hundreds of times and have proved to be totally indispensable.