Annotations and inference

You do not annotate everything

TypeScript reads your code before you run it, and it is good at working out what a value is. const count = 12; is a number, and it will stay a number — annotating it as : number adds nothing the compiler did not already know.

So the habit is not "annotate everything". It is: annotate where the compiler cannot know, and let it infer everywhere else. That keeps the code readable and the checks just as tight.

The distinction that matters is whether a name can be reassigned. A const is bound once, so the compiler can keep the narrowest type it saw. A let may be given another value later, so the inferred type is the general one — let count = 12; is still a number, and assigning a string to it is still an error.

How the checker reads a declaration

For a declaration without an annotation, the checker works from the inside out: it types the literal, then the operator, then the call, and finally gives the name the type that came back. For a declaration with one, it works the other way around. The annotation is the contract, and the value on the right has to fit inside it. That is why const total: number = 3 * 4; is accepted while const total: number = "12"; is not: the second value is a string, and a string does not fit a number. An annotation can be wider than the value, but never narrower, and it never converts anything — it only describes.

One of these needs help

const count = 12;            // inferred: number
const label = "loaves";      // inferred: string

const names = [];            // inferred: any[] — no help at all

function greet(who) {        // who could be anything
  return "Hello, " + who;
}

Where inference stops

An empty list is the clearest case: with nothing inside it, there is nothing to infer, and TypeScript falls back to any — the type that switches checking off for that value. const names: string[] = []; says what will go in, and from then on every push is checked.

Function parameters are the other case. A function is written for every caller the compiler cannot see, so the parameter types are exactly the part you have to say out loud. In return, every call site is checked against them.

Types are checked, then erased

TypeScript does not run in the browser. The types are checked first, then removed, and the JavaScript that remains is what the page executes. That is why a type error stops the build even though the running program would never see a type.

The escape hatches are worth knowing. any switches checking off for a value; unknown says "not known yet" and forces you to narrow it with typeof or a check before using it. Prefer unknown at a boundary: it makes the check explicit instead of silent.

Names for shapes

A type alias gives a name to a shape: type Point = { x: number; y: number };. The compiler checks the shape wherever the name is used, and the name explains the intent at every call site. An interface does the same job for objects and is the usual choice when the shape may be extended; for a quick alias, type is shorter.

Use a named type when the same shape appears twice. Repeating { x: number; y: number } in three signatures works, but changing the shape then means finding all three.

What goes wrong

The empty list is the quiet one. const names = []; compiles, because any[] accepts everything, and the mistake does not surface at the declaration. It surfaces later, where something assumes a string: names[0].toUpperCase() is allowed and can fail at run time. Hovering the name shows any[], and that is the signal to write string[] and let the compiler check every push.

The other common failure is a parameter the compiler cannot see a caller for. With noImplicitAny on, function greet(who) { is an error naming the parameter: Parameter ’who’ implicitly has an ’any’ type. The fix is one annotation, not a cast. A cast here would silence the message and leave the caller unchecked, which is exactly the trade you do not want.

Try these next

• Declare a type Point and write a function that takes one and returns its distance from zero.
• Annotate an empty array with string[] and push two names.
• Write a function that takes unknown, narrow it with typeof, and log the result.