A glossary of TypeScript

Motivation

Once upon a time, there was a developer that had an issue using the TypeScript language. He wanted to share his issue with the community to get help, but he didn't know how to properly write the title that would best describe his problem. He struggled to find the appropriate words as he didn't know how to name "this behavior" or "that kind of type mechanism".

This story encouraged me to start writing a glossary of TypeScript. Hopefully it will help you if you have to look for an issue, write an issue, or communicate with other TypeScript developers.

Disclaimer: it was me, I was the developer that struggled. I still struggle though, but this means I still have things to learn, which is great!

You may not agree with some definitions or examples in this document. Please, feel free to leave a comment and let me know, only together can we improve this glossary! Also, if the stars are aligned and this gist gets more and more attention, I might move it into its own repository so we can all contribute via issues and pull-requests! 🚀

UPDATE 2021-03-28

I decided to create a GitHub repository: ruizb/glossary-typescript. This gist will not be updated anymore, please refer to the repository instead! 🙂

Table of content

Ambient declaration
Conditional type
Diagnostic message
Discriminated union
IntelliSense
Intersection type
Intrinsic type
Literal type
Mapped type
Type alias
Type assertion
Type check
Type guard
Type inference
Type narrowing
Type predicate
Union type

Glossary

Ambient declaration

An ambient declaration lets you tell the compiler that a global variable/function exists, and which type it has: "I know you can't find it but trust me, this variable/function exists at runtime, and it has this type". The declare keyword lets you write such declaration.

Example

doSomething(42) // TS error, "Cannot find name 'doSomething'"

// no implementation is provided here, because it's available at runtime.
declare function doSomething(n: number): void

doSomething(42) // no TS error

Conditional type

Conditional types were introduced in TypeScript v2.8. They can be used to make non-uniform type mapping, meaning they can be considered as functions for types, like mapped types but more powerful.

TypeScript provides several conditional types for the developers, such as Exclude, NonNullable, Parameters or ReturnType.

Example

// { "strict": true }

const isDefined = <A>(value: A | null | undefined): value is NonNullable<A> =>
  value !== null && value !== undefined

const button = document.getElementById('my-button') // HTMLElement | null
if (isDefined(button)) {
  console.log(`Button text: ${button.innerText}`)
} else {
  console.log('Button is not defined')
}

In this example we are using the conditional type NonNullable in strict mode as a type guard to make sure the value is defined in the "true" branch of our condition.

Example

type SyncOperationName = 'getViewportSize' | 'getElementSize'
type AsyncOperationName = 'loadUsers' | 'sendData'
type OperationName = SyncOperationName | AsyncOperationName

type Operation<A extends OperationName> = A extends SyncOperationName
  ? { type: 'syncOperation', name: A }
  : { type: 'asyncOperation', name: A, timeout: number }

Here we are mapping A to a completely different type Operation<A>, which depends on the effective type of A:

If A is a SyncOperationName then Operation<A> is { type: 'syncOperation', name: A }.
Otherwise, since A is a OperationName, OperationName is a union type and the first element of that union type has already been checked with A extends SyncOperationName, then A must be a AsyncOperationName in the "else" branch of this ternary expression. Therefore, Operation<A> becomes { type: 'asyncOperation', name: A, timeout: number }.

This is a very powerful feature that allows building complex types, especially when using type inference in conditional types.

You can check the official documentation for more information about conditional types.

Diagnostic message

When TypeScript detects an error/warning in your program, its checker (an internal component of the language) generates a diagnostic message.

Example

// { "strict": true }

const value: string = undefined

Type 'undefined' is not assignable to type 'string'. (2322)

The 2322 number is an ID that could be used to reference the type of diagnostic message when creating an issue for example. More specifically, the 2322 ID relates to the Type '{0}' is not assignable to type '{1}'. diagnostic. You can also check the wiki for more information about these messages.

Discriminated union

Discriminated unions were introduced in TypeScript 2.0 as "tagged union types".

Example

interface Square {
  kind: 'square'
  size: number
}

interface Rectangle {
  kind: 'rectangle'
  width: number
  height: number
}

interface Circle {
  kind: 'circle'
  radius: number
}

type Shape = Square | Rectangle | Circle

Here, Shape is the discriminated union, where the discriminant - also known as singleton property or tag - is the kind property.

You can also check the official documentation section on discriminated unions.

IntelliSense

IntelliSense is the ability for the IDE - thanks to the language - to provide valuable hints for the developer depending on the context he's in, such as relevant and accurate autocompletions and code transformations. Usually, IDEs provide this feature via the ctrl + space shortcut.

Intersection type

Intersection types were introduced in TypeScript v1.6 as a complement to union types. This allows us to type a value that is both a A and a B.

Example

interface WithName {
  name: string
}

interface WithAge {
  age: number
}

type User = WithName & WithAge

The User type is computed as { name: string, age: number }, which is the intersection of both types WithName and WithAge.

The intersection of types that have nothing in common results in the never type, introduced in TypeScript v2.0.

Example

type A = 'a' & 'b'

type B = { name: string, age: number } & { name: number, adult: boolean }

Here, A is never, because the string literals 'a' and 'b' have nothing in common.

For B, its type results in { name: never, age: number, adult: boolean } because string and number have nothing in common. As one of its properties type is never, there's no way to create a value which type is B, because no value can be assigned to the never type.

Intrinsic type

An intrinsic type is a type which implementation is provided by the TypeScript compiler. It's a type that cannot be expressed by any feature provided by the type system of the language.

It was first introduced in this PR by a TypeScript maintainer for the v4.1 release. This PR adds 4 intrinsic string types to TypeScript:

type Uppercase<S extends string> = intrinsic;
type Lowercase<S extends string> = intrinsic;
type Capitalize<S extends string> = intrinsic;
type Uncapitalize<S extends string> = intrinsic;

More intrinsic types could be added in the future.

Literal type

Literal types were introduced in TypeScript v1.8. They are meant to expect only a specific set of strings, numbers or boolean, instead of "any string, number or boolean".

Example

type Scheme = 'http' | 'https'

const prependWithScheme = (scheme: Scheme, domain: string, path: string): string =>
  `${scheme}://${domain}/${path}`

prependWithScheme('http')
prependWithScheme('https')
prependWithScheme('')

Here, no TypeScript error is raised for prependWithScheme('http') and prependWithScheme('https'). Even better, the IDE knows which values are available for autocompletion. However, an error is raised for prependWithScheme('') as the empty string '' is not available in the string literal type Scheme.

Example

interface SuccesfulResponse {
  successfulRequest: true
  status: 200 | 201 | 202
  data: unknown
}

interface UnsuccesfulResponse {
  successfulRequest: false
  status: 400 | 500
  errorMessage: string
}

const handleResponse = (response: SuccesfulResponse | UnsuccesfulResponse): void => {
  if (response.successfulRequest) {
    console.log(`Status: ${response.status}, data: ${response.data}`)
  } else {
    console.log(`Status: ${response.status}, error message: ${response.errorMessage}`)
  }
}

Mapped type

Mapped types were introduced in TypeScript v2.1. They can be used to make uniform type mapping, allowing a developer to transform a type into another type of the same "form":

A mapped type can use a string or subset of a string (i.e. string literal type) to build an object thanks to the built-in Record mapped type:

type A = Record<'firstname' | 'lastname' | 'surname', string>
/**
 * {
 *   firstname: string,
 *   lastname: string,
 *   surname: string
 * }
 */

A mapped type can be a subset of the original type, e.g. using Pick or Omit (cf. example below).
A mapped type can change the optionality of all the properties of the original type using Required, Nullable or Partial.
A mapped type can change the visibility of all the properties of the original type using Readonly.

Example

interface Config {
  address: string
  port: number
  logsLevel: 'none' | 'error' | 'warning' | 'info' | 'debug'
}

type A = Partial<Config>
type B = Omit<Config, 'address' | 'logsLevel'>
type C = Pick<Config, 'logsLevel'>
type D = Readonly<Config>

Types A, B, C and D are all uniform mappings of Config thanks to the built-in mapped types Partial, Omit, Pick and Readonly:

A is computed as:

{
  address?: string | undefined,
  port?: number | undefined,
  logslevel?: 'none' | 'error' | 'warning' | 'info' | 'debug' | undefined
}

B is computed as:
```
{
  port: number
}
```

C is computed as:

{
  logslevel: 'none' | 'error' | 'warning' | 'info' | 'debug'
}

D is computed ad:

{
  readonly address: string,
  readonly port: number,
  readonly logslevel: 'none' | 'error' | 'warning' | 'info' | 'debug'
}

There is a section in the official documentation about mapped types.

Type alias

A type alias attaches a name to the definition of a type, whatever its complexity. In addition to naming function and object types like interfaces, type aliases can be used to name primitives, unions, tuples... Whatever type actually.

Example

type Name = string
type LazyName = () => string

interface User_1 {
  name: string
  age: number
}

type User_2 = {
  name: string
  age: number
}

interface Predicate_1<A> {
  (value: A): boolean
}

type Predicate_2<A> = (value: A) => boolean

You can go to the official documentation regarding type aliases for more information.

Type assertion

Type assertions, frequently named type casting wrongly, let you tell the compiler "trust me, I know a type more suitable for this value than the one you inferred". Contrary to casting in other languages, assertions don't change the structure of the value, they don't have any impact at runtime. The language assumes you did the runtime checks before using a type assertion, so it's your responsibility to make sure a value has the correct type when using an assertion.

There are 2 ways to use a type assertion, either by using the as X keyword, or <X> syntax.

Example

const name: unknown = 'Bob'

const strLength = (name as string).length
// or
const altStrLength = (<string>name).length

Bear in mind that, if the type inferred by TypeScript and your type assertion don't overlap, then the compiler will raise an error. To avoid this, either the type assertion must be a subtype of the type inferred by TypeScript, or the other way around.

const value = 42 // inferred as `number`

const res = (value as string).length
/** TS error 2352 on `value as string`:
 * Conversion of type 'number' to type 'string' may be a mistake because neither type sufficiently overlaps with the other.
 * If this was intentional, convert the expression to 'unknown' first.
 */

Type check

Type checking is one of the features available with the TypeScript language. The type checker verifies the semantics of the types of your project to make sure the program is "correct" type-wise. Other features included in TypeScript are code parsing, code transformations (TS/JS => JS), language service for tools that allow e.g. IntelliSense.

If a line of code doesn't type check then a diagnostic is generated and displayed as an error/warning to the user.

Example

const name: string = 12

Here, the type checker tells us there is an error for the type of name: Type '12' is not assignable to type 'string'..

Type guard

"A type guard is some expression that performs a runtime check that guarantees the type in some scope."

From the official documentation.

We can use the typeof operator or a type predicate to enable type guards. It also allows for a type to be narrowed in a conditional branch.

Example

declare const value: string | number

const getNumberOfChars = (s: string): number => s.length

const isGreaterThan = (n: number, bound: number): boolean => n > bound

if (typeof value === 'string') {
  console.log(`Number of chars in ${value}: ${getNumberOfChars(value)}.`)
} else if (typeof value === 'number') {
  console.log(`Is ${value} greater than 20? ${isGreaterThan(value, 20) ? 'Yes' : 'No'}.`)
} else {
  throw 'Impossible, perhaps the archives are incomplete'
}

By checking the type of value with typeof, TypeScript knows that in the if branch, value must have that type and not the others:

In the if (typeof value === 'string') { ... } branch, value type is narrowed from string | number to string.
In the if (typeof value === 'number') { ... } branch, value type is narrowed from string | number to number.
In the else { ... } branch, since all the possible types have been checked in the previous if conditions, value type is narrowed from string | number to never (it "can't" happen since all the possible cases have been checked already).

Type inference

Type inference is the ability for the TypeScript compiler to appropriately guess the type of a value, without manually specifying the type for that value.

Example

const username = 'Bob'
const port = 8080
const names = ['Bob', 'Henri', 'Elizabeth']
const finiteNames = ['Bob', 'Henri', 'Elizabeth'] as const

Type of username is the string literal type 'Bob'
Type of port is the number literal type 8080
Type of names is string[]
Type of finiteNames is readonly ['Bob', 'Henri', 'Elizabeth'], in other words a readonly tuple of 3 elements

Type narrowing

It's the ability for the TypeScript language to restrict the type of a value to a subset of that type.

Example

type A =
  | { kind: 'a', arg1: 'hey' }
  | { kind: 'b', arg1: 'Hello', arg2: 'World' }
  | { kind: 'c' }

declare const value: A

if (value.kind === 'a') {
  console.log(`Value of kind ${value.kind} has argument ${value.arg1}`)
} else if (value.kind === 'b') {
  console.log(`Value of kind ${value.kind} has arguments ${value.arg1} and ${value.arg2}`)
} else {
  console.log(`Value of kind ${value.kind} has no argument`)
}

If value.kind === 'a' is true, then value type is { kind: 'a', arg1: 'hey' }
Otherwise, if value.kind === 'b' is true, then value type is { kind: 'b', arg1: 'Hello', arg2: 'World' }
Otherwise, since we've already handled the cases { kind: 'a', arg1: 'hey' } and { kind: 'b', arg1: 'Hello', arg2: 'World' }, only the last one of the discriminated union A is left, i.e. { kind: 'c' }

More examples are available in the type guard section.

Type predicate

The developer can define type guards specific to his domain by returning a type predicate to a function. A type predicate uses the paramName is Type syntax.

Example

interface User {
  name: string
  age: number
}

// You can ignore this function for the sake of this example
const hasOwnProperty = <A extends {}, B extends PropertyKey>(obj: A, prop: B): obj is A & Record<B, unknown> =>
  obj.hasOwnProperty(prop)

const isUser = (v: unknown): v is User =>
  typeof v === 'object' &&
  v !== null &&
  hasOwnProperty(v, 'name') &&
  typeof v.name === 'string' &&
  hasOwnProperty(v, 'age') &&
  typeof v.age === 'number'

declare const value: unknown

if (isUser(value)) {
  console.log(`User(name = ${value.name}, age = ${value.age})`)
} else {
  throw `Invalid user provided: ${JSON.stringify(value)}`
}

We created the v is User type predicate as the return value of the isUser function, which tells TypeScript that if isUser(value) returns true, then value is guaranteed to be a User in the if branch, otherwise it will keep the initial type (unknown here).

Some other examples of type predicates are available in the TypeScript documentation.

Union type

Union types were introduced in TypeScript v1.4. It's a way of expressing mulitple possible types for a given value.

Example

declare const value: string | number | boolean

Here, value type can be either string, number or boolean.

ruizb/README.md

A glossary of TypeScript

Motivation

UPDATE 2021-03-28

Table of content

Glossary

Ambient declaration

Example

Conditional type

Example

Example

Diagnostic message

Example

Discriminated union

Example

IntelliSense

Intersection type

Example

Example

Intrinsic type

Literal type

Example

Example

Mapped type

Example

Type alias

Example

Type assertion

Example

Type check

Example

Type guard

Example

Type inference

Example

Type narrowing

Example

Type predicate

Example

Union type

Example

jcdiprose commented Jan 3, 2024