[FEE-10100] Iterator Helpers — 迭代器的 .map()、.filter()、.take()
INFO
你現在可以直接在任何迭代器(包括 generator 與 Set)上串接 .map()、.filter()、.take(),不需要先展開成陣列。
Web Platform Proposals
此提案已達 TC39 Stage 4,並作為 ECMAScript 2025 的一部分正式發布。 可用於 Chrome 122+、Firefox 131+、Safari 18.4+。Iterator Helpers 自 2025 年 3 月起成為 Baseline Newly Available。 請查閱 MDN 以取得最新相容性表格。
背景
JavaScript 對可迭代物件(iterable)的組合處理一直存在問題。陣列擁有豐富的轉換方法:.map()、.filter()、.reduce()。這些方法只適用於陣列。其他任何可迭代物件(Set、Map、generator、NodeList)都必須先被實體化為陣列,才能進行任何有意義的操作。
四個核心問題
1. 強制急切求值(eager materialization)。 如果你有一個裝有使用者 ID 的 Set,想要對其進行映射,你無法直接呼叫 .map()。你必須先展開它:
const ids = new Set([1, 2, 3, 4, 5]);
// 這行不通 — Set 沒有 .map()
ids.map(id => fetchUser(id)); // TypeError
// 必須先實體化
[...ids].map(id => fetchUser(id));展開操作會建立一個完整的中間陣列,即使你只需要第一個結果也一樣。
2. 中間陣列不斷累積。 在陣列上串接 .filter() 和 .map() 會建立兩個獨立的中間陣列。對於大型資料集而言,這是一種浪費:
const result = largeArray
.filter(x => x.active) // 中間陣列 #1
.map(x => x.name) // 中間陣列 #2
.slice(0, 10); // 最終結果三次資料遍歷、三次記憶體配置。最後的 .slice(0, 10) 讓所有針對第 11 項以後元素所做的工作都付諸流水。
3. Generator 沒有組合工具。 Generator 函式是表達惰性序列的強大工具,但它們實作的迭代器協定(iterator protocol)沒有任何內建的輔助方法。一個能 yield 一萬個項目的 generator 沒有 .filter()、沒有 .take(),什麼都沒有:
function* naturals() {
let n = 0;
while (true) yield n++;
}
// 要取得前 5 個偶數,必須手動撰寫迴圈
function firstFiveEvens() {
const result = [];
for (const n of naturals()) {
if (n % 2 === 0) result.push(n);
if (result.length === 5) break;
}
return result;
}每一個需要提前退出的 generator,都得手動寫出這段迴圈,而且每次出現都要重新審閱一次。Lodash、Ramda 等函式庫填補了陣列的這個空缺。Lodash 的 _.chain() 是廣為人知的變通方案,但它需要執行期依賴,且只能操作陣列,而非迭代器。
4. 無限序列在實務上難以使用。 因為沒有辦法說「在取得 5 個結果後停止」,擁有無限 generator 的開發者要麼被迫手動收集成一個大型的有限陣列,要麼每次都從頭撰寫提前退出的迴圈。
Iterator helpers 一次解決了這四個問題。
實際案例:分頁資料
你的團隊從 API 接收大型分頁資料集。一位資深工程師撰寫了一個非同步 generator(async generator),以惰性方式逐筆 yield 資料,而非一次拉取所有分頁:
async function* fetchRecords(endpoint) {
let cursor = null;
do {
const resp = await fetch(`${endpoint}?cursor=${cursor ?? ''}`);
const page = await resp.json();
for (const record of page.items) yield record;
cursor = page.nextCursor;
} while (cursor);
}你需要從這個資料流中找到前 10 位活躍的付費用戶。Iterator.from() 只接受同步可迭代物件,而 fetchRecords 是一個 async function*,因此 Iterator.from(fetchRecords('/users')) 在這裡並不適用。Iterator.from() 會把 next() 的回傳值當成已經解析完成的 { done, value } 結果來處理;但對非同步 generator 而言,next() 實際上回傳的是一個 Promise,所以 value 會讀到 undefined,第一次呼叫 .filter() 的判斷式就會拋出 TypeError: Cannot read properties of undefined (reading 'active')。
能讓你對非同步來源寫出乾淨鏈式呼叫的提案是 AsyncIterator helpers,這是另一個獨立的 TC39 提案。截至 2026 年年中,它仍處於 Stage 2,尚未納入 ES2025,也尚未在任何瀏覽器中實作(詳見〈瀏覽器支援與版本對照〉)。在它推出之前,非同步來源仍然需要手動撰寫帶有提前退出的迴圈:
const result = [];
for await (const r of fetchRecords('/users')) {
if (r.active && r.plan === 'premium') result.push(r);
if (result.length === 10) break;
}對於同步來源,例如遍歷已經載入記憶體資料的 generator,iterator helpers 今天就能完整解決這個問題。下方的範例 1 會端對端執行同一個「篩選後截取」的鏈式呼叫。
圖解
急切路徑無論你需要多少結果都會建立三個中間陣列。惰性路徑一次拉取一個值。一旦 .take(5) 收集到 5 個項目,generator 就不會再被呼叫。
範例
1. 篩選並截取同步資料流
function* cachedRecords() {
yield { id: 1, active: true, plan: 'premium' };
yield { id: 2, active: false, plan: 'premium' };
yield { id: 3, active: true, plan: 'free' };
yield { id: 4, active: true, plan: 'premium' };
yield { id: 5, active: true, plan: 'premium' };
// 真實資料集會持續 yield 更多筆資料
}
const result = Iterator.from(cachedRecords())
.filter(r => r.active && r.plan === 'premium')
.take(10)
.toArray();
console.log(result);
// [{ id: 1, active: true, plan: 'premium' },
// { id: 4, active: true, plan: 'premium' },
// { id: 5, active: true, plan: 'premium' }]這就是〈背景〉中「篩選後截取」的鏈式呼叫,套用在同步 generator 上實際執行的結果。.take(10) 會在收集到 10 筆符合項目,或 generator 耗盡之後停止,以先到者為準。像 fetchRecords 這種非同步來源目前還沒有對應的鏈式寫法,詳見〈背景〉與〈瀏覽器支援與版本對照〉。
2. 帶有惰性篩選的無限費波那契數列
function* fibonacci() {
let [a, b] = [0, 1];
while (true) {
yield a;
[a, b] = [b, a + b];
}
}
// 前 5 個偶數費波那契數
const result = Iterator.from(fibonacci())
.filter(n => n % 2 === 0)
.take(5)
.toArray();
console.log(result); // [0, 2, 8, 34, 144]Generator 無限地 yield 值;.take(5) 確保在收集到 5 個偶數後停止。
3. 使用 Iterator.from(Set) 去重並轉換
const raw = new Set([1, 2, 3, 2, 1, 4, 5]);
const doubled = Iterator.from(raw)
.map(x => x * 2)
.toArray();
console.log(doubled); // [2, 4, 6, 8, 10]Iterator.from() 包裝了 Set,它在構造上就已經去重,並賦予其完整的 iterator helper API。
4. 映射 Map 的條目
const scores = new Map([
['Alice', 92],
['Bob', 78],
['Carol', 85],
]);
const passing = Iterator.from(scores)
.filter(([, score]) => score >= 80)
.map(([name, score]) => `${name}: ${score}`)
.toArray();
console.log(passing); // ["Alice: 92", "Carol: 85"]5. Lodash 對比範例
Lodash _.chain() 模式的並排對比:
// Lodash — 基於陣列,需要依賴套件
import _ from 'lodash';
const lodashResult = _.chain([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
.filter(n => n % 2 === 0)
.map(n => n * n)
.take(3)
.value();
// [4, 16, 36]
// Iterator helpers — 原生,適用於任何可迭代物件
function* nums() { let n = 1; while (true) yield n++; }
const nativeResult = Iterator.from(nums())
.filter(n => n % 2 === 0)
.map(n => n * n)
.take(3)
.toArray();
// [4, 16, 36]Iterator helpers 版本適用於無限序列(infinite sequence);Lodash 版本需要一個有限陣列作為起點。
6. 使用 .find() 和 .some() 提前退出
const data = Iterator.from([10, 3, 7, 25, 2, 18]);
// 在第一個符合項目處短路 — 不會消費整個迭代器
const firstBig = data.find(n => n > 20);
console.log(firstBig); // 25
// 不收集就檢查是否存在
const hasTiny = Iterator.from([10, 3, 7, 25]).some(n => n < 5);
console.log(hasTiny); // true最佳實踐
工程師應在任何急切終端方法之前串接 iterator helpers,以避免中間陣列。 惰性輔助方法(.map()、.filter()、.take()、.drop()、.flatMap())會回傳新的迭代器物件。在終端方法消費整個鏈之前,不會執行任何工作。
// 正確:所有轉換都是惰性的,最後才有一個終端方法
const result = Iterator.from(data)
.filter(x => x.active)
.map(x => x.name)
.take(10)
.toArray();
// 錯誤:中間的 .toArray() 破壞了惰性求值
const names = Iterator.from(data)
.filter(x => x.active)
.toArray() // 急切求值 — 在此實體化
.map(x => x.name) // 現在操作的是陣列,而非迭代器
.slice(0, 10);工程師必須使用 Iterator.from() 才能在非陣列可迭代物件上使用輔助方法。 Set、Map、generator 結果和 NodeList 並不直接繼承自 Iterator.prototype。先用 Iterator.from() 包裝它們:
const set = new Set([1, 2, 3, 4, 5]);
// TypeError — Set.prototype 沒有 .filter()
set.filter(x => x > 2);
// 正確
Iterator.from(set).filter(x => x > 2).toArray(); // [3, 4, 5]在可能無限或非常大的 generator 上使用 .take(n) 作為安全閥。 任何可以 yield 無限值的 generator,在以 .toArray() 或 .reduce() 結尾的鏈中都應包含 .take(n)。若沒有它,篩選條件中的一個 bug 可能導致消費者永遠掛起:
// 危險:如果沒有值滿足篩選條件,這永遠不會結束
Iterator.from(infiniteSource()).filter(isRare).toArray();
// 安全:保證會停止
Iterator.from(infiniteSource()).filter(isRare).take(100).toArray();迭代器是一次性使用的。 迭代器一旦被消費(全部或部分),就會耗盡。你無法倒回或再次迭代。如果需要多次迭代相同的資料,每次呼叫工廠函式以取得新的迭代器:
const iter = Iterator.from(mySet);
iter.take(3).toArray(); // [a, b, c]
iter.take(3).toArray(); // [] — 迭代器已耗盡
// 正確:每次建立新的迭代器
const fresh = () => Iterator.from(mySet);
fresh().take(3).toArray(); // [a, b, c]
fresh().take(3).toArray(); // [a, b, c]當只需要檢查或取得單一元素時,優先使用 .find() 或 .some(),而非 .filter().toArray()[0]。 它們在找到第一個符合項目時即短路,不會消費迭代器的其餘部分。
工程師不應僅為了效能,就把既有、資料量小且已在記憶體中的 .filter().map() 鏈式呼叫改寫成 iterator helpers。 對於小型有限陣列,急切求值的 Array 方法通常更快也更簡單。iterator helpers 的優勢在於避免對大型、無限或提前退出的來源做多餘的工作,而非提升原始吞吐量;相關取捨請見〈設計思維〉。
設計思維
惰性求值在其他語言是標準,在 JS 陣列卻例外
大多數現代語言預設將迭代視為惰性的。Python 內建的 map() 和 filter() 回傳惰性 generator。在你迭代結果之前不會執行任何工作。Haskell 的串列(list)在構造上就是惰性的:無限串列 [1..] 完全合法,因為在被消費之前不會進行任何求值。Rust 的迭代器轉接器(.map()、.filter()、.take_while())以零成本著稱:編譯器會將整個鏈融合成單一緊湊的迴圈。
JavaScript 採取了相反的方式。ES5 引入的陣列方法是為那個「瀏覽器中的大型資料」還不是真實問題的年代設計的,針對記憶體中的小型集合。這些方法是急切的:在回傳之前,每個元素都會被轉換。ES6 加入了 Symbol.iterator 協定,但那只是底層協定。沒有隨之帶來高層的輔助方法。
於是陣列擁有了方法庫,而其他可迭代物件則只有原始的 next() 協定。Iterator helpers 弭平了這道鴻溝。
Array 方法仍佔優勢的時候
惰性求值並非沒有成本。每個 iterator helper 都會配置一個小型輔助物件,並透過 next() 協定一次驅動一個值,因此對於已經在記憶體中、篇幅不長的有限陣列而言,Iterator.from(arr).filter(fn).map(fn).toArray() 通常比 arr.filter(fn).map(fn) 做更多工作。社群的效能比較顯示,當來源資料量大、轉換鏈較深,或消費端會透過 .take()、.find() 提前退出時,iterator helpers 才會展現優勢。對於記憶體中的小型陣列,普通的 Array 方法仍然更快也更簡單。使用 iterator helpers 的理由,是避免對你不需要的完整資料做多餘的工作,而不是把它當成小型陣列上既有 .filter().map() 鏈式呼叫的效能升級。
Lodash 的 _.chain() 是 userland 的解答
Lodash 的 _.chain() 十多年來一直是廣泛使用的變通方案:
import _ from 'lodash';
const result = _.chain([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
.filter(n => n % 2 === 0)
.map(n => n * n)
.take(3)
.value(); // [4, 16, 36]_.chain() 會把陣列包裝在一個惰性包裝器中,延遲執行直到呼叫 .value() 為止,不過 Lodash 的惰性求值與捷徑融合(shortcut fusion)只有在鏈夠長、符合條件時才會啟動。鏈越長,它與 iterator helpers 的行為越接近;陣列越小,兩者的落差就越明顯。更根本的結構性差異在於,_.chain() 仍然操作陣列,而非迭代器協定本身,因此無法原生消費 generator 或非陣列的可迭代物件。Iterator helpers 則是這個模式的原生、協定層級版本。
無限序列現在切實可行
在 iterator helpers 出現之前,無限序列大多只是一個概念工具。它對於解釋 generator 很有用,但在實際程式碼中使用起來很笨拙。現在,開發者可以將「給我自然數中前 N 個偶數的平方」表達為直接的管道:
function* naturals() {
let n = 0;
while (true) yield n++;
}
// 前 5 個偶數平方 — 讀起來像規格說明
Iterator.from(naturals())
.map(n => n * n)
.filter(n => n % 2 === 0)
.take(5)
.toArray(); // [0, 4, 16, 36, 64]Generator 從不產生無限序列。每一步一次拉取一個值:.take(5) 請求 5 個,.filter() 從 .map() 拉取直到 5 個通過,.map() 從 naturals() 一次拉取一個值。
為什麼陣列保持急切求值
將 Array.prototype.map() 改為回傳惰性迭代器會破壞 Web。數以千計的程式碼庫依賴 Array.prototype.map() 立即回傳一個真實陣列。TC39 委員會明確選擇在 Iterator.prototype 上新增輔助方法,而非改變 Array.prototype,讓陣列行為保持不變。這與給我們帶來 const/let 而非改變 var 的向後相容性原則如出一轍。
深入探討
完整 API 參考
惰性方法(回傳新的迭代器輔助器,尚未執行任何工作)
| 方法 | 說明 |
|---|---|
.map(mapperFn) | 轉換每個值;一次一個地 yield 映射後的值 |
.filter(predicateFn) | 跳過不符合條件的值 |
.take(limit) | 在 yield limit 個值後停止 |
.drop(limit) | 跳過前 limit 個值,yield 其餘的 |
.flatMap(mapperFn) | 將每個值映射為可迭代物件,然後展開一層 |
關於索引的說明: .map()、.filter()、.flatMap()、.forEach()、.some()、.every() 與 .find() 都會接收 (element, index),與 Array.prototype 方法收到的第二個引數相同。若要將值與其索引配對,可使用 iterator.map((v, i) => [i, v])。提案原本包含一個獨立的方法(先前命名為 asIndexedPairs,後來改名為 indexed),用來將每個值與其索引配對;但它在 ECMAScript 2025 定案前就被移除了,因為 .map() 等方法上的 index 參數已經涵蓋了這個用例。
const indexed = iterator.map((v, i) => [i, v]);急切方法(消費迭代器,觸發求值)
| 方法 | 說明 |
|---|---|
.toArray() | 將所有剩餘值收集到一個 Array 中 |
.reduce(reducerFn, initialValue) | 將值折疊成單一結果 |
.forEach(fn) | 對每個值呼叫 fn;回傳 undefined |
.some(predicateFn) | 如果任何值通過則回傳 true;短路 |
.every(predicateFn) | 如果所有值通過則回傳 true;在第一次失敗時短路 |
.find(predicateFn) | 回傳第一個通過的值;短路 |
靜態方法
| 方法 | 說明 |
|---|---|
Iterator.from(iterableOrIterator) | 包裝任何可迭代物件或迭代器,以存取 Iterator.prototype 的輔助方法 |
Iterator.from() 的運作方式
Iterator.from() 會檢查其引數是否已繼承自 Iterator.prototype。如果是,則直接回傳它。如果不是,則建立一個薄包裝器,委派給底層迭代器的 next() 和 return() 方法。這意味著包裝的開銷極小,且原始迭代器的任何清理語義(例如 generator 的 finally 區塊)都會被保留:
function* gen() {
try {
yield 1;
yield 2;
yield 3;
} finally {
console.log('已清理');
}
}
// .take(1) 呼叫 iterator.return() 以發出提前終止信號
// generator 的 finally 區塊仍然會執行
Iterator.from(gen()).take(1).toArray();
// 輸出:「已清理」
// 回傳:[1]繼承 Iterator
Iterator 類別被設計為可繼承的。如果你建立了一個具有自訂迭代器的自訂資料結構,可以讓它繼承自 Iterator,免費獲得所有輔助方法:
class Range extends Iterator {
#start; #end;
constructor(start, end) {
super();
this.#start = start;
this.#end = end;
}
next() {
if (this.#start >= this.#end) return { done: true, value: undefined };
return { done: false, value: this.#start++ };
}
}
const range = new Range(1, 11);
range.filter(n => n % 2 === 0).toArray(); // [2, 4, 6, 8, 10]瀏覽器支援與版本對照
目前的可用性
對於尚未支援 iterator helpers 的環境,有一個符合規格的 polyfill 可用:
npm install iterator-helpers-polyfill或在 Babel 中使用 useBuiltIns: 'usage' 配置的 core-js polyfill。該 polyfill 會修補 Iterator.prototype 並加入 Iterator.from()。根據 MDN 的相容性資料,所有輔助方法(.map()、.filter()、.take()、.drop()、.flatMap()、.forEach()、.some()、.every()、.find()、.reduce()、.toArray(),以及 Iterator.from())的原生支援分別於 Chrome 122、Firefox 131 與 Safari 18.4 到位,與上方狀態區塊的資訊一致。
同步版與非同步版 iterator helpers
本文所談的都是同步版的 Iterator 提案,也就是已納入 ES2025 的那個版本。另一個獨立的提案 AsyncIterator helpers 會把同一組 .filter()/.map()/.take() 家族加到非同步迭代器與 async function* generator 上。截至 2026 年年中,它仍處於 TC39 Stage 2,尚未在任何瀏覽器中實作。在它推出之前,非同步來源仍需要〈背景〉中展示的手動 for await 迴圈。
TC39 Stage 歷程
Iterator helpers 在 ECMAScript 2025(2025 年 6 月發布)定案前達到 TC39 Stage 4,並作為該版本的一部分正式發布。該提案由 Gus Caplan、Michael Ficarra、Adam Vandolder、Jason Orendorff 與 Kevin Gibbons 共同撰寫,並由 Michael Ficarra 與 Yulia Startsev 在 TC39 中擔任提倡者(champion)推動。它在 Stage 3 停留了數年,等待瀏覽器實作跟上,最終於 2024 年 10 月的全體會議(plenary)上達到 Stage 4。
延伸閱讀
參考資料
- TC39 proposal-iterator-helpers — 提案儲存庫,包含規格文字、作者與提倡者(champion)名單
- TC39 proposal-async-iterator-helpers — 另一個獨立、仍處於 Stage 2 的非同步 iterator helpers 提案
- MDN: Iterator — 完整方法參考與瀏覽器相容性
- V8 blog: Iterator helpers — 來自 V8 團隊的實作說明與範例
- web.dev: Iterator helpers Baseline 公告 — Baseline Newly Available 公告,2025 年 3 月
- ECMAScript 2025 finalized — socket.dev — Iterator helpers 與 Set Methods 納入 ES2025
- LogRocket: Iterator helpers,ES2025 中最被低估的功能 — 附範例的實務指南