1# Promise Polyfill
2
3[![travis][travis-image]][travis-url]
4
5[travis-image]: https://img.shields.io/travis/taylorhakes/promise-polyfill.svg?style=flat
6[travis-url]: https://travis-ci.org/taylorhakes/promise-polyfill
7
8Lightweight ES6 Promise polyfill for the browser and node. Adheres closely to
9the spec. It is a perfect polyfill IE or any other browser that does
10not support native promises.
11
12For API information about Promises, please check out this article
13[HTML5Rocks article](http://www.html5rocks.com/en/tutorials/es6/promises/).
14
15It is extremely lightweight. **_< 1kb Gzipped_**
16
17## Browser Support
18
19IE8+, Chrome, Firefox, IOS 4+, Safari 5+, Opera
20
21### NPM Use
22
23```
24npm install promise-polyfill --save-exact
25```
26
27### Bower Use
28
29```
30bower install promise-polyfill
31```
32
33### CDN Polyfill Use
34
35This will set a global Promise object if the browser doesn't already have `window.Promise`.
36
37```html
38<script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>
39```
40
41## Downloads
42
43* [Promise](https://raw.github.com/taylorhakes/promise-polyfill/master/dist/polyfill.js)
44* [Promise-min](https://raw.github.com/taylorhakes/promise-polyfill/master/dist/polyfill.min.js)
45
46## Simple use
47
48If you would like to add a global Promise object (Node or Browser) if native Promise doesn't exist (polyfill Promise). Use the method below. This is useful it you are building a website and want to support older browsers.
49Javascript library authors should _NOT_ use this method.
50
51```js
52import 'promise-polyfill/src/polyfill';
53```
54
55If you would like to not affect the global environment (sometimes known as a [ponyfill](https://github.com/sindresorhus/ponyfill), you can import the base module. This is nice for library authors or people working in environment where you don't want
56to affect the global environment.
57
58```js
59import Promise from 'promise-polyfill';
60```
61
62If using `require` with Webpack 2+ (rare), you need to specify the default import
63
64```js
65var Promise = require('promise-polyfill').default;
66```
67
68then you can use like normal Promises
69
70```js
71var prom = new Promise(function(resolve, reject) {
72  // do a thing, possibly async, then…
73
74  if (/* everything turned out fine */) {
75    resolve("Stuff worked!");
76  }  else {
77    reject(new Error("It broke"));
78  }
79});
80
81prom.then(function(result) {
82  // Do something when async done
83});
84```
85
86## Performance
87
88By default promise-polyfill uses `setImmediate`, but falls back to `setTimeout`
89for executing asynchronously. If a browser does not support `setImmediate`
90(IE/Edge are the only browsers with setImmediate), you may see performance
91issues. Use a `setImmediate` polyfill to fix this issue.
92[setAsap](https://github.com/taylorhakes/setAsap) or
93[setImmediate](https://github.com/YuzuJS/setImmediate) work well.
94
95If you polyfill `window.setImmediate` or use `Promise._immediateFn = yourImmediateFn` it will be used instead of `window.setTimeout`
96
97```
98npm install setasap --save
99```
100
101```js
102import Promise from 'promise-polyfill/src/polyfill';
103import setAsap from 'setasap';
104Promise._immediateFn = setAsap;
105```
106
107## Unhandled Rejections
108
109promise-polyfill will warn you about possibly unhandled rejections. It will show
110a console warning if a Promise is rejected, but no `.catch` is used. You can
111change this behavior by doing.
112
113-**NOTE: This only works on promise-polyfill Promises. Native Promises do not support this function**
114
115```js
116Promise._unhandledRejectionFn = <your reject error handler>;
117```
118
119If you would like to disable unhandled rejection messages. Use a noop like
120below.
121
122```js
123Promise._unhandledRejectionFn = function(rejectError) {};
124```
125
126## Testing
127
128```
129npm install
130npm test
131```
132
133## License
134
135MIT
136