TypeScript union types allow us to combine individual types into flexible combinations.

Union Types

diagram of 3 boxes that have differently shaped slots to allow specific (and non-specific) shapes to pass through the slot. On the first one, only a specific triangle shape can pass through. On the second box, there are two slots, one for triangle and one for squares. In the last box, it allows triangles, squares, and circles to pass through.

TypeScript lets us type variables with different levels of _type specificity_. If we want to enforce that a variable is a `string`, we can type it as a `string`. This type is very specific since TypeScript will only allow the variable to have a string value.

On the other end of the specificity spectrum, we could type a variable as `any`. This type is very unspecific. TypeScript will allow a value of any type to be assigned without complaining and throwing an error.

These two levels of type specificity work for many parts of our programs. However, sometimes we need to strike a balance between extreme specificity and being totally unspecific with our types. Imagine that we have to write a program that takes in an employee’s ID, then prints the ID to the console. The catch is that an employee’s ID could be a string or a number. Since we need our ID variable to allow more than one type, we could use an `any` type, like this:

```ts
let ID: any;

console.log(`The ID is ${ID}.`);
```

The problem with the `any` type is that any value might not work with our program. To solve this problem, TypeScript allows us to be flexible with how specific our types are by combining different types. When we combine types, it is called a _union_. 


Introduction

Typing with unions gives us more flexibility with type specificity, but there’s also more to consider. For instance, look over this union: 

```ts
function getMarginLeft(margin: string | number) {
  // ...
}
```

Since `margin` can be a `string` or a `number`, we may want to perform different logic in the `getMarginLeft()` function’s body that does one thing for strings and another for numbers. To do this, we could implement a _type guard_. A type guard is a conditional that checks if a variable is a certain type, like this:

```ts
function getMarginLeft(margin: string | number) {
  // margin may be a string or number here
  
  if (typeof margin === 'string') {
    // margin must be a string here
  }
}
```

In the example above, TypeScript is able to read the type guard and infer that the `margin` variable inside the type guard must be a `string`. Since TypeScript knows `margin` is a `string`, it will allow us to use `string` methods on `margin`, like this:

```ts
if (typeof margin === 'string') {
  return margin.toLowerCase();
}
```

If we tried to call `margin.toLowerCase()` outside of the string type guard, TypeScript would complain that the `.toLowerCase()` method does not exist on `number` types. This error would occur because `margin` is typed as a `string | number` union.

This concept is called _type narrowing_. Type narrowing is when TypeScript can figure out what type a variable can be at a given point in our code. In our examples, TypeScript has narrowed the type inside the type guard to only be a `string`. Type narrowing allows us to use unions, then perform type-specific logic without TypeScript getting in the way.

Type Narrowing

When we put type members in a union, TypeScript will only allow us to use the common methods and properties that all members of the union share. Take this code:

```ts
const batteryStatus: boolean | number = false;

batteryStatus.toString(); // No TypeScript error
batteryStatus.toFixed(2); // TypeScript error
``` 

Since `batteryStatus` can be a `boolean` or a `number`, TypeScript will only allow us to call methods that both `number` and `boolean` share. They both share `.toString()`, so we’re good there. But, since only `number` has a `.toFixed()` method, TypeScript will complain if we try to call it.

This rule also applies to type objects that we define. Take this code:

```ts
type Goose = { 
  isPettable: boolean; 
  hasFeathers: boolean;
  canThwartAPicnic: boolean;
}

type Moose = {
  isPettable: boolean; 
  hasHoofs: boolean;
}

const pettingZooAnimal: Goose | Moose = { isPettable: true };

console.log(pettingZooAnimal.isPettable); // No TypeScript error
console.log(pettingZooAnimal.hasHoofs); // TypeScript error
```

Like before, since `.isPettable` is on both `Goose` and `Moose` types, TypeScript will allow us to call it. But since `.hasHoofs` is only a property on `Moose`, we cannot call that method on `pettingZooAnimal`. Any properties or methods that are not shared by all of the union’s members won’t be allowed and will produce a TypeScript error.

Common Key Value Pairs

Unions are even more powerful when used in combination with arrays.

For instance, we can represent time in TypeScript with a number or a string type. If we had a list of dates in both types, we’d need an array that allows for string and number values. Unions are here to help. 

To create a union that supports multiple types for an array's values, wrap the union in parentheses `(string | number)`, then use array notation `[]`.

```ts
const dateNumber = new Date().getTime(); // returns a number
const dateString = new Date().toString(); // returns a string

const timesList: (string | number)[] = [dateNumber, dateString];
```

Above, the `timesList` variable is typed to allow `string` and `number` types as values in its array. If we try to add a value to `timesList` that is not either type, like with `timesList.push(true)`, TypeScript would display an error that `boolean` types are not allowed inside `timesList`.

One last thing: the parentheses are vitally important to type arrays correctly. If we left out the parentheses and wrote `string | number[]`, that type would allow strings _or_ arrays of only numbers.


Unions and Arrays

Unions allow us to define multiple allowed _type members_ by separating each type member with a vertical line character `|`. With a union, we can re-type the program from the previous exercise like this:

```ts
let ID: string | number;

// number
ID = 1;

// or string
ID = '001';

console.log(`The ID is ${ID}.`);
```

In this example, `string | number` is a union that allows `ID` to be a `string` or a `number`. It’s more flexible than a single primitive type, but much more specific than the `any` type. 

Unions can be written anywhere a type value is defined, including function parameters:

```ts
function getMarginLeft(margin: string | number) {
  return { 'marginLeft': margin };
}
```

Using unions to type function parameters is especially convenient because functions often need to handle multiple types of input.


Defining Unions

🙌 Way to go! We’ve learned a variety of ways to create types that are as specific as we need with unions. To recap, we’ve learned:

- We can combine multiple types with a vertical bar character `|`. This is the syntax for defining a _union_. Each type in a union is called a _type member_. 
- We can narrow down what methods and properties are available in a program with _type narrowing_. Type narrowing allows us to type a variable as a union, then narrow down the union with a _type guard_ to call type member specific methods and properties.
- If a function can return multiple types, TypeScript will infer all possible return types as a union.
- We can use unions to allow arrays to have multiple types of values.
- To call a method or property on a variable typed as a union, we can only call methods or properties that are identical on all members of the union.
- We can define states within our program by using literal types and unions.


Review Unions

We can use literal types with TypeScript unions. Literal type unions are useful when we want to create distinct states within a program. 

For instance, if we were writing the code that controlled stoplights, we might write a program like this:

```ts
type Color = 'green' | 'yellow' | 'red';

function changeLight(color: Color) {
  // ...
}
```

With the code above, we could ensure that wherever `changeLight()` is called, that it gets passed only allowed stoplight colors. If we tried to call `changeLight('purple')`, TypeScript would complain, since that is not a valid stoplight color.

This technique allows us to write functions that are specific about the states they can handle, which helps us write code that’s less prone to errors.

Unions with Literal Types

One of the awesome things about TypeScript is that it’s able to infer types in many cases so that we don’t have to manually write them. A great example is a function’s return type. TypeScript will look at the contents of a function and infer which types the function can return. If there are multiple possible return types, TypeScript will infer the return type as a union.

For instance, take this example, where we call a function named `getBookFromServer()`, which might fail:

```ts
function getBook() {
  try {
    return getBookFromServer();
  } catch (error) {
    return `Something went wrong: ${error}`;
  }
}
```

If the call is successful, the function will return a `Book` type describing a book. If the call fails, the function will return a `string`. `getBook()` can return a `Book` or `string` type, TypeScript infers the return type as the union `Book | string`. Since TypeScript can infer the function's return type, there's no need for us to manually define it.
