TypeScript from Scratch: Theory, Notes, and Practical Examples

TypeScript is a language developed by Microsoft.

It is a superset of JavaScript, which means it extends JavaScript with additional features.

The most important of these is:

static typing.

Example:

let age: number = 35;

TypeScript knows that age is a number.

Therefore, this is valid:

age = 40; // ✅

but this is not:

age = "forty"; // ❌

TypeScript will report an error.

TypeScript Does Not Run Directly in the Browser

We write:

const message: string = "Hello";

but after TypeScript is processed, it becomes JavaScript:

const message = "Hello";

The type annotation:

:string

disappears.

The process of converting TypeScript into JavaScript is called transpilation.

We can remember it like this:

TypeScript
    ↓
transpilation
    ↓
JavaScript
    ↓
browser / Node.js

---

The easiest way to start a project is with Vite.

In the terminal, run:

npm create vite@latest

Then select TypeScript as the project's language.

After creating the project, run:

cd project-name
npm install
npm run dev

The project also contains this file:

tsconfig.json

This is the TypeScript configuration file.

Among other things, it determines how the code is checked and processed.

---

string

Text:

let firstName: string = "Anna";

number

Whole numbers and decimal numbers:

let age: number = 32;
let price: number = 19.99;

TypeScript does not have separate integer or float types.

We use:

number

boolean

A logical value:

let isLoggedIn: boolean = true;

Possible values:

true
false

null

The intentional absence of a value:

let selectedUser: null = null;

undefined

A value has not been assigned yet:

let result: undefined;

---

We do not always have to write:

let age: number = 32;

We can write:

let age = 32;

TypeScript sees the number and determines the type automatically:

age → number

Similarly:

let name = "Robert";

TypeScript infers:

name → string

and it recognizes:

let isActive = true;

as:

isActive → boolean

Therefore:

let age = 32;

age = "Robert"; // ❌

will also produce an error.

TypeScript has already determined that age is of type number.

Because age is declared with let, TypeScript infers the wider type number, not the literal type 32. By contrast, a primitive declared with const, such as const quantity = 10, is typically inferred as the literal type 10.

When Should You Write a Type Explicitly?

You do not need to add a type to every variable.

This:

const quantity = 10;

is completely valid.

It is especially useful to specify types explicitly when:

• describing a function,
• creating a data model,
• defining an object received from an API,
• reusing a type in several places,
• code without the type would be harder to understand.

---

JavaScript:

const product = {
  name: "Desk",
  price: 300
};

TypeScript can use exactly the same code and infer its structure automatically.

However, we can also write the type explicitly:

const product: {
  name: string;
  price: number;
} = {
  name: "Desk",
  price: 300
};

This means:

product
├── name → string
└── price → number

We can no longer do this:

product.price = "expensive"; // ❌

because price must be a number.

---

If the same kind of object appears repeatedly, we do not want to write out the entire structure every time.

Instead of:

const laptop: {
  name: string;
  price: number;
} = {
  name: "Laptop",
  price: 900
};

we create an interface.

interface Product {
  name: string;
  price: number;
}

Now we can write:

const laptop: Product = {
  name: "Laptop",
  price: 900
};

const monitor: Product = {
  name: "Monitor",
  price: 250
};

Product describes the object's structure.

We can read:

const laptop: Product

as:

laptop must be an object that matches the Product interface.

---

Not every property has to be required.

Example:

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

name is required.

age is optional.

Therefore, both objects are valid:

const user1: User = {
  name: "Adam"
};

and:

const user2: User = {
  name: "Maria",
  age: 28
};

The symbol:

?

means:

this property may exist, but it is not required.

---

If a value should not be changed:

interface Account {
  readonly id: number;
  name: string;
}

We create an object:

const account: Account = {
  id: 101,
  name: "Mark"
};

We can change:

account.name = "John"; // ✅

but not:

account.id = 500; // ❌

id is read-only.

TypeScript enforces readonly during type checking; it does not freeze the object at runtime. It is also shallow, so nested objects must be made read-only separately when needed.

---

An array of numbers:

const numbers: number[] = [10, 20, 30];

An array of strings:

const cities: string[] = ["Berlin", "Paris", "Warsaw"];

There is also another syntax:

const numbers: Array<number> = [10, 20, 30];

and:

const cities: Array<string> = ["Berlin", "Paris"];

Both forms mean the same thing.

The shorter form is used most often:

number[]
string[]
User[]
Product[]

---

Suppose we have:

interface Product {
  id: number;
  name: string;
}

An array of products:

const products: Product[] = [
  {
    id: 1,
    name: "Chair"
  },
  {
    id: 2,
    name: "Table"
  }
];

Each element must match the Product structure.

This is invalid:

products.push({
  id: 3
}); // ❌ name is missing

---

A union means:

OR.

Example:

let userId: string | number;

We read this as:

userId can be either a string OR a number.

Therefore:

userId = 15;       // ✅
userId = "user15"; // ✅
userId = true;     // ❌

We can remember the symbol:

|

as:

OR

---

Instead of allowing any string, we can allow only specific strings.

let theme: "light" | "dark";

Valid values:

theme = "light";
theme = "dark";

Invalid value:

theme = "blue"; // ❌

A very practical example:

type PaymentStatus = "waiting" | "paid" | "failed";

Then:

let payment: PaymentStatus = "waiting";

payment = "paid"; // ✅
payment = "hello"; // ❌

---

We can give a type a name.

Instead of repeatedly writing:

string | number

we create:

type Id = string | number;

Now:

let customerId: Id = 100;
let orderId: Id = "ORDER-200";

Both values are valid.

---

An intersection means:

AND.

If we have:

interface Person {
  name: string;
}

and:

interface Employee {
  department: string;
}

we can combine them:

type Worker = Person & Employee;

Now Worker must have the properties from both structures:

const worker: Worker = {
  name: "Thomas",
  department: "IT"
};

In simple terms:

Person
  name

+

Employee
  department

=

Worker
  name
  department

Remember:

| = OR
& = AND / COMBINED

---

To begin with, you can follow a simple rule:

interface

Use it most often to describe objects:

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

type

It is very convenient for unions, literal types, and intersections:

type Id = string | number;

type Role = "admin" | "user";

type Employee = Person & Job;

In practice, the capabilities of type and interface overlap to some extent, but the rule above is a good starting point.

---

In JavaScript:

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

In TypeScript:

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

Let us break it down:

a: number

The first parameter must be a number.

b: number

The second parameter must be a number.

): number

The function returns a number.

We can read:

function add(a: number, b: number): number

as:

the function accepts two numbers and returns a number.

---

If a function does not return anything:

function showMessage(message: string): void {
  console.log(message);
}

void means:

the function performs an action but does not return a value.

---

We can use ?.

function greet(name: string, age?: number): void {
  if (age !== undefined) {
    console.log(name + " is " + age + " years old.");
  } else {
    console.log(name);
  }
}

Both calls are valid:

greet("Anna", 25);
greet("Robert");

But this is not:

greet("Anna", "25"); // ❌

age may be omitted, but if it is provided, it must be a number.

---

We have:

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

We want to get an array of names.

function getNames(users: User[]): string[] {
  return users.map(function (user) {
    return user.name;
  });
}

Data:

const users: User[] = [
  { id: 1, name: "Anna" },
  { id: 2, name: "Mark" },
  { id: 3, name: "Peter" }
];

Call the function:

const names = getNames(users);

names will be:

["Anna", "Mark", "Peter"]

The function:

accepts → User[]
returns → string[]

---

We can also describe the structure of a function itself.

type MathFunction = (a: number, b: number) => number;

NOTE:

=>

Here, it does not mean that we have to write an arrow function.

It is simply the syntax used to describe a function type.

We can still use an ordinary function:

const multiply: MathFunction = function (a, b) {
  return a * b;
};

MathFunction means:

a function that accepts two numbers and returns a number.

---

An enum lets us create a named set of constant values.

An order status is a good example:

enum OrderStatus {
  New = "NEW",
  Paid = "PAID",
  Sent = "SENT",
  Delivered = "DELIVERED"
}

We can now write:

let status: OrderStatus = OrderStatus.New;

Later:

status = OrderStatus.Paid;

and:

status = OrderStatus.Sent;

Instead of manually entering this string everywhere:

"SENT"

we use:

OrderStatus.Sent

---

An enum can also contain numbers:

enum HttpStatus {
  Ok = 200,
  NotFound = 404,
  ServerError = 500
}

Example:

console.log(HttpStatus.NotFound);

Output:

404

If we do not provide explicit values:

enum Step {
  Start,
  Processing,
  Finished
}

TypeScript assigns these values by default:

Start      = 0
Processing = 1
Finished   = 2

---

Union type:

type Status = "loading" | "success" | "error";

Usage:

let status: Status = "loading";

Enum:

enum Status {
  Loading = "loading",
  Success = "success",
  Error = "error"
}

Usage:

let status: Status = Status.Loading;

In many simple cases, a union type is sufficient and more concise.

A useful rule of thumb is:

If I do not need the features provided by enum, I start with a union type.

---

A generic can be understood as:

a placeholder for a type.

It is most commonly written as:

<T>

T does not represent one specific type.

The type will be determined later.

Example:

function returnValue<T>(value: T): T {
  return value;
}

This call:

returnValue<string>("Hello");

means:

T = string

And this call:

returnValue<number>(50);

means:

T = number

The same function works with different types.

---

We could write:

function returnValue(value: any): any {
  return value;
}

The problem is that TypeScript loses information about the type.

A generic version:

function returnValue<T>(value: T): T {
  return value;
}

preserves that type information.

If we pass:

const result = returnValue(50);

TypeScript knows:

result → number

This is why generics provide:

flexibility + type safety.

---

A function that returns the first element:

function getFirst<T>(items: T[]): T | undefined {
  return items[0];
}

For:

getFirst([10, 20, 30]);

TypeScript infers:

T = number

For:

getFirst(["red", "green", "blue"]);

TypeScript infers:

T = string

The return type includes:

T | undefined

because an empty array does not have a first element.

---

We can create a reusable box:

interface Box<T> {
  value: T;
}

A box containing a number:

const priceBox: Box<number> = {
  value: 100
};

Here:

T = number

A box containing text:

const messageBox: Box<string> = {
  value: "Hello"
};

Here:

T = string

In simple terms:

Box<number>

= a box containing a number

Box<string>

= a box containing text.

---

Here is a very practical use case:

interface ApiResponse<T> {
  data: T;
  status: number;
}

A response containing a user:

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

const response: ApiResponse<User> = {
  data: {
    id: 1,
    name: "Anna"
  },
  status: 200
};

Here:

T = User

which means:

data: User

We can reuse the same interface for a product:

interface Product {
  id: number;
  title: string;
}

const productResponse: ApiResponse<Product> = {
  data: {
    id: 50,
    title: "Phone"
  },
  status: 200
};

Now:

T = Product

We do not need to create a separate response interface for every data type.

---

A Promise represents the eventual completion or failure of an asynchronous operation.

You can think of it like this:

call a function
      ↓
receive a Promise
      ↓
wait
      ↓
receive the result

The simplest JavaScript version:

function getMessage() {
  return new Promise(function (resolve) {
    resolve("Hello");
  });
}

TypeScript:

function getMessage(): Promise<string> {
  return new Promise(function (resolve) {
    resolve("Hello");
  });
}

The type:

Promise<string>

means:

When the Promise is fulfilled, it will provide a string.

Promise<string> describes the fulfilled value only. The Promise can still be rejected.

---

function getPrice(): Promise<number> {
  return new Promise(function (resolve) {
    resolve(250);
  });
}

Read this as:

Promise<number>

= if the Promise is fulfilled, its value will be a number.

---

We have:

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

The function:

function getUser(): Promise<User> {
  return new Promise(function (resolve) {
    resolve({
      id: 10,
      name: "Adam"
    });
  });
}

Read this as:

Promise<User>

= if the Promise is fulfilled, its value will be one User object.

---

function getUsers(): Promise<User[]> {
  return new Promise(function (resolve) {
    resolve([
      {
        id: 10,
        name: "Adam"
      },
      {
        id: 11,
        name: "Maria"
      }
    ]);
  });
}

Read the types like this:

User

= one user

User[]

= an array of users

Promise<User[]>

= if the Promise is fulfilled, its value will be an array of users.

---

We can receive the result of a Promise with .then():

getUser().then(function (user) {
  console.log(user.name);
});

Because getUser() returns:

Promise<User>

TypeScript knows that:

user

has the type:

User

---

async/await is a more modern way to work with Promises.

Example:

async function getName(): Promise<string> {
  return "Anna";
}

An async function always returns a Promise.

Therefore:

async function getName(): Promise<string>

means:

an asynchronous function that returns a Promise whose fulfilled value is a string.

---

Suppose an API returns:

{
  "id": 15,
  "name": "Martin",
  "email": "martin@example.com"
}

We describe the data:

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

Then:

async function fetchUser(id: number): Promise<User> {
  const response = await fetch(
    `https://api.example.com/users/${id}`
  );

  const data = (await response.json()) as User;

  return data;
}

Let us break it down.

Parameter

id: number

The function accepts a number as its parameter.

Result

Promise<User>

The function returns a Promise whose fulfilled value is a user.

Fetch

await fetch(...)

We wait for the server response.

JSON

await response.json()

We read the JSON data.

as User

as User

We tell TypeScript:

Treat this value as if it had the User structure.

This is a compile-time assertion, not a runtime check.

---

This is very important.

const data = (await response.json()) as User;

does not mean:

TypeScript checked the server response and confirmed that the data was valid.

It means:

The programmer is telling TypeScript to treat this data as a User.

The assertion does not convert the value or add any missing properties.

If the server returns invalid data, as User will not validate it.

To genuinely check external data, we need validation that runs while the program is executing.

---

If the API returns multiple users:

async function fetchUsers(): Promise<User[]> {
  const response = await fetch(
    "https://api.example.com/users"
  );

  const data = (await response.json()) as User[];

  return data;
}

Here:

Promise<User[]>

= the function returns a Promise whose fulfilled value is an array of users.

And:

as User[]

= TypeScript should treat the received data as an array of User objects. It does not validate the array at runtime.

---

Axios lets us conveniently describe the response data type with a generic.

Installation:

npm install axios

Import:

import axios from "axios";

Once again, suppose we have:

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

We can write:

async function fetchUser(id: number): Promise<User> {
  const response = await axios.get<User>(
    `https://api.example.com/users/${id}`
  );

  return response.data;
}

The key part is:

axios.get<User>()

This uses a generic.

We can think of it as:

T = User

Therefore, TypeScript treats:

response.data

as the type:

User

The generic provides compile-time type information, but it does not validate the server response at runtime.

---

If the API returns an array of users:

async function fetchUsers(): Promise<User[]> {
  const response = await axios.get<User[]>(
    "https://api.example.com/users"
  );

  return response.data;
}

The key part is:

axios.get<User[]>()

It means:

Treat the response data as an array of User objects at compile time.

It does not check the response data at runtime.

---

Fetch

async function getProduct(): Promise<Product> {
  const response = await fetch("/product");

  const data = (await response.json()) as Product;

  return data;
}

Axios

async function getProduct(): Promise<Product> {
  const response = await axios.get<Product>("/product");

  return response.data;
}

With fetch, we often explicitly assert the type after reading the JSON:

as Product

With Axios, we pass the type as a generic:

axios.get<Product>()

Neither approach validates the received data at runtime. Both only provide type information to TypeScript.

---

Basic Types

string
number
boolean
null
undefined

Array

string[]
number[]
User[]

Interface

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

Optional Property

age?: number;

Read-Only Property

readonly id: number;

Union

string | number

which means:

string OR number

Intersection

TypeA & TypeB

which means:

TypeA AND TypeB combined

Literal Type

type Role = "admin" | "user";

Function

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

Function with No Return Value

function showMessage(message: string): void {
  console.log(message);
}

Generic

<T>

= a placeholder for a type.

One User

User

An Array of Users

User[]

A Promise with a User

Promise<User>

A Promise with an Array of Users

Promise<User[]>

Axios – One User

axios.get<User>()

Axios – An Array of Users

axios.get<User[]>()

---

let age: number;

age is a number.

let name: string;

name is a string.

const users: User[] = [];

users is an array of users.

function getUser(): User

The function returns a user.

function getUsers(): User[]

The function returns an array of users.

function getUser(): Promise<User>

The function returns a Promise whose fulfilled value is a user.

function getUsers(): Promise<User[]>

The function returns a Promise whose fulfilled value is an array of users.

axios.get<User>()

Axios treats the response data as one user at compile time.

axios.get<User[]>()

Axios treats the response data as an array of users at compile time.

interface Box<T>

Box can work with different types.

Box<number>

T = number.

Box<string>

T = string.

---

TypeScript does not replace JavaScript with a different programming model.

In most cases, we still write ordinary JavaScript:

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

and add type information:

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

The central idea of TypeScript is:

The more TypeScript knows about our data, the earlier it can detect a mistake.

At the beginning, the most important concepts to understand are:

string
number
boolean

interface

T[]

Union |

Intersection &

function → parameters + return type

<T> → Generic

Promise<T>

axios.get<T>()

Once these concepts are clear, you are ready to start using TypeScript with React.