Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


by Nicholas C. Zakas

If you find this useful, please consider supporting my work with a donation.


An implementation of JavaScript promises that matches the ECMA-262 specification as closely as possible. Some differences:

  1. Intentionally does not address Realm concerns as this isn't important to understanding promises.
  2. In order to make things more "JavaScripty", some functions in the specification are represented as classes in this package.
  3. Where variable names were too confusing, I chose to replace them with more meaningful names.

Note: This package is intended only for educational purposes and should not be used in production. There's no reason to use this package because the JavaScript Promise class already implements all of this functionality.

Blog Posts

This package was created as part of the, "Creating a JavaScript promise from scratch," blog post series. If you have questions about this package, please be sure to check out the blog posts:

  1. Part 1: Constructor
  2. Part 2: Resolving to a promise
  3. Part 3: then(), catch(), and finally()
  4. Part 4: Promise.resolve() and Promise.reject()

Additionally, thanks to my GitHub sponsors the following posts are now or will soon be available:

  1. Part 5: Promise.race() and Promise.any()
  2. Part 6: Promise.all() and Promise.allSettled()
  3. Unhandled rejection tracking

If you found this series and code helpful, please sponsor me on GitHub.



Install using npm or yarn:

npm install @humanwhocodes/pledge --save

# or

yarn add @humanwhocodes/pledge

Import into your Node.js project:

// CommonJS
const { Pledge } = require("@humanwhocodes/pledge");

// ESM
import { Pledge } from "@humanwhocodes/pledge";


Import into your Deno project:

import { Pledge } from "";


It's recommended to import the minified version to save bandwidth:

import { Pledge } from "";

However, you can also import the unminified version for debugging purposes:

import { Pledge } from "";


After importing, create a new instance of Pledge and use it like a Promise:

// basics
const pledge = new Pledge((resolve, reject) => {

    // or


pledge.then(value => {
}).catch(reason => {
}).finally(() => {

// create resolved pledges
const fulfilled = Pledge.resolve(42);
const rejected = Pledge.reject(new Error("Uh oh!"));

To watch for unhandled rejections:

// this function is called when any pledge is rejected without a handler
// similar to window.onunhandledrejection
Pledge.onUnhandledRejection = event => {
    const { pledge, reason } = event;

    // cancel warning about this unhandled rejection

// this function is called when a previously unhandled rejection becomes handled
// similar to window.onrejectionhandled;
Pledge.onRejectionHandled = event => {
    const { pledge, reason } = event;

Frequently Asked Questions (FAQ)

Why make this package?

Promises have a lot of difficult concepts to understand, and sometimes the easiest way to understand difficult concepts is to put them into a familiar paradigm. In this case, creating an implementation of promises in JavaScript gave me a better understanding of how they work, and hopefully, they will help others understand them better, too.