`await` feels like magic — but a Promise is just a tiny state machine you can build yourself. Implement one from scratch: `.then()` chaining, microtask timing, `Promise.all`, and the gnarly thenable edge cases that pass the official Promise/A+ spec.
Every time you write await, a small state machine springs to life — yet most developers have never seen inside it. A Promise isn't framework magic; it's a pending → fulfilled/rejected state machine wrapped around a list of callbacks and a precisely-timed scheduler. In this project you build that machine yourself, MyPromise, one testable layer at a time, until your class behaves exactly like the native one.
You start with the skeleton: a class that takes an executor, runs it synchronously, hands it resolve/reject, and locks its state forever after the first settle. Then comes the idea that makes promises composable — .then() chaining. You'll discover that .then() doesn't just register a callback; it returns a brand-new promise whose fate depends on what your handler returns, throws, or itself resolves to. Get this right and fetch().then(parse).then(render) flows; get it wrong and the whole tower wobbles. On top you add the sugar — .catch() and .finally() — and learn how a single .catch() rescues an error thrown five links up the chain.
Next is the subtlety almost everyone gets wrong: timing. Native handlers never run synchronously, even when the promise is already resolved — they're deferred onto the microtask queue, which is why Promise.resolve().then(...) runs before setTimeout(..., 0). You'll wire handlers through queueMicrotask and watch the execution order snap into place. Then you build the combinators you reach for daily — Promise.all, race, allSettled, and any — each with its own settle-once logic, index-preserving results, and AggregateError edge cases.
The finale is Promise/A+ compliance: the Resolution Procedure, recursive thenable unwrapping, self-resolution detection, and genuinely evil edge cases (a .then getter that throws, a thenable that calls resolve and reject). Every challenge is graded by real test suites, so the bar is behavior, not vibes. By the end, await will never feel like magic again.