Build a promise from scratch

Build a promise to see how it works

Earlier lessons showed how to use promises: their states, chains, combinators, errors, microtasks, and the event loop. In this lesson you build your own small promise class, called MyPromise. Building one shows you why promises behave the way they do.

You build MyPromise in five versions. Each version adds one rule. Read each row of the table as: "in this version, the class learns this rule, and this is why it matters."

In real apps you will still use the built-in Promise. Building one yourself is practice in reading code. Once you have seen every part, you can explain a promise bug step by step.

Start with the smallest class that works. A new promise starts pending: it has no result yet. Later it settles, which means it gets its final result. It can settle in one of two ways:

• Fulfilled, with a value. The resolve function does this.
• Rejected, with a reason. The reject function does this.

Both functions start with the same check, called a guard: if the state is no longer pending, stop right away. This guard is why extra calls to resolve and reject do nothing.

The executor is the function you pass to new MyPromise(...). The class calls it right away and hands it resolve and reject.

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 7 and 12 are the guards. Line 18 calls the executor. If the executor throws an error, line 20 catches it and rejects the promise. This version can't run handlers yet. But it already has the most important rule: a promise gets one outcome.

1const order = [];2const ticket = new MyPromise((resolve) => {3  order.push("executor");4  resolve("ready");5});6order.push("after new");7ticket.then((value) => console.log(order.join(" -> ") + ": " + value));

Line 2 creates the promise, so line 3 runs right away and adds "executor" to the order array. Line 4 fulfills the promise with "ready". Line 6 still runs before the handler. Then the handler from line 7 prints executor -> after new: ready.

1const saved = new MyPromise((resolve) => {2  resolve("saved");3  throw new Error("late");4});5saved.then((value) => console.log(value));6const failed = new MyPromise(() => { throw new Error("offline"); });7failed.catch((error) => console.log("caught: " + error.message));8const adopted = new MyPromise((resolve) => {9  resolve({ then: (fulfill) => setTimeout(() => fulfill("adopted"), 0) });10  throw new Error("after resolve");11});12adopted.then((value) => console.log("adopted: " + value));

This example has three executors:

• The first calls resolve on line 2, then throws on line 3. The promise already has its value, so the throw can't replace "saved". Line 5 prints saved.
• The second throws on line 6 while the promise is still pending. So the promise rejects, and line 7 prints caught: offline.
• The third calls resolve on line 9 with a thenable: an object with a then method. Version 4 explains thenables. The promise is still waiting for the thenable when line 10 throws. But calling resolve already locked the promise, so the throw is ignored. Line 12 prints adopted: adopted.

A promise is useful when other code can react to its result. A handler is a function you pass to then. In this version, then does one of two things:

• If the promise is pending, it saves the handler in a list.
• If the promise has settled, it schedules the handler to run soon, with the stored 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");

Both handlers get "order ready". Running a handler doesn't use up the value. A promise is a stored result plus a list of handlers waiting for it. It is not like an event, which is gone once its listeners have run.

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");

1const request = MyPromise.reject("offline");2request.then(null, (reason) => console.log("handled later: " + reason));

Line 1 rejects the promise before any handler is added. Line 2 adds a handler later. It still gets the stored reason in a microtask, and prints handled later: offline.

An unhandled rejection is a rejection that no handler ever catches. Browsers and Node.js warn you about those. MyPromise keeps the rejection for later handlers, but it never sends that warning.

The built-in then never changes the promise you call it on. It returns a new promise right away. Later, when the handler runs, the new promise settles from what the handler does:

• The handler returns a value: the new promise fulfills with that value.
• The handler throws an error: the new promise rejects with that error.
• The handler returns a promise: the new promise waits for it and takes its result. This is called adopting the promise.

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 handler at a time. Line 3 returns a plain number, 5, so the next promise fulfills with 5. Line 6 returns another promise, so the next promise adopts it. Line 9 gets the adopted value, 10, not 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  });

1const original = MyPromise.reject("offline");2const next = original.then();3console.log("new promise: " + (next !== original));4next.catch((reason) => console.log("passed through: " + reason));5MyPromise.resolve("tea").then(() => { throw new Error("no tea"); })6  .catch((error) => console.log("caught: " + error.message));

Line 1 creates a rejected promise. Line 2 calls then with no handlers at all. Line 3 checks that then returned a different promise, and prints new promise: true. Line 4 catches the same "offline" reason, because nothing handled it on the way. Line 5 throws inside a handler. Line 6 catches that new error and prints caught: no tea.

So then must also deal with missing handlers. The first function you pass to then is the fulfillment handler; it runs on success. The second is the rejection handler; it runs on failure.

• No fulfillment handler: the value passes through to the next promise.
• No rejection handler: the reason passes through, so the next promise rejects too.
• A handler that throws: the next promise rejects with that error.

These rules are all that catch needs. You will build it from then later in this lesson.

Storing a value is easy. The hard part is deciding what to do with the value a handler returns. The rules for this have a name: the Promise Resolution Procedure. They say:

• If the value is the promise itself, reject with a TypeError. A promise can't wait for itself.
• If the value is a plain value, like a number, fulfill with it.
• If the value is a thenable, read its then once, call it, and adopt the result. Every promise is a thenable, and so is any object with a then method.
• Only the first call to resolve or reject from a thenable counts.

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 reads = 0;2const order = {3  get then() { reads += 1; return (resolve) => resolve("tea"); },4};5MyPromise.resolve(order).then((value) => console.log(value + ": " + reads));

A getter is a property that runs a function each time you read it. Line 1 starts a counter at 0. Line 3 makes then a getter: each read adds 1 to the counter and returns a function. MyPromise reads then once, keeps the function, and calls it. So line 5 prints tea: 1. If the code read then twice, a getter like this could give two different answers.

1const order = {2  get then() { throw new Error("broken order"); },3};4MyPromise.resolve(order).catch((error) => console.log("rejected: " + error.message));

Line 2 makes then a getter that throws an error. The procedure catches the error and rejects the promise. So the catch on line 4 prints rejected: broken order. A broken thenable can't crash the chain. Its error goes down the normal rejection path instead.

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});

Line 5 resolves the built-in promise with itself. Line 14 does the same with MyPromise. Both reject with a TypeError, and lines 7 and 16 print the messages.

• In Node 22 and Chrome, the built-in message is TypeError: Chaining cycle detected for promise #<Promise>.
• MyPromise uses the same message, but names #<MyPromise>.

Promises/A+, the shared rulebook you'll meet near the end of this lesson, requires the TypeError. It doesn't require the exact words.

A handler must never run right away, inside then. Not even when the promise is already fulfilled. It must wait until the code that is running now has finished. MyPromise does this with queueMicrotask, a built-in function that runs a function as a microtask. In very old environments without queueMicrotask, it uses a built-in promise to do the same job.

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. Line by line:

• Line 1 runs right away.
• The MyPromise handler runs before the built-in one, because line 2 adds it first.
• Both promise handlers and the job from line 4 are microtasks.
• The timer on line 5 is a task, a bigger job. Every waiting microtask runs before the next task, so timeout prints last.

Once then and the resolution rules work, the other methods are short:

• catch(onRejected) is just then(null, onRejected).
• finally(cleanup) runs cleanup, then passes on the first value or reason. If cleanup fails, the promise rejects with that error instead.
• MyPromise.resolve(value) makes a promise fulfilled with value, or adopts it if it is a thenable. If value is already a MyPromise, it gives it back as it is.
• MyPromise.reject(reason) makes a promise rejected with reason.

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));

Lines 1 to 3 print value: tea. Lines 5 to 7 print caught: missing. On line 11 the cleanup returns a promise, which prints cleanup. finally wraps it in MyPromise.resolve(cleanup()).then(...), so it waits for that promise. Only then does line 13 get "saved" and print after finally: saved.

A combinator is a method that takes many promises and gives back one promise. You call it on the class, like MyPromise.all(...), not on one promise. Each combinator is a loop that calls MyPromise.resolve and then on every input. It needs no hidden engine features. It only needs careful counting:

• Keep the results in the same order as the inputs.
• Settle only once.
• Treat a plain value, like "plain", as an already-fulfilled promise.

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});

Line 10 passes an empty array, so all fulfills with an empty array at once and prints empty 0 first. Line 6 waits for slow, fast, and "plain". slow finishes last, but its value stays first, so line 7 prints slow,fast,plain.

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});

fast fulfills after 5 milliseconds and slow after 20. So race fulfills with "fast", and line 9 prints fast.

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});

• Lines 1 to 6 print fulfilled/rejected. allSettled waits for every input and reports each one's status.
• Lines 8 to 11 print yes B. any uses the first input that fulfills and skips rejections.
• Lines 13 to 18 reject with an AggregateError: an error that keeps a list of errors in its errors property. They print AggregateError: no A,no B.

Three edge cases to remember:

• Promise.all rejects with the first rejection, but it doesn't stop the other work.
• Promise.race([]) has nothing to wait for, so it stays pending forever.
• Promise.any([]) rejects at once with an AggregateError, because no input can succeed.

Promises/A+ is a short, shared rulebook for promises. Promise libraries wrote it before promises were built into JavaScript, so that their promises could work together. It covers two things:

• How then must behave.
• The Promise Resolution Procedure.

It does not cover:

• Methods like all and race.
• Browser warnings for unhandled rejections.
• async and await.
• How fast an engine runs promises.

The table compares three things. Read each row as one question, answered for MyPromise, for the built-in Promise, and for Promises/A+.

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}

Lines 1 to 6 list four small cases. Lines 8 to 11 run each case once with MyPromise and once with the built-in Promise, and print both results. Every pair matches.

The official promises-aplus-tests package is a full conformance suite: a large set of tests that checks an implementation against every A+ rule. It is not installed here, so this is only a small check. The built-in Promise also has features outside A+:

• It tracks unhandled rejections.
• Node 22 has Promise.withResolvers.
• Newer browsers have Promise.try, but Node 22 does not.

Where this helps, and common mistakes

You will rarely ship your own promise class. But knowing how one works helps when you:

• debug tests that use promises,
• review helper functions built on promises,
• wrap old callback-style functions in promises,
• explain why a then handler didn't run when someone expected.

• “A fulfilled promise runs its handler right away.” It schedules the handler as a microtask.
• “then changes the original promise.” It returns a new promise.
• “Returning a promise from a handler puts a promise inside a promise.” The next promise adopts it, so you get the value.
• “A thenable can both resolve and reject.” It can try, but only the first call counts.
• “Promise.all stops the other promises when one fails.” It rejects early, but the other work keeps running.
• “Promises/A+ is the whole built-in Promise.” A+ covers only then and resolution. The JavaScript standard and the browser add the rest.

Each row below is a mistake people make when they build a promise. Read it as: "if you do this, you see this, and this is the fix."

Key takeaways

• A promise keeps one state and one result, and it settles only once.
• then saves handlers and returns a new promise for each handler's outcome.
• The Promise Resolution Procedure adopts promises and thenables, rejects a promise resolved with itself, and counts only the first call.
• Handlers always run as microtasks, even when the promise is already fulfilled.
• Combinators are loops that call resolve and then on many promises and keep careful count.
• Promises/A+ covers then and resolution; the built-in Promise adds more.

One-line summary: To build a promise, let the state change only once, settle the next promise from each handler's result, and run every handler after the current code finishes.

Up next: Classic utilities. You'll build more helpers yourself, such as deep clone, deep equal, curry, and memoize.