DEV Community: Cameron McHenry

The Difference Between TypeScript Unions, Enums, and Objects

Cameron McHenry — Sun, 01 May 2022 17:42:07 +0000

This article was originally posted on my blog: https://camchenry.com/blog/typescript-union-vs-enum-vs-object.

When you first encounter unions and enums in TypeScript, you might wonder what the difference is between them. At first glance, they are very similar, but in fact they are quite different. The situation becomes even more complicated when we consider "constant objects" which are essentially another way to implement an enumeration.

In this article we'll look at their similarities and differences, and when you might want to use each of them.

What are TypeScript unions?

I've already written a comprehensive article on everything you need to know about union types. In short, union types are a way of modeling a discrete set of mutually exclusive types, or more simply put: unions model choices, where only one choice can be made.

Union types are great because choices are everywhere in the real world, so they are a powerful tool to allow TypeScript to programmatically reason about all possibilities that could result from different decisions.

This means that our code will be safer automatically because TypeScript does all of the hard work of checking every possibility for us.

What are TypeScript enums?

Enums, short for enumerations, are a more traditional programming language feature in imperative languages like C/C++ and Java. Their purpose is similar to union types, except they act on a much more basic principle.

Enums give values (strings and numbers) a human-readable name that can be referenced easily in code via the name for the enumeration.

Enums were added to TypeScript in anticipation of them becoming a standard JavaScript feature, however that currently seems unlikely based on the 4 year old TC39 enum proposal still being stuck at Stage 0.

TypeScript enum example

To make this more clear, let's look at a simple example of an enum. Suppose that we are building an application that models the days of the week as numbers (0 through 6). Instead of needing to remember what the number for each day of the week is, we can create an enum that stores that information:

enum DayOfWeek {
  Monday = 0,
  Tuesday = 1,
  Wednesday = 2,
  Thursday = 3,
  Friday = 4,
  Saturday = 5,
  Sunday = 6,
}

Now, instead of needing to type the numbers each time, we can use the enum instead:

function isWeekend(day: DayOfWeek) {
  return day === DayOfWeek.Saturday || day === DayOfWeek.Sunday;
}

Using enums in this case makes our code easier to read and prevents simple typos.

Constant enums

It is also possible to define an enum as a const enum similar to the constant objects which we will talk about in this article. However, using const enums comes with some pitfalls/caveats which make them slightly more difficult to use in some cases. They don't offer a significant advantage over constant objects, so we won't discuss them in more detail here, but check out the TypeScript documentation on const enums for more info.

What are TypeScript constant objects?

A constant object is no different from any other object in JavaScript, but when defined as const in TypeScript, it becomes a much stricter type. To create a constant object, we simply define an object and then add as const to make it a constant object.

Making it constant makes it act similar to enum, and it can be used in almost the same way. Let's look at the previous enum example, but now using an object with as const:

const DayOfWeek = {
  Monday: 0,
  Tuesday: 1,
  Wednesday: 2,
  Thursday: 3,
  Friday: 4,
  Saturday: 5,
  Sunday: 6,
} as const;

Using as const makes all of the properties readonly, so the values are not allowed to be changed in the type system. So, all of the keys and values are guaranteed to never change as long as we abide by the type system, just like an enum.

Now that we are a little bit familiar with unions, enums, and constant objects, let's compare them with each other and see how they stack up.

Comparison between unions, enums, and constant objects

To help you decide whether to use a union, enum, or object, I've created a table that summarizes the key similarities and differences:

Feature	Unions	Enums	Constant objects
Strictly typed	✅ Yes	✅ Yes	🟡 Partial¹
Available at compile-time	✅ Yes	✅ Yes	✅ Yes
Available at run-time	❌ No	✅ Yes	✅ Yes
Named values	🟡 Partial²	✅ Yes	✅ Yes
Unique values	✅ Yes	❌ No	❌ No
Sub-typing	✅ Yes	🟡 Partial³	🟡 Partial³
Mixed types	✅ Yes	🟡 Partial⁴	✅ Yes
Computed values	🟡 Partial⁵	❌ No	✅ Yes
Reverse mappings	❌ No	✅ Yes	❌ No

1) Constant objects cannot be used directly as types, but it is simple to create a type of the key values:

   type Key = keyof typeof ConstantObject;

2) Unions can emulate named values when the values are strings, by making the value the same as the name. For example:

   enum Dimension {
     X = "x",
     Y = "y",
     Z = "z",
   }

   // can be written as:
   type Dimension = "x" | "y" | "z";

3) Only keys can be easily derived, the values are not possible to subtype.
4) Enums do not support mixed types within each state other than strings and numbers, such as objects, booleans, etc. (For example: you cannot use an enum to refer to an object value, even if it is constant.)
5) Unions allow strings to be interpolated into them, but the interpolation will be interpreted as a template literal type. If the interpolated value is a union, multiple possibilities will be generated. If the interpolated value is a string, only one possibility will be generated.

Unions, enums, and constant objects all support type safety

Regardless of which language feature you choose, the one thing they share in common is static type safety. We can create additional types that derive from a union, enum, or object. This helps us lean into leveraging the full power of the TypeScript compiler and make our code safer and reduce the amount of work a developer needs to do.

Another advantage of using these features over a more generic type like string is that the number of possible values is much lower and is enforced by the compiler. Rather than allowing all strings or all numbers, we can reduce it to just a few strings or a few numbers.

The TypeScript compiler ensures that we cannot make any spelling mistakes in values because all of the possibilities are known. Using string or number does not provide the same guarantees. So, unions and enums help make the code safer by automatically preventing simple typing mistakes.

What's similar between enums and constant objects

Enums are constant objects are very similar, and so they are many properties in common:

⭐️ Run-time usable: Enums and objects can be used while the program is running (for example, to build a selection menu UI)
Named values: Both can give given names or aliases to specific values.
No uniqueness: Both do not enforce uniqueness of values. There may be duplicate values.
Partial sub-typing: Both only support sub-typing on the keys, not the values.

Both: named values

Another unique advantage of enums and objects is that keys and values can be named independently. This is great for improving the readability of code, essentially creating two sets: human-readable names, and machine-readable values.

This is good if you don't control the values, but want to give them understandable names. For example, using an enum or object to identify pin numbers for microchips:

enum Pin {
  Power = 0,
  LED0 = 4,
  LED1 = 5,
  Button1 = 8,
  Button2 = 3,
  Ground = 1,
}

const Pin = {
  Power: 0,
  LED0: 4,
  LED1: 5,
  Button1: 8,
  Button2: 3,
  Ground: 1,
} as const;

This is one of the advantages of using an enum or object instead of a union type, because union types cannot be referred to by name, only by their value.

Both: run-time usability

The biggest advantage of using an enum is that they exist even after code is compiled, while the program is running. This is because enums are ultimately generated as normal JavaScript objects.

This can be helpful when it is necessary to have the benefits of type safety and compile time, while also remembering the set of values while the program is running.

Union types cannot be used as values, and cannot be used in executable code:

type Color = "Red" | "Green" | "Blue";

// Note: `Color` does not exist at run-time, so we
// cannot do something like this:
console.log(Object.values(Color));
//                        ^^^^^ ERROR: 'Color' only refers
// to a type, but is being used as a value here

On the other hand, an enum is essentially an alias for a JavaScript object. It is both a type and a value at the same time, similar to how a class can act as both a type and an actual value in JavaScript.

enum Color {
  Red,
  Green,
  Blue,
}
// Or:
const Color = {
  Red: "Red",
  Green: "Green",
  Blue: "Blue",
} as const;

// Note: `Color` _does_ exist as an actual value at run-time,
// so we can use it just like any object:
console.log(Object.values(Color));
// => ["Red", "Green", "Blue"]

Advantages of union types

There are several advantages to using union types in TypeScript:

Unique values: Unions automatically simplify values to be unique
⭐️ Mixed types: Unions can represent more kinds of types like objects, arrays, booleans, and so on.
Sub-typing: Unions support creating subtypes easily
Computed types: Unions have partial support for dynamic values, limited to the possibilities of template literal types.

Union advantage: unique values

Unlike enums, values in a union represent a set, which is a collection of unique values. So, if any values are repeated, then they will only appear once in the resulting type. For example, type N = 1 | 2 | 3 | 1 | 2 | 3 simplifies to just N = 1 | 2 | 3.

Union advantage: mixed types

One of the most important properties of unions is that they can contain all different kinds of types, not just strings and numbers. For example, this is a perfectly valid union which would be impossible to represent with an enum:

type SomeUnionOfTypes =
  | "this is a string" // string
  | 1234 // number
  | { this_is: "an object" } // object
  | Array<unknown>; // array (object)
  | true; // boolean

Using many different kinds of types brings some challenges, such as how to differentiate between them. To learn more on how to differentiate between types in a union, check out my complete guide on TypeScript type guards.

Union advantage: sub-typing

Another great benefit of union types is that they can be easily transformed into other types. For example, we can use union types to generate a large set of possible values:

type Direction = "top" | "right" | "left" | "bottom";
type Property = "margin" | "padding";

type Properties = `${Property}-${Direction}`;
// => "margin-top" | "margin-right" | "margin-left"
//  | "margin-bottom" | "padding-top" | "padding-right"
//  | "padding-left" | "padding-bottom"

Or values can be narrowed down to just a subset:

type Direction = "top" | "right" | "left" | "bottom";

type VerticalDirection = Pick<Direction, "top" | "bottom">;
type HorizontalDirection = Omit<Direction, VerticalDirection>;

Union advantage: computed types

Neither enums nor unions have full support for dynamic values, but unions do have some partial support for dynamic value in the form of template literal types. Values can be interpolated in to a union, like so:

type Color = "red" | "green" | "blue";
type ColorDeclaration = `color: ${Color};`;
// => "color: red;" | "color: green;" | "color: blue;"

To some degree, types can be interpolated in even if they are dynamic also, but little inference is possible, so type safety is somewhat limited:

type NamedValue = "red" | "green" | "blue";
type Value = string | NamedValue;
type Declaration = `color: ${Value};`;
// => `color: ${string};`;

Using the dynamic input eliminates the previous type safety that was given by knowing all of the possible values. On the other hand, this does allow us to represent dynamic values to at least some degree.

Enums do not support computed values or computed keys, so this is a uniquely union type advantage.

Unique advantage of enums: reverse mapping

The main advantage that enums have over unions and constant objects is that the values are automatically mapped to their names, as well as the reverse: names can be mapped to values. This can be useful when it is necessary to often go between the names and values often. For example, let's use the Pin enum from before:

enum Pin {
  Power = 0,
  LED0 = 4,
  LED1 = 5,
  Button1 = 8,
  Button2 = 3,
  Ground = 1,
}

We can easily answer two questions with the enum:

What is the purpose of pin 0?

  const purpose: string = Pin[0]; // => "Power"

What pin number corresponds to Ground?

  const ground: number = Pin.Ground; // => 1

However, two things diminish the usefulness of this:

This feature can be replicated with objects when it is needed.
If we don't need the reverse mapping, this results in useless code being generated. This can bloat the JavaScript bundle size significantly depending on how many enums are used in a project.

Unique advantage of constant objects: computed values

One unique advantage of constant objects that can be helpful in some circumstances is that it is possible to used computed values as keys or values. For example, suppose we have an object which resolves theme values for whether we should show a light or dark-mode color scheme. In addition to the base keys and values, we can also create other dynamically computed values:

const defaultColorScheme: string = "light";
const lightAlias: string = "day";
const darkAlias: string = "night";

const ColorScheme = {
  default: defaultColorScheme,
  light: "light",
  dark: "dark",
  [lightAlias]: "light",
  [darkAlias]: "dark",
} as const;

We still retain the type safety of saying ColorScheme.light or ColorScheme.dark but can also use it in dynamic circumstances to find ColorScheme.default or ColorScheme[usedSpecifiedTheme].

This is the type that TypeScript ultimately resolves for this object:

const ColorScheme: {
  readonly [x: string]: string;
  readonly default: string;
  readonly light: "light";
  readonly dark: "dark";
};

It's not perfect, but at least it is possible to use computed values if necessary.

What type should I use?

We've looked at a lot of examples and caveats of unions, enums, and objects. So, let's wrap things up by looking at a subjective opinion of what type I recommend you should use depending on the circumstances.

If you just want a quick summary:

Use union types as a default
Use constant objects for run-time purposes
Avoid using enum if possible

When should you use a union in TypeScript

As a general guide, union types might be a good choice to use if many of the following apply:

You have a known set of possible values
The values are self-descriptive
All of the values must be unique
The values are only needed at compile-time (i.e., not used in the output)

When should you use a constant object in TypeScript

Constant objects could be a good choice if several of the following apply to the situation:

You have a known set of possible values
The values don't correspond to their name
The values are used in the output (for example, a selection menu or printed to the screen)
The keys or values can be dynamic

When should you use an enum in TypeScript: probably never

Besides automatically doing reverse mapping (which can actually be a disadvantage), there are not enough benefits to justify using an enum over a constant object. Using a constant object over an enum will result in a smaller bundle size, and more flexibility with being able to use dynamic values and interoperate with standard JavaScript syntax.

Enums were added to TypeScript in anticipation of them becoming a standard JavaScript feature, however it seems extremely unlikely that will happen anytime soon, or ever (see: TC39 proposal). As such, they have not seen many language improvements in the last few years.

Conclusion

Hopefully this guide helped clear up the confusion between enums and unions, and made the advantages and disadvantages between enums, unions, and constant objects clear. However, enums are somewhat lackluster when compared to the other two, and probably should not be used in most cases. On the other hand, unions and constant objects work together very well and can be used together, or independently, in a broad set of situations to implement mutual exclusivity in TypeScript programs.

Good luck and happy coding!

How Serverless Saved Money on My Heating Bill

Cameron McHenry — Wed, 05 Jan 2022 15:00:11 +0000

This post was originally published on my blog.

Currently, it's winter in the Northeastern United States, where I live. That means it gets uncomfortably cold outside. That means one big thing for everyone living here: figuring out how to keep our homes warm without literally burning money.

Where I live, the only viable heating option right now is burning propane.

Unfortunately, propane is more expensive now in the US than it has been at any time in the past 5 years.¹

Naturally, this meant that I wanted to save some money on my heating bill this year, if possible. The only way to do that is to reduce the amount of propane I burned by reducing the amount of heat I need to produce.

The problem is that I can't measure how much heat I need to produce, I can only measure how much propane I have used. The company that supplies propane to us provides a dashboard where I can check how much propane is in the tank.

Sadly, the dashboard only shows the current level of propane in the tank, but doesn't show the propane used per day, or any sort of historical data.

It's hard to improve what isn't measured.

So, to know whether more insulation or other efficiency improvements are actually saving money, I needed to start tracking the data.

The Solution

When faced with a problem, I did what any software engineer would do: build a full-stack web application deployed to the edge using the hottest JavaScript framework.

The idea was to build a web application to periodically scrape the current level of propane in the tank, then store that in a database, and use the stored information to compute consumption rate and display historical data.

That meant I needed to pick:

a scraping tool (for fetching the current gas level)
a database (for storing the data)
a framework (for interacting with the database and rendering pages)
a host (for hosting the whole application)

So, I decided to use:

Scraping: Browserless
Database: Supabase
Web framework: Remix
Hosting: Fly.io

Here is a diagram that shows the architecture of the application:

Architecture diagram of the gas tracking application, which shows how Remix coordinates rendering pages for our client, receiving fetch requests, scraping webpages, and updating the database.

Scraping tool: Browserless

For the scraping tool, I chose to use Browserless which I wanted to try in a real-world scenario. It's essentially Puppeteer-as-a-Service, so you don't need to worry about installing Chromium or anything. Just install the puppeteer library, connect to Browserless, and start scraping.

It includes 20,000 CPU seconds for free, beyond which you have to start paying, but the free allotment of CPU time was more than enough for this project.

Database: Supabase

I chose to use Supabase as my database, because I wanted to use PostgreSQL as the database since I like schemas and everything that SQL affords. However, I didn't want the bother of hosting the database myself, getting it set up, maintaining it, and so on.

I just wanted to get a database running as quickly as possible so I could build my application. Supabase was perfect for that.

Framework: Remix

I was an early supporter of Remix, because I think it's a great framework that has the potential to dramatically change the face of JavaScript web development. It lets you have fast server-rendered web pages without having to give up building an awesome user interface with JavaScript. There's a lot to say about it, but I'll leave that for another time.

Suffice to say, this project probably wouldn't be possible without Remix.

Remix lets me build a true full-stack JavaScript application quickly and easily without having to give up the benefits of a complex client-side application, or the benefits of a server, such as querying a database, implementing authentication, and so on.

These things are possible with other frameworks, but there are more limitations to where it can be deployed and what sorts of libraries can be imported, and how they can be used.

For this project, Remix will orchestrate rendering the pages with React, scraping the latest data on a POST request, and fetching historical data from Supabase.

Host: Fly.io

In the spirit of trying another new service, I chose to use Fly.io as my hosting provider. It's been a great experience so far, and the underlying technology is impressive, allowing for a secure, efficient, and fast serverless environment. This allows it to be deployed all over the world, close to where your users lives so your web application is faster.

Remix also comes with a Fly.io deployment template, which means you can deploy your application anywhere in the world in just a few minutes after creating your application.

The Result

Putting all of these serverless services together, I was able to build my gas-tracking application over a weekend (while on a bus!) and deploy it for my own personal use.

The dashboard for the gas tracking application, which helps me gauge how much heat is being used and how effectively different house work affects our heating bill.

So far, using this application, I've been able to realize hundreds of dollars in savings on our heating bill and accurately measure how much propane is used.

Something I didn't expect is that this project cost me nothing at all, except for the time it took to develop it. The framework is free. All of the libraries I used are open source and free. The application hosting on Fly.io is free, and I got a free randomly generated fly.dev domain name with HTTPS. Even the database and scraping tool are free for the amount that I use them.

Take-away

Hopefully you have figured out by now that this article isn't really about how to save money on your heating bill.

This is an article about how building a serverless application is easier and better than ever in 2022.

Edge-focused web frameworks like Remix make it easy to build full-stack web applications that can be deployed to hosts like Fly.io and run anywhere in the world for free. In addition, services like Supabase make it easy to build a production-ready application in a short amount of time.

Now is a better time than ever to start building a website.

While there's absolutely a learning curve to getting started, once you've got momentum, modern web development feels like having rocket boosters. The distance between idea and execution is as short as it's ever been.
— Simeon Griggs, There has never been a better time to build a website

Even compared to a few years ago, there are far more capabilities available today to developers and at a substantially lower cost.

You don't need a dedicated server. You don't need a domain name. You don't need to be an expert. You don't even have to write code!

Right now is a great time to be a web developer. So let's get out there, lift each other up, and build great things!

A rising tide lifts all boats

Source for propane price: https://ycharts.com/indicators/us_residential_propane_price. ↩

Everything You Need To Know About TypeScript Union Types

Cameron McHenry — Mon, 29 Nov 2021 05:22:39 +0000

This was originally posted on my blog. If you enjoy posts like this, consider following me at @cammchenry!

Programming in TypeScript is all about creating models that help us to write safe code. Among those models, union types are one of the most useful, because they allow us to model mutually exclusive states like: low, medium, or high, one or none, on or off, and so on. In this article, I'll teach you what a union type is, when to use it, and tips on how to use it effectively.

What is a union type in TypeScript?

A union type (or "union" or "disjunction") is a set of types that are mutually exclusive. The type represents all of the possible types simultaneously. A union type is created with the union operator |, by listing out each type and separating them with a pipe character.

type Union = "A" | "B" | "C";

The union type provides more information to the TypeScript compiler that allows it to prove code is safe for all possible situations, which is a powerful tool. We may not know whether the user will pass a string, number, or object (for example) to a function, but we can guarantee that every case is handled without needing to write any unit tests to check that.

When should you use a union type?

Union types are a perfect fit for a situation where we know exactly what all of the possible states are, but we don't know when we compile the program which one will be used. For example, we could use union types to store:

days of the week,
color palettes,
columns of a database table
DOM event names,
finite state machine states

As a counterexample, something like a person's name is not a good fit for a union type, because there are essentially an infinite (or very large) number of possible states.

Examples of union types

In the DOM, we can only store strings for values, or numbers as strings. So, the only acceptable types for a DOM value are essentially a string or a number. (This is exactly the definition of the ReactText type).

// Acceptable DOM values
type Value = string | number;

Similarly, DOM events are always happen independently of each other (events are processed one at a time). So, there is a finite list of possible events that can be processed:

type Event = MouseEvent | KeyboardEvent; /* and so on */

We can also use a union type to represent a subset of primitive types like string or number.

For example, we could write some business logic functions that only accept days of the week:

type DayOfWeek =
  | "Monday"
  | "Tuesday"
  | "Wednesday"
  | "Thursday"
  | "Friday"
  | "Saturday"
  | "Sunday";

function isBusinessDay(day: DayOfWeek): boolean {
  return day !== "Saturday" && day !== "Sunday";
}

isBusinessDay("Monday"); // => true
isBusinessDay("Saturday"); // => false
isBusinessDay("Whensday");
//             ^^^^^^^^ ERROR: Argument of type '"Whensday"'
// is not assignable to parameter of type 'DayOfWeek'

If every type in the union is the same, then we can use functions and operators as expected on those types.

type NumberOfColumns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;

function getColumnWidth(totalWidth: number, columns: NumberOfColumns) {
  return `${(totalWidth / columns).toFixed(2)}px`;
}

getColumnWidth(1920, 6); // => "320.00px"
getColumnWidth(1920, 16);
//                   ^^ ERROR: Argument of type '16' is not
// assignable to parameter of type 'NumberOfColumns'

If the types are different (which is most of the time), then we cannot simply call functions on them or use arithmetic operators. We need to differentiate between the types in the union.

How to tell which type is currently in use

Of course, it's great that we can model mutually exclusive states with union types, but how do we actually use them? What if every type is not the same? How do we make sense of a union and figure out which specific case we have?

We can differentiate between types in a union with a type guard. A type guard is a conditional check that allows us to differentiate between types. And in this case, a type guard lets us figure out exactly which type we have within the union.

There are multiple ways to do this, and it largely depends on what types are contained within the union. I cover this topic in much more detail here on my post about type guards.

However, there is a shortcut to making differentiating between types in a union easy.

Enter discriminated unions.

What is a discriminated union?

A discriminated union (also called "distinguished union" or "tagged union") is a special case of a union type that allows us to easily differentiate between the types within it.

This is accomplished by adding a field to each type that has a unique value, which can be used to differentiate between the types using an equality type guard.

For example, if we had a type which represented all possible events that could occur, we could give each event a unique name. Then, we just need to check the event name to know exactly what type/case we are handling.

type AppEvent =
  | { kind: "click"; x: number; y: number }
  | { kind: "keypress"; key: string; code: number }
  | { kind: "focus"; element: HTMLElement };

function handleEvent(event: AppEvent) {
  switch (event.kind) {
    case "click":
      // We know it is a mouse click, so we can access `x` and `y` now
      console.log(`Mouse clicked at (${event.x}, ${event.y})`);
      break;
    case "keypress":
      // We know it is a key press, so we can access `key` and `code` now
      console.log(`Key pressed: (key=${event.key}, code=${event.code})`);
      break;
    case "focus":
      // We know it is a focus event, so we can access `element`
      console.log(`Focused element: ${event.element.tagName}`);
      break;
  }
}

In this example, the advantage is that we can have completely disparate types in our union, and easily handle each case with just a single if check. This lends itself well to extension, because we can easily add new events and new cases to our application and lean on TypeScript to ensure that we don't forget to handle them.

How to get a single type from a union type

Sometimes, we want to deal with just a single type from union type, or a subset of the types. Thankfully, TypeScript provides a built-in utility type called Extract to extract a single type from a union type.

Using the DayOfWeek type from before, we can extract individual days from the type:

type DayOfWeek =
  | "Monday"
  | "Tuesday"
  | "Wednesday"
  | "Thursday"
  | "Friday"
  | "Saturday"
  | "Sunday";

type BusinessDay = Extract<
  DayOfWeek,
  "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday"
>;
// => "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday"
type Weekend = Extract<DayOfWeek, "Saturday" | "Sunday">;
// => "Saturday" | "Sunday"

This might seem redundant, but the advantage is that we are deriving types based on our DayOfWeek type. So, if the base type ever changes, we can be sure that all of our types are still valid.

But, Extract is more powerful than just extracting a single type. It can extract all assignable types from a union type.

// Type for a configuration value that can be defined in multiple ways:
// either as a single value (string or number), array of values, or an object.
type Value = string | number;
type Config = Value | Array<Value> | Record<string, Value>;

// Only config values that are assignable to objects will have this type
type Objects = Extract<Config, object>;
// => Value[] | Record<string, Value>

How to get a subset of a union type

We saw that Extract can be used to a subset of a union type, but only for a few specific types. When we want to extract most types, we can use the complement of Extract type, which is Exclude.

In TypeScript, we can use the Exclude type to get all types from a union type, except for those that are assignable to another union.

For example, let's redefine our types derived from DayOfWeek to use Exclude instead:

type BusinessDay = Exclude<DayOfWeek, "Saturday" | "Sunday">;
// => "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday"
type Weekend = Exclude<
  DayOfWeek,
  "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday"
>;
// => "Saturday" | "Sunday"

These types are exactly the same as the ones we defined before, but we defined them using Exclude instead of Extract.

When to use `Extract` or `Exclude`

For the most part, Extract and Exclude are interchangeable, they are just complements of each other. So the general rule for when to use them is:

Use Extract when you only need to extract a few types from a union type
Use Exclude when you need to extract most types from a union type

Both of these types become even more powerful when we leverage each of their respective strengths. For example, we can redefine our day of the week types to use Extract and Exclude in combination:

type Weekend = Extract<DayOfWeek, "Saturday" | "Sunday">;
// => "Saturday" | "Sunday"

type BusinessDay = Exclude<DayOfWeek, Weekend>;
// => "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday"

This version is both much shorter (so it is easier to read) and it also better conveys the meaning and intention behind the types.

When should you not use a union type?

Although union types are an excellent modeling tool, there are legitimate reasons to not use them:

When the types are known at compile-time, we can use generics instead to provide further type safety and flexibility. If the types are known ahead of time, then there is no need to use a union type.
When we need to enumerate all possibilities at run-time (use an enum instead for this). For example, if we wanted to iterate over all of the days of the week and construct an array, we would need to use an enum, because union types are a TypeScript-only feature, so it is compiled away when compiling to JavaScript.

What is the difference between an `enum` and a union type?

At first, an enum and a union appear to be almost the same, so what's the difference? The two main differences between an enum and unions are:

A union type exists only at compile-time, an enum exists at compile-time and run-time.
A union type is an enumeration of any kind of type, an enum is an enumeration of only strings or numbers.

Of these differences, the one that has the most important practical implications is that unions only exist in TypeScript's type system, while an enum actually exists as an object in JavaScript. Unions are a convenient way to model many types, but they do not actually affect the program's execution in any way. So, when we compile TypeScript to JavaScript, the union type will disappear from the code.

type Color = "Red" | "Green" | "Blue";

// Note: `Color` does not exist at run-time, so we
// cannot do something like this:
console.log(Object.values(Color));
//                        ^^^^^ ERROR: 'Color' only refers
// to a type, but is being used as a value here

enum Color {
  Red,
  Green,
  Blue,
}

// Note: `Color` _does_ exist as an actual value at run-time,
// so we can use it just like any object:
console.log(Object.values(Color));
// => ["Red", "Green", "Blue"]

So, if it is necessary to be able to iterate over all the possible values and use the values in our program, then an enum might be a better choice instead.

Conclusion

Union types are a fantastic feature of TypeScript. They are an ergonomic way to model a finite number of mutually exclusive cases, and allow new cases to be added without breaking any existing code. However, union types do not exist at compile-time, so any programs that need access to the enumerated values should probably use an enum instead.

If you're interested in learning more about union types and the theory behind them, check out these additional resources:

If this post helped you understand union types better, consider sending me a message to me (@cammchenry) and let me know what you thought. Happy coding!

How To Do Anything in TypeScript With Type Guards

Cameron McHenry — Wed, 03 Nov 2021 16:52:19 +0000

This article was originally published on my blog: camchenry.com. If you enjoy this article, please consider joining my mailing list for more content like this one.

TypeScript is valuable because it enables us to write safe code. Because when every type in the code is known at compile time, we can compile the code with TypeScript and perform type checking, which ensures that the code will not crash or cause errors.

However, it is not always possible to know every type at compile time, such as when accepting arbitrary data from an external API. To check types at run-time or differentiate between different types, we to need narrow the types using a type guard.

What is narrowing?

In TypeScript, narrowing is the process of refining broad types into more narrow types. Narrowing is useful because it allows code to be liberal in the types that it accepts. Then, we can use type guards to narrow the type down to something more useful.

These are some common examples of narrowing:

unknown or any to string
string | object | number to string
number | null | undefined to number
string to a custom type like NonEmptyString

What is a type guard?

A type guard is a kind of conditional check that narrows a type. Type guards allow for run-time type checking by using expressions to see if a value is of a certain type or not.

So, what does a type guard look like? These are all examples of type guards:

typeof value === 'string'
'name' in data
value instanceof MouseEvent
!value

A type guard is a special kind of expression that changes the type of a variable. We will look at more examples of type guards in practice later.

The kinds of type guards (how to check a type)

Most type guards revolve around regular JavaScript operators, which are given extra abilities in TypeScript that make it possible to narrow types by writing typical JavaScript code. So, it is possible that you've used a type guard before without even realizing it!

Fundamentally, every type guard relies on checking that some expression evaluates to true or false.

As a result, the first kind of type guard which we will look at is a simple truthiness check. But we can utilize more complex type guards like in, typeof, and instanceof that tell us much more information.

In addition to all of these built-in type guards, we can can go even further and create our own custom type guards that can check any type.

Boolean type guard (truthiness)

As stated previously, checking the truthiness of a value is the essence of all type guards.

However, a boolean type guard only checks the truthiness of a value, but gives us no additional information beyond that. Other more complex type guards can check more complex types or verify more properties, but the boolean type guard is the most basic type guard.

function getAvailableRooms(rooms: number | undefined) {
  if (rooms) {
    return `There are ${rooms} hotel rooms available to book.`;
  }
  return "Sorry, all rooms are currently booked.";
}

getAvailableRooms(undefined); // "Sorry, all rooms are currently booked."
getAvailableRooms(5); // "There are 5 hotel rooms available to book."

When using a boolean type guard, the value is implicitly casted to a boolean. This has a logical interpretation most of the time, but not always.

For example, if use a boolean type guard to check a type of number | undefined, we might expect that it will only exclude the undefined case. However, it will also rule out the case where the value is 0, which might not be what you expect in some cases. For more information on this common bug, check out Kent C. Dodd's article, "Use ternaries rather than && in JSX."

Equality type guard

In the boolean type guard, we checked the truthiness of an expression. In an equality type guard, we check the value of an expression.

This kind of type guard is useful when we know all of the possible values of a type. For example, if we have an enumeration of string or number values, or if we want to know that a value is not null or undefined.

Here is an example where we use an equality type guard to remove undefined from the type of a variable:

function getGreeting(timeOfDay?: "morning" | "afternoon") {
  if (timeOfDay === undefined) {
    return `Hello!`;
  }
  // Now the type of `timeOfDay` is narrowed to `morning` | `afternoon`,
  // so we can use string methods on it safely.
  return `Good ${timeOfDay[0].toUpperCase()}${timeOfDay.slice(1)}!`;
}

getGreeting(); // "Hello!"
getGreeting("afternoon"); // "Good Afternoon!"
getGreeting("morning"); // "Good Morning!"

We can also use a switch block to accomplish exactly the same thing:

function getGreeting(timeOfDay?: "morning" | "afternoon") {
  switch (timeOfDay) {
    case "afternoon":
    case "morning":
      return `Good ${timeOfDay[0].toUpperCase()}${timeOfDay.slice(1)}!`;
    default:
      return `Hello!`;
  }
}

Using a switch block like this might be preferable if you have a lot of possible values to check and which might share the same code.

Discriminated unions deserve their own article, but they are essentially a more powerful version of the equality type guard.

A discriminated union is a type that has multiple possible types, with a field that allows to us to discriminate (or differentiate) between them. In other words, when we check the value of a single field (like type), it automatically includes a number of other properties.

`typeof` type guard

In contrast to the previous example, where we checked the value of a variable (or expression), with a typeof type guard, we check the type of a variable.

When there is a value which has several possible types, like string | number, we can use typeof to figure out which type it is.

For example, we can use typeof to write a comparison function that compares two values to each other and returns the difference:

function compare(a: number | string, b: number | string): number {
  if (typeof a === "number" && typeof b === "number") {
    // Both a and b are numbers, so we can compare them directly.
    return a - b;
  }
  if (typeof a === "string" && typeof b === "string") {
    // We can use string methods on `a` and `b` safely.
    return a.localeCompare(b);
  }
  throw new Error(
    `Cannot compare unrelated types '${typeof a}' and '${typeof b}'`
  );
}

compare("a", "b"); // => -1
compare("b", "a"); // => 1
compare(123, 321); // => -198

The biggest limitation of the typeof guard is that it can only differentiate between types that JavaScript recognizes. The types that typeof can check are:

boolean
string
number
bigint
object
symbol
function
undefined

`instanceof` type guard

When we have a variable that is an instance of a class, we can use instanceof to check whether if the variable has that type or not.

For example, the DOM APIs define many classes and subclasses which can be quickly checked using instanceof:

function handleEvent(event: Event) {
  if (event instanceof MouseEvent) {
    // `event` now has type `MouseEvent`, so we can access mouse-specific properties
    console.log(`A mouse event occurred at (${event.x}, ${event.y}`);
  }
  if (event instanceof KeyboardEvent) {
    // `event` now has type `KeyboardEvent`, so we can access key-specific properties
    console.log(`A keyboard event occurred: ${event.key} ${event.}`);
  }
  console.log("An event occurred: ", event.type);
}

This is useful when dealing with potentially generic DOM objects, because a single instanceof check grants access to all of the properties and methods of the class.

This can also be used to differentiate between common objects in JavaScript, like Map, Date, Array, or Set. For example, we can create a function to create a lookup table which accepts many possible inputs:

// Creates a Map which returns some value given a string key
// (ignoring the fact that the Map constructor already accepts some of these)
function createLookupTable<Value>(
  db: [string, Value][] | Map<string, Value> | Record<string, Value>
): Map<string, Value> {
  // `db` has type `[string, Value][] | Map<string, Value> | Record<string, Value>`
  if (db instanceof Array) {
    // `db` now has type `[string, Value][]`
    return new Map(db);
  }
  // `db` has type `Map<string, Value> | Record<string, Value>`
  if (db instanceof Map) {
    // `db` now has type `Map<string, Value>`
    return db;
  }
  // `db` has type `Record<string, Value>`
  return new Map(Object.entries(db));
}

createLookupTable([
  ["hat", 14.99],
  ["shirt", 24.95],
]);
// => Map (2) {"hat" => 14.99, "shirt" => 24.95}

createLookupTable(
  new Map([
    ["hat", 14.99],
    ["shirt", 24.95],
  ])
);
// => Map (2) {"hat" => 14.99, "shirt" => 24.95}

createLookupTable({ hat: 14.99, shirt: 24.95 });
// => Map (2) {"hat" => 14.99, "shirt" => 24.95}

Here is another example using instanceof to check if a type is a Date or a string and decide whether to construct a new Date object or not:

function getDate(value: string | Date): Date {
  if (value instanceof Date) {
    return value;
  }
  return new Date(value);
}

getDate("2021-05-06 03:25:00");
// => Date: "2021-05-06T07:25:00.000Z"
getDate(new Date("2021-05-06 03:25:00"));
// => Date: "2021-05-06T07:25:00.000Z"

`in` type guard

The in type guard allows us to differentiate between multiple types by checking if an object has a specific property. In JavaScript, the in operator, like all type guards, returns a boolean value that indicates if the object has the property or not. For example,

"data" in { name: "test", data: { color: "blue" } }; // => true
"data" in { name: "test", data: undefined }; // => true
"data" in { name: "test" }; // => false

In this way, we can use in to differentiate objects that have different sets of properties. For example, we can use it to differentiate between different types of classes (in this case, events):

function handleEvent(event: MouseEvent | KeyboardEvent) {
  if ("key" in event) {
    // event now has type `KeyboardEvent`
    console.log(`A keyboard event occurred: ${event.key}`);
  } else {
    // event now has type `MouseEvent`
    console.log(`A mouse event occurred: ${event.button}`);
  }
}

The important thing here is that key is only defined for KeyboardEvent, but not for MouseEvent. If the property we check exists in multiple cases, the narrowing will not work. For example, the following code will not work:

type EventInput =
  | { type: "mouse"; button: string }
  | { type: "key"; key: string };

function handleEventInput(event: EventInput) {
  // This type guard will NOT work:
  if ("type" in event) {
    // event still has type `EventInput`, so the type guard does not
    // do any narrowing in this case
  }
}

Though not always related to its use for narrowing types, the in operator is also often used to check for browser support of certain features.

For example, the guard 'serviceWorker' in navigator checks whether the browser supports service workers.

Assertion type guard (or assertion function)

In TypeScript 3.7, TypeScript added support for assertion functions. An assertion function is a function that assumes a condition is always true, and throws an error when it does not.

To create an assertion function, we need to add something called an "assertion signature," which is a formal declaration of what the function will assert. The assertion signature is additional information about a function (like a return type) that lets the TypeScript compiler narrow the type.

Let's look at an example:

function assertString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`Expected 'string', got: '${typeof value}'`);
  }
}

const x = "123";
assertString(x);
// x now has type 'string', so it is safe to use string methods
x.toLowerCase();

Previously, we discussed how all type guards are based around a boolean check. That is still true in this case, but the actual usage is slightly different from other type guards.

With other type guards, we typically used something like if or switch to create different branches of execution. With an assertion function, the two branches are: continue as normal, or stop the script (throw an error).

Other than the difference of how an assertion type guard can throw an exception, assertion type guards are similar to other type guards. However, something that we must be careful about is accidentally creating a type guard which asserts the wrong condition.

This is one way that we can end up with a false sense of safety. Here is an example where the function asserts something, but the actual code asserts nothing.

function assertString(value: unknown): asserts value is string {
  // This check does not match the assertion signature
  if (typeof value === "boolean") {
    throw new TypeError();
  }
}

const x: unknown = 123;
assertString(x);
// We get a run-time exception here (!!!), which TypeScript should
// be able to prevent under normal circumstances:
x.toLowerCase();
// "TypeError: x.toLowerCase is not a function"

User-defined (custom) type guard

Most type guards have limitations to what they can check, such as only primitive types for typeof, or only classes for instanceof. But with user-defined type guards, there are no limitations on what we can check.

Custom type guards are the most powerful kind of type guard, because we can verify any type, including ones that we defined ourselves, as well as built-in types from JavaScript or the DOM. The main downside of custom type guards is that they are not predefined, so we have to write them ourselves.

There are a few built-in custom type guards though, such as Array.isArray:

const data: unknown = ["a", "b", 123, false];
if (Array.isArray(data)) {
  // data now has type "array", so it is safe to use array methods
  data.sort();
}

In the next section, we will look at all of the different ways that we can define our own type guard functions.

Type guard functions

A type guard function is a function that returns a value and has a type predicate.

A type predicate is an additional declaration that is added to a function (like a return type) which gives additional information to TypeScript and allows it to narrow the type of a variable. For example, in the definition of Array.isArray,

function isArray(arg: any): arg is any[];

the type predicate is arg is any[]. In spoken word, the signature of this function might be: "isArray takes one argument of type any and checks if it is an array." In general, type predicates take the form: variable is type.

For a function to be eligible as a type guard, it must:

Return a boolean value
Have a type predicate

The type predicate replaces the return type, because a function with a type predicate must always return a boolean value.

Examples of type guard functions

Check if a value is a string

This example is essentially a reusable form of the built-in typeof type guard.

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Check if a value is defined (not null or undefined)

A common use case for type guards is to refine the type of something like Type | null or Type | undefined down to just Type, effectively eliminating the null or undefined case. We can do this by accepting a generic type which can be null or undefined, and adding a type predicate to remove null | undefined from the type.

function isDefined<Value>(value: Value | undefined | null): value is Value {
  return value !== null && value !== undefined;
}

Then, it can be used like this:

const x: string | undefined = 123;
if (isDefined(x)) {
  // x is defined, so it is safe to use methods on x
  x.toLowerCase();
}

Remove all values `null` or `undefined` values from array

Using the isDefined type guard we just defined, we can use it with the built-in Array.filter function, which has special support for type predicates. The Array.filter function is defined like:

function filter<Filtered extends Item>(
  predicate: (value: Item, index: number, array: Item[]) => value is Filtered
): Filtered[];

(The definition here has been altered slightly for improved understanding and readability). Essentially, every usage of Array.filter is a type guard, except in most cases the type before and after calling Array.filter is the same type.

But if the function passed to Array.filter narrows the type (like a type guard), then the return type of Array.filter changes. So we can use our isDefined type guard to remove all null and undefined values from the array, as well as removing null and undefined types from the array items.

// 'values' is an array of strings, but can have null or undefined values
const values: (string | null | undefined)[] = [null, "a", "b", undefined];

// We can safely assign 'filtered' to an array of strings (string[])
// because `isDefined` changes the type of the variable 'values'
const filtered: string[] = values.filter(isDefined);

Check if a number is positive

A common use-case for creating our own types is so that we can ensure certain conditions are met. For example, we might want to ensure that an object has certain properties, a string is not empty, or a number is positive.

First, we need to create a custom PositiveNumber type, and a type guard to check for it.

type PositiveNumber = number & { __type: "PositiveNumber" };

function isPositive(n: number): n is PositiveNumber {
  return n >= 0;
}

To create a new type of number, we use a technique called "type branding." Essentially, we add a phantom property to the number type to differentiate it from all other types of numbers. In this case, I chose to use { __type: 'PositiveNumber' }, but we could picked any arbitrary key/value, as long as it is unique and not already defined.

The important thing is that we cannot create PositiveNumber by declaring a variable:

const x: PositiveNumber = 49;
// ERROR: Type 'number' is not assignable to type 'PositiveNumber

This may seem inconvenient, but it is exactly why it allows us to write safe code, because we must always check conditions with the type guard and prevents us from writing code like this:

const x: PositiveNumber = -100;

As an example of how we might use this type guard, we can write a square root function which accepts only positive numbers:

function squareRoot(n: PositiveNumber): PositiveNumber {
  return Math.sqrt(n) as PositiveNumber;
}

Then, we can use the type guard to compute the square root:

const x = 49;

squareRoot(x);
// ERROR: ^^^ 'number' is not assignable to parameter of type 'PositiveNumber'

if (isPositive(x)) {
  // OK: Now x has type 'PositiveNumber', so we can take the square root
  squareRoot(x);
}

Check if a string is a GUID

Similar to the previous example, we can create a custom Guid type that is based on the string type and write a type guard to check for it.

type Guid = string & { __type: "Guid" };

const guidPattern =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

function isGuid(value: string): value is Guid {
  return guidPattern.test(value);
}

As an example of how to use this type and type guard in practice, we will create a list of users that can be searched by GUID.

type User = {
  id: Guid;
  name: string;
};
const users: User[] = [
  /* ... */
];

function getUserById(id: Guid) {
  return users.find((user) => user.id === id);
}

const id = "abc123";

getUserById(id);
// ERROR:   ^^ Argument of type 'string' is not assignable to parameter of type 'Guid'

if (isGuid(id)) {
  // OK: id now has type `Guid`:
  getUserById(id);
}

Check if a value is a valid React element (`React.isValidElement`)

The isValidElement function included with React checks if a value is a valid React element, which can be rendered by React.

function isValidElement<P>(
  object: {} | null | undefined
): object is ReactElement<P>;

The implementation of this function is not relevant here, but it is a perfect example of a common type guard function that verifies a custom type that cannot be verified with other type guards.

Pros and cons of custom type guard functions

Custom type guard functions are powerful and sometimes be the only option in order to write type-safe code. However, they can be a tricky to write and are susceptible to mistakes.

The advantages of custom type guard functions are:

Flexibility: can check any type, including custom types that we define
Run-time type checking: allows type-checking at run-time, ensuring that safety is ensured both when code is compiled, and also when it is running
Reusable: type guard functions allow us to combine multiple type guards into one and easily use them in multiple places

The disadvantages of a custom type guard function are:

Manual: type guard functions have to be written manually (currently no automatic way to generate type guards)
Performance: using type guard functions has a slight overhead to call the function and run the checks (negligible in practice)
Fragile: custom type guards can be implemented incorrectly on accident, which may provide a false sense of security and safety

Where can a type guard be used?

Now that we know all about the available type guards, we will briefly look at where we can use type guards. There are a limited number of places that type guards can be used. The most common place they are used is in a if/else block, like this:

if (typeof value === "string") {
  // value has type 'string' in this block
} else {
  // value does NOT have type 'string' in this block
}

Since we can use type guards in an if/else block, then you might expect that we can also use them with the ternary operator, since it's a shorthand for an if/else block. And you would be correct!

typeof value === 'string'
  ? /* value has type 'string' in this block */
  : /* value does NOT have type 'string' in this block */

In addition, since TypeScript 4.4, we can use type guards with aliased conditions.

const isString = typeof value === "string";
if (isString) {
  // value has type 'string' in this block
} else {
  // value does NOT have type 'string' in this block
}

Beyond just if/else, type guards can also be used in a while block:

while (typeof value === "string") {
  // value has type 'string' in this block
}

Finally, type guards are also compatible with a switch/case block:

switch (typeof value) {
  case "string":
    // value has type 'string' in this block
    break;
}

Conclusion

Type guards are conditional checks that allow types to be refined from one type to another, allowing us to write code that is type-safe and easy to write at the same time. Since TypeScript is a superset of JavaScript, many common operators like typeof or instanceof act as type guards. But, we can also use custom type guards to verify any condition and any type, given enough effort.

Summary

In general, I would recommend using the type guard that feels the most natural, which will come from experience. Don't write a custom type guard function when a simple typeof check can suffice. However, it may be necessary to write a custom type guard.

To summarize the strengths of each type guard, here is a summary table.

Type guard	Usage
Boolean / truthiness	Rule out falsy values like `null`, `undefined`, `''`, `0`, etc.
Equality	Narrow multiple possible types down to a single type
`typeof`	Narrow a type to a primitive type (like `string` or `number`)
`instanceof`	Check if a value is an instance of a specific class
`in`	Check if a property can be accessed
Assertion function	Assert invariants that should always be true
Custom type guard function	Check that a type meets some arbitrary conditions

If this article was helpful, let me know on Twitter at @cammchenry! If you enjoy guides like this, consider signing up for my mailing list to be notified when new posts are published.

Good luck, and happy coding!

How to Delete Dead Code in TypeScript Projects

Cameron McHenry — Tue, 19 Oct 2021 19:09:25 +0000

This was originally posted on my blog: https://camchenry.com/blog/deleting-dead-code-in-typescript.

What is dead code?

"Dead code" is code that is never used. It is not referenced by any other code, it is not imported, it is not used in the final build in any way.

Refactoring a project to make certain types, methods, or properties obsolete without removing that obsolete code will create dead code. Changing the direction of a project, like choosing to use a different API or library can also produce dead code. On large projects with many different teams and shifting priorities, the occurrence of dead code is inevitable.

Why should you delete dead code?

There are many reasons why you should delete dead code. There are many effects that dead code can have on a large project:

Dead code must be compiled, which slows down the compilation time. It may be included in the final output too, increasing the total executable size.
Dead code must be downloaded, which increase the project size.
Dead code may reference other dead code and make it appear important.
Dead code must be understood, which makes the project harder to maintain and work on.

When you delete dead code, you:

Make it easier to understand and maintain a project.
Speed up compilation time.
Decrease the project size.

As a result of removing dead code, a program will be faster to download and compile, and its output executable will be smaller and faster.

How to find dead code

First, you will need to be using TypeScript in your projects for these tools to work. TypeScript simplifies the difficult task of determining whether any given piece of code is actually used or not.

Second, you will want to install ts-prune and ts-unused-exports globally, so they can be used for any project. Run these commands in a terminal:

npm install -g ts-prune ts-unused-exports

In my experience, no single tool will give perfect results for identifying dead code. So, I recommend alternating between both of these tools to find dead code.

How to use `ts-prune`

To run ts-prune, run the following command in a terminal:

ts-prune --project tsconfig.json

You should see some output like this:

\src\components\Avatar\index.ts:18 - STYLE_CLASSES
\src\components\BulkActions\index.ts:26 - BulkAction
\src\components\CheckableButton\index.ts:13 - CheckableButtonProps
\src\components\Choice\index.ts:9 - ChoiceProps
\src\components\Combobox\index.ts:2 - ComboboxTextField
\src\components\DataTable\utilities.ts:34 - isEdgeVisible (used in module)
\src\components\DropZone\index.ts:38 - DropZoneFileType
\src\components\IndexTable\index.ts:6 - CellProps
\src\components\IndexTable\index.ts:11 - Cell

The left-hand side is the file and line number of where the potential dead code occurs. The right-hand side is the name of the export that appears to be unused. If the export is only used internally, it will have the text (used in module) appended to it. If the default export is unused, the right-hand side will say default.

I'm OK with unused exports as long as the export is used internally, so I recommend filtering out the lines with (used in module) in them. You can do that by piping the output into grep:

ts-prune --project tsconfig.json | grep -v '(used in module)'

How to use `ts-unused-exports`

To run ts-unused-exports, run these commands in a terminal:

ts-unused-exports tsconfig.json

which should create some output like this:

src\utilities\features\index.ts: Features, useFeatures
src\utilities\focus-manager\index.ts: FocusManagerContextType
src\utilities\frame\index.ts: FrameContextType
src\utilities\index-table\index.ts: useRowHovered
src\utilities\listbox\index.ts: ListboxContextType
src\utilities\media-query\index.ts: MediaQueryContextType
src\utilities\portals\index.ts: PortalsManager
src\utilities\resource-list\index.ts: ResourceListContextType
src\utilities\theme\index.ts: ProcessedThemeConfig
src\utilities\theme\types.ts: ThemeLogo, Role, AppThemeConfig
src\utilities\theme\utils.ts: buildCustomPropertiesNoMemo

The left-hand side lists the file that contains unused exports. The right-hand side lists the names of unused exports in the file. If the default module export is unused, the right-hand side will include default.

I will often ignore unused types, since it is typically not much of an issue. In many cases, it is indicative of work that
is in progress. It is also not included in the compiled JavaScript (since types don't exist in JavaScript), so leaving it in the project won't affect the build size. To do that, add the --allowUnusedTypes flag to the command:

ts-unused-exports tsconfig.json --allowUnusedTypes

How to delete dead code

Unfortunately, you will have to manually go through each result and determine whether to keep it or delete it. There is often a moderate false positive rate when it comes to finding dead code. Not all unused code is dead code, but all dead code is unused code.

If any patterns emerge while identifying dead code, I recommend automating the process. Create scripts to combine the results from these tools. Filter it to remove any false positives. Then, automatically generate diffs to remove dead code. For small projects, this is probably overkill (and that's OK). For large projects, this is a force multiplier that will make everyone on your team more productive.

When deleting dead code, there are a couple exceptions that I always keep in mind:

Exported component prop types are OK. These may not be "used," but they will likely be used by consumers of the module to create derivative types.

   // OK:
   export type ComponentProps = {
     /* ... */
   };

Exported default values are OK. These allow consumers of a module to access the implicit default values of objects and functions, which are otherwise inaccessible programmatically.

   // OK:
   export const defaultFadeTime = 100;
   export function animate(fadeTime = defaultFadeTime) {
     /* ... */
   }

Recently added code (less than a month old) is probably OK. Sometimes in-progress work will appear unused because it is incomplete.

   // Probably OK:
   const UserTable = () => {
     /* TODO: Going to implement this next week */
   };
   // NOT OK:
   const UserTable = () => {
     /* TODO: Going to implement this next week ... 2015-06-01 (6 years ago) */
   };

Metadata and specific code may be OK. If there are pieces of code that serve a special purpose (e.g. preprocessed by another tool, expected by a framework, etc.) then it may not be unused or dead code. For example, server-side rendered frameworks may export functions that are not used in the client output, but are rendered on the server instead.

   // OK: special function used by the Next.js framework
   export async function getServerSideProps({ req, res }) {
     /* ... */
   }

Conclusion

Deleting dead code is a worthwhile effort that can make working in a project faster and easier. Using the ts-prune and ts-unused-export tools, we can simplify the process of identifying dead code.

If you are a junior developer, automating the process of finding dead code and deleting it is a great senior-level task to learn how to do. Everyone on your team will appreciate having less code to download, compile, and understand. And it will help you understand your codebase better. You'll probably learn many other useful skills along the way too.

Good luck and happy hunting!

How to Power Up the React Context API with TypeScript

Cameron McHenry — Fri, 08 Oct 2021 16:05:06 +0000

This post was originally published on my blog, camchenry.com. If you find this post interesting, check out my website for more content like this.

What is the React Context API?

React Context is one of the core React APIs that can be used anytime you are developing with React. Context allows us to create a piece of state that is globally shared among many different components.
For example, an application might have a context for the current locale, language, or theme, because that data will be used by
many different components. Context is ideal for globally shared values.

(NOTE: In this article the terms "Context" (uppercase) and "context" (lowercase) will be used interchangeably. Generally speaking, these refer to the same thing. However, "Context" more often refers to the React Context feature, while "context" refers to the general concept, or a specific instance of context (for example, an "authentication context" may use Context).)

What problems does React Context solve?

At its core, Context helps to solve one main issue: "prop drilling." Prop drilling is the name for when a property
must be passed down through an entire component tree in order to render the application.

For example, suppose that we store information about a user's application preferences (language, timezone, privacy, etc.) and need to use that to render the application correctly. To render the application, we must write something like:

<App preferences={preferences} />
// Inside App:
<Profile preferences={preferences} />
// Inside Profile:
<Settings preferences={preferences} />
// ... and so on

Ultimately, we end up writing the same code repeatedly in order to pass that state down. Now, if we ever have to rename preferences or change its type, we have to change it for every component that passes that state down.

That's a huge pain, especially for large applications, where it's not unheard of to have components that are nested dozens of layers deep inside of other components.

In addition to the increased effort, this sort of behavior also makes components less flexible, because they are expected to take certain properties, and be nested in certain ways. So, restructuring and moving components around becomes more difficult.

So, how can we solve the prop drilling problem?

Enter React Context.

How Context solves the problems with prop drilling

Context solves the problems that come from prop drilling by allowing components to "skip" an arbitrary number of layers in the component tree. In this way, components can access directly shared state directly.

In a context, there are two main pieces: the provider and the consumer.

The provider is the component where the shared state is defined. All components under a provider will be rerendered when the state changes.
A consumer is the component where the state from the provider is accessed and used. As long as it is a descendent of the provider, it can access the provider's state. A consumer always reads the value of the nearest provider.

An Analogy for Context

Imagine that a context is like a wireless network, where the provider is a 🌐 wireless network, and the consumer is a device like a 💻 laptop.

Summary of comparison between wireless network and context

🌐 Wireless Network	💡 Context
When a laptop is connected to the network, can send and receive data from anywhere, regardless of physical location	When a consumer is nested under a provider, the consumer can send and receive state from anywhere, regardless of how it is nested (or how deeply nested).
A laptop will try to find the closest access point in the network to get the best wireless signal.	A consumer will try to find the closest provider (nearest ancestor) to get the current state.
If there is no wireless access point, devices will not work.	If there is no context provider, then consumers will only get the default value.

A laptop that is connected to the network is like a consumer component that is nested under the provider. As long as the
laptop is connected, it can communicate and receive data regardless of where it is physically located. In the same way, as long as a consumer is under the provider, it can exist anywhere in the component tree and access state directly.

Similarly, a laptop always tries to find the closest access point in order to get the best signal possible. This is like the behavior of the consumer, which always reads the value of the nearest (least nested) provider. If there's no network (i.e., there is no context provider), then our laptop (consumer) can't work!

How do we define a context?

Now that we understand what a context is and the problems that it solves, how do we actually create a context? The React API
offers two functions to create and use contexts, which are aptly named createContext and useContext, respectively.

For a simple example, we will create a theme context which tells all consumers whether the current theme is 🌚 dark or 🌞 light.

import React from "react";

const ThemeContext = React.createContext("light");

We create a context called ThemeContext, which has a default value of light. The first argument of createContext is a default value which will be used if there are no providers. We will cover how to create a context without a default value later.

(NOTE: The ThemeContext variable is uppercase because createContext returns an object which contains components.
The JSX convention is that components always start with an uppercase letter. So, that means we should uppercase ThemeContext)

Then, in our application we would render the context just like any other component. In this case, we don't render ThemeContext directly (because it is an object), but instead we render ThemeContext.Provider.

const App = () => (
  <ThemeContext.Provider value="light">
    {/* ... rest of the application code here ... */}
  </ThemeContext.Provider>
);

Then, our consumer is a component that calls useContext to access the state.

const CurrentThemeDisplay = () => {
  const theme = React.useContext(ThemeContext); // this will be "light"
  return <div>{theme}</div>;
};

Now, we can place CurrentThemeDisplay anywhere underneath the ThemeContext.Provider and it will always get the current theme:

const App = () => (
  <ThemeContext.Provider value="light">
    <CurrentThemeDisplay />
  </ThemeContext.Provider>
);

Ultimately, this example will end up rendering:

<div>light</div>

A note about class-based Context

There is a class-based version of React Context that uses "render props" and the ThemeContext.Consumer component. However, if you are just starting a new React application, I would recommend that you do not use these APIs.
While working on a large React application, I've never had any need to use the old class API or render props.

React Hooks completely revolutionized the way that we can interact with a context and makes it much easier to reuse contexts
and compose them together. In my opinion, the newer, functional API is easier to understand and scales very well to large applications.

How TypeScript helps us work with contexts

So far, we've covered the basics of how to use the Context API, but how does TypeScript help us use context more effectively?

To answer that, let's look at some of the issues that we might experience when using JavaScript and contexts:

Accessing a non-existent property in the context could cause an error
Renaming a property in the context, or change its type (e.g., from string to object) means we have to check every instance where that context is used
May be possible to put context into invalid states (misspelled string literals, wrong types, etc.)
Have to reference where the context is defined originally to figure out what properties it contains

Most or all of these issues are typical with any JavaScript application, not just ones that use Context. However, TypeScript can solve or mitigate all of these issues:

Accessing a non-existent property in a context will cause a compile error, preventing any misuse of the context
Renaming a property or changing the type of a property in the context will cause a compile error, if any code relied on the old name or type
All types are checked, so invalid context states will not compile, preventing many classes of bugs
A typed context enables IDEs (like Visual Studio Code) to autocomplete what properties are available in a context

Furthermore, we don't incur any run-time cost for these benefits. That is, using TypeScript doesn't make our bundle size any larger because all of the types will be removed when compiled.

How to use the React Context API with TypeScript

Let's revisit how we defined the theme context example earlier. Now we are going to add explicit types for the context.

type ThemeState = "light" | "dark";

const ThemeContext = React.createContext<ThemeState>("light");

Now if we try to provide an invalid value to the context, the application will not compile.

// ❌ This will NOT compile:
const App = () => (
  // ERROR: Type '"tomato"' is not assignable to type 'ThemeState'
  //                     ⬇️
  <ThemeContext.Provider value="tomato">
    <CurrentThemeDisplay />
  </ThemeContext.Provider>
);

In addition, we are also prevented from misusing the value provided from the context. Here is a modified example of the CurrentThemeDisplay:

// ❌ This will NOT compile:
const CurrentThemeDisplay = () => {
  const theme = React.useContext(ThemeContext);
  if (theme === "peach") {
    // ~~~~~~~~~~~~~~~~
    // ERROR: This condition will always return 'false' since the
    // types 'ThemeState' and '"peach"' have no overlap.
    return "🍑 Peach";
  }
  return <div>{theme}</div>;
};

How to provide default values to a React Context

As mentioned earlier, the createContext function requires that we pass a default value as the first argument. So, if we want to provide a default default, then we can just say:

const defaultValue = { user: null };
const Context = React.createContext(defaultValue);

What if we don't want to provide a default value though? This may come up if we want to require that a provider is defined somewhere in our application. For example, maybe we want to fetch information from an API and use that as a default value.

To do this, we still have to provide a default value to createContext, but we can throw an error if there was no value in the context (which means that no provider was rendered).

Theme context example with "no default value"

As an example, let's create a new version of the theme context which tells the application about the current theme. In this case, it's perhaps a bit contrived for a theme provider why you might want to have "no default value," but there are good reasons to do so for something like an authentication context or other context that might make API calls.

To keep things simple though, we will build from our previous theme example.

We will use null as a sentinel value that indicates that no provider provided a value and consumers should consider this default value as invalid. So, if the value is null, we will throw an error. This will then allow TypeScript to infer that the value from the context is definitely defined.

type ThemeState = "light" | "dark";

const ThemeContext = React.createContext<ThemeState | null>(null);

The context value can either be our expected set of values for the context, or null (if no provider is created). Then, where we consume the context, we can check if the value is null, and throw an error.

const CurrentThemeDisplay = () => {
  const theme = React.useContext(ThemeContext); // this will be "light"
  if (theme === null) {
    throw new Error(
      "Theme state not found. Try wrapping a parent component with <ThemeContext.Provider>."
    );
  }
  return <div>{theme}</div>;
};

Now, we ensure that anywhere we use the theme context, that a theme provider must be rendered before the application works. In this way, we surface potential usage issues with our context much sooner than if we didn't throw an error.

We also retain the type safety of TypeScript, because throwing an error when theme === null gives the compiler enough information to narrow the type of ThemeState | null to just ThemeState, which makes it safe to render theme.

(NOTE: The error message also includes what went wrong, explains how to fix the error: wrap a parent component with ThemeContext.Provider.

Providing descriptive error messages that indicate clearly went wrong, and some possible ways to fix the issue is immensely valuable. You and future developers will thank you many times over.)

How to write a TypeScript custom hook for a React Context

Now that we've explored how to add a type to the context, and enforce that a provider is used, it has become a bit cumbersome to actually use the context. We can fix that by creating a custom hook that calls useContext for us.

const useTheme = (): ThemeState => {
  const themeState = React.useContext(ThemeContext);
  if (themeState === null) {
    throw new Error(
      "Theme state not found. Try wrapping a parent component with <ThemeContext.Provider>."
    );
  }
  return themeState;
};

Now, we have a reusable hook called useTheme that lets us access the current theme from anywhere. It guarantees that we consistently check if there is a theme provider, and it also removes the dependency on the ThemeContext variable, which makes the code a bit shorter and easier to change if we want to switch how the theme state is accessed. Context is now an implementation detail of getting the theme.

So, our CurrentThemeDisplay component from before is much simpler:

function CurrentThemeDisplay() {
  const { theme } = useTheme();
  return <div>{theme}</div>;
}

How to update state in a context

So far, we've only covered read-only contexts that don't allow consumers to update the state of the context. But it is also possible to provide functions in the context that actually allow the state of the context to change. Using the theme example, let's add a function to change the current theme.

First, we need to add an additional type for the theme state, plus a callback to change the state. Why do we need to declare it separately? Because we are going to define the state and the callback separately before combining them into the context value.

type ThemeState = "light" | "dark";
type ThemeStateWithCallbacks = {
  // The current theme state
  theme: ThemeState;
  // Callback for any consumer to change the current theme state
  setTheme: (newTheme: ThemeState) => void;
};
const ThemeContext = React.createContext<ThemeStateWithCallbacks | null>(null);

Then, to actually store the state and create a callback to change it, we will use React.useState which conveniently does exactly that for us. To use a hook though, we need to create a component for the provider.

const ThemeProvider = ({ children }: React.PropsWithChildren<unknown>) => {
  const [theme, setTheme] = useState<ThemeState>("light");
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
};

We use the separate theme state type with useState to define both the current state and create a callback to change it. Then, our theme context simply expects an object that has both a theme property and setTheme property.

Now, because we are using useState, if any consumer changes the current theme, ThemeProvider will rerender and broadcast the change to all context consumers of the theme state.

(NOTE: For this simple case, useState is sufficient to meet our needs. However, in larger applications, I would strongly
recommend taking a look at useReducer to make
complex state changes simpler and easier to test.)

Conclusion

Context is a simple, but powerful feature that can be used in any React project. In this post, we looked at the problems that Context solves, and how to use the React Context API to solve those problems. By adding TypeScript types, we can dramatically improve the type safety when using a context. Furthermore, we can also write a custom hook to ensure that we use the context consistently and safely, as well as make it easier to use.

If this guide helped you understand how to use React Context and TypeScript better, let me know and tweet me at @cammchenry!

DEV Community: Cameron McHenry

The Difference Between TypeScript Unions, Enums, and Objects

What are TypeScript unions?

What are TypeScript enums?

TypeScript enum example

Constant enums

What are TypeScript constant objects?

Comparison between unions, enums, and constant objects

Unions, enums, and constant objects all support type safety

What's similar between enums and constant objects

Both: named values

Both: run-time usability

Advantages of union types

Union advantage: unique values

Union advantage: mixed types

Union advantage: sub-typing

Union advantage: computed types

Unique advantage of enums: reverse mapping

Unique advantage of constant objects: computed values

What type should I use?

When should you use a union in TypeScript

When should you use a constant object in TypeScript

When should you use an enum in TypeScript: probably never

Conclusion

How Serverless Saved Money on My Heating Bill

The Solution

Scraping tool: Browserless

Database: Supabase

Framework: Remix

Host: Fly.io

The Result

Take-away

Everything You Need To Know About TypeScript Union Types

What is a union type in TypeScript?

When should you use a union type?

Examples of union types

How to tell which type is currently in use

What is a discriminated union?

How to get a single type from a union type

How to get a subset of a union type

When to use Extract or Exclude

When should you not use a union type?

What is the difference between an enum and a union type?

Conclusion

How To Do Anything in TypeScript With Type Guards

What is narrowing?

What is a type guard?

The kinds of type guards (how to check a type)

Boolean type guard (truthiness)

Equality type guard

typeof type guard

instanceof type guard

in type guard

Assertion type guard (or assertion function)

User-defined (custom) type guard

Type guard functions

Examples of type guard functions

Check if a value is a string

Check if a value is defined (not null or undefined)

Remove all values null or undefined values from array

Check if a number is positive

Check if a string is a GUID

Check if a value is a valid React element (React.isValidElement)

Pros and cons of custom type guard functions

Where can a type guard be used?

Conclusion

Summary

How to Delete Dead Code in TypeScript Projects

What is dead code?

Why should you delete dead code?

How to find dead code

How to use ts-prune

How to use ts-unused-exports

How to delete dead code

Conclusion

How to Power Up the React Context API with TypeScript

What is the React Context API?

What problems does React Context solve?

How Context solves the problems with prop drilling

An Analogy for Context

When to use `Extract` or `Exclude`

What is the difference between an `enum` and a union type?

`typeof` type guard

`instanceof` type guard

`in` type guard

Remove all values `null` or `undefined` values from array

Check if a value is a valid React element (`React.isValidElement`)

How to use `ts-prune`

How to use `ts-unused-exports`