TypeScript Reference ยท tsconfig: Language, Modules and Emit Options
TypeScript downlevelIteration option
Reference for downlevelIteration: how for...of, spread and destructuring behave when compiled to ES5 or ES3, and why modern targets make it irrelevant.
downlevelIteration matters only when target is es5 or es3. Those engines have no iterator protocol, so the compiler normally turns for...of, array spread and array destructuring into simple index loops that work on arrays only. With the option on, it emits helper code that follows the real iterator protocol, so strings, Map, Set and generators iterate correctly.
For any target from ES2015 up the option has no effect, because the engine already supports iteration natively. Recent TypeScript versions deprecate the old targets, and TypeScript 7 no longer targets ES5, so this page is mainly for maintaining older projects.
{ "compilerOptions": { "target": "es5", "downlevelIteration": true } }
Try it
These examples run natively on the ES2024 target. They show exactly the behaviors that the option exists to preserve on older targets.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Without downlevelIteration, an ES5 build would reject or mis-handle every line above that iterates something other than an array.
Syntax
{ "compilerOptions": { "target": "es5", "lib": ["es2015", "dom"], "downlevelIteration": true } }
| Name | Description |
|---|---|
downlevelIteration |
true emits iterator-protocol helpers (__values, __read, __spreadArray) for ES5/ES3 targets. Default false. |
Usage notes
- Without it, iterating a non-array under
target: es5is a compile error (TS2495 or TS2802, "can only be iterated through when using the --downlevelIteration flag"). - The helpers add code size and slow loops; pair with
importHelpersto share them. libmust still include the types forMap,SetandSymbol.iterator, and the runtime needs polyfills for them.- Behavior differs subtly without it: spreading a string splits by UTF-16 units, not code points.
- For modern targets, remove the option from your config; it only adds noise.
- If you still need an old browser, compiling with a bundler plus a polyfill service is usually easier than lowering with
tsc.