JavaScript Array.fromAsync 怎么收集异步可迭代对象

收集异步可迭代对象，最小写法就是 const list = await Array.fromAsync(source)。它会逐项读取数据源，等待每个值，并在迭代完成后返回一个兑现为普通数组的 Promise。分页接口、异步生成器和按需读取的数据流，都可以用这条语句汇总成数组。

MDN 参考：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync

ECMAScript 规范：https://tc39.es/ecma262/multipage/indexed-collections.html#sec-array.fromasync

最小可用写法

下面的异步生成器先产出一个值，短暂等待后再产出第二个值。Array.fromAsync() 会一直等到生成器结束，因此调用端必须使用 await，或者继续处理它返回的 Promise。

async function* numbers() {
  // 第一个值可以立即被消费。
  yield 1;
  await new Promise((resolve) => setTimeout(resolve, 20));
  // 第二个值在异步工作完成后才出现。
  yield 2;
}

const result = await Array.fromAsync(numbers());
console.log(result); // [1, 2]

返回值不是“边读边可用”的数组，而是最终完成时一次性得到的数组。若调用方需要收到一个处理一个，应直接使用 for await...of，不要先收集。

Array.fromAsync 能收集哪些输入

该方法覆盖三类输入。第一类是实现 Symbol.asyncIterator 的异步可迭代对象，例如异步生成器；第二类是实现 Symbol.iterator 的同步可迭代对象，例如数组、Set；第三类是带有 length 和数字下标的类数组对象。无论输入属于哪一类，结果都是一个浅拷贝数组。

对于同步可迭代对象，迭代得到的每个值也会被等待。这与 Array.from() 不同：后者立即返回数组，不会等待 Promise 元素。

const tasks = [Promise.resolve("A"), Promise.resolve("B")];

// Array.from() 只复制 Promise，不等待它们。
const pending = Array.from(tasks);

// Array.fromAsync() 等待每个值后再写入结果数组。
const values = await Array.fromAsync(tasks);
console.log(values); // ["A", "B"]

收集分页异步生成器

更常见的场景是把分页接口包装成异步生成器。生成器负责游标、请求和逐项产出，调用端只关心最终数组。下面的 loadPages() 每次仅请求一页，不会预先创建所有请求。

async function* loadPages(fetchPage) {
  let cursor = null;

  do {
    // 当前页完成后才会继续读取下一页。
    const page = await fetchPage(cursor);
    for (const item of page.items) {
      // 逐项产出，避免在生成器内部再保存一份总数组。
      yield item;
    }
    cursor = page.nextCursor;
  } while (cursor !== null);
}

const users = await Array.fromAsync(
  loadPages(fetchPage),
  async (user, index) => {
    // mapFn 返回 Promise 时会被等待，结果仍保持输入顺序。
    const profile = await loadProfile(user.id);
    return { ...user, profile, order: index };
  },
);

mapFn 的第二个参数是从 0 开始的索引。若映射函数需要固定上下文，可以传第三个参数 thisArg；箭头函数不会绑定自己的 this，此时应改用普通函数。

const formatter = {
  prefix: "用户",
  format(user) {
    // 普通函数通过 thisArg 读取 formatter。
    return `${this.prefix}-${user.id}`;
  },
};

const labels = await Array.fromAsync(
  loadPages(fetchPage),
  formatter.format,
  formatter,
);

与 Promise.all 的选择边界

Array.fromAsync() 和 Promise.all() 都能得到数组，但调度方式不同。前者从数据源逐项取值并等待，再请求下一项；后者接收一个已经准备好的 Promise 集合，通常让它们并发推进。它们解决的不是同一个问题。

如果你已经有一组互相独立的 URL，并希望尽快完成所有请求，可以先 map() 创建 Promise，再交给 Promise.all()。如果数据源只能按需给出下一项，或希望自然限制请求节奏，优先使用 Array.fromAsync()。

mapFn 与 Promise 值的细节

对同步可迭代输入，元素中的 Promise 会被等待；对异步可迭代输入，迭代协议通常直接提供已完成值。异步生成器会自动展开 yield 的 Promise，但自定义异步迭代器可以更灵活。若来源实现不确定，而业务要求结果中绝不能保留 Promise，可显式使用映射函数：

const settledValues = await Array.fromAsync(
  customAsyncIterable,
  async (value) => {
    // 再显式等待一次，确保映射结果是业务值。
    return await value;
  },
);

映射在写入最终数组之前完成，因此比“先收集，再调用异步 map”更直接。不要写 await array.map(async ...)，因为 map() 返回的是 Promise 数组；若输入本来就是普通数组且需要并发映射，应使用 await Promise.all(array.map(async ...))。

失败、清理与取消

读取下一项、等待元素或执行 mapFn 任一阶段抛错，Array.fromAsync() 返回的 Promise 都会拒绝。调用方应在业务边界使用 try...catch。同步迭代器在异常时会触发关闭流程；自定义异步数据源仍应通过 try...finally 释放连接、文件句柄或订阅。

async function* readEvents(signal) {
  const connection = await openConnection();
  try {
    while (!signal.aborted) {
      // 数据源自行观察 AbortSignal，才能真正停止底层工作。
      yield await connection.next();
    }
  } finally {
    // 正常结束、异常或提前 return 都执行资源清理。
    await connection.close();
  }
}

const controller = new AbortController();
try {
  const events = await Array.fromAsync(readEvents(controller.signal));
  console.log(events);
} catch (error) {
  // 在这里记录上下文或转换成业务错误。
  console.error("收集事件失败", error);
}

Array.fromAsync() 本身没有 signal 参数，取消能力必须由数据源实现。只调用 controller.abort() 而数据源从不检查信号，并不会自动终止迭代。

无限流与内存边界

该方法只有在迭代结束后才兑现结果，而且会把全部元素留在数组中。因此不要直接收集日志流、消息订阅或没有结束条件的传感器流。可以先加数量边界，再收集有限窗口：

async function* take(source, limit) {
  let count = 0;
  for await (const item of source) {
    // 达到上限后 return，触发上游迭代器关闭。
    if (count >= limit) return;
    count += 1;
    yield item;
  }
}

// 只把前 100 条放入内存，避免无界增长。
const sample = await Array.fromAsync(take(eventStream, 100));

如果每条数据都能独立落库、写文件或更新统计值，直接用 for await...of 逐项处理更稳妥；只有确实需要随机访问、排序、整体校验或一次性提交时，才值得收集成数组。

兼容性与轻量回退

MDN 将 Array.fromAsync() 标记为 Baseline，主流浏览器自 2024 年起已经广泛可用，但旧浏览器和旧运行时仍可能缺少该静态方法。上线前可做特性检测，并用 for await...of 实现常见语义的轻量回退：

async function collectAsync(items, mapFn = (value) => value) {
  const result = [];
  let index = 0;

  for await (const item of items) {
    // 顺序等待映射结果，接近常见的 Array.fromAsync 用法。
    result.push(await mapFn(item, index));
    index += 1;
  }
  return result;
}

const collect = typeof Array.fromAsync === "function"
  ? Array.fromAsync.bind(Array)
  : collectAsync;

const list = await collect(loadPages(fetchPage));

这段回退覆盖异步可迭代和同步可迭代对象，但没有完整复刻规范中的类数组、构造器与所有异常边界。若项目需要完整兼容，应使用维护中的 polyfill，并在目标运行时执行测试。

快速排查清单

• 得到的是 Promise 而不是数组：调用处漏了 await。
• 收集一直不结束：数据源是无限流，或退出条件从未满足。
• 速度比 Promise.all 慢：顺序等待是设计行为；独立任务应改用并发集合。
• 内存持续上涨：正在把过多元素汇总到一个数组，应分批或流式处理。
• 取消无效：异步迭代器没有观察 AbortSignal，也没有在 finally 中释放资源。
• 旧环境报“不是函数”：先做特性检测，再加载 polyfill 或使用回退函数。

小结：用 await Array.fromAsync(asyncIterable) 就能把异步可迭代对象收集为数组；需要转换时把异步 mapFn 作为第二个参数传入。它的优势是按需取值、顺序明确，代价是最终仍要把全部结果放进内存。数据无界时流式处理，任务彼此独立且要并发时选择 Promise.all()，边界就清楚了。