Type Annotations in TypeScript

Analogy categoryAnalogies

1. Introduction

A type annotation is how you explicitly tell the TypeScript compiler what type a variable, function parameter, or function return value is allowed to hold. Annotations are written using a colon followed by the type, and they are the foundation of TypeScript's static type checking.

🏏

Cricket analogy: A type annotation is like the label on a scoreboard slot that says this field only holds an integer run count, writing runs: number tells the compiler exactly what kind of value is allowed to go there, the foundation of static checking.

Annotations act as a contract: once a variable is annotated with a type, the compiler will flag any attempt to assign a value of an incompatible type, catching bugs before the code ever runs.

🏏

Cricket analogy: An annotation like runs: number is a contract with the scorer, try to write not out into that field and the compiler flags it before the scorecard is ever printed, catching the mistake long before a real match discrepancy.

2. Syntax

typescript

let variableName: type = value;

function fnName(param: type): returnType {
  // ...
}

const arrow: (param: type) => returnType = (param) => { /* ... */ };

3. Explanation

Annotations can be applied to variables (let age: number = 30), function parameters (function greet(name: string)), and function return types (function add(a: number, b: number): number). They can also be applied to object shapes and arrays.

🏏

Cricket analogy: Annotations apply to a player's age (let age: number = 28), a bowler function's spell length parameter (function bowl(overs: number)), and its return type (function bowlSpell(overs: number): number); they can also describe a scorecard object's shape or an array of innings totals.

TypeScript's compiler uses these annotations to perform structural type checking at compile time. Once compiled to JavaScript, all annotations are erased — they exist purely for development-time safety and produce zero runtime overhead.

🏏

Cricket analogy: TypeScript's compiler checks a scorecard object's structure at compile time against its annotated shape, but once the app is compiled to JavaScript for the stadium's display board, every annotation is erased, the run count still shows, but the type-checking scaffolding leaves zero runtime overhead.

Type annotations are optional whenever TypeScript can infer the type on its own. Writing let age: number = 30; is redundant because let age = 30; already infers number. Over-annotating obvious initializations is considered noisy style — reserve explicit annotations for function parameters, return types, and cases where inference would be too wide (e.g. empty arrays) or too narrow.

4. Example

typescript

let username: string = "alice";
let age: number = 30;
let isAdmin: boolean = false;

function describeUser(name: string, years: number): string {
  return `${name} is ${years} years old`;
}

console.log(describeUser(username, age));
console.log(`Admin status: ${isAdmin}`);

// This line would be a compile-time error if uncommented:
// age = "thirty"; // Error: Type 'string' is not assignable to type 'number'.

5. Output

text

alice is 30 years old
Admin status: false

6. Key Takeaways

Type annotations use a colon followed by a type: let x: number.
Annotations can appear on variables, parameters, and function return types.
Annotations are erased entirely during compilation — they add zero runtime cost.
Use annotations when TypeScript cannot infer a type on its own, not on every single declaration.
Mismatched assignments are caught at compile time, before the code ever runs.