TypeScript at a Glance

# Overview

TypeScript is an open-source language under the Apache License, developed and maintained by Microsoft.
It is a superset of JavaScript that compiles to plain JavaScript, and it was first released in October 2012.

# Why TypeScript?

The strong type systems used in structured, refined languages such as C# and Java can provide high readability and code quality, and because errors occur in the compile environment rather than at runtime, critical bugs are much easier to catch.

JavaScript, on the other hand, is a dynamic programming language without a type system, and a JavaScript variable can hold values of many types, such as strings, numbers, and booleans.
You can describe it as a weakly typed language. It gives you a relatively flexible development environment, but it has the downside that errors can easily occur at runtime.

TypeScript applies a strong type system to JavaScript, so you can catch most errors in the compile environment while you type your code.

# Using TypeScript

Just as JavaScript is written in files with the .js extension, TypeScript is written in files with the .ts extension, and after writing it, you compile it into JavaScript files with the TypeScript compiler.

1
2
$ tsc sample.ts
## compiled to `sample.js`

# TypeScript features

• Cross-platform support: You can use it on any platform where JavaScript runs.
• Object-oriented language: It provides powerful features such as classes, interfaces, and modules, and you can write purely object-oriented code.
• Static types: Because it uses static types, you can check for errors while you type your code. (This needs the help of an editor or plugin.)
• DOM control: Like JavaScript, it can control the DOM to add or remove elements.
• Support for the latest ECMAScript features: It lets you easily use the latest JavaScript syntax, ES6 and beyond.

# Development environment

# VSCode and WebStorm

VSCode (Visual Studio Code) and WebStorm have built-in TypeScript support, so they recognize TypeScript files (.ts, tsconfig.json, etc.) without any extra setup, and you can use many features right away, such as code checking, quick fixes, running, and debugging.
However, they don't include the compiler, so you need to install it separately. (e.g., npm install typescript)

VSCode Error

WebStorm Error

# Installing the compiler

To use the tsc command, install TypeScript globally as shown below.
If you give a TypeScript file as a path, it compiles that file.

1
2
3
$ npm install -g typescript
$ tsc --version
$ tsc ./src/index.ts

Or, if you want to use it only in a single project, you can install it locally as usual and run it with the npx tsc command.

1
2
3
$ npm install -D typescript
$ npx tsc --version
$ npx tsc ./src/index.ts

# Compiler options

You can set many options for compilation in TypeScript.
For the main options, see TypeScript Configuration (tsconfig.json) Summary.

1
$ tsc ./src/index.ts --watch --target ES2022 --lib ES2022,DOM --module ESNext

Or you can manage options with a tsconfig.json file, as shown below.
By also adding the "include" and "exclude" options, you can set the paths to include and the paths to exclude for compilation.

If you use VScode or WebStorm, creating a tsconfig.json file at the project root lets the editor read the configuration options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "module": "ESNext",
    "moduleResolution": "Bundler"
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

1
$ tsc --watch

TypeScript 6.0 changed the default values of key options.
Strict type checking (strict) is now on by default, target is the latest ECMAScript specification, module is ESNext, and types is an empty array.
Up to version 5, strict was off, so if you use an older version, you need to set the values yourself, as in the example above.
On the other hand, outFile and moduleResolution: "Classic" have been removed, and baseUrl, moduleResolution: "Node", and target: "ES5" are deprecated, so you shouldn't use them.
This is also why the example above sets moduleResolution as well.
If you set only module: "ESNext", versions up to 5 resolve modules as "Classic", which is slated for removal, so if you use a bundler, it's a good idea to set "Bundler" explicitly.

Among recently added options, the ones this post also covers are as follows.

# TypeScript Playground

https://typescriptlang.org/play

It's a REPL on the official TypeScript site, where you can see right away how your code is converted to JavaScript depending on the compiler options.

typescript playground

# Vite

If you want to test TypeScript quickly, Vite is a good choice.
Setting up a project is simple:

1
2
3
4
5
6
7
npm create vite@latest typescript-test
  ✔ Select a framework: Vanilla
  ✔ Select a variant: TypeScript
cd typescript-test
npm install
npm run dev
## Server running at http://localhost:5173

# Parcel

You can also set things up from scratch with the Parcel bundler.
Set up the project as follows.

1
2
3
4
$ mkdir typescript-test
$ cd typescript-test
$ npm init -y
$ npm install -D parcel typescript

Project structure

Create a tsconfig.json file and add the options you want.
Here is an example.

1
2
3
4
5
6
7
8
{
  "compilerOptions": {
    "strict": true
  },
  "exclude": [
    "node_modules"
  ]
}

Create a main.ts file and write whatever TypeScript code you want.

1
2
3
4
5
function add(a: number, b: number) {
  return a + b
}
const sum: number = add(1, 2)
console.log(sum)

Create an index.html file and link the .ts file directly instead of a .js file.
The Parcel bundler compiles the TypeScript automatically when it builds.

1
2
3
4
5
6
7
8
9
10
<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>TypeScript Test</title>
</head>
<body>
  <script type="module" src="main.ts"></script>
</body>
</html>

Finally, build with the Parcel bundler, using index.html as the entry file:

1
2
$ npx parcel index.html
## Server running at http://localhost:1234

# Node.js

If you want to test in a Node.js environment, you can run .ts files directly without a separate runner.
Node.js introduced a feature that strips type annotations and runs the code (type stripping) in version 22.6, and it works by default without any option from versions 22.18 and 23.6.
From versions 24.12 and 25.2, it is stable.
Setting up a project is simple:

1
2
3
4
$ mkdir typescript-test
$ cd typescript-test
$ npm init -y
$ npm install -D typescript @types/node

@types/node is a type declaration module for the Node.js API.
For more on @types, see the 'Modules' section.

Project structure

Create a tsconfig.json file and add the options you want.
Here is an example.

1
2
3
4
5
6
7
8
9
{
  "compilerOptions": {
    "strict": true,
    "module": "NodeNext"
  },
  "exclude": [
    "node_modules"
  ]
}

Create a main.ts file and write whatever TypeScript code you want.

1
console.log('TypeScript on NodeJS!')

Run main.ts directly.

1
2
$ node main.ts
## TypeScript on NodeJS!

# Types

# Type annotations

In TypeScript, you can annotate types on ordinary variables, parameters, object properties, and so on, in the form : TYPE.

1
2
3
4
function someFunc(a: TYPE_A, b: TYPE_B): TYPE_RETURN {
  return a + b
}
let some: TYPE_SOME = someFunc(1, 2)

In the following example,
the parameters a and b of the add function are annotated as number,
and because the return value of that function is inferred to be a number, the variable sum is also annotated as number.

1
2
3
4
5
function add(a: number, b: number) {
  return a + b
}
const sum: number = add(1, 2)
console.log(sum) // 3

The result of compiling it to JavaScript is as follows.

1
2
3
4
5
6
"use strict";
function add(a, b) {
  return a + b;
}
const sum = add(1, 2);
console.log(sum);

# Type errors

If you annotate the variable sum as string instead of number, as below, an error occurs while you are writing the code, before you even compile.

1
2
3
4
5
function add(a: number, b: number) {
  return a + b
}
const sum: string = add(1, 2)
console.log(sum)

Typescript error - TS2322

In the image above, you can see the error code TS2322, and a quick search for it will tell you more about the error.

Search Typescript error code

# Type declarations

# Boolean

Represents a simple true (true) or false (false) value.

1
2
let isBoolean: boolean
let isDone: boolean = false

# Number

You can use any floating-point value.
It also supports the binary and octal literals introduced in ES6.

1
2
3
4
5
6
7
8
let num: number
let integer: number = 6
let float: number = 3.14
let hex: number = 0xf00d // 61453
let binary: number = 0b1010 // 10
let octal: number = 0o744 // 484
let infinity: number = Infinity
let nan: number = NaN

# String

Represents a string.
It supports not only single quotes (') and double quotes (") but also ES6 template strings.

1
2
3
4
5
let str: string
let red: string = 'Red'
let green: string = "Green"
let myColor: string = `My color is ${red}.`
let yourColor: string = 'Your color is' + green

# Array

Represents an ordinary array that holds values in order.
You can declare the type of an array in two ways, as follows.

1
2
3
4
5
6
7
8
9
// An array of strings only
let fruits: string[] = ['Apple', 'Banana', 'Mango']
// Or
let fruits: Array<string> = ['Apple', 'Banana', 'Mango']

// An array of numbers only
let oneToSeven: number[] = [1, 2, 3, 4, 5, 6, 7]
// Or
let oneToSeven: Array<number> = [1, 2, 3, 4, 5, 6, 7]

With a union type (multiple types), you can also declare 'an array that holds both strings and numbers'.

1
2
3
let array: (string | number)[] = ['Apple', 1, 2, 'Banana', 'Mango', 3]
// Or
let array: Array<string | number> = ['Apple', 1, 2, 'Banana', 'Mango', 3]

If you can't be sure of the values of the items the array holds, you can use unknown.

1
let someArr: unknown[] = [0, 1, {}, [], 'str', false]

You can also use interfaces or custom types.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
interface IUser {
  name: string,
  age: number,
  isValid: boolean
}
let userArr: IUser[] = [
  {
    name: 'Neo',
    age: 85,
    isValid: true
  },
  {
    name: 'Lewis',
    age: 52,
    isValid: false
  },
  {
    name: 'Evan',
    age: 36,
    isValid: true
  }
]

It isn't very useful, but you can also write a specific value in place of a type, like this.

1
2
3
4
let array: 10[]
array = [10]
array.push(10)
array.push(11) // Error - TS2345

You can also create a readonly array.
Use the readonly keyword or the ReadonlyArray type.

1
2
3
4
5
6
7
8
let arrA: readonly number[] = [1, 2, 3, 4]
let arrB: ReadonlyArray<number> = [0, 9, 8, 7]

arrA[0] = 123 // Error - TS2542: Index signature in type 'readonly number[]' only permits reading.
arrA.push(123) // Error - TS2339: Property 'push' does not exist on type 'readonly number[]'.

arrB[0] = 123 // Error - TS2542: Index signature in type 'readonly number[]' only permits reading.
arrB.push(123) // Error - TS2339: Property 'push' does not exist on type 'readonly number[]'.

# Tuple

The tuple type is very similar to an array.
The difference is that it represents an array of fixed length with fixed types.

1
2
3
4
let tuple: [string, number]
tuple = ['a', 1]
tuple = ['a', 1, 2] // Error - TS2322
tuple = [1, 'a'] // Error - TS2322

Instead of storing the data in separate variables, you can use a single tuple type:

1
2
3
4
5
6
7
8
9
10
// Variables
let userId: number = 1234
let userName: string = 'HEROPY'
let isValid: boolean = true

// Tuple
let user: [number, string, boolean] = [1234, 'HEROPY', true]
console.log(user[0]) // 1234
console.log(user[1]) // 'HEROPY'
console.log(user[2]) // true

Going a step further, you can use this approach to build an array of tuples (a two-dimensional array).

1
2
3
4
5
let users: [number, string, boolean][]
// Or
// let users: Array<[number, string, boolean]>

users = [[1, 'Neo', true], [2, 'Evan', false], [3, 'Lewis', true]]

Here too, you can use values in place of types.

1
2
3
4
let tuple: [1, number]
tuple = [1, 2]
tuple = [1, 3]
tuple = [2, 3] // Error - TS2322: Type '2' is not assignable to type '1'.

A tuple represents an array of fixed length with fixed types, but this applies only to assignment.
It can't stop you from adding values with .push(), .splice(), and so on.

1
2
3
4
5
6
let tuple: [string, number]
tuple = ['a', 1]
tuple = ['b', 2]
tuple.push(3)
console.log(tuple) // ['b', 2, 3]
tuple.push(true) // Error - TS2345: Argument of type 'true' is not assignable to parameter of type 'string | number'.

As with arrays, you can use the readonly keyword to create a readonly tuple.

1
2
let a: readonly [string, number] = ['Hello', 123]
a[0] = 'World' // Error - TS2540: Cannot assign to '0' because it is a read-only property.

# Enum

An enum is a type that lets you give names (members) to a set of numeric or string values, and it's useful when the kinds of values are limited to a fixed range.

By default, it starts at 0 and each value increases by 1.

1
2
3
4
5
6
7
8
9
enum Week {
  Sun,
  Mon,
  Tue,
  Wed,
  Thu,
  Fri,
  Sat
}

enum example

You can change values manually, and from the point where you changed a value, values again increase by 1.

enum example

One interesting thing about enums is that they support reverse mapping.
This means you can access a value through an enumerated member (like Sun or Mon), and a member through its value.

Let's print Week to the console.

1
2
3
4
5
6
7
enum Week {
  // ...
}
console.log(Week)
console.log(Week.Sun) // 0
console.log(Week['Sun']) // 0
console.log(Week[0]) // 'Sun'

Reverse mapping of the enum type

Besides numeric values, an enum can also be initialized with string values.
However, this approach doesn't support reverse mapping, so you have to initialize each member individually.

1
2
3
4
5
6
7
enum Color {
  Red = 'red',
  Green = 'green',
  Blue = 'blue'
}
console.log(Color.Red) // red
console.log(Color['Green']) // green

The following example replaces the Color enum above with an as const object.

1
2
3
4
5
6
7
8
const Color = {
  Red: 'red',
  Green: 'green',
  Blue: 'blue'
} as const
type Color = typeof Color[keyof typeof Color] // 'red' | 'green' | 'blue'

console.log(Color.Red) // red

# Any

Any means every type.
So, just like an ordinary JavaScript variable, you can assign a value of any type to it.
It can come in handy when you work with external resources and simply can't pin down a type.

1
2
3
4
let any: any = 123
any = 'Hello world'
any = {}
any = null

You can also use it to represent an array that holds various values.

1
const list: any[] = [1, true, 'Anything!']

To keep the benefits of a strong type system, you can use the compiler option "noImplicitAny": true to raise an error when something implicitly becomes Any because no type is given.
This option is included in strict, and strict is on by default, so it applies even if you don't set it separately.

# Unknown

Unknown, a top type like Any, means a type that isn't known.
Like Any, you can assign a value of any type to Unknown, but you can't assign Unknown to other types.

1
2
3
4
5
6
7
let a: any = 123
let u: unknown = 123

let v1: boolean = a // The any type (any) can be assigned anywhere.
let v2: number = u // The unknown type (unknown) can't be assigned to any type except any.
let v3: any = u // OK!
let v4: number = u as number // It can be assigned once you assert its type.

# Object

By default, it represents every type for which the typeof operator returns "object".

1
2
3
4
5
6
let obj: object = {}
let arr: object = []
let func: object = function () {}
let nullValue: object = null
let date: object = new Date()
// ...

Because it's a supertype of many types, it isn't very useful.
To annotate types more precisely, you can annotate the type of each object property individually, like this.

1
2
3
4
5
6
7
8
9
10
let userA: { name: string, age: number } = {
  name: 'HEROPY',
  age: 123
}

let userB: { name: string, age: number } = {
  name: 'HEROPY',
  age: false, // Error
  email: 'thesecon@gmail.com' // Error
}

For reuse, it's better to use interface or type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
interface IUser {
  name: string
  age: number
}

let userA: IUser = {
  name: 'HEROPY',
  age: 123
}

let userB: IUser = {
  name: 'HEROPY',
  age: false, // Error
  email: 'thesecon@gmail.com' // Error
}

# Null, Undefined

Null and Undefined represent the values null and undefined respectively, and they can't be assigned to other types.
They can't be assigned to each other's types either.

1
2
3
4
5
6
7
8
let num: number = undefined // Error - TS2322: Type 'undefined' is not assignable to type 'number'.
let str: string = null
let obj: { a: 1, b: false } = undefined
let arr: any[] = null
let und: undefined = null
let nul: null = undefined
let voi: void = null
// ...

This behavior comes from the compiler option "strictNullChecks": true, which is included in strict and on by default.
Conversely, if you turn the option off, Null and Undefined become subtypes of every type, so all the assignments above are allowed, and this used to be the default behavior.

However, regardless of the option, you can assign Undefined to Void.

1
let voi: void = undefined // ok

# Void

Void is usually used in functions that don't return a value.
The : void position is where a function specifies its return type.

1
2
3
function hello(msg: string): void {
  console.log(`Hello ${msg}`)
}

A function that doesn't return a value actually returns undefined.

1
2
3
4
5
function hello(msg: string): void {
  console.log(`Hello ${msg}`)
}
const hi: void = hello('world') // Hello world
console.log(hi) // undefined

# Never

Never represents a value that never occurs, and no type can be assigned to it.

1
2
3
function error(message: string): never {
  throw new Error(message)
}

You usually see Never when you mistakenly declare an empty array as a type, like this.

1
2
const never: [] = []
never.push(3) // Error - TS2345: Argument of type '3' is not assignable to parameter of type 'never'.

# Literal

A type that allows only one specific value is called a literal type.
Instead of a broad range like string or number, you write the value itself in the type position.

1
2
3
4
5
6
let yes: 'Yes'
yes = 'Yes'
yes = 'No' // Error - TS2322: Type '"No"' is not assignable to type '"Yes"'.

let answer: 'Yes' | 'No' | 'Cancel'
answer = 'Cancel' // ok

A type that allows only one value is rarely useful on its own, so it's mainly used with unions to build a list of allowed values, like answer above.
The union you'll see next and the 'Discriminated unions' section later on are both based on literal types.

A string literal can be extended into a template literal type, which uses ${} interpolation.
It's a way to specify the shape of a value rather than a single value.

1
2
3
4
5
6
7
8
type UserId = `user_${number}`
let idA: UserId = 'user_123'
let idB: UserId = 'admin_123' // Error - TS2322

type Lang = 'ko' | 'en'
type TitleKey = `title_${Lang}` // 'title_ko' | 'title_en'
let keyA: TitleKey = 'title_ko'
let keyB: TitleKey = 'title_jp' // Error - TS2322

# Union

When a type allows two or more types, it's called a union.
Types are separated with | (vertical bar), and () is optional.

1
2
3
4
let union: (string | number)
union = 'Hello type!'
union = 123
union = false // Error - TS2322: Type 'false' is not assignable to type 'string | number'.

# Intersection

When you combine two or more types with & (ampersand), it's called an intersection.
Intersections are useful because they let you combine existing types without creating a new type, but they aren't used often.

If you can think of the union above as 'Or', you can think of an intersection as 'And'.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// If existing types can be combined, you can use an intersection.
interface IUser {
  name: string
  age: number
}
interface IValidation {
  isValid: boolean
}
const heropy: IUser = {
  name: 'Heropy',
  age: 36,
  isValid: true // Error -  TS2322: Type '{ name: string; age: number; isValid: boolean; }' is not assignable to type 'IUser'.
}
const neo: IUser & IValidation = {
  name: 'Neo',
  age: 85,
  isValid: true
}

# Function

You can annotate a function's types at the same time you declare it.

1
2
3
function add(a: number, b: number): number {
  return a + b
}

If needed, you can also annotate the type separately in arrow function form, like this.
Enter the types of the arguments and the type of the return value.

1
2
3
4
5
6
7
8
9
10
11
// myFunc is a function that takes 2 number arguments and returns a number.
let myFunc: (arg1: number, arg2: number) => number
myFunc = function (x, y) {
  return x + y
}

// No arguments and no return value.
let yourFunc: () => void
yourFunc = function () {
  console.log('Hello world~')
}

An async function returns a Promise instance, so you specify its return type with generics, like this.

1
2
3
4
5
6
7
8
type Movie = {
  title: string
  poster: string
}
async function getMovie(title: string): Promise<Movie[]> {
  const res = fetch(`https://gettitles.movie/${title}`)
  return await res.json()
}

# Type inference

When a type isn't declared explicitly, TypeScript infers it for you.
The concept is very simple, but very important!

[Infer]: To reach a conclusion based on evidence and reasoning.

1
2
let num = 12
num = 'Hello type!' // TS2322: Type '"Hello type!"' is not assignable to type 'number'.

The variable num was initialized with the number 12, so it was inferred as the Number type, and an error occurs because a String value like 'Hello type!' can't be assigned to it.

TypeScript infers types in the following cases.

• Initialized variables
• Parameters with default values
• Functions with return values

1
2
3
4
5
6
7
8
// The initialized variable `num`
let num = 12

// The parameter `b`, which has a default value
function add(a: number, b: number = 2): number {
  // A function with a return value (`a + b`)
  return a + b
}

# Type assertions

When something goes beyond the range of types TypeScript can determine through type inference, you can tell it to stop inferring.
This is called a 'type assertion', and it's for situations where you, the programmer, understand the type better than TypeScript does.

[Assert]: To state something firmly and confidently.

Let's look at the following example.

The function's parameter val is a union type, so it can be a string or a number.
The parameter isNumber is a boolean, and from its name, we can infer that it tells whether the value is a number.
So we know for sure that when isNumber is true, val will be a number and we can use toFixed on it.
But TypeScript can't infer this from the name 'isNumber' alone, so it reports the following error (at the compile stage), saying "you can't use toFixed when val is a string".

1
2
3
4
5
6
function someFunc(val: string | number, isNumber: boolean) {
  // some logics
  if (isNumber) {
    val.toFixed(2) // Error - TS2339: ... Property 'toFixed' does not exist on type 'string'.
  }
}

So we can assert that val is a number when isNumber is true in two ways, as follows.
The second way (<number>val) can trip up the parser on certain syntax when you use JSX, so you can't use it at all in .tsx files.

1
2
3
4
5
6
7
8
9
10
function someFunc(val: string | number, isNumber: boolean) {
  // some logics
  if (isNumber) {
    // 1. variable as Type
    (val as number).toFixed(2)
    // Or
    // 2. <Type>variable
    // (<number>val).toFixed(2)
  }
}

# Non-null assertion operator

With the non-null assertion operator, which uses !, you can assert that an operand isn't a nullish value (null or undefined). It's useful because you can use it easily on variables and properties.

In the fnA function in the following example, the parameter x is treated as a number inside the function, where toFixed is used, but an error occurs because it may be null or undefined.
You could solve this with a type assertion or an if statement, but you can clean it up simply with the non-null assertion operator, !, as in the last function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Error - TS2533: Object is possibly 'null' or 'undefined'.
function fnA(x: number | null | undefined) {
  return x.toFixed(2)
}

// if statement
function fnD(x: number | null | undefined) {
  if (x) {
    return x.toFixed(2)
  }
}

// Type assertion
function fnB(x: number | null | undefined) {
  return (x as number).toFixed(2)
}
function fnC(x: number | null | undefined) {
  return (<number>x).toFixed(2)
}

// Non-null assertion operator
function fnE(x: number | null | undefined) {
  return x!.toFixed(2)
}

It's especially useful when working with the DOM, which is hard to check in the compile environment.
Of course, you can also use an ordinary type assertion.

1
2
3
4
5
6
7
8
9
// Error - TS2531: Object is possibly 'null'.
document.querySelector('.menu-item').innerHTML

// Type assertion
(document.querySelector('.menu-item') as HTMLDivElement).innerHTML
(<HTMLDivElement>document.querySelector('.menu-item')).innerHTML

// Non-null assertion operator
document.querySelector('.menu-item')!.innerHTML

# Const assertions

A const assertion, which uses as const, fixes a value to a literal type and makes all of its properties readonly.
Use it when you want to keep a value from being inferred as a broader type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Inferred: { mode: string; size: number }
const configA = {
  mode: 'dark',
  size: 10
}

// Inferred: { readonly mode: 'dark'; readonly size: 10 }
const configB = {
  mode: 'dark',
  size: 10
} as const

configA.mode = 'light' // ok
configB.mode = 'light' // Error - TS2540: Cannot assign to 'mode' because it is a read-only property.

Used on an array, it becomes a readonly tuple.
How to use this to turn all the elements of an array into a union type is covered in the 'Interfaces / keyof' section.

# Type guards

As in the following example, you sometimes end up using type assertions many times to guarantee the type of val each time.

1
2
3
4
5
6
7
8
9
10
function someFunc(val: string | number, isNumber: boolean) {
  if (isNumber) {
    (val as number).toFixed(2)
    isNaN(val as number)
  } else {
    (val as string).split('')
    (val as string).toUpperCase()
    (val as string).length
  }
}

In this case, if you provide a type guard, TypeScript can guarantee the type within a specific scope it can infer.
A type guard is a function that declares a type predicate as its return type, in the form NAME is TYPE.
In the following example, the type predicate is val is number.
With the type assertions gone, it's much cleaner.

[Predicate]: The part of a sentence that describes the state or nature of the subject.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Type guard
function isNumber(val: string | number): val is number {
  return typeof val === 'number'
}

function someFunc(val: string | number) {
  if (isNumber(val)) {
    val.toFixed(2)
    isNaN(val)
  } else {
    val.split('')
    val.toUpperCase()
    val.length
  }
}

Since TypeScript 5.5, you can leave out the type predicate in simple cases like the example above.
If the function's return value narrows the type of a parameter, TypeScript infers the predicate.

1
2
3
4
5
6
7
8
9
10
11
12
// Inferred as `val is number` even without an explicit return type.
function isNumber(val: string | number) {
  return typeof val === 'number'
}

function someFunc(val: string | number) {
  if (isNumber(val)) {
    val.toFixed(2)
  } else {
    val.toUpperCase()
  }
}

Besides the approach above, there are more type guards you can use.
These are type guards that use the typeof, in, and instanceof operators directly.
They are recommended for relatively simple logic.

The typeof operator recognizes all 8 results, string, number, bigint, boolean, symbol, undefined, object, and function, as type guards.
The in operator works on union types as is, and you don't need to assert the right-hand object as any.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Even without providing (abstracting) `isNumber` as in the earlier example, using the `typeof` operator directly works as a type guard.
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof
function someFuncTypeof(val: string | number) {
  if (typeof val === 'number') {
    val.toFixed(2)
    isNaN(val)
  } else {
    val.split('')
    val.toUpperCase()
    val.length
  }
}

// Provides a type guard with the `in` operator, without a separate abstraction.
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in
interface IFixed {
  toFixed(digits: number): string
}
interface ISplit {
  split(separator: string): string[]
}
function someFuncIn(val: IFixed | ISplit) {
  if ('toFixed' in val) {
    val.toFixed(2)
  } else {
    val.split('')
  }
}

// Likewise, provides a type guard with the `instanceof` operator, without a separate abstraction.
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof
class Cat {
  meow() {}
}
class Dog {
  woof() {}
}
function sounds(ani: Cat | Dog) {
  if (ani instanceof Cat) {
    ani.meow()
  } else {
    ani.woof()
  }
}

# Type satisfaction

TypeScript provides the satisfies keyword, which checks whether an object satisfies a type.
Let's look at a few examples based on a User interface where the name and age properties are required.

1
2
3
4
interface User {
  name: string
  age: number
}

In the following example, the object assigned to userA doesn't match the User type, but no error occurs because of the type assertion.
userB is declared to be of the User type, so an object that doesn't match the User type can't be assigned to it, and an error occurs.
The object assigned to userC is checked with the satisfies keyword to see whether it satisfies the User type, and an error occurs because it doesn't.
In short, a type assertion can be unsafe because developers make mistakes, declaring the type directly is the safest option, and since satisfies only checks whether a type is satisfied, it doesn't look very useful so far.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Pass.. an unsafe type 'assertion'..
const userA = { 
  name: 'Neo' 
} as User

// Error! A safe type 'declaration'!
const userB: User = {
  name: 'Neo' 
}

// Error! A safe type 'satisfaction'!
const userC = { 
  name: 'Neo' 
} satisfies User

In the following example, the object assigned to the info property of userD doesn't match the User type, but no error occurs because of the type assertion.
userE wants its info property to be of the User type, but syntactically you can't declare a type directly on an object property.
For userF, the object assigned to the info property is checked with the satisfies keyword to see whether it satisfies the User type, and an error occurs because it doesn't.
This is where satisfies shines: it can check whether the types inside an object are satisfied.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Pass.. an unsafe inner object type 'assertion'..
const userD = { 
  info: { 
    name: 'Neo', 
    age: 85,
    isValid: true
  } as User, 
  photo: null 
}

// Pass.. an inner object type that can't be 'declared' syntactically..
const userE = { 
  info: { 
    name: 'Neo', 
    age: 85, 
    isValid: true 
  }, 
  photo: null 
}

// Error! A safe inner object type 'satisfaction'!
const userF = { 
  info: { 
    name: 'Neo', 
    age: 85, 
    isValid: true 
  } satisfies User,
  photo: null 
}

Note that the satisfies keyword only checks whether the target satisfies a type and doesn't annotate the type, so you can use it like this.
satisfies checks type satisfaction, and as annotates (asserts) the type.

1
2
3
4
5
6
7
8
9
// Error! A safe inner object type 'satisfaction'! then an 'assertion'
const userF = { 
  info: { 
    name: 'Neo', 
    age: 85, 
    isValid: true 
  } satisfies User as User,
  photo: null 
}

# Type aliases

You can create a new combination of types with the type keyword, and this is called a type alias.
You combine one or more types and give them an alias (a name); more precisely, you create an alias that refers to each of the combined types.
In general, unions are often used to compose a combination of two or more types.

In TUser, T is used as a prefix meaning Type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
type MyType = string
type YourType = string | number | boolean
type TUser = {
  name: string
  age: number
  isValid: boolean
} | [string, number, boolean]

let userA: TUser = {
  name: 'Neo',
  age: 85,
  isValid: true
}
let userB: TUser = ['Evan', 36, false]

function someFunc(arg: MyType): YourType {
  switch (arg) {
    case 's':
      return arg.toString() // string
    case 'n':
      return parseInt(arg) // number
    default:
      return true // boolean
  }
}

# Interfaces

In TypeScript, an interface is a kind of rule, or structure, that defines the shape of objects.
You write one with the interface keyword, as shown below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
interface IUser {
  name: string
  age: number
  isAdult: boolean
}

let user1: IUser = {
  name: 'Neo',
  age: 123,
  isAdult: true
}

// Error - TS2741: Property 'isAdult' is missing in type '{ name: string; age: number; }' but required in type 'IUser'.
let user2: IUser = {
  name: 'Evan',
  age: 456
}

You can separate members with ; or ,, or leave the separators out entirely.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
interface IUser {
  name: string,
  age: number
}
// Or
interface IUser {
  name: string;
  age: number;
}
// Or
interface IUser {
  name: string
  age: number
}

If you use ? on a property, as below, you can define it as an optional property.
Optional properties are explained separately in the Optional section, but in short, this is a way to 'define a property that isn't required'.

1
2
3
4
5
6
7
8
9
10
11
interface IUser {
  name: string
  age: number
  isAdult?: boolean // Optional property
}

// No error occurs even if you don't initialize `isAdult`.
let user: IUser = {
  name: 'Neo',
  age: 123
}

# Readonly properties

With the readonly keyword, you can define readonly properties that must keep their initialized values.

1
2
3
4
5
6
7
8
9
10
11
12
13
interface IUser {
  readonly name: string
  age: number
}

// Initialization
let user: IUser = {
  name: 'Neo',
  age: 36
}

user.age = 85 // Ok
user.name = 'Evan' // Error - TS2540: Cannot assign to 'name' because it is a read-only property.

If every property is readonly, you can use a utility or a type assertion.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// All readonly properties
interface IUser {
  readonly name: string
  readonly age: number
}
let user: IUser = {
  name: 'Neo',
  age: 36
}
user.age = 85 // Error
user.name = 'Evan' // Error


// Readonly Utility
interface IUser {
  name: string
  age: number
}
let user: Readonly<IUser> = {
  name: 'Neo',
  age: 36
}
user.age = 85 // Error
user.name = 'Evan' // Error


// Type assertion
let user = {
  name: 'Neo',
  age: 36
} as const
user.age = 85 // Error
user.name = 'Evan' // Error

# Function types

When you define a function type with an interface, you use what's called a call signature.
A call signature specifies the function's parameters and return type, like this.

1
2
3
interface IName {
  (PARAMETER: PARAM_TYPE): RETURN_TYPE // Call signature
}

Let's look at a simple example.
The function type is defined through the interface IGetUser, which takes one name parameter (the name doesn't have to match) and must return the IUser type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
interface IUser {
  name: string
}
interface IGetUser {
  (name: string): IUser
}

// Parameter names don't have to match the interface.
// Also, through type inference, parameters can get implicit types in order.
const getUser: IGetUser = function (n) { // n is name: string
  // Find user logic..
  // ...
  return user
}
getUser('Heropy')

# Class types

When you define a class with an interface, you use the implements keyword.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
interface IUser {
  name: string
  getName(): string
}

class User implements IUser {
  constructor(public name: string) {}
  getName() {
    return this.name
  }
}

const neo = new User('Neo')
neo.getName() // Neo

The basic usage isn't hard.
But if you use the defined class as an argument, you may run into the following problem.
That's because the interface ICat in the following example isn't a callable structure.

1
2
3
4
5
6
7
8
9
10
11
12
13
interface ICat {
  name: string
}

class Cat implements ICat {
  constructor(public name: string) {}
}

function makeKitten(c: ICat, n: string) {
  return new c(n) // Error - TS2351: This expression is not constructable. Type 'ICat' has no construct signatures.
}
const kitten = makeKitten(Cat, 'Lucy')
console.log(kitten)

For this, you can provide a construct signature.
A construct signature is similar to the call signature we saw above, but it must use the new keyword.

1
2
3
interface IName {
  new (PARAMETER: PARAM_TYPE): RETURN_TYPE // Construct signature
}

Change the earlier example as follows.
If you define a callable interface called ICatConstructor with a construct signature, you can see that it works without problems.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
interface ICat {
  name: string
}
interface ICatConstructor {
  new (name: string): ICat
}

class Cat implements ICat {
  constructor(public name: string) {}
}

function makeKitten(c: ICatConstructor, n: string) {
  return new c(n) // ok
}
const kitten = makeKitten(Cat, 'Lucy')
console.log(kitten)

Here's a similar but more fun example.
It's enough if you find where the error occurs and understand why.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
interface IFullName {
  firstName: string
  lastName: string
}
interface IFullNameConstructor {
  new(firstName: string): IFullName // Construct signature
}


function makeSon(c: IFullNameConstructor, firstName: string) {
  return new c(firstName)
}
function getFullName(son: IFullName) {
  return `${son.firstName} ${son.lastName}`
}


// Anderson family
class Anderson implements IFullName {
  public lastName: string
  constructor (public firstName: string) {
    this.lastName = 'Anderson'
  }
}
const tomas = makeSon(Anderson, 'Tomas')
const jack = makeSon(Anderson, 'Jack')
getFullName(tomas) // Tomas Anderson
getFullName(jack) // Jack Anderson


// Smith family?
class Smith implements IFullName {
  public lastName: string
  constructor (public firstName: string, agentCode: number) {
    this.lastName = `Smith ${agentCode}`
  }
}
const smith = makeSon(Smith, 7) // Error - TS2345: Argument of type 'typeof Smith' is not assignable to parameter of type 'IFullNameConstructor'.
getFullName(smith)

# Indexable types

With interfaces, we can define the types of specific properties (methods and so on), but the usual approach alone has limits for structures that have a great many properties or include arbitrary properties you can't be sure of. Let's look at index signatures, which are useful in these situations.

There are indexable types, which you index with a 'number', as in arr[2], or with a 'string', as in obj['name'].
An interface that defines such indexable types can have what's called an index signature.
An index signature specifies the name and type of the indexer used for indexing and the return value of the indexing result, as in the following structure.
The type of the indexer can be string, number, symbol, or a template literal pattern.

1
2
3
interface INAME {
  [INDEXER_NAME: INDEXER_TYPE]: RETURN_TYPE // Index signature
}

The number (string) that points to a position in an array (object) is called an index, and using an index to access each array element (object property) is called indexing. (Each value that makes up an array is called an array element.)

To help you understand, look at the following example.
The interface IItem has an index signature, item uses that IItem as its type (interface), and when you index item with a number, as in item[0] or item[1], the returned value must be a string such as 'a' or 'b'.
Indexing item with a string, as in item['0'], causes an error.