# promise
This is a simple implementation of Promises. It is a super set of ES6 Promises designed to have readable, performant code and to provide just the extensions that are absolutely necessary for using promises today.
For detailed tutorials on its use, see www.promisejs.org
**N.B.** This promise exposes internals via underscore (`_`) prefixed properties. If you use these, your code will break with each new release.
[![travis][travis-image]][travis-url]
[![dep][dep-image]][dep-url]
[![npm][npm-image]][npm-url]
[![downloads][downloads-image]][downloads-url]
[travis-image]: https://img.shields.io/travis/then/promise.svg?style=flat
[travis-url]: https://travis-ci.org/then/promise
[dep-image]: https://img.shields.io/gemnasium/then/promise.svg?style=flat
[dep-url]: https://gemnasium.com/then/promise
[npm-image]: https://img.shields.io/npm/v/promise.svg?style=flat
[npm-url]: https://npmjs.org/package/promise
[downloads-image]: https://img.shields.io/npm/dm/promise.svg?style=flat
[downloads-url]: https://npmjs.org/package/promise
## Installation
**Server:**
$ npm install promise
**Client:**
You can use browserify on the client, or use the pre-compiled script that acts as a polyfill.
```html
```
Note that the [es5-shim](https://github.com/es-shims/es5-shim) must be loaded before this library to support browsers pre IE9.
```html
```
## Usage
The example below shows how you can load the promise library (in a way that works on both client and server using node or browserify). It then demonstrates creating a promise from scratch. You simply call `new Promise(fn)`. There is a complete specification for what is returned by this method in [Promises/A+](http://promises-aplus.github.com/promises-spec/).
```javascript
var Promise = require('promise');
var promise = new Promise(function (resolve, reject) {
get('http://www.google.com', function (err, res) {
if (err) reject(err);
else resolve(res);
});
});
```
If you need [domains](https://iojs.org/api/domain. display for errors. Note that if possible you should indicate that the error was a false positive if `onHandled` is called. `onHandled` is only called if `onUnhandled` has already been called.
To reduce the chance of false-positives there is a delay of up to 2 seconds before errors are logged. This means that if you attach an error handler within 2 seconds, it won't be logged as a false positive. ReferenceErrors and TypeErrors are only subject to a 100ms delay due to the higher likelihood that the error is due to programmer error.
## API
Before all examples, you will need:
```js
var Promise = require('promise');
```
### new Promise(resolver)
This creates and returns a new promise. `resolver` must be a function. The `resolver` function is passed two arguments:
1. `resolve` should be called with a single argument. If it is called with a non-promise value then the promise is fulfilled with that value. If it is called with a promise (A) then the returned promise takes on the state of that new promise (A).
2. `reject` should be called with a single argument. The returned promise will be rejected with that argument.
### Static Functions
These methods are invoked by calling `Promise.methodName`.
#### Promise.resolve(value)
(deprecated aliases: `Promise.from(value)`, `Promise.cast(value)`)
Converts values and foreign promises into Promises/A+ promises. If you pass it a value then it returns a Promise for that value. If you pass it something that is close to a promise (such as a jQuery attempt at a promise) it returns a Promise that takes on the state of `value` (rejected or fulfilled).
#### Promise.reject(value)
Returns a rejected promise with the given value.
#### Promise.all(array)
Returns a promise for an array. If it is called with a single argument that `Array.isArray` then this returns a promise for a copy of that array with any promises replaced by their fulfilled values. e.g.
```js
Promise.all([Promise.resolve('a'), 'b', Promise.resolve('c')])
.then(function (res) {
assert(res[0] === 'a')
assert(res[1] === 'b')
assert(res[2] === 'c')
})
```
#### Promise.denodeify(fn)
_Non Standard_
Takes a function which accepts a node style callback and returns a new function that returns a promise instead.
e.g.
```javascript ccccccccccccccccccccccc',
nlink: undefined,
dev: undefined,
ino: undefined },
{ path: '200-hard',
mode: '644',
type: '0',
depth: undefined,
size: 200,
linkpath: '',
nlink: 2,
dev: 234881026,
ino: 51681874 },
{ path: '200ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc',
mode: '644',
type: '1',
depth: undefined,
size: 0,
linkpath: path.resolve(target, '200-hard'),
nlink: 2,
dev: 234881026,
ino: 51681874 } ]
, ef = 0
, expectFiles =
[ { path: '',
mode: '40755',
type: 'Directory',
depth: 0,
linkpath: undefined },
{ path: '/200-hard',
mode: '100644',
type: 'File',
depth: 1,
size: 200,
linkpath: undefined,
nlink: 2 },
{ path: '/200LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL',
mode: '120777',
type: 'SymbolicLink',
depth: 1,
size: 200,
linkpath: '200ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc',
nlink: 1 },
{ path: '/200cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc`.then` is rejected with that exception.
#### Promise#catch(onRejected)
Sugar for `Promise#then(null, onRejected)`, to mirror `catch` in synchronous code.
#### Promise#done(onFulfilled, onRejected)
_Non Standard_
The same semantics as `.then` except that it does not return a promise and any exceptions are re-thrown so that they can be logged (crashing the application in non-browser environments)
#### Promise#nodeify(callback)
_Non Standard_
If `callback` is `null` or `undefined` it just returns `this`. If `callback` is a function it is called with rejection reason as the first argument and result as the second argument (as per the node.js convention).
This lets you write API functions that look like:
```javascript
function awesomeAPI(foo, bar, callback) {
return internalAPI(foo, bar)
.then(parseResult)
.then(null, retryErrors)
.nodeify(callback)
}
```
People who use typical node.js style callbacks will be able to just pass a callback and get the expected behavior. The enlightened people can not pass a callback and will get awesome promises.
## License
MIT