javascript 55 lines · 10 steps

Building a Promise from scratch

A minimal Promise implementation showing how state, microtasks, and chaining fit together.

Explained by highlit

Advanced promises state-machine microtasks async chaining

1const PENDING = 'pending';
2const FULFILLED = 'fulfilled';
3const REJECTED = 'rejected';
4 
5class MyPromise {
constructor(executor) {
  this.state = PENDING;
  this.value = undefined;
  this.callbacks = [];
  const resolve = (value) => this.settle(FULFILLED, value);
  const reject = (reason) => this.settle(REJECTED, reason);
  try {
    executor(resolve, reject);
  } catch (err) {
    reject(err);
  }
}
18 
settle(state, value) {
  if (this.state !== PENDING) return;
  this.state = state;
  this.value = value;
  this.callbacks.forEach((cb) => this.schedule(cb));
  this.callbacks = [];
}
26 
schedule(cb) {
  queueMicrotask(() => cb(this.state, this.value));
}
30 
then(onFulfilled, onRejected) {
  return new MyPromise((resolve, reject) => {
    const handle = (state, value) => {
      const handler = state === FULFILLED ? onFulfilled : onRejected;
      if (typeof handler !== 'function') {
        state === FULFILLED ? resolve(value) : reject(value);
        return;
      }
      try {
        const result = handler(value);
        if (result instanceof MyPromise) result.then(resolve, reject);
        else resolve(result);
      } catch (err) {
        reject(err);
      }
    };
    if (this.state === PENDING) this.callbacks.push(handle);
    else this.schedule(handle);
  });
}
51 
catch(onRejected) {
  return this.then(undefined, onRejected);
}
55}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1A promise is a small state machine that transitions from pending to a single terminal state exactly once.
2Callbacks registered before settlement are queued, and resolution always runs asynchronously via the microtask queue.
3then returns a new promise whose fate is decided by the handler's return value, enabling chains and flattening nested promises.

Related explainers

javascript

'use server'
 
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'

How a Next.js Server Action updates a post

server-actions authorization validation

Intermediate 7 steps

typescript

type RetryOptions = {
  retries?: number;
  timeoutMs?: number;
  baseDelayMs?: number;

Retry with timeout and backoff in TypeScript

promises retry exponential-backoff

Intermediate 10 steps

javascript

const express = require('express');
 
const v1 = express.Router();

Versioning an API with Express Routers

api versioning routing modularity

Intermediate 10 steps

javascript

const RATE_LIMIT = 100;
const WINDOW_MS = 60 * 1000;
const BLOCK_MS = 5 * 60 * 1000;

Building a rate-limiting middleware in Express

rate-limiting middleware closures

Intermediate 9 steps

javascript

const transitions = {
  cart: { checkout: 'shipping' },
  shipping: { submitAddress: 'payment', back: 'cart' },
  payment: { submitPayment: 'review', back: 'shipping' },

A finite state machine for checkout flow

state-machine event-driven data-driven-design

Intermediate 7 steps

javascript

import { useState, useEffect, useCallback, useRef } from "react";
 
export function usePersistentForm(storageKey, initialValues) {
  const [values, setValues] = useState(() => {