Mastering JavaScript Promises: From Scratch to Full A+ Implementation

Overview

This guide explains how to implement a Promise library in JavaScript from scratch, covering the basic functionality, asynchronous execution, chaining, state management, error handling, and compliance with the Promise/A+ specification.

Version 1 – Basic Promise

Start with a simple class that stores callbacks, provides a then method to collect them, and resolves them when _resolve is called.

class Promise {
  callbacks = []
  constructor(fn) {
    fn(this._resolve.bind(this))
  }
  then(onFulfilled) {
    this.callbacks.push(onFulfilled)
  }
  _resolve(val) {
    const me = this
    me.callbacks.forEach(fn => fn(val))
  }
}

Version 2 – Asynchronous Execution and Chaining

Add a setTimeout in _resolve to ensure callbacks run asynchronously and return this from then to enable simple chaining.

class Promise {
  callbacks = []
  constructor(fn) {
    fn(this._resolve.bind(this))
  }
  then(onFulfilled) {
    this.callbacks.push(onFulfilled)
    return this
  }
  _resolve(val) {
    setTimeout(() => {
      this.callbacks.forEach(fn => fn(val))
    })
  }
}

Version 3 – Proper Chainable Promises

Introduce internal state ( pending, fulfilled), store the resolved value, and make then return a new Promise that resolves with the result of the previous callback, achieving true chaining.

class Promise {
  callbacks = []
  value = null
  state = 'pending'
  constructor(fn) {
    fn(this._resolve.bind(this))
  }
  then(onFulfilled = null) {
    const me = this
    return new Promise(resolve => {
      me._handle({ onFulfilled, resolve })
    })
  }
  _handle(cbObj) {
    if (this.state === 'pending') {
      this.callbacks.push(cbObj)
      return
    }
    if (!cbObj.onFulfilled) {
      this._resolve(this.value)
      return
    }
    const val = cbObj.onFulfilled(this.value)
    cbObj.resolve(val)
  }
  _resolve(val) {
    setTimeout(() => {
      this.value = val
      this.state = 'fulfilled'
      this.callbacks.forEach(cb => this._handle(cb))
    })
  }
}

Version 3.1 – Handling Returned Promises

Detect if a callback returns a promise or thenable and bind its then to the internal resolve, allowing nested asynchronous operations.

_resolve(val) {
  const me = this
  if (val && (typeof val === 'object' || typeof val === 'function')) {
    const then = val.then
    if (then && typeof then === 'function') {
      then.call(val, me._resolve.bind(me))
      return
    }
  }
  setTimeout(() => {
    me.value = val
    me.state = 'fulfilled'
    me.callbacks.forEach(cb => me._handle(cb))
  })
}

Version 4 – Full A+ Compliance

Add rejected state, reject method, and error handling in then. The implementation now follows the Promise/A+ spec, including protection against multiple state changes and handling of self‑resolution errors.

class Promise {
  callbacks = []
  value = null
  reason = null
  state = 'pending'
  constructor(fn) {
    try {
      fn(this._resolve.bind(this), this._reject.bind(this))
    } catch (e) {
      this._reject(e)
    }
  }
  then(onFulfilled = null, onRejected = null) {
    const me = this
    return new Promise((resolve, reject) => {
      me._handle({ onFulfilled, onRejected, resolve, reject })
    })
  }
  _handle(cbObj) {
    if (this.state === 'pending') {
      this.callbacks.push(cbObj)
      return
    }
    const cb = this.state === 'fulfilled' ? cbObj.onFulfilled : cbObj.onRejected
    const next = this.state === 'fulfilled' ? cbObj.resolve : cbObj.reject
    if (!cb) {
      next(this.state === 'fulfilled' ? this.value : this.reason)
      return
    }
    try {
      const val = cb(this.state === 'fulfilled' ? this.value : this.reason)
      cbObj.resolve(val)
    } catch (e) {
      cbObj.reject(e)
    }
  }
  _resolve(val) {
    if (this.state !== 'pending') return
    if (this === val) {
      return this._reject(new TypeError('cannot return the same promise object from onfulfilled or onrejected callback.'))
    }
    if (val && (typeof val === 'object' || typeof val === 'function')) {
      const then = val.then
      if (then && typeof then === 'function') {
        then.call(val, this._resolve.bind(this), this._reject.bind(this))
        return
      }
    }
    setTimeout(() => {
      this.value = val
      this.state = 'fulfilled'
      this._execute()
    })
  }
  _reject(reason) {
    if (this.state !== 'pending') return
    setTimeout(() => {
      this.reason = reason
      this.state = 'rejected'
      this._execute()
    })
  }
  _execute() {
    this.callbacks.forEach(cb => this._handle(cb))
  }
}

The article also provides links to the Promise/A+ spec, a reference implementation by 阮一峰, and instructions for running the promises-aplus-tests suite against the custom implementation.