Promise.withResolvers 适合封装哪些外部回调

Promise.withResolvers() 最适合“Promise 在这里创建，但完成它的回调在别处触发”的场景：事件监听器、消息队列、流、Worker 或第三方 SDK 回调。它一次返回 promise、resolve 和 reject，让调用方只等待 promise，适配器保留两个 resolver，避免为了取出 resolver 而在构造器里套一层作用域。

项目目标：把推送回调变成可 await 的队列

我们做一个小型适配器：外部消息到达时进入缓冲区，消费者使用 for await 逐条读取。当前没有消息时，才创建一个 deferred 等待者；收到错误时 reject，源结束时返回 done: true。这比“每次事件直接 resolve 同一个 Promise”更安全，因为 Promise 只能结算一次，突发消息也不能没有缓冲地覆盖掉。

常见的合适对象包括：只绑定一次但会多次发出信号的事件源、把回调式 SDK 转成 await 接口的适配层、一次等待由 UI 的“确认/取消”按钮在别处完成的协调器，以及测试中由外部条件释放的栅栏。

核心代码：缓冲值，只为当前等待创建 deferred

function callbackQueue(subscribe) {
  const values = [];
  let waiter = null;
  let closed = false;
  let failure = null;

  function flushWaiter() {
    if (!waiter) return;

    // 先取走当前等待者，避免外部回调重复结算同一个 Promise。
    const current = waiter;
    waiter = null;

    if (failure !== null) {
      current.reject(failure);
    } else if (values.length > 0) {
      current.resolve({ value: values.shift(), done: false });
    } else if (closed) {
      current.resolve({ value: undefined, done: true });
    }
  }

  // subscribe 只执行一次，返回函数用于解绑外部监听器。
  const unsubscribe = subscribe({
    next(value) {
      values.push(value);
      flushWaiter();
    },
    error(error) {
      failure = error;
      flushWaiter();
    },
    complete() {
      closed = true;
      flushWaiter();
    },
  });

  return {
    next() {
      // 已经有数据或结束状态时直接返回，不额外制造悬空等待。
      if (failure !== null) return Promise.reject(failure);
      if (values.length > 0) {
        return Promise.resolve({ value: values.shift(), done: false });
      }
      if (closed) return Promise.resolve({ value: undefined, done: true });
      if (waiter) return Promise.reject(new Error("不支持并发 next()"));

      waiter = Promise.withResolvers();
      return waiter.promise;
    },
    return() {
      // 消费者提前退出时解绑监听，并释放仍在等待的 next()。
      closed = true;
      unsubscribe?.();
      flushWaiter();
      return Promise.resolve({ value: undefined, done: true });
    },
    [Symbol.asyncIterator]() {
      return this;
    },
  };
}

这里 withResolvers() 只负责创建“当前等待者”。消息先到就存进 values；等待先到才保存 deferred。这样既能吸收突发回调，又能让错误和结束状态落到同一个异步迭代协议中。

接入外部回调并完成验收

适配器只要求 subscribe 能提供 next、error、complete 三种信号，并返回清理函数。下面用通用事件源展示接法，实际项目可替换成 WebSocket、Worker、串口库或 SDK 的注册函数。

const messages = callbackQueue(({ next, error, complete }) => {
  const onMessage = (event) => next(event.data);
  const onError = (event) => error(event.error ?? new Error("消息源失败"));
  const onClose = () => complete();

  // 监听器只绑定一次，由队列把多次回调转换为多次 await。
  source.addEventListener("message", onMessage);
  source.addEventListener("error", onError);
  source.addEventListener("close", onClose);

  return () => {
    // 提前停止消费时，必须对称移除全部监听器。
    source.removeEventListener("message", onMessage);
    source.removeEventListener("error", onError);
    source.removeEventListener("close", onClose);
  };
});

for await (const message of messages) {
  // 业务只处理值，不再接触底层回调注册细节。
  renderMessage(message);
}

验收时至少覆盖四种状态：消息先到后读不会丢；读取先发生会等待；错误能让当前或下一次读取失败；消费者提前退出会执行解绑。还要用 "withResolvers" in Promise 检查目标运行环境，旧环境需要构建工具或兼容实现。

哪些情况不值得使用

常见问题

withResolvers 比 new Promise 更强吗？

核心结算语义并没有更强，它主要把 promise、resolve、reject 放到同一作用域，减少提取 resolver 时的嵌套，并更方便轮换等待者。

把 resolve 暴露到全局是否合适？

不合适。resolver 应限制在适配器或协调对象内部，并配套结束、错误与清理规则；全局暴露会让任何代码都能提前结算，难以追踪生命周期。