downlevelIteration in tsconfig.json

Checking for iterator implementations before downleveling

December 16, 2022

What's it for?

Without downlevelIteration enabled, a for / of loop on any object is downleveled to a traditional for loop.

This usually works, but there are edge cases in which it fails.

E.g. certain strings, such as emoji (😜), have a .length of 2 (or even more!), but should iterate as 1 unit in a for-of loop.

When downlevelIteration is enabled, TypeScript will use a helper function that checks for a Symbol.iterator implementation (either native or polyfill). If this implementation is missing, you’ll fall back to index-based iteration.1

What's Symbol.iterator?

Whenever an object needs to be iterated (such as at the beginning of a for...of loop), its @@iterator method is called with no arguments, and the returned iterator is used to obtain the values to be iterated. 2