downlevelIteration în TypeScript

"compilerOptions": {
  "target": "es5",
  "downlevelIteration": true
}

Ce face downlevelIteration

ES5 nu are iteratori, deci tsc transformă for (const x of sir) într-o buclă cu index (for (var i = 0; i < sir.length; i++)). Asta merge pentru tablouri, dar nu respectă regulile reale: un șir cu emoji este parcurs pe unități UTF-16, iar Set și Map nu pot fi parcurse deloc (eroarea TS2802).

Cu downlevelIteration, tsc folosește Symbol.iterator când există la rulare, deci comportamentul este cel din specificație. Codul generat este mai mare și mai lent. Contează doar pentru target es5; de la es2015 iterarea este nativă. Implicit: false.

Parametri

Parametru	Descriere
true	Iterarea respectă protocolul de iteratori și la target: es5.
false	Valoarea implicită.

Exemple

Exemplul 1: Un emoji numărat greșit

Fără opțiune, bucla cu index numără 4 caractere (emoji-ul are două unități UTF-16). Cu --downlevelIteration, rezultatul corect este 3.

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5"
  }
}

// index.ts
let numar = 0;
for (const caracter of "a😀b") {
  numar++;
}
console.log(numar);

Rezultat (tsc 5.9)

$ npx tsc && cat index.js
var numar = 0;
for (var _i = 0, _a = "a😀b"; _i < _a.length; _i++) {
    var caracter = _a[_i];
    numar++;
}
console.log(numar);

$ node index.js
4

$ npx tsc --downlevelIteration && node index.js
3

Exemplul 2: Set fără downlevelIteration

Destructurarea unui Set cere iteratori, deci la es5 fără opțiune apare eroare.

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es2015", "dom"]
  }
}

// index.ts
const [prima] = new Set(["Iași", "Cluj"]);
console.log(prima);

Rezultat (tsc 5.9)

$ npx tsc --noEmit
index.ts(1,7): error TS2802: Type 'Set<string>' can only be iterated through when using the '--downlevelIteration' flag or with a '--target' of 'es2015' or higher.

Exemplul 3: Iterare nativă

Exemplele de pe site sunt compilate pentru ES2024, deci iterarea este nativă și corectă fără opțiune.

const text = "a😀b";
console.log("lungime UTF-16:", text.length);
console.log("caractere:", [...text].length);

const orase = new Set(["Iași", "Cluj"]);
const [prima] = orase;
console.log(prima);

Rezultat

lungime UTF-16: 4
caractere: 3
Iași

Greșeli frecvente

• Să pornești opțiunea cu target es2015 sau mai nou. Nu are niciun efect.

Comenzi înrudite

• target: Versiunea de JavaScript generată: sintaxa mai nouă decât ținta este transformată în cod echivalent mai vechi.
• importHelpers: Ia funcțiile ajutătoare (__awaiter, __decorate…) din pachetul tslib, în loc să le copieze în fiecare fișier.
• strictBuiltinIteratorReturn: Iteratorii obținuți din Array, Map, Set și String au valoarea finală (done: true) de tip undefined, nu any.
• lib: Alege ce declarații de tipuri pentru mediul de rulare sunt incluse: versiunea JavaScript (es2022) și API-urile (dom, webworker).