Basic Types and Annotations

With a working toolchain, the TypeScript for Beginners series can finally start annotating code. This chapter covers the primitive annotations you will type a hundred times a week, how null and undefined behave under strict mode, the power of type inference — why you usually write fewer annotations than expected — the handful of places an annotation is genuinely required, and how to read the error messages the compiler sends back.

Annotating primitives

An annotation is a colon and a type name: value: Type. The primitives mirror JavaScript's runtime values, with one important naming decision — TypeScript has no int or float, just number:

let username: string = "Ada";
let age: number = 36;
let active: boolean = true;

username = 42;

Expected output:

error TS2322: Type 'number' is not assignable to type 'string'.

The right-hand side is judged against the annotation, not against the value the variable happened to hold earlier. That single rule prevents an enormous family of bugs at almost no cost.

null and undefined

JavaScript has two “empty” values, and TypeScript keeps them distinct: undefined means never assigned, while null usually means deliberately empty. Under strict mode — which this whole series uses — neither is smuggled into other types:

let missing: undefined = undefined;
let empty: null = null;

let name: string = null;

Expected output:

error TS2322: Type 'null' is not assignable to type 'string'.

That third line is the payoff of strictNullChecks: a string is a string, full stop. When a value really can be absent you say so honestly, using a union — the subject of Union and Intersection Types:

let nickname: string | null = null;
nickname = "Ada";        // fine
nickname = nickname.toUpperCase();   // compiler still asks you to check first

Inference: when you can leave types out

You rarely annotate a plain variable, because the compiler infers the type from the value you gave it:

let count = 5;          // inferred: number
let label = "chapters"; // inferred: string

count = "five";

Expected output:

error TS2322: Type 'string' is not assignable to type 'number'.

let count = 5 behaves exactly as if you had written let count: number = 5 — the annotation adds nothing. const goes one step further and keeps the exact literal, because the value can never change:

let mode = "light";     // string  — may be reassigned to any string
const limit = 10;       // 10      — only ever the value 10

Literal types look fussy now; they become genuinely useful when you start building state machines from "loading" | "error" values.

When an annotation really is required

Inference works wherever there is a value to read. That leaves a short list of places where you must speak up:

• Function parameters — nothing infers them at declaration time, so under strict an untyped parameter is an error. You will meet this properly in Functions in TypeScript.
• Declarations without an initializer — let score: number; has nothing to infer from; using it before assigning triggers error TS2454: Variable 'score' is used before being assigned.
• Empty collections — let ids: number[] = []; tells the compiler what may go in before the first element arrives.
• Incoming or untrusted data — JSON.parse and friends know nothing about your shapes.

One annotation per boundary, none per line. A useful rule of thumb: annotate the inputs and outputs of functions — the contract — and let inference handle everything inside:

function totalPrice(price: number, quantity: number): number {
  return price * quantity;
}

const items = totalPrice(9.99, 3);   // inferred as number

Expected output: console.log(items) prints 29.97. The call site needed no annotation at all, yet hovering over items shows number.

unknown: the safe version of I don't know

Sometimes you genuinely have no idea what a value is. any answers that by switching the compiler off; unknown answers it by making the compiler wait until you prove what you have:

let input: unknown = JSON.parse('{"score": 42}');
console.log(input.score);

Expected output:

error TS18046: Variable 'input' is of type 'unknown'.

Nothing is allowed on an unknown value until it has been narrowed. Check first, then convert:

if (typeof input === "object" & input !== null & "score" in input) {
  const score = (input as { score: number }).score;
  console.log(score);
}

Expected output: 42. The cast is safe here only because the guard ran immediately above it.

Reading type errors

Every compiler message follows the same shape — location, code, explanation — and the second half is almost always the whole story:

src/main.ts(3,8): error TS2322: Type 'string' is not assignable to type 'number'.
src/main.ts(5,7): error TS2304: Cannot find name 'pricee'.

Read them in this order: the TS number identifies the family of mistake, the message states the two types involved, and the location sends your cursor to the line. If the location points at the line after your mistake, do not panic — an unclosed brace or a missing return often reports itself downstream. And when a message names a type you do not recognise, note that it is quoted exactly as the compiler sees it: the best clue you will get.

Common mistakes

• Annotating every single variable — let count: number = 5 everywhere adds noise without adding safety; inference already knows.
• Looking for an int type — TypeScript has only number; age = 36.5 compiles happily, so validate ranges yourself.
• Assigning null without declaring it — under strict mode write string | null or use an optional property instead of fighting TS2322.
• Reaching for any when a value is unknown — any disables checking; unknown pauses it until you narrow.
• Trusting an annotation to validate data — const u: User = JSON.parse(x) checks nothing at runtime; the types are erased after compilation.

Practice checklist

1. Declare one variable of each primitive type above, reassign each to a wrong type, and collect the five error messages.
2. Write let total = 10 with and without an annotation, confirm the inferred type by hovering, and trigger the same TS2322 both ways.
3. Try let n: number = null, read the error, then fix it with number | null.
4. Store a parsed JSON value in an unknown, reproduce TS18046, then narrow it and log a property successfully.
5. Type a function with two annotated parameters and one unannotated parameter; note which line the compiler complains about.

What's next?

Primitives are only the first layer — next you will type groups of values in Arrays, Tuples and Objects.