Build a promise from scratch

Build the mental model before the class

The earlier promise lessons taught how to use promises: states, chains, combinators, errors, microtasks, and the event loop. This lesson turns those behaviors inside out by building a small, real MyPromise implementation.

We will still use native Promise in production. Rebuilding one is a professional reading exercise: it makes promise bugs feel mechanical instead of mysterious.

Start with the smallest useful shell. A promise begins pending. It can become fulfilled with a value or rejected with a reason. Both transitions use the same guard: if the state is no longer pending, return immediately. That guard is why extra resolve and reject calls are ignored.

1class MyPromise {2  constructor(executor) {3    this.state = "pending";4    this.result = undefined;5 6    const resolve = (value) => {7      if (this.state !== "pending") return;8      this.state = "fulfilled";9      this.result = value;10    };11    const reject = (reason) => {12      if (this.state !== "pending") return;13      this.state = "rejected";14      this.result = reason;15    };16 17    try {18      executor(resolve, reject);19    } catch (error) {20      reject(error);21    }22  }23}

Line 3 stores the state. Lines 6 and 11 enforce “settle once.” Lines 16–18 run the executor and convert a synchronous throw into a rejection. This version cannot call handlers yet, but it already captures the heart of a promise: one outcome.

A promise becomes useful when other code can register reactions. then has two jobs in this version: if the promise is pending, store a handler record; if it is already settled, schedule that record with the remembered result.

1let release;Run2const ticket = new MyPromise((resolve) => {3  release = resolve;4});5 6ticket.then((value) => {7  console.log("first: " + value);8});9ticket.then((value) => {10  console.log("second: " + value);11});12 13release("order ready");14release("ignored");

The important detail is that the value is not consumed. Both handlers receive "order ready". A promise is closer to a stored result plus a notification queue than to an event that disappears after the first listener runs.

1let release;2const ticket = new MyPromise((resolve) => {3  release = resolve;4});5 6ticket.then((value) => {7  console.log("first: " + value);8});9ticket.then((value) => {10  console.log("second: " + value);11});12 13release("order ready");14release("ignored");

Native then never mutates the original promise. It returns a new promise immediately. Later, when the handler runs, that new promise is resolved from the handler’s return value or rejected from a thrown error.

1MyPromise.resolve(2)Run2  .then((value) => {3    return value + 3;4  })5  .then((value) => {6    return MyPromise.resolve(value * 2);7  })8  .then((value) => {9    console.log(value);10  });

Read the chain one callback at a time. Line 3 returns a plain number, so the next promise fulfills with that number. Line 6 returns another promise, so the next promise adopts it. Line 9 receives the adopted value rather than a promise object.

1MyPromise.resolve(2)2  .then((value) => {3    return value + 3;4  })5  .then((value) => {6    return MyPromise.resolve(value * 2);7  })8  .then((value) => {9    console.log(value);10  });

Non-function handlers matter too. If onFulfilled is not a function, the value passes through. If onRejected is not a function, the reason keeps rejecting. That is the basis for catch.

The hard part is not storing a value. The hard part is deciding what to do with the value a handler returns. The Promise Resolution Procedure says: reject cycles, fulfill ordinary values, and adopt promise-shaped values by calling their then carefully.

1const thenable = {Run2  then(resolve, reject) {3    resolve("first");4    reject("second");5    resolve("third");6  },7};8 9MyPromise.resolve(thenable)10  .then((value) => value + " adopted")11  .then((value) => console.log(value));

1let nativeResolve;2const native = new Promise((resolve) => {3  nativeResolve = resolve;4});5nativeResolve(native);6native.catch((error) => {7  console.log("native: " + error.name + ": " + error.message);8});9 10let myResolve;11const mine = new MyPromise((resolve) => {12  myResolve = resolve;13});14myResolve(mine);15mine.catch((error) => {16  console.log("mine: " + error.name + ": " + error.message);17});

In Node 22 and Chrome’s V8 engine, native self-resolution rejects with TypeError: Chaining cycle detected for promise #<Promise>. This lesson’s MyPromise rejects with the same shape and names #<MyPromise>. The exact wording is not part of Promises/A+, but the TypeError rejection is the required behavior.

A promise implementation that calls handlers inline is broken, even when the promise is already fulfilled. Handlers must wait until the current stack finishes. Our implementation uses queueMicrotask with a promise fallback for older environments.

1console.log("sync");2MyPromise.resolve("mine").then((value) => console.log("my " + value));3Promise.resolve("native").then((value) => console.log("native " + value));4queueMicrotask(() => console.log("queued"));5setTimeout(() => console.log("timeout"), 0);

The output is sync, my mine, native native, queued, then timeout. The MyPromise handler is queued before the native handler because line 2 registers it first. Both promise handlers and the direct microtask beat the timer task.

Once then and resolution work, the helpers are small. catch is then(null, onRejected). finally runs cleanup and then passes through the original value or reason, unless cleanup itself fails.

1MyPromise.resolve("tea").then((value) => {2  console.log("value: " + value);3});4 5MyPromise.reject("missing").catch((reason) => {6  console.log("caught: " + reason);7});8 9MyPromise.resolve("saved")10  .finally(() => {11    return MyPromise.resolve("cleanup").then((value) => console.log(value));12  })13  .then((value) => console.log("after finally: " + value));

The finally example returns a promise from cleanup. MyPromise.resolve(cleanup()).then(...) makes the final then wait before it sees "saved".

Static combinators are loops around MyPromise.resolve and then. They do not need secret engine hooks. They need careful bookkeeping: preserve input order, settle once, and treat plain values like already-fulfilled inputs.

1const slow = new MyPromise((resolve) => {2  setTimeout(() => resolve("slow"), 20);3});4const fast = MyPromise.resolve("fast");5 6MyPromise.all([slow, fast, "plain"]).then((values) => {7  console.log(values.join(","));8});9 10MyPromise.all([]).then((values) => {11  console.log("empty " + values.length);12});

1const slow = new MyPromise((resolve) => {2  setTimeout(() => resolve("slow"), 20);3});4const fast = new MyPromise((resolve) => {5  setTimeout(() => resolve("fast"), 5);6});7 8MyPromise.race([slow, fast]).then((value) => {9  console.log(value);10});

1MyPromise.allSettled([2  MyPromise.resolve("ok"),3  MyPromise.reject("bad"),4]).then((results) => {5  console.log(results.map((item) => item.status).join("/"));6});7 8MyPromise.any([9  MyPromise.reject("no A"),10  MyPromise.resolve("yes B"),11]).then((value) => console.log(value));12 13MyPromise.any([14  MyPromise.reject("no A"),15  MyPromise.reject("no B"),16]).catch((error) => {17  console.log(error.name + ": " + error.errors.join(","));18});

Promise.all rejects with the first rejection in time, but it does not cancel other work. Promise.race([]) has no first settlement, so it stays pending. Promise.any([]) rejects immediately with AggregateError because success is impossible.

Promises/A+ standardized the interoperable core: the shape of then and the resolution procedure. It did not define every native static method, browser unhandled-rejection events, async/await, or engine performance work.

1async function runScenario(PromiseLibrary) {2  const chain = await PromiseLibrary.resolve(2)3    .then((value) => value + 3)4    .then((value) => PromiseLibrary.resolve(value * 2));5 6  const recovered = await PromiseLibrary.reject("lost")7    .catch((reason) => "fixed " + reason);8 9  const all = await PromiseLibrary.all([10    new PromiseLibrary((resolve) => setTimeout(() => resolve("slow"), 20)),11    PromiseLibrary.resolve("fast"),12    "plain",13  ]);14 15  const race = await PromiseLibrary.race([16    new PromiseLibrary((resolve) => setTimeout(() => resolve("slow"), 20)),17    new PromiseLibrary((resolve) => setTimeout(() => resolve("fast"), 5)),18  ]);19 20  return [chain, recovered, all.join(","), race].join(" | ");21}

1const cases = [2  ["value chain", (P) => P.resolve(1).then((value) => value + 1)],3  ["rejection recovery", (P) => P.reject("lost").catch(() => "fixed")],4  ["thenable adoption", (P) => P.resolve({ then(resolve) { resolve("thenable"); } })],5  ["all order", (P) => P.all([P.resolve("A"), "B"]).then((values) => values.join("-"))],6];7 8for (const [label, run] of cases) {9  run(MyPromise).then((value) => console.log("my " + label + ": " + value));10  run(Promise).then((value) => console.log("native " + label + ": " + value));11}

The official promises-aplus-tests package is a real conformance suite for A+ implementations. It is not installed here, so our tests are intentionally described as a mini suite. Native promises also include platform behavior outside A+, such as unhandled rejection tracking, Promise.withResolvers in Node 22, and Promise.try in newer browsers but not this Node runtime.

Practical use and misconceptions

You rarely ship a promise implementation. You do use this knowledge when debugging tests, reviewing promise utilities, adapting old callback APIs, and explaining why then callbacks do not run where someone expected.

• “A fulfilled promise calls then immediately.” It schedules a microtask.
• “then changes the original promise.” It returns a new promise.
• “Returning a promise creates a nested promise.” Resolution adopts it.
• “A thenable can call resolve and reject.” It can try, but only the first call counts.
• “Promise.all cancels the rest.” It fails fast without canceling other work.
• “Promises/A+ is the whole native API.” A+ standardized the core then behavior; ECMAScript and hosts add more.

Key takeaways

• A promise implementation stores one state and one result, then settles once.
• then registers handlers and returns a new promise for the callback outcome.
• The Promise Resolution Procedure adopts promises and thenables, rejects cycles, and ignores double settlement.
• Handlers are microtasks, so even already-fulfilled promises never call callbacks inline.
• Combinators are bookkeeping around many calls to resolve and then.
• Promises/A+ covers the core then contract; native promises add more platform behavior.

One-line summary: Build promises by protecting one state transition, resolving each returned value correctly, and scheduling every reaction after the current stack.

Up next: Classic utilities. The same build-it-yourself method will guide deep clone, deep equal, curry, memoize, and related helpers.