Soundness Holes and How to Stay Safe

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Sound

A value that passes the checker can never break its type at runtime. TypeScript is not fully sound.

Covariant

Accepts a narrower type where a wider one is expected, like Dog[] where Animal[] is expected.

Contravariant

Accepts a wider type where a narrower one is expected. Function parameters are the usual case.

Bivariant

Accepts both directions. Loose and unsafe, but convenient. Method parameters are bivariant.

strictFunctionTypes

A strict flag: parameters of function-type properties are checked contravariantly. Methods are exempt.

any leak

An any entering your program from a library call or a cast and silently spreading to everything it touches.

noUncheckedIndexedAccess

A flag that adds undefined to the type of an array element or index-signature read.

Unsound on purpose

A hole the TypeScript team accepted so that common JavaScript patterns type-check.

1. 1

   Close the array hole

   In the first example, change const animals: Animal[] = dogs; to const animals: readonly Animal[] = dogs;. Predict which line becomes the error, and what happens in the Console. The error moves to animals.push(new Cat()) (TS2339, "Property 'push' does not exist on type 'readonly Animal[]'"). The Console still crashes, because types are erased: the checker warned, it did not stop the program.

2. 2

   Turn a property into a method

   In the second example, change handle: (x: string | number) => void; in WithProp to handle(x: string | number): void;. Predict whether the error on the p line disappears. It does, and the Console still crashes on m.handle(42): the same function is now accepted.

3. 3

   Copy before you call

   In the narrowing example, rewrite show to read const email = u.email; first and test email. Predict whether the program still crashes. It does not: the Console prints A@X.IO, because the local const keeps its string even after reset(u) removes the property.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: If you believe the checker is a proof, you stop looking where it cannot see. Knowing the exact places where it stays quiet while the program can still crash tells you where to add your own care. (Recall from Topic 7.7: covariance and contravariance describe which direction a type may be widened.) A type system is sound when a value that passes the checker can never break its type at runtime. TypeScript is not sound, on purpose (the TypeScript Design Goals list a sound or "provably correct" type system as a non-goal and say to "strike a balance between correctness and productivity"). The holes are few and well known. The examples below each end with a real crash, shown in the Console, so you can see exactly what the types promised and what happened.

2. 2

   Hole 1: array covariance. An array of Dog is accepted where an array of Animal is expected, because a Dog is an Animal. But the array can be written to: through the Animal[] view you can push a Cat, and the original Dog[] now holds a cat. The first example crashes with d.bark is not a function. The fix is to take a read-only view: readonly Animal[] has no push, so the unsafe write is a type error.

3. 3

   Hole 2: method bivariance. A function type written as a property (handle: (x: string | number) => void) is checked strictly under strictFunctionTypes: a function that only accepts string is refused. But a method declaration (handle(x: string | number): void) is exempt and is checked loosely in both directions (bivariant). The same narrow function is accepted there, and m.handle(42) crashes. The reason is history: many built-in types (like Array) are written with methods, and making them strict would have broken a large amount of existing code. The fix is to declare callbacks as properties, and a lint rule (method-signature-style) enforces it.

4. 4

   **Hole 3: any leaks.** any switches checking off, and it spreads: whatever you read from an any is any again. Standard library functions that return any, such as JSON.parse (and response.json()), put an any into your program without you writing the word. In the example, age: number is accepted, because parsed.age is any; then age.toFixed crashes. The fix is unknown at the boundary and a check or validation before use (Topic 13.4); the lint rules no-explicit-any and the no-unsafe-* family catch the leaks.

5. 5

   Hole 4: index access. names[2] has the element type, string, even when the array has two items. With noUncheckedIndexedAccess (part of the tsc --init set, so on by default in these examples) the type becomes string | undefined, and the crash is caught at compile time. Turn the flag off and the example compiles and then crashes. The same idea applies to index signatures on objects.

6. 6

   Hole 5: narrowing is not invalidated by calls. After if (u.email) the checker believes u.email is a string. If you then call a function that changes u (here, reset(u) deletes the email), the checker does not know, and the next line crashes. The checker assumes function calls do not change the properties you narrowed. Keep narrowed values in a const local: const email = u.email; if (email) { reset(u); email.toUpperCase(); } is safe, because a local const cannot change.

7. 7

   Hole 6: assertions and the readonly escape hatch. value as T is allowed whenever the types overlap (Topic 16.1), ! removes null and undefined by decree, readonly number[] can be cast to number[] with as, and an object can be assigned to a wider property type ({ a: string } to { a: string | number }), after which a write through the wider view breaks the narrower one. All of these are you telling the checker to trust you. The last example shows the two worst: a mutation of a "readonly" array, and an a that is suddenly a number.

8. 8

   Staying safe, in practice. (1) Turn on strict and noUncheckedIndexedAccess. (2) Treat external data as unknown and check it. (3) Prefer readonly arrays and properties for anything you only read. (4) Declare callback members as properties, not methods. (5) Copy narrowed values into a const before calling anything. (6) In review, grep for as, ! and any. (7) Use typescript-eslint rules: no-explicit-any, no-unsafe-assignment, no-unsafe-member-access, no-unsafe-call, no-unsafe-return, no-unsafe-argument, no-unsafe-type-assertion, no-non-null-assertion, no-unsafe-declaration-merging and method-signature-style all exist in typescript-eslint 8.

• ↔

  Each safety habit has a cost: readonly everywhere needs more annotations, noUncheckedIndexedAccess adds checks after array reads, and unknown needs validation code. The cost is paid once; a crash found in production is paid by a user.

• ↔

  Lint rules for any and as produce noise in older code. Introduce them with warnings first and tighten them file by file (Topic 15.4).

• I can show array covariance crashing and fix it with a readonly view.

• I can explain method bivariance and why callbacks should be properties.

• I can name where any enters a program without being typed.

• I can explain noUncheckedIndexedAccess and why narrowing across calls is unsafe.

• I can list the flags, habits and lint rules that close the holes.