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 |
|
8 | Lightweight ES6 Promise polyfill for the browser and node. Adheres closely to
|
9 | the spec. It is a perfect polyfill IE or any other browser that does
|
10 | not support native promises.
|
11 |
|
12 | For API information about Promises, please check out this article
|
13 | [HTML5Rocks article](http://www.html5rocks.com/en/tutorials/es6/promises/).
|
14 |
|
15 | It is extremely lightweight. **_< 1kb Gzipped_**
|
16 |
|
17 | ## Browser Support
|
18 |
|
19 | IE8+, Chrome, Firefox, IOS 4+, Safari 5+, Opera
|
20 |
|
21 | ### NPM Use
|
22 |
|
23 | ```
|
24 | npm install promise-polyfill --save-exact
|
25 | ```
|
26 |
|
27 | ### Bower Use
|
28 |
|
29 | ```
|
30 | bower install promise-polyfill
|
31 | ```
|
32 |
|
33 | ### CDN Polyfill Use
|
34 |
|
35 | This 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 |
|
48 | If 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 if you are building a website and want to support older browsers.
|
49 | Javascript library authors should _NOT_ use this method.
|
50 |
|
51 | ```js
|
52 | import 'promise-polyfill/src/polyfill';
|
53 | ```
|
54 |
|
55 | If 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
|
56 | to affect the global environment.
|
57 |
|
58 | ```js
|
59 | import Promise from 'promise-polyfill';
|
60 | ```
|
61 |
|
62 | If using `require` with Webpack 2+ (rare), you need to specify the default import
|
63 |
|
64 | ```js
|
65 | var Promise = require('promise-polyfill').default;
|
66 | ```
|
67 |
|
68 | then you can use like normal Promises
|
69 |
|
70 | ```js
|
71 | var 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 |
|
81 | prom.then(function(result) {
|
82 | // Do something when async done
|
83 | });
|
84 | ```
|
85 |
|
86 | ## Performance
|
87 |
|
88 | By default promise-polyfill uses `setImmediate`, but falls back to `setTimeout`
|
89 | for executing asynchronously. If a browser does not support `setImmediate`
|
90 | (IE/Edge are the only browsers with setImmediate), you may see performance
|
91 | issues. 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 |
|
95 | If you polyfill `window.setImmediate` or use `Promise._immediateFn = yourImmediateFn` it will be used instead of `window.setTimeout`
|
96 |
|
97 | ```
|
98 | npm install setasap --save
|
99 | ```
|
100 |
|
101 | ```js
|
102 | import Promise from 'promise-polyfill/src/polyfill';
|
103 | import setAsap from 'setasap';
|
104 | Promise._immediateFn = setAsap;
|
105 | ```
|
106 |
|
107 | ## Unhandled Rejections
|
108 |
|
109 | promise-polyfill will warn you about possibly unhandled rejections. It will show
|
110 | a console warning if a Promise is rejected, but no `.catch` is used. You can
|
111 | change this behavior by doing.
|
112 |
|
113 | -**NOTE: This only works on promise-polyfill Promises. Native Promises do not support this function**
|
114 |
|
115 | ```js
|
116 | Promise._unhandledRejectionFn = <your reject error handler>;
|
117 | ```
|
118 |
|
119 | If you would like to disable unhandled rejection messages. Use a noop like
|
120 | below.
|
121 |
|
122 | ```js
|
123 | Promise._unhandledRejectionFn = function(rejectError) {};
|
124 | ```
|
125 |
|
126 | ## Testing
|
127 |
|
128 | ```
|
129 | npm install
|
130 | npm test
|
131 | ```
|
132 |
|
133 | ## License
|
134 |
|
135 | MIT
|