eduardweb.
TypeScriptIntermediar#typescript#best-practices#refactoring#types

satisfies vs as vs anotări explicite: ghid decizional în 4 cazuri reale

De Radu Grigore, 3 nov. 2026 · 16 vizualizări · 2 like-uri

Postat 3 nov. 2026
typescript
type ColorMap = Record<string, string | [number, number, number]>;

// 1. satisfies: validează structura, dar păstrează tipul exact
const palette = {
  primary: '#3b82f6',
  background: [255, 255, 255],
} satisfies ColorMap;

palette.primary.toUpperCase(); // OK: știe că e string
palette.background.map((c) => c / 2); // OK: știe că e tuple numeric

// 2. Anotare clasică: pierde specificitatea
const badPalette: ColorMap = {
  primary: '#3b82f6',
};
// badPalette.primary.toUpperCase(); // Eroare: badPalette.primary poate fi și [number, number, number]

Până la TypeScript 4.9, eram prinși între două extreme: fie pierdeai autocomplete-ul exact pentru că forțai o adnotare de tip, fie mințeai compilatorul cu un as aruncat la disperare. satisfies a rezolvat fix zona asta gri, dar văd încă multă confuzie în PR-uri despre când are sens fiecare.

La un monorepo cu vreo 120k linii de cod pe care l-am migrat acum un an, am eliminat peste 40 de bug-uri silențioase doar înlocuind as cu satisfies sau cu type annotations curate. Regulile mele de decizie s-au redus la 4 scenarii.

1. Configurații și dicționare unde vrei valori literale (satisfies)

Când ai un obiect de configurare — rute, culori, permisiuni — vrei ca TypeScript să valideze structura conform unei interfețe, dar fără să-i șteargă specificitatea.

Dacă scrii const theme: Theme = { primary: '#ff0000', ... }, TypeScript lărgește tipul lui primary la string. Ai pierdut instant capacitatea de a ști valoarea exactă la nivel de tip, iar autocomplete-ul devine inutil. Cu const theme = { ... } satisfies Theme, compilatorul verifică dacă obiectul respectă Theme, dar ține minte că primary e exact stringul '#ff0000', nu un string oarecare.

2. API contracts și limite de modul (: Type)

Anotarea explicită clasică (const user: User = ... sau return type la funcții) rămâne de bază când nu vrei ca tipul să fie inferat din implementare. Vrei să impui contractul.

Un trade-off sincer aici: satisfies lasă tipul inferat să „scape” în afară. Dacă expui o funcție dintr-un pachet shared, aproape întotdeauna vrei anotare explicită pe return (function getUser(): User). Altfel, orice mică modificare internă de implementare va schimba tipul returnat fără să-ți dai seama, rupând compatibilitatea pentru consumatori fără vreun avertisment direct la definire.

3. Boundary cu date externe și DOM (as)

Operatorul as nu este validare, este o promisiune oarbă pe care o faci compilatorului: „taci din gură, știu eu mai bine”. Îl folosești doar când TypeScript chiar nu are cum să deducă adevărul din runtime.

Cazuri legitime: document.getElementById('app') as HTMLDivElement sau când citești un payload din localStorage și treci printr-un pas intermediar înainte de un validator gen Zod. Dacă folosești as doar ca să scapi de o eroare roșie într-un obiect pe care tocmai l-ai scris cu mâna ta în cod, faci o greșeală de începător.

4. Validarea exhaustivă fără pierdere de proprietăți (satisfies)

Am avut cazul clasic: un record unde cheile trebuiau să fie toate valorile dintr-un union (type Role = 'admin' | 'editor' | 'viewer'), iar fiecare valoare avea permisiuni diferite.

Dacă foloseai Record<Role, Permission>, toate branch-urile erau forțate la același tip generic și pierdeai metodele specifice per rol. Cu satisfies Record<Role, unknown>, te asiguri că nu ai uitat niciun rol, dar fiecare proprietate își păstrează forma exactă declarată în obiect. Dacă uiți de 'viewer', primești eroare la compilare. Dacă accesezi config.admin.specialSuperAction(), TypeScript știe că există.

Regula scurtă: folosește : pentru contracte și exporturi, satisfies pentru configuri interne unde vrei inferență precisă, și as doar când interacționezi cu runtime-ul și nu ai altă soluție. Voi mai aveți vreun loc legitim de as în cod nou?

Răspunsuri 0

Se încarcă răspunsurile…

Loghează-te pentru a răspunde

Doar membrii comunității pot lăsa comentarii.