Primitive types

Beginner · 6 min

The seven primitive types TypeScript checks, why they are written lowercase, and what the compiler rejects once a value has one.

Before thisWhy TypeScript, and what a type checker does

Net Ninja · 6 min

Primitive types

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by Net NinjaReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • TypeScript has one type for each JavaScript primitive: `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, and `undefined`.
  • The primitive types are written in lowercase; `String`, `Number`, and `Boolean` with a capital letter name the wrapper objects and should not be used as annotations.
  • There is a single `number` type for integers and floats alike, because JavaScript has a single number representation; `bigint` is a separate type that does not mix with `number` in arithmetic.
  • Once a variable has a primitive type, the compiler rejects assigning a value of a different primitive type and rejects calling methods that type does not have.
  • Primitive types exist only at compile time; the emitted JavaScript contains no trace of them, so they describe values rather than convert them.

Starting from the values JavaScript already has

JavaScript has a small, fixed set of primitive values: strings, numbers, booleans, bigints, symbols, null, and undefined. Everything else is an object. The JavaScript roadmap covers how these behave at runtime. The question here is narrower: how does TypeScript name them, so it can check that a variable meant to hold one kind of value never ends up holding another?

The answer is direct. Each primitive gets a type of the same name:

let title: string = "Dune";
let pages: number = 412;
let inStock: boolean = true;
let isbnChecksum: bigint = 9780441013593n;
let tag: symbol = Symbol("book");
let missing: undefined = undefined;
let empty: null = null;

The : string part is a type annotation, a promise about what the variable will hold. The next lesson covers annotations and why you rarely need to write them on lines like these. For now, notice how little there is to learn: if you know the seven JavaScript primitives, you know the seven primitive types.

What the compiler now refuses

A type is only useful if something gets rejected. Once pages is a number, two kinds of mistake stop compiling:

let pages: number = 412;

pages = "four hundred"; // Error: Type 'string' is not assignable to type 'number'.
pages.toUpperCase(); // Error: Property 'toUpperCase' does not exist on type 'number'.

The first is an assignment of the wrong kind of value. The second is a call to a method the type does not have. Plain JavaScript would accept both lines and fail later, possibly much later, when some other code tried to do arithmetic with the string. TypeScript reports the problem at the line that caused it.

Think of a primitive type as the label on a shipping container. The label does not change what is inside, and it is not stored inside either. It tells the dock crew what may be loaded in, and the crew turns away anything else.

Lowercase, always

You will sometimes see String, Number, or Boolean with a capital letter. These name the wrapper objects that new String("x") creates, a corner of JavaScript almost nobody uses on purpose. They compile as annotations, which is what makes them a trap:

let label: String = "draft"; // compiles, but is the wrong type
let flag: Boolean = new Boolean(false); // a wrapper object, and it is truthy

The rule is simple: annotate with lowercase string, number, boolean, bigint, and symbol. The TypeScript team’s own guidance says the capitalized forms should never be used as types.

One number, and a separate bigint

Developers coming from Java or C# often look for int and float. They do not exist, because JavaScript has a single number representation: a 64-bit float. 3 and 3.5 are the same kind of value at runtime, so there is nothing for a type checker to tell apart.

bigint is different. It is a genuinely separate runtime value for integers of arbitrary size, and JavaScript refuses to mix it with number in arithmetic. TypeScript reflects that:

let big = 10n;
let small = 5;

const sum = big + small; // Error: Operator '+' cannot be applied to types 'bigint' and 'number'.
const fixed = big + BigInt(small); // fine: both sides are bigint

Bigint literals like 10n also need your compile target to be ES2020 or later, a setting covered in the tsconfig lesson.

symbol, null, and undefined

symbol is the type of values created with Symbol(), mostly used as unique object keys. You will meet it rarely in application code.

null and undefined are types too, each with exactly one value. How they behave depends heavily on a compiler flag, strictNullChecks, and that story has its own lesson: null, undefined, and strict null checks. The short version is that under strict, a string can never secretly be null.

Types vanish when the code runs

Every annotation above is erased when TypeScript compiles to JavaScript. The emitted file contains let pages = 412; and nothing more. That has two consequences worth holding onto from day one.

First, a type never converts anything. Writing : number on a variable that receives "42" from a form field does not turn it into a number; it makes the compiler complain, and you write the Number(...) call yourself.

Second, the guarantee only covers values your checked code produced. Data crossing into your program from outside, such as a JSON response or localStorage, arrives without any checking. Later lessons cover how to deal with that honestly.

About the video

Net Ninja’s episode from his 2023 TypeScript crash course is a quick, hands-on tour of string, number, and boolean: declaring variables, trying to assign the wrong kind of value, and watching the compiler object. It assumes the project setup from earlier in the series, which you will already have from the toolchain lessons here. The video does not cover bigint, symbol, or the capitalized wrapper types; the sections above fill those in. Jack Herrington’s video in the links goes a little wider, into arrays and objects, which are the next stops in this group.

Check yourself

  1. 01Why is `let id: String = "abc"` considered a mistake even though it compiles?

    `String` with a capital S is the type of the wrapper object created by `new String()`, not the primitive. It happens to accept primitive strings, but it is a wider and stranger type than intended, and a value typed `String` cannot be passed to anything that expects a `string`. The annotation you want is lowercase `string`.

  2. 02Why does TypeScript have no `int` or `float` type?

    TypeScript describes JavaScript values, and JavaScript stores every ordinary number as a 64-bit float. There is nothing at runtime that separates `3` from `3.5`, so the type system has nothing to check. Whole numbers beyond the safe integer range go in `bigint`, which is a genuinely different runtime value.

  3. 03What happens when you write `const total = 10n + 5`, and why?

    The compiler reports that the `+` operator cannot be applied to a `bigint` and a `number`. JavaScript throws a `TypeError` for that mix at runtime, so TypeScript catches it earlier. Convert one side explicitly, for example `10n + BigInt(5)`.

  4. 04If types are erased when TypeScript compiles, what stops a `number` variable from holding a string at runtime?

    Nothing at runtime. The protection is that the compiler refused to build code that assigned a string to it. That guarantee only holds for values your own checked code produced; data from outside, such as JSON from an API, still needs validating.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark