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