Inference basics: how the checker fills in the types you didn't write

Inference from initializers

When you declare a variable with a value, TypeScript infers its type from the right-hand side. But the exact type depends on the binding keyword, because of widening:

let a = "hello";
//  ^? let a: string  — `let` is mutable, so the literal widens to its base type

const b = "hello";
//    ^? const b: "hello"  — `const` can never change, so the literal type is kept

This is the single most important inference rule to internalize. A let can be reassigned, so pinning it to the literal "hello" would be useless — TS widens to string. A const is immutable, so the precise literal type "hello" is both safe and more informative. Same for numbers and booleans: let n = 3 is number, const n = 3 is 3.

Object properties widen — even under const

Here’s the surprise that bites everyone. const on the binding doesn’t make the contents immutable, because object properties are mutable:

const config = { mode: "dark", retries: 3 };
//    ^? const config: { mode: string; retries: number }
//       NOT { mode: "dark"; retries: 3 } — properties widen
config.mode = "light"; // legal — the property is mutable, so its type is widened `string`

The const only freezes the reference config, not config.mode. Since you could reassign the property, TS widens it to string. When you actually need the literal types preserved — say, to pass into a function expecting a union — use a const assertion:

const config = { mode: "dark", retries: 3 } as const;
//    ^? const config: { readonly mode: "dark"; readonly retries: 3 }
config.mode = "light";
// Error: Cannot assign to 'mode' because it is a read-only property.

as const makes every property readonly and keeps its literal type. We go deep on this in the literal-types lesson; for now, know it’s the fix when widening throws away information you needed.

Contextual typing: callbacks get types for free

Inference also flows inward from the expected type. When a function expects a callback, the callback’s parameters are typed from that expectation — you don’t annotate them:

const names = ["ada", "alan", "grace"];
const upper = names.map((n) => n.toUpperCase());
//                       ^? (parameter) n: string
//    ^? const upper: string[]

n is string because Array<string>.map declares its callback as (value: string, ...) => U. This is contextual typing: the position the function literal sits in supplies the parameter types. It’s why DOM handlers work without annotation too:

button.addEventListener("click", (e) => {
  //                                ^? (parameter) e: MouseEvent
  console.log(e.clientX);
});

The string "click" selects the overload whose handler takes a MouseEvent, and that flows into e. Annotating e: MouseEvent here is redundant noise.

Best-common-type for array literals

When you write an array literal, TypeScript computes a single element type — the best common type — that all elements satisfy:

const xs = [1, 2, 3];
//    ^? const xs: number[]

const mixed = [1, "two", 3];
//    ^? const mixed: (string | number)[]  — union of the element types

If the elements have no common supertype already in scope, TS forms a union of them. Note that const on the binding does not keep [1,2,3] as a tuple [number, number, number] — it’s still number[]; only as const produces a readonly [1, 2, 3] tuple (covered in the literal-types lesson).

Return types are inferred too

You almost never annotate a function’s return type for internal helpers — TS infers it from the return statements:

function parsePort(raw: string) {
  const n = Number(raw);
  return Number.isInteger(n) ? n : null;
}
//       ^? function parsePort(raw: string): number | null

The inferred return is number | null from the two branches. This is great for locals — but a sharp tool at API boundaries.

When to annotate vs let it infer

This is the question every TypeScript codebase eventually forces: over-annotate and you’re fighting the checker; under-annotate and you lose the contract. Here’s the rule professional codebases converge on:

The principle: annotate boundaries, infer interiors. Explicit return types on exported functions are the highest-value annotations — they make the contract intentional and catch accidental widening when you refactor the body.