Implement Promise from scratch

Implementing Promise from scratch is the senior version of the polyfill question. The naive version (then runs the callback) gets you 50%; the rest is state-machine correctness, microtask scheduling, and thenable assimilation.

State machine. A promise is in one of three states: "pending", "fulfilled", or "rejected". Transitions happen at most once (pending → fulfilled or pending → rejected); subsequent calls to resolve/reject are no-ops. Once settled, value/reason is locked in.

The minimum API.

type State = "pending" | "fulfilled" | "rejected";

class MyPromise<T> {
  private state: State = "pending";
  private value: T | undefined;
  private reason: unknown;
  private callbacks: Array<{ onF?: any; onR?: any; resolve: any; reject: any }> = [];

  constructor(executor: (resolve: (v: T | PromiseLike<T>) => void, reject: (e: unknown) => void) => void) {
    try { executor(this._resolve.bind(this), this._reject.bind(this)); }
    catch (e) { this._reject(e); }
  }

  private _resolve(value: T | PromiseLike<T>) {
    if (this.state !== "pending") return;
    // If value is itself a thenable, adopt its state.
    if (value && (typeof value === "object" || typeof value === "function") && typeof (value as any).then === "function") {
      try { (value as any).then(this._resolve.bind(this), this._reject.bind(this)); }
      catch (e) { this._reject(e); }
      return;
    }
    this.state = "fulfilled";
    this.value = value as T;
    this._flush();
  }

  private _reject(reason: unknown) {
    if (this.state !== "pending") return;
    this.state = "rejected";
    this.reason = reason;
    this._flush();
  }

  private _flush() {
    for (const cb of this.callbacks) this._schedule(cb);
    this.callbacks = [];
  }

  private _schedule(cb: { onF?: any; onR?: any; resolve: any; reject: any }) {
    queueMicrotask(() => {
      try {
        if (this.state === "fulfilled") {
          const v = cb.onF ? cb.onF(this.value) : this.value;
          cb.resolve(v);
        } else {
          if (cb.onR) { const v = cb.onR(this.reason); cb.resolve(v); }
          else cb.reject(this.reason);
        }
      } catch (e) { cb.reject(e); }
    });
  }

  then<U>(onF?: (v: T) => U | PromiseLike<U>, onR?: (e: unknown) => U | PromiseLike<U>): MyPromise<U> {
    return new MyPromise<U>((resolve, reject) => {
      const cb = { onF, onR, resolve, reject };
      if (this.state === "pending") this.callbacks.push(cb);
      else this._schedule(cb);
    });
  }

  catch<U>(onR: (e: unknown) => U | PromiseLike<U>) { return this.then(undefined, onR); }

  finally(onFinally: () => void) {
    return this.then(
      v => { onFinally(); return v; },
      e => { onFinally(); throw e; }
    );
  }

  static resolve<T>(v: T | PromiseLike<T>) { return new MyPromise<T>(r => r(v)); }
  static reject<T = never>(e: unknown) { return new MyPromise<T>((_, r) => r(e)); }
}

The four senior details.

1. Microtask scheduling. Spec says then callbacks run as microtasks, not synchronously. Use queueMicrotask (or Promise.resolve().then if polyfilling for old environments). Without this, callbacks would run before the rest of the current synchronous code — breaks ordering.

1. Thenable assimilation in _resolve. If you resolve(somePromise), your promise must adopt that promise's state, not become a fulfilled promise of a promise. Same for any object with a .then method (a "thenable") — calling then on it kicks off the chain.

1. then returns a new promise. Each call must return a fresh promise so chains compose. The new promise resolves with the callback's return value, or rejects if the callback throws.

1. Single transition. _resolve and _reject are no-ops if the promise is no longer pending. The lock prevents a buggy executor from settling twice.

Common interview follow-ups.

• Promise.all — wait for all to fulfill, fail-fast on first reject. Tracking remaining count + result array, capture each index.
• Promise.allSettled — already covered separately.
• Promise.race — first to settle wins. Iterate and call then on each, pass through to outer resolve/reject.
• Promise.any — first to fulfill wins; if all reject, throw AggregateError.

Edge cases worth mentioning.

• Resolving with self → infinite loop in spec; production polyfills detect and reject with TypeError.
• Throwing inside then callback → next promise rejects.
• Awaiting a non-promise → wrapped in Promise.resolve automatically.
• Unhandled rejection event — the runtime fires unhandledrejection if no .catch is attached by the next microtask; production code should add a global handler that logs to Sentry.

When you'd actually do this. Almost never. Native Promise exists everywhere. The polyfill exercise tests whether you understand the semantics — chaining, state machine, microtask timing — not whether you should ship it.