TypeScript Reference ยท Concepts and Comparisons
Soundness and its limits in TypeScript
Where TypeScript's type system is deliberately unsound: array covariance, method bivariance, assertions, index access and any, with examples.
A sound type system guarantees that a value of static type T always has type T at run time. TypeScript does not promise that. Its goal is to catch common mistakes while staying convenient for JavaScript code, so it permits some patterns that can be wrong.
Knowing the gaps tells you where bugs can slip past the compiler, and which strict flags close which gap.
const dogs: string[] = ["rex"]; const things: (string | number)[] = dogs; // allowed, though unsafe
Try it
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.
Known unsound areas
- Array and object covariance.
Dog[]is assignable toAnimal[]; writing a differentAnimalinto it breaks the original. - Method bivariance. Parameters of methods declared with method syntax are compared in both directions, even with
strictFunctionTypes. Properties with function types are checked strictly. - Index access. Reading
array[i]orrecord[key]yieldsT, notT | undefined, unless noUncheckedIndexedAccess is on. - Type assertions with
astell the compiler to believe you. Only sufficiently related types can be asserted directly, butas unknown as Tbypasses even that. anydisables checks for everything it touches.- Non-null assertion
!and definite assignment!:are promises, not proofs. - Narrowing across calls. A narrowed property stays narrowed after a function call that may have changed it.
- Optional/readonly:
readonlyis not part of assignability, so a read-only view can alias a mutable object. - Excess properties are only checked on fresh literals, not on values passed through variables.
- Function parameter count: a function taking fewer parameters is assignable to one taking more, which matches JavaScript callbacks.
- Declared but wrong types:
.d.tsfiles, JSON parsing andfetchresults are trusted, never verified.
Usage notes
- Turn on
strictand considernoUncheckedIndexedAccessandexactOptionalPropertyTypesto close the biggest gaps. - Validate boundaries. Check external data once at the edge with a runtime validator; see Runtime validation.
- Prefer
readonlyarrays andReadonlyArrayparameters for inputs you will not modify, which prevents the covariance write problem in the callee. - Soundness was not a goal. TypeScript's design notes favor usability and JavaScript compatibility over strict guarantees; do not expect new releases to make covariance errors.
- Tests still matter. Types remove many tests, not all.