ES6-Promise is a lightweight polyfill library providing tools for organizing asynchronous code by implementing the ES6 Promise specification. It's a subset of rsvp.js extracted for minimal footprint and maximum compatibility, ideal for environments lacking native Promise support or with broken Promise implementations.
npm install es6-promiseconst { Promise } = require('es6-promise');For automatic polyfilling:
require('es6-promise/auto');
// Promise is now available globallyES6 modules:
import Promise from 'es6-promise';const { Promise } = require('es6-promise');
// Create a new promise
const myPromise = new Promise((resolve, reject) => {
setTimeout(() => {
if (Math.random() > 0.5) {
resolve('Success!');
} else {
reject(new Error('Something went wrong'));
}
}, 1000);
});
// Use the promise
myPromise
.then(result => console.log(result))
.catch(error => console.error(error));
// Static methods
const resolved = Promise.resolve('immediate value');
const rejected = Promise.reject(new Error('immediate error'));
// Promise.all for multiple promises
Promise.all([
Promise.resolve(1),
Promise.resolve(2),
Promise.resolve(3)
]).then(values => {
console.log(values); // [1, 2, 3]
});ES6-Promise provides a complete Promise implementation with:
resolve, reject, all, race for creating and combining promisesCreates a new Promise instance with an executor function.
/**
* Promise constructor - creates a new Promise
* @param executor - Function with resolve and reject parameters
*/
function Promise(executor: (resolve: (value?: any) => void, reject: (reason?: any) => void) => void): Promise;The executor function is called immediately with resolve and reject functions.
Registers callbacks for promise fulfillment and/or rejection.
/**
* Register callbacks for promise fulfillment/rejection
* @param onFulfilled - Called when promise resolves
* @param onRejected - Called when promise rejects
* @returns New promise with the result of the callback
*/
then(onFulfilled?: (value: any) => any, onRejected?: (reason: any) => any): Promise;Sugar for then(undefined, onRejected) - handles promise rejections.
/**
* Handle promise rejections
* @param onRejected - Called when promise rejects
* @returns New promise
*/
catch(onRejected?: (reason: any) => any): Promise;Executes a callback regardless of promise outcome (fulfill or reject).
/**
* Execute callback regardless of promise outcome
* @param onFinally - Called when promise settles (fulfilled or rejected)
* @returns Promise with original value/reason
*/
finally(onFinally?: () => any): Promise;Creates a resolved promise with the given value.
/**
* Create a resolved promise
* @param value - Value to resolve with (optional)
* @returns Promise resolved with the given value
*/
Promise.resolve(value?: any): Promise;If value is already a promise, returns it unchanged. If value is a thenable, converts it to a promise.
Creates a rejected promise with the given reason.
/**
* Create a rejected promise
* @param reason - Rejection reason
* @returns Promise rejected with the given reason
*/
Promise.reject(reason: any): Promise;Returns a promise that fulfills when all input promises fulfill, or rejects when any input promise rejects.
/**
* Wait for all promises to fulfill
* @param promises - Array of promises or values
* @returns Promise that resolves with array of all resolved values
*/
Promise.all(promises: Array<any | Promise>): Promise;The result array maintains the same order as the input array.
Returns a promise that settles with the same value/reason as the first input promise to settle.
/**
* Return first promise to settle (fulfill or reject)
* @param promises - Array of promises or values
* @returns Promise that settles like the first settled input
*/
Promise.race(promises: Array<any | Promise>): Promise;Patches the global environment with ES6-Promise if the native Promise is missing or broken.
/**
* Polyfill global Promise if missing or broken
* @returns void - Modifies global environment
*/
function polyfill(): void;Usage:
require('es6-promise').polyfill();
// or
require('es6-promise/auto'); // automatic polyfillThe polyfill detects whether the native Promise implementation is compliant and only replaces it if necessary.
/**
* Thenable interface - objects with a then method
*/
interface Thenable<R> {
then<U>(
onFulfilled?: (value: R) => U | Thenable<U>,
onRejected?: (error: any) => U | Thenable<U>
): Thenable<U>;
}
/**
* Promise class implementing Thenable
*/
class Promise<R> implements Thenable<R> {
constructor(executor: (resolve: (value?: R | Thenable<R>) => void, reject: (error?: any) => void) => void);
then<U>(onFulfilled?: (value: R) => U | Thenable<U>, onRejected?: (error: any) => U | Thenable<U>): Promise<U>;
catch<U>(onRejected?: (error: any) => U | Thenable<U>): Promise<U>;
finally(onFinally?: () => any | Thenable<any>): Promise<R>;
static resolve(): Promise<void>;
static resolve<R>(value: R | Thenable<R>): Promise<R>;
static reject<R>(error: any): Promise<R>;
static all<R>(values: Array<R | Thenable<R>>): Promise<R[]>;
static race<R>(promises: (R | Thenable<R>)[]): Promise<R>;
}Promises automatically catch exceptions thrown in executor functions and then/catch callbacks, converting them to rejections:
const promise = new Promise((resolve, reject) => {
throw new Error('This becomes a rejection');
});
promise.catch(error => {
console.error(error.message); // "This becomes a rejection"
});catch and finally: promise['catch'](), promise['finally']().cast())