Promise &
async/await
底层原理全解

// 定义三种状态常量
const PENDING = 'pending' as const;
const FULFILLED = 'fulfilled' as const;
const REJECTED = 'rejected' as const;

type PromiseState = typeof PENDING | typeof FULFILLED | typeof REJECTED;

class MyPromise<T = any> {
  private state: PromiseState = PENDING;   // ← 初始状态必须是 pending
  private value: T | undefined = undefined;
  private reason: any = undefined;

  // A+ 2.2.6: then 可以被调用多次, 所以用数组存储回调
  private onFulfilledCallbacks: Array<(value: T) => void> = [];
  private onRejectedCallbacks: Array<(reason: any) => void> = [];

  constructor(executor: (resolve: (value: T) => void, reject: (reason: any) => void) => void) {
    try {
      executor(this.resolve.bind(this), this.reject.bind(this));
    } catch (err) {
      this.reject(err); // ← executor 抛错自动 reject
    }
  }

  // A+ 2.1.1 & 2.1.2: 状态只能 pending → fulfilled/rejected, 不可逆
  private resolve(value: T) {
    if (this.state !== PENDING) return;  // ← 关键: 已决议则忽略
    this.state = FULFILLED;
    this.value = value;
    // 异步执行所有排队的回调 (A+ 2.2.4)
    this.onFulfilledCallbacks.forEach(fn => fn(value));
  }

  private reject(reason: any) {
    if (this.state !== PENDING) return;  // ← 同样不可逆
    this.state = REJECTED;
    this.reason = reason;
    this.onRejectedCallbacks.forEach(fn => fn(reason));
  }
}

class MyPromise<T = any> {
  // ... 前面的代码 ...

  then<TResult1 = T, TResult2 = never>(
    onFulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
    onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
  ): MyPromise<TResult1 | TResult2> {
    // A+ 2.2.1: onFulfilled/onRejected 如果不是函数, 必须被忽略
    // 这保证了 .then(null, err => ...) 和 .then(val => ..., null) 的正确透传
    const realOnFulfilled = typeof onFulfilled === 'function'
      ? onFulfilled
      : (value: T) => value as any;  // ← 值穿透: 直接返回 value
    const realOnRejected = typeof onRejected === 'function'
      ? onRejected
      : (reason: any) => { throw reason }; // ← 错误穿透: 继续抛出

    // A+ 2.2.7: .then 必须返回一个新 Promise (这是链式调用的基础!)
    const promise2 = new MyPromise<TResult1 | TResult2>((resolve, reject) => {
      // 封装统一的处理函数, 包含 A+ 2.3 Resolution Procedure
      const handle = (fn: Function, value: any) => {
        // A+ 2.2.4: 异步执行 (用 queueMicrotask 模拟)
        queueMicrotask(() => {
          try {
            const x = fn(value);           // ← 执行回调得到返回值 x
            resolvePromise(promise2, x, resolve, reject); // ← A+ 2.3 处理 x
          } catch (err) {
            reject(err);                   // ← 回调抛错, promise2 reject
          }
        });
      };

      if (this.state === FULFILLED) {
        handle(realOnFulfilled, this.value);
      } else if (this.state === REJECTED) {
        handle(realOnRejected, this.reason);
      } else {
        // 还是 pending 状态 → 订阅, 等待 resolve/reject 时执行
        this.onFulfilledCallbacks.push(val => handle(realOnFulfilled, val));
        this.onRejectedCallbacks.push(reason => handle(realOnRejected, reason));
      }
    });

    return promise2; // ← 返回新 Promise, 支持链式调用!
  }
}

/**
 * A+ 2.3 Resolution Procedure
 * 这是整个 Promise 实现中最复杂的部分
 * 负责处理 .then 回调返回值 x 的所有可能类型
 */
function resolvePromise<T>(
  promise2: MyPromise<T>,  // ← 当前正在构建的新 Promise
  x: any,                   // ← .then 回调的返回值
  resolve: (value: T) => void,
  reject: (reason: any) => void
) {
  // A+ 2.3.1: x === promise2 → 循环引用! 必须 reject
  if (x === promise2) {
    return reject(new TypeError('循环引用: .then 不能返回自身'));
  }

  // A+ 2.3.2: x 是 Promise 实例 → 直接采纳其状态
  if (x instanceof MyPromise) {
    x.then(resolve, reject); // ← 递归采纳, 如果 x 还是 pending 会等它决议
    return;
  }

  // A+ 2.3.3: x 是对象或函数 (可能是 thenable)
  if (x !== null && (typeof x === 'object' || typeof x === 'function')) {
    let called = false; // ← A+ 2.3.3.3.3: 防止多次调用

    try {
      const then = x.then; // ← A+ 2.3.3.1: 取 .then 属性(可能是 getter!)

      if (typeof then === 'function') {
        // A+ 2.3.3.3: x 是 thenable → 调用其 .then
        then.call(
          x,
          (y: any) => {
            if (called) return; called = true;
            resolvePromise(promise2, y, resolve, reject); // ← 递归解析! y 可能还是 Promise
          },
          (r: any) => {
            if (called) return; called = true;
            reject(r);
          }
        );
      } else {
        // A+ 2.3.3.4: x 是普通对象, 不是 thenable
        resolve(x as T);
      }
    } catch (err) {
      // A+ 2.3.3.2 & 2.3.3.3.4: 只在首次调用时捕获错误
      if (called) return;
      called = true;
      reject(err);
    }
    return;
  }

  // A+ 2.3.4: x 是普通值 (string/number/boolean/null/undefined)
  resolve(x as T);
}

class MyPromise<T = any> {
  // ... then 和构造函数代码 ...

  // catch 就是 then(null, onRejected) 的语法糖
  catch<TResult = never>(
    onRejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
  ): MyPromise<T | TResult> {
    return this.then(null, onRejected);
  }

  // finally 不改变 Promise 的值/原因, 只是附加清理逻辑
  finally(onFinally?: (() => void) | null): MyPromise<T> {
    return this.then(
      (value) => {
        // ← 关键: onFinally() 返回的 Promise 要等它完成
        // 然后返回原始 value, 不是 onFinally 的返回值!
        return MyPromise.resolve(onFinally?.()).then(() => value);
      },
      (reason) => {
        return MyPromise.resolve(onFinally?.()).then(() => { throw reason; });
      }
    );
  }

  // ===== 静态方法 =====

  // Promise.resolve: 将值包装为已决议的 Promise
  static resolve<T>(value: T | PromiseLike<T>): MyPromise<T> {
    if (value instanceof MyPromise) return value; // ← 已经是 Promise 直接返回
    return new MyPromise((resolve) => resolve(value));
  }

  // Promise.reject: 创建一个已拒绝的 Promise
  static reject<T = never>(reason: any): MyPromise<T> {
    return new MyPromise((_, reject) => reject(reason));
  }

  // Promise.all: 并行执行, 全部成功才 resolve, 一个失败就 reject
  static all<T>(promises: Array<T | PromiseLike<T>>): MyPromise<T[]> {
    return new MyPromise((resolve, reject) => {
      const results: T[] = [];
      let count = 0;
      const len = promises.length;

      if (len === 0) return resolve([]); // ← 边界: 空数组直接 resolve

      promises.forEach((p, i) => {
        MyPromise.resolve(p).then((val) => {
          results[i] = val;  // ← 用索引保证顺序 (A+ 不要求顺序, 但 all 要求)
          count++;
          if (count === len) resolve(results); // ← 全部完成
        }, reject); // ← 任一失败立即 reject (fail-fast)
      });
    });
  }

  // Promise.allSettled: 等所有 Promise 都完成(不论成功失败)
  static allSettled<T>(promises: Array<T | PromiseLike<T>>) {
    return new MyPromise((resolve) => {
      const results: any[] = [];
      let count = 0;
      const len = promises.length;
      if (len === 0) return resolve([]);

      promises.forEach((p, i) => {
        MyPromise.resolve(p).then(
          (value) => { results[i] = { status: 'fulfilled', value }; },
          (reason) => { results[i] = { status: 'rejected', reason }; }
        ).finally(() => {
          count++;
          if (count === len) resolve(results);
        });
      });
    });
  }

  // Promise.race: 首个决议(成功或失败)就采纳
  static race<T>(promises: Array<T | PromiseLike<T>>): MyPromise<T> {
    return new MyPromise((resolve, reject) => {
      promises.forEach((p) => {
        MyPromise.resolve(p).then(resolve, reject); // ← 谁先决议谁赢
      });
    });
  }
}

# 1. 安装 promises-aplus-tests 测试套件
npm install -D promises-aplus-tests

# 2. 在 my-promise.ts 底部导出适配器
# (测试套件要求 exports 一个 { resolved, rejected, deferred } 接口)

# 3. 运行 872 个测试用例
npx promises-aplus-tests my-promise.ts

# ✅ 输出结果:
# 872 passing (2.3s)
# 0 failing

# 测试覆盖: 2.1.x (状态) + 2.2.x (then) + 2.3.x (Resolution)
# 所有边界情况: 循环引用、thenable、多次调用、异步执行...