promise-polyfill

What is promise-polyfill?

The promise-polyfill npm package is a lightweight implementation of the ES6 Promise specification. It is designed to provide a simple and efficient way to use Promises in environments that do not natively support them, such as older browsers.

What are promise-polyfill's main functionalities?

Basic Promise Usage

This code demonstrates the basic usage of a Promise. It creates a new Promise that resolves with the message 'Success!' after 1 second, and then logs the message to the console.

const Promise = require('promise-polyfill');

const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);
});

promise.then((message) => {
  console.log(message); // 'Success!'
});

Chaining Promises

This code demonstrates how to chain multiple .then() calls to handle a sequence of asynchronous operations. Each .then() call receives the resolved value from the previous Promise and returns a new value.

const Promise = require('promise-polyfill');

const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve(1);
  }, 1000);
});

promise
  .then((value) => {
    console.log(value); // 1
    return value + 1;
  })
  .then((value) => {
    console.log(value); // 2
    return value + 1;
  })
  .then((value) => {
    console.log(value); // 3
  });

Handling Errors

This code demonstrates how to handle errors in Promises using the .catch() method. If the Promise is rejected, the error message is logged to the console.

const Promise = require('promise-polyfill');

const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    reject('Error occurred!');
  }, 1000);
});

promise
  .then((value) => {
    console.log(value);
  })
  .catch((error) => {
    console.error(error); // 'Error occurred!'
  });

Other packages similar to promise-polyfill

es6-promise

The es6-promise package is another polyfill for the ES6 Promise specification. It provides a similar API to promise-polyfill and is widely used in environments that lack native Promise support. Compared to promise-polyfill, es6-promise is slightly larger in size but offers more comprehensive test coverage and compatibility.

bluebird

Bluebird is a fully-featured Promise library that offers a wide range of additional features and optimizations beyond the ES6 Promise specification. It includes utilities for working with collections, cancellation, and more. While it is more powerful and feature-rich than promise-polyfill, it is also significantly larger in size.

q

Q is a popular Promise library that predates the ES6 Promise specification. It provides a rich set of features for working with asynchronous code, including support for deferred objects and advanced error handling. Q is more feature-rich than promise-polyfill but has a larger footprint and a different API.

README

Promise Polyfill

Lightweight ES6 Promise polyfill for the browser and node. Adheres closely to the spec. It is a perfect polyfill IE or any other browser that does not support native promises.

For API information about Promises, please check out this article HTML5Rocks article.

It is extremely lightweight. < 1kb Gzipped

Browser Support

IE8+, Chrome, Firefox, IOS 4+, Safari 5+, Opera

NPM Use

npm install promise-polyfill --save-exact

Bower Use

bower install promise-polyfill

CDN Polyfill Use

This will set a global Promise object if the browser doesn't already have window.Promise.

<script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>

Downloads

• Promise
• Promise-min

Simple use

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. Javascript library authors should NOT use this method.

import 'promise-polyfill/src/polyfill';

If you would like to not affect the global environment (sometimes known as a ponyfill, you can import the base module. This is nice for library authors or people working in environment where you don't want to affect the global environment.

import Promise from 'promise-polyfill';

If using require with Webpack 2+ (rare), you need to specify the default import

var Promise = require('promise-polyfill').default;

then you can use like normal Promises

var prom = new Promise(function(resolve, reject) {
  // do a thing, possibly async, then…

  if (/* everything turned out fine */) {
    resolve("Stuff worked!");
  }  else {
    reject(new Error("It broke"));
  }
});

prom.then(function(result) {
  // Do something when async done
});

Performance

By default promise-polyfill uses setImmediate, but falls back to setTimeout for executing asynchronously. If a browser does not support setImmediate (IE/Edge are the only browsers with setImmediate), you may see performance issues. Use a setImmediate polyfill to fix this issue. setAsap or setImmediate work well.

If you polyfill window.setImmediate or use Promise._immediateFn = yourImmediateFn it will be used instead of window.setTimeout

npm install setasap --save

import Promise from 'promise-polyfill/src/polyfill';
import setAsap from 'setasap';
Promise._immediateFn = setAsap;

Unhandled Rejections

promise-polyfill will warn you about possibly unhandled rejections. It will show a console warning if a Promise is rejected, but no .catch is used. You can change this behavior by doing.

-NOTE: This only works on promise-polyfill Promises. Native Promises do not support this function

Promise._unhandledRejectionFn = <your reject error handler>;

If you would like to disable unhandled rejection messages. Use a noop like below.

Promise._unhandledRejectionFn = function(rejectError) {};

Testing

npm install
npm test

License

MIT

Changelog

8.3.0

• Add Promise.any