tessl/npm-es6-promise

A lightweight ES6 Promise polyfill library for organizing asynchronous code

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

ES6 Promise

Name: tessl/npm-es6-promise
Author: tessl

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.

Package Information

Package Name: es6-promise
Package Type: npm
Language: JavaScript with TypeScript definitions
Installation: npm install es6-promise

Core Imports

const { Promise } = require('es6-promise');

For automatic polyfilling:

require('es6-promise/auto');
// Promise is now available globally

ES6 modules:

import Promise from 'es6-promise';

Basic Usage

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]
});

Architecture

ES6-Promise provides a complete Promise implementation with:

Core Promise Class: Full ES6 Promise specification compliance with constructor, instance methods
Static Methods: resolve, reject, all, race for creating and combining promises
Polyfill System: Automatic detection and replacement of broken or missing native Promise implementations
TypeScript Support: Complete type definitions with generic support and thenable interfaces
Cross-Platform: Works in Node.js, browsers, and Web Workers

Capabilities

Promise Constructor

Creates 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.

Instance Methods

then()

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;

catch()

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;

finally()

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;

Static Methods

Promise.resolve()

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.

Promise.reject()

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;

Promise.all()

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.

Promise.race()

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;

Polyfill Functions

polyfill()

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 polyfill

The polyfill detects whether the native Promise implementation is compliant and only replaces it if necessary.

Types

/**
 * 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>;
}

Error Handling

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"
});

Compatibility Notes

IE<9: Use bracket notation for catch and finally: promise['catch'](), promise['finally']()
Environment Detection: Automatically detects Node.js, browser, and Web Worker environments
Native Promise: Only polyfills if native Promise is missing or broken (doesn't implement .cast())
Error Objects: For consistency and debugging, rejection reasons should be Error instances

Install with Tessl CLI

npx tessl i tessl/npm-es6-promise

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/es6-promise@4.2.x
Publish Source: CLI
Badge