Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{ "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.

TypeScript Iterating strings and Sets correctly

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.

TypeScript Generators with for...of and spread

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

JSON
{
  "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: es5 is 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 importHelpers to share them.
  • lib must still include the types for Map, Set and Symbol.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.