Building a Tiny Promise

A promise is a state machine with three states, a value, and a queue of continuations. That is genuinely all a promise is, and the parts you leave out are about interoperability rather than about the core idea.

The states are pending, fulfilled and rejected. A promise starts pending and settles exactly once, which means the transition happens a single time and every later attempt is ignored.

The queue holds the handlers that were registered before the promise settled. When the promise settles, the queue is flushed and each handler runs. If the promise was already settled when a handler was registered, the handler runs as a microtask instead, which keeps the timing consistent either way.

Two details make the real thing hard. The first is that then has to return a new promise, so that the result of a handler can be resolved or rejected in turn, which is what makes chaining work. The second is that the resolution procedure is not just a resolve call. If you resolve with a thenable, the promise adopts its state, which is why returning a promise from an async function works.

What you can skip in an interview version. The thenable adoption, the species mechanism for subclassing, and the careful ordering between queued and immediate handlers. What you must not skip is the single settlement, the queue, and the fact that handlers run asynchronously rather than during the call to then.

The implementation below has a state, a value and a queue of jobs. The then method returns a new promise, which is what makes chaining work.

// A minimal promise: state, value, and a queue of continuations.
class MiniPromise {
  constructor(executor) {
    this.state = "pending";
    this.value = null;
    this.queue = [];

    const settle = (state, value) => {
      if (this.state !== "pending") return;
      this.state = state;
      this.value = value;
      this.flush();
    };

    try {
      executor((v) => settle("fulfilled", v), (e) => settle("rejected", e));
    } catch (err) {
      settle("rejected", err);
    }
  }

  flush() {
    const pending = this.queue;
    this.queue = [];
    for (const job of pending) job();
  }

  then(onFulfilled, onRejected) {
    return new MiniPromise((resolve, reject) => {
      const job = () => {
        const handler = this.state === "fulfilled" ? onFulfilled : onRejected;

        if (typeof handler !== "function") {
          resolve(this.value);
          return;
        }

        try {
          resolve(handler(this.value));
        } catch (err) {
          reject(err);
        }
      };

      if (this.state === "pending") {
        this.queue.push(job);
      } else {
        queueMicrotask(job);
      }
    });
  }

  catch(onRejected) {
    return this.then(undefined, onRejected);
  }
}

new MiniPromise((resolve) => resolve("done"))
  .then((value) => console.log("value:", value));

new MiniPromise((_, reject) => reject(new Error("boom")))
  .catch((err) => console.log("caught:", err.message));

The important design decision is that then returns a new promise rather than the same one. The new promise is resolved with whatever the handler returned, and rejected if the handler threw, which means an exception in one step of a chain turns into a rejection that the next step can catch. That is the behaviour that makes chains reliable.

The other decision is the queueMicrotask call. Handlers registered after the promise has settled still run asynchronously, which keeps the timing identical whether you attach a handler early or late. Without it, a handler attached to an already settled promise would run synchronously, and the ordering of your code would depend on when you attached the handlers.

Two things a real implementation adds. The resolution procedure adopts the state of a thenable, so resolving with a promise waits for it. And the promise is callable, so you can pass a function to resolve and have it invoked with the resolve and reject functions, which is the executor pattern the real promise uses.

Here is the smallest possible version, just enough to see the state machine and the difference between a fulfilled and a rejected promise.

// The three states, with a tiny promise of your own.
const tiny = (executor) => {
  let state = "pending";
  let value = null;

  const promise = {
    then(onFulfilled) {
      if (state === "fulfilled") onFulfilled(value);
      return promise;
    },
    catch(onRejected) {
      if (state === "rejected") onRejected(value);
      return promise;
    },
  };

  executor(
    (v) => { state = "fulfilled"; value = v; },
    (e) => { state = "rejected"; value = e; }
  );

  return promise;
};

tiny((resolve) => resolve("ok")).then((v) => console.log("fulfilled:", v));
tiny((_, reject) => reject(new Error("bad"))).catch((e) => console.log("rejected:", e.message));

Notice what this version leaves out. The handlers run synchronously, so a handler registered after the promise settled runs immediately, whereas a real promise always runs handlers in a microtask. And the state is checked at the moment the handler is registered rather than when the promise settles, so a handler attached to a still pending promise would never run.

That is fine for a demonstration, and it makes the state machine obvious. It also shows why the real implementation needs a queue: the handlers have to be remembered for later, and they have to run at the right time.

The exercise is worth doing because it demystifies the combinators. Once you have written the queue yourself, it is obvious that the race combinator is a promise that settles with whichever input settles first, and that the all combinator is a promise that settles when every input has settled. The combinators are not magic, they are just promises built out of promises.