TypeScript Type Inference: When to Annotate and When Not

Type inference is TypeScript working out a type you did not write. Initialize a variable and it takes the type of the value; return a value from a function and the return type follows. Most TypeScript code carries far fewer annotations than people expect.

let count = 0;            // number
let language = "TypeScript"; // string
let tags = ["ts", "js"];  // string[]
let user = { name: "Ada", age: 36 }; // { name: string; age: number }

function area(w: number, h: number) {
    return w * h;          // return type inferred as number
}

const size = area(3, 4);  // number
console.log(count, language, tags, user, size);

// The inferred types are enforced like written ones:
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
count = "one";

The comments show what an editor displays when you hover each name. The last line is a compile error (TS2322) even though count was never annotated; // @ts-expect-error marks it as expected so the rest of the block runs.

let vs const: Literal Widening

A const can never change, so TypeScript gives it the narrowest type: the literal value itself. A let gets the wider type, because it may be reassigned later.

let a = "left";    // string
const b = "left";  // "left"
let c = 42;        // number
const d = 42;      // 42
const e = true;    // true

This matters when a function accepts only certain values:

// This does not compile: `let` widened "left" to string.
function move(direction: "left" | "right") {
    console.log("moving", direction);
}

let dir = "left";
move(dir);

const fixed = "left";
move(fixed); // fine: fixed has type "left"

index.ts(7,6): error TS2345: Argument of type 'string' is not assignable to parameter of type '"left" | "right"'.

Fix it with const, or by annotating the variable: let dir: "left" | "right" = "left". Literal types have their own page, literal types.

Objects and Arrays Widen Their Members

Properties of an object literal are mutable, so they widen like let, even when the object itself is const. Array elements do the same. as const makes everything readonly and keeps the literal types.

const config = { mode: "dark", retries: 3 };
// config: { mode: string; retries: number }
config.mode = "light"; // allowed: mode is string

const frozen = { mode: "dark", retries: 3 } as const;
// frozen: { readonly mode: "dark"; readonly retries: 3 }

const sizes = ["s", "m", "l"];            // string[]
const fixedSizes = ["s", "m", "l"] as const; // readonly ["s", "m", "l"]

console.log(config.mode, frozen.mode, sizes.length, fixedSizes[0]);

Return Type Inference

A function's return type is inferred from its return statements. When there are several, the result is the union of them.

function parsePort(text: string) {
    if (text === "") return null;
    return Number(text);
}
// parsePort returns number | null

const port = parsePort("8080");
if (port !== null) {
    console.log(port + 1); // 8081: port is number inside the check
}

function log(message: string) {
    console.log(message);
}
// log returns void: there is no return value

log("done");

Inferred return types are fine for most functions. Write the return type explicitly on exported or public functions when you want the signature to be a contract: a change inside the body that returns a different type then fails at the function, not at some distant caller.

Contextual Typing: Callbacks Get Their Types

Parameters are not inferred from how a function is called. There are two exceptions. A parameter with a default value takes the default's type (function retry(times = 3) makes times a number). And a function written where a function type is already expected gets its parameter types from that context, so callback parameters need no annotation.

const names = ["ada", "grace", "alan"];

// s is string: map on a string[] passes strings
const upper = names.map((s) => s.toUpperCase());

// a and b are strings, the result must be a number
const sorted = [...names].sort((a, b) => a.length - b.length);

// The variable's type gives the arrow its parameter and return types
const greet: (name: string) => string = (n) => `Hello, ${n}`;

console.log(upper, sorted, greet("Ada"));

The same applies to forEach, filter, reduce, Promise callbacks, event handlers and any function you pass to a parameter with a declared function type.

Parameters Need Annotations

Without a default value or a context like that, TypeScript does not look at how a function is called to guess its parameter types. With strict on, an unannotated parameter is error TS7006:

// This does not compile: a parameter with no type and no context.
function double(x) {
    return x * 2;
}
console.log(double(21));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

Write function double(x: number) and the block prints 42, with the return type number inferred from x * 2.

Best Common Type

For an array literal with different kinds of values, TypeScript infers an array of the union of their types. It does not look for a shared base type you did not mention.

const mixed = [1, "two", null]; // (string | number | null)[]
const nums = [1, 2.5, -3];      // number[]

class Animal { name = "animal"; }
class Dog extends Animal { bark() { return "woof"; } }
class Cat extends Animal { meow() { return "meow"; } }

const pets = [new Dog(), new Cat()];            // (Cat | Dog)[]
const animals: Animal[] = [new Dog(), new Cat()]; // annotate to get Animal[]

console.log(mixed.length, nums, pets.length, animals[0].name);

An empty array is the one case to watch. const list = [] starts as an "evolving" array whose type grows with each push; an annotation, const list: string[] = [], states the intent up front and is clearer.

When to Annotate

The quickest way to see what was inferred is to hover the name in your editor. Without an editor, assign the value to a variable of a wrong type, such as const probe: boolean = mixed;, and the compiler's error message names the inferred type.