Everyday Types

An annotation is you telling the compiler a type: let count: number = 0. Inference is the compiler working the type out from the value: let count = 0 gets number all by itself. Both produce exactly the same type information; the difference is only who wrote it down.

TypeScript infers far more than people expect. Every variable with an initialiser, every function's return type, every array and object literal gets a type without you saying anything. So the real skill isn't "how do I annotate"; it's knowing where inference can't reach or gives an answer you don't want, and annotating exactly there.

A useful mental model: inference flows from values to names. When there's a value to look at (an initialiser, a return expression), the compiler reads its type and gives it to the name. When there's no value yet (a function parameter, a variable declared empty), there's nothing to read, and you have to supply the type.

function add(a: number, b: number) {
  return a + b;
}

const total = add(2, 3); // const total: number

let count = 0; // let count: number
const limit = 10; // const limit: 10
const tags = ["a", "b"]; // const tags: string[]
const mixed = [1, "two", null]; // const mixed: (string | number | null)[]

let status: "idle" | "loading" = "idle";
status = "loading";
status = "done"; // ❌ Type '"done"' is not assignable to type '"idle" | "loading"'.

type User = { id: number; name: string };

function findUser(users: User[], id: number): User {
  const user = users.find((u) => u.id === id);
  return user; // ❌ Type 'User | undefined' is not assignable to type 'User'.
}

Normal inference goes inside out: look at a value, work out its type. Contextual typing goes outside in: the compiler looks at where an expression sits, sees what type that position expects, and uses that expectation to type the expression. It's why you almost never annotate callback parameters.

Mental model: an expression put into a typed slot takes its shape from the slot, like water poured into a mould. The slots are function arguments whose parameter type is known, variables with a function-type annotation, return statements in functions with a declared return type, object-literal properties with a known target type, and so on.

const names = ["ada", "grace"];
const upper = names.map((name) => name.toUpperCase()); // const upper: string[]

window.addEventListener("keydown", (event) => {
  console.log(event.key); // event: KeyboardEvent
});

type Comparator = (a: number, b: number) => number;
const ascending: Comparator = (a, b) => a - b; // a and b: number from Comparator

const handler = (event) => console.log(event.key); // ❌ Parameter 'event' implicitly has an 'any' type.
window.addEventListener("keydown", handler);

TypeScript has a type for each JavaScript primitive: string, number, boolean, bigint, symbol, null and undefined. They're written in lowercase. The capitalised String, Number and Boolean are the types of the wrapper objects (new String("x")), which you never want.

On top of those, every literal value can be a type of its own. "dark" is a type whose only value is the string "dark"; 42 is a type with one value; true is a type, and boolean is literally the union true | false. Literal types are how TypeScript models "one of these exact values", like type Theme = "light" | "dark", and they're the building blocks for discriminated unions and template literal types.

The thing to understand is widening. When the compiler infers a type from a literal, it has to guess how specific you meant to be. The rule is about mutability: if the place holding the value can change (a let, an object property, an array element), the literal widens to its primitive ("dark" → string). If it can't change (a const variable), the literal type is kept.

let a = "hello"; // let a: string
const b = "hello"; // const b: "hello"
let c = b; // let c: string
const d = b; // const d: "hello"

const e: "hello" = "hello";
let f = e; // let f: "hello"

type Theme = "light" | "dark";
function setTheme(theme: Theme) {}

const config = { theme: "dark" }; // const config: { theme: string }
setTheme(config.theme); // ❌ Argument of type 'string' is not assignable to parameter of type 'Theme'.

const fixedByAsConst = { theme: "dark" } as const; // { readonly theme: "dark" }
setTheme(fixedByAsConst.theme);

const fixedByAnnotation: { theme: Theme } = { theme: "dark" };
setTheme(fixedByAnnotation.theme);

const big = 9007199254740993n; // const big: 9007199254740993n
let total = 10n; // let total: bigint
total = total + 1; // ❌ Operator '+' cannot be applied to types 'bigint' and '1'.

let id = Symbol("id"); // let id: symbol
const key = Symbol("key"); // const key: typeof key  (a unique symbol)

let wrapped: String = "text";
let plain: string = wrapped; // ❌ Type 'String' is not assignable to type 'string'.

An array type describes the element type: every element of a number[] is a number. There are two spellings for the same type, number[] and Array<number>. They're identical to the compiler; the generic form is just the Array<T> interface written out. Most code uses T[] for simple element types and teams sometimes prefer Array<…> for long unions because it doesn't need parentheses.

Where it gets interesting is mixed arrays and read-only arrays. "An array that may contain strings and numbers" and "either an array of strings or an array of numbers" are different types, and the difference shows up in what you can put in them. Read-only arrays are a separate type with all the mutating methods removed, which is how you promise a function won't modify the array you pass it.

const scores: number[] = [90, 85];
const sameType: Array<number> = scores;

const ids: (string | number)[] = [1, "a2", 3];
const allOneKind: string[] | number[] = [1, "a2", 3]; // ❌ Type '(string | number)[]' is not assignable to type 'string[] | number[]'.

const noParens: string | number[] = "just a string";

function sum(values: readonly number[]): number {
  values.push(0); // ❌ Property 'push' does not exist on type 'readonly number[]'.
  values[0] = 1; // ❌ Index signature in type 'readonly number[]' only permits reading.
  return values.reduce((acc, v) => acc + v, 0);
}

const nums = [1, 2, 3];
sum(nums);

const view: ReadonlyArray<number> = nums;
const backToMutable: number[] = view; // ❌ The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
type NotAllowed = readonly Array<number>; // ❌ 'readonly' type modifier is only permitted on array and tuple literal types.

A tuple is an array with a fixed length where each position has its own type. [string, number] means exactly two elements, a string first and a number second. At runtime it's just an array; the tuple-ness exists only in the type checker.

Why bother? Because positional data is common and arrays type it badly. useState returns a value and a setter. Object.entries returns [key, value] pairs. A coordinate is [x, y]. With a plain array type, every element would be typed as the union of everything (string | number), and you'd lose which position holds what. A tuple keeps that information.

let entry: [string, number] = ["age", 42];
const [label, value] = entry; // label: string, value: number

entry = [42, "age"]; // ❌ Type 'number' is not assignable to type 'string'. (and the reverse for position 1)
entry = ["age"]; // ❌ Type '[string]' is not assignable to type '[string, number]'.
entry[2]; // ❌ Tuple type '[string, number]' of length '2' has no element at index '2'.

const pair = ["age", 42]; // const pair: (string | number)[]
const first = pair[0]; // const first: string | number

function useToggle(initial: boolean): [boolean, () => void] {
  let on = initial;
  const toggle = () => {
    on = !on;
  };
  return [on, toggle];
}

const [isOpen, toggle] = useToggle(false); // isOpen: boolean, toggle: () => void

An object type lists the properties a value must have and the type of each. You can write it inline ({ name: string; age: number }), name it with a type alias, or declare it as an interface; for plain object shapes the three behave the same (the differences are in type vs interface).

Remember that TypeScript is structural: a value matches an object type if it has the required properties with compatible types. It doesn't matter what it was "declared as", and extra properties are generally fine (with one exception, excess property checking).

Two modifiers change what a property means. ? makes a property optional: it may be missing, and reading it gives T | undefined. readonly stops assignment to the property through this type. Both are compile-time only; they emit nothing.

interface User {
  readonly id: number;
  name: string;
  email?: string;
}

const user: User = { id: 1, name: "Ada" };
user.name = "Ada Lovelace";
user.id = 2; // ❌ Cannot assign to 'id' because it is a read-only property.

user.email.toLowerCase(); // ❌ 'user.email' is possibly 'undefined'.
if (user.email) {
  user.email.toLowerCase();
}
const domain = user.email?.split("@")[1]; // const domain: string | undefined

interface Order {
  readonly items: string[];
  readonly customer: { name: string };
}

const order: Order = { items: [], customer: { name: "Ada" } };
order.items = ["pen"]; // ❌ Cannot assign to 'items' because it is a read-only property.
order.items.push("pen");
order.customer.name = "Grace";

const point: { readonly x: number } = { x: 1 };
const writable: { x: number } = point;
writable.x = 99;
console.log(point.x); // 99

Both make a parameter something the caller can skip, but they differ in what the function body sees. With name?: string, a missing argument arrives as undefined, so inside the function name is string | undefined and you must handle that. With a default, name = "stranger", JavaScript substitutes the default before your code runs, so inside the function name is just string.

From the caller's side they look identical: both appear as name?: string in the signature. The default's type is inferred from the default value, so you rarely need to annotate it.

function greet(name?: string) {
  // name: string | undefined
  return `Hello, ${name ?? "stranger"}`;
}

function greetWithDefault(name = "stranger") {
  // name: string
  return `Hello, ${name.toUpperCase()}`;
}

greet();
greetWithDefault();
greetWithDefault(undefined);
greetWithDefault(null); // ❌ Argument of type 'null' is not assignable to parameter of type 'string | undefined'.

function bad(a?: number, b: number) {} // ❌ A required parameter cannot follow an optional parameter.

function okay(a = 1, b: number) {}
okay(undefined, 2);
okay(2); // ❌ Expected 2 arguments, but got 1.

function log(message: string, level: string | undefined) {}
log("hi"); // ❌ Expected 2 arguments, but got 1.
log("hi", undefined);

interface ConnectOptions {
  host?: string;
  port?: number;
}

function connect({ host = "localhost", port = 5432 }: ConnectOptions = {}) {
  return `${host}:${port}`; // host: string, port: number
}

connect();
connect({ port: 6543 });

TypeScript is structural, so normally an object with extra properties is perfectly acceptable wherever a smaller shape is expected: a { name, age } object is a valid { name }. But there's one special case. When you write an object literal directly where a type is expected, and the literal has a property the target type doesn't know about, the compiler reports an error.

The reasoning: a fresh object literal has no other references. If you pass { colour: "red" } straight into a function that expects { color?: string }, nothing anywhere can ever read colour; it's almost certainly a typo or a misunderstanding of the API. So the compiler applies a stricter check to these fresh literals only. Once the object has been stored in a variable, it might be used elsewhere with its full type, so the extra property could be meaningful, and the normal structural rules apply again.

interface Options {
  color?: string;
  size?: number;
}
function draw(options: Options) {}

draw({ colour: "red" }); // ❌ Object literal may only specify known properties, but 'colour' does not exist in type 'Options'. Did you mean to write 'color'?

const withSize = { colour: "red", size: 2 };
draw(withSize);

const typoOnly = { colour: "red" };
draw(typoOnly); // ❌ Type '{ colour: string; }' has no properties in common with type 'Options'.

any switches the type checker off for a value. Anything can be assigned to an any, an any can be assigned to anything, and every operation on it (property access, calls, arithmetic) is allowed and produces another any. It's the escape hatch that lets TypeScript coexist with untyped JavaScript.

From my notes: use any when working with data from dynamic or unknown sources (third-party libraries, JSON from APIs), but only when you have no better option. The better option is almost always unknown; any is mainly for migrating JavaScript and for the rare type you genuinely can't express.

Mental model: any isn't "a type that can hold anything" (that's unknown). It's "don't check this". And it's contagious: whatever you derive from an any is any too, so one any can quietly switch off checking far beyond where it was written.

let someValue: any = "Hello, World!";
someValue = 42; // No error, type is flexible
someValue.toFixed(2); // No error, though someValue could be any type

someValue = "back to a string";
someValue.toFixed(2); // still no error, but it throws at runtime

const data = JSON.parse('{"user":{"name":"Ada"}}'); // const data: any
const name = data.user.nmae; // const name: any  (typo not caught)
const upper: string = name.toUpperCase(); // any flows into a string variable

function getConfig(): any {
  return { retries: "3" };
}
const retries: number = getConfig().retries; // compiles; really a string

unknown is the type-safe counterpart of any. Like any, every value is assignable to it: it's the "top type", the set of all values. Unlike any, you can't do anything with an unknown value (read a property, call it, pass it where a string is needed) until you've proven what it is. The compiler forces the check that any lets you skip.

Mental model: unknown is a sealed parcel. You can accept any parcel and pass it around, but you have to open it and look inside (narrow it) before you can use what's in it. any is a parcel you're allowed to use without looking, and you find out what it was when something breaks.

This is the example from my notes:

let input: unknown;
input = "Hello";
console.log(input.toUpperCase()); // ❌ 'input' is of type 'unknown'.

if (typeof input === "string") {
  console.log(input.toUpperCase()); // Works, narrowed
}

interface User {
  name: string;
  age: number;
}

function parseUser(json: string): User {
  const data: unknown = JSON.parse(json);
  if (
    typeof data === "object" &&
    data !== null &&
    "name" in data &&
    typeof data.name === "string" &&
    "age" in data &&
    typeof data.age === "number"
  ) {
    return { name: data.name, age: data.age };
  }
  throw new Error("Not a valid user");
}

declare const a: any;
declare const u: unknown;

const s1: string = a;
const s2: string = u;
const n: unknown = 42;
a.foo.bar();
u.foo;
if (typeof u === "number") u.toFixed(1);

In JavaScript you can throw anything: an Error, a string, a number, null, a plain object. So when you catch, you genuinely don't know what you've got. For years TypeScript typed the catch variable as any, which meant err.message compiled even when err was a string.

TypeScript 4.4 added the useUnknownInCatchVariables option, and it's part of strict, so in any strict project the catch variable is unknown. That forces you to check what was thrown before using it, which is the honest type.

try {
  JSON.parse("{ not json");
} catch (err) {
  console.log(err.message); // ❌ 'err' is of type 'unknown'.

  if (err instanceof Error) {
    console.log(err.message); // err: Error
  } else {
    console.log("Non-error thrown:", String(err));
  }
}

try {
  // ...
} catch (err: Error) { // ❌ Catch clause variable type annotation must be 'any' or 'unknown' if specified.
}

function getErrorMessage(err: unknown): string {
  if (err instanceof Error) return err.message;
  if (typeof err === "string") return err;
  return String(err);
}

Promise.reject(new Error("boom")).catch((err) => {
  // err: any here, strict mode doesn't change Promise callbacks
  console.log(getErrorMessage(err));
});

never is the type with no values at all: the empty set. No value can ever have type never, so if the compiler says an expression is never, it's saying "this can't happen". It's the opposite end from unknown: unknown contains every value (top type), never contains none (bottom type).

Mental model: think of types as sets of values. string | number is the union of two sets. never is the empty set, so string | never is just string (adding nothing changes nothing), and string & number is never (no value is both). This set view explains every place never shows up:

• A function that never returns (it always throws or loops forever) has return type never: there's no value it can produce.
• A variable narrowed until no possibilities are left has type never, which is what powers exhaustiveness checking.
• An impossible intersection like string & number is never.
• Conditional types return never to drop union members, which is how Exclude works (see Exclude and Extract).

The examples from my notes:

function throwError(message: string): never {
  throw new Error(message);
}

function fail(): never {
  while (true) {}
}

function parsePort(value: string | undefined): number {
  if (value === undefined) throwError("PORT is not set");
  return Number.parseInt(value, 10); // value: string here
}

function crash() {
  throw new Error("boom");
} // function crash(): void

const crashArrow = () => {
  throw new Error("boom");
}; // const crashArrow: () => never

const failFast = (msg: string): never => {
  throw new Error(msg);
};

function check(value: string | number) {
  if (typeof value !== "string") failFast("not a string");
  value.toUpperCase(); // ❌ Property 'toUpperCase' does not exist on type 'string | number'.
}

type Impossible = string & number; // type Impossible = never
type Clash = { kind: "a" } & { kind: "b" }; // type Clash = never
type Conflict = { id: string } & { id: number };
type ConflictId = Conflict["id"]; // type ConflictId = never

type Cleaned = string | never; // type Cleaned = string

function describe(x: string | number) {
  if (typeof x === "string") {
    // A
  } else if (typeof x === "number") {
    // B
  } else {
    // C
  }
}

From my notes: void is used when a function doesn't return anything useful: it completes, but returns no value. never is used when a function never completes: it throws or runs forever.

At runtime, a void function does return, with the value undefined (every JavaScript function call produces a value). void says "don't use what comes back". A never function doesn't return at all; control goes to a catch somewhere, or nowhere.

function logMessage(msg: string): void {
  console.log(msg);
}

function exitWith(code: number): never {
  process.exit(code);
}

const result = logMessage("hi"); // const result: void
if (result) {} // ❌ An expression of type 'void' cannot be tested for truthiness.

const numbers = [1, 2, 3];
const copy: number[] = [];
numbers.forEach((n) => copy.push(n)); // push returns a number, and that's fine

type Callback = () => void;
const getsIgnored: Callback = () => "a string";
const value = getsIgnored(); // const value: void
value.toUpperCase(); // ❌ Property 'toUpperCase' does not exist on type 'void'.

function shout(): void {
  return "HI"; // ❌ Type 'string' is not assignable to type 'void'.
}

type Handler = () => void;

const a: Handler = () => 42;
function b(): void { return 42; }
const c: () => undefined = () => 42;
const d: Handler = () => { throw new Error(); };
const e: () => never = () => {};

An async function always returns a promise. If it doesn't return anything, its type is () => Promise<void>: "a promise that fulfils with nothing useful". That's very different from () => void, but because of the rule in the previous topic, an async function is assignable to a void-returning function type. A Promise<void> is a value, and void return types accept any value.

So the compiler happily lets you pass an async function wherever a plain callback is expected, and the API you passed it to will ignore the promise. It won't wait for it, and nobody handles it if it rejects. This is the "async callbacks can bite you" problem: the types line up, the behaviour doesn't.

const saved: string[] = [];

async function save(id: string): Promise<void> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  saved.push(id);
}

async function saveAllBroken(ids: string[]) {
  ids.forEach(async (id) => {
    await save(id);
  });
  console.log("broken:", saved.length); // broken: 0
}

async function saveAll(ids: string[]) {
  await Promise.all(ids.map((id) => save(id)));
  console.log("fixed:", saved.length); // fixed: 4
}

await saveAllBroken(["a", "b"]);
await saveAll(["c", "d"]);

type Listener = () => void;

function onClick(listener: Listener) {
  try {
    listener();
  } catch (err) {
    console.log("handled:", err);
  }
}

onClick(async () => {
  throw new Error("boom");
});

async function withRetry(task: () => Promise<void>, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    try {
      await task();
      return;
    } catch (err) {
      if (i === attempts) throw err;
    }
  }
}

withRetry(() => console.log("sync")); // ❌ Type 'void' is not assignable to type 'Promise<void>'.
withRetry(async () => console.log("async"));