TypeScript Runtime Type Checking
Tags: typescript, javascript, typesafety, advanced
Published: 2023-04-24 20:15:56

## Intro
Typescript is the best thing to happen to Javascript since the Great Callback Pyramid crumbled.

We got types, autocomplete, compile-time issue catching, and the world was finally at peace, until *someone* decided to use `instanceof` (yes it was me).

You see, even though we got all of the aforementioned goodies, there are still a few quirks of the typescript type system that may fly under the radar since they don't arise often, especially when you're writing relatively simple applications.

In this article, I want to dive into the topic of objects. Specifically, the different ways an object can be instantiated, why they matter, and how the `instanceof` operator can be used / misused.

I'll back everything up with a practical example about error handling, and show you how we can get the flexibility of typescript's structured typing system with the power of runtime object type checks.

---
## An Example Use case
You're a frontend dev and you've been asked to implement error handling for an application. Let's say for this application that the types of errors you need to handle are:
- authentication errors
- backend errors
- any uncaught errors that don't fit into the previous two types.

Let's see how we would implement something for that.

## 1. What if we only used typescript?
Like a good developer, we start things simple by creating a type for each of our errors:

```typescript
type AuthError = { reason: string };

type BackendError = { reason: string };

type UnknownError = { reason: string };
```

Right out of the gate, we have a few major issues:
- To typescript, these are all [the same thing](https://www.typescriptlang.org/docs/handbook/type-compatibility.html)
- To javascript, these don't even exist
- Code Repetition

Let's move on to something better.

## 2. What if we used classes?

Good idea! After all, classes are also available during runtime which solves the second issue.

```typescript
class AuthError {
	constructor(public reason: string) {}
}

class BackendError {
	constructor(public reason: string) {}
}

class UnknownError {
	constructor(public reason: string) {}
}
```

We still have two issues. These are still the same thing for typescript, and we're still repeating ourselves.

The code repeating issue is simple enough to take care of. We can make a super class and have the others extend it:

```typescript
class CustomError {
	constructor(public reason: string) {}
}

class AuthError extends CustomError {}

class BackendError extends CustomError {}

class UnknownError extends CustomError {}
```

The code above is perfectly valid. Though typescript can't tell the difference, maybe we don't need it do! After all, we can use `instanceof` and the following code works perfectly fine:

```typescript
function handleError(error: CustomError) {
	if (error instanceof AuthError) {
		// do something
	} else if (error instanceof BackendError) {
		// do something
	} else if (error instanceof UnknownError) {
		// do something
	}
}
```

Great! Now we took care of all issues we mentioned before, but the article is not finished yet. Uh oh. Something is about to change your view about something in javascript.

The issue is hidden in how `instanceof` works.

In the simplest terms, `someObject instanceof SomeClass` returns true if `someObject` was created by or inherits from `SomeClass`'s constructor, meaning there has to be a `new` keyword in their somewhere. Big deal, so what? We'll just throw our errors like this:
```typescript
throw new AuthError('Session is expired or something');
```

Okay. fair enough, except that this is the wild untamed land of javascript, where you could also do this:
```typescript
throw { reason: 'Session is expired or something' };
```

Zero warnings. Zero errors. But that's the not even the worst part. You've just lost the ability to check this at runtime:

```typescript
const errorObj: AuthError = { reason: 'Session is expired or something' };

console.log(errorObj instanceof AuthError); // -> False
```

`instanceof` does NOT work when you don't use instantiate objects with the `new` keyword.

Even though this is a rather unlikely issue, I've personally lost faith in `instanceof`. Whenever an issue happens in this area of the code, a little voice in my head will keep telling me *"What if it's because of that really rare bug you read about once?"*

We need a different approach. One that saves us from the quirks of javascript, and allows typescript to truly shine.

### 3. Back to types again
Introducing tags! A tag is simply a property with constant value which placed in a type, allowing us to confidently narrow the type of a given object during both compile-time and runtime.

Here's how we could define our errors now:
```typescript
type AuthError = {
	reason: string,
	errorType: 'auth-error', // <- tag
};

type BackendError = {
    reason: string,
    errorType: 'backend-error', // <- tag
};

type UnknownError = {
    reason: string,
    errorType: 'unknown-error', // <- tag
};

type CustomError = AuthError | BackendError | UnknownError;
```

Interestingly, `CustomError` is now on the bottom of our hierarchy instead of at the top. Using the `|` (union) operator, we tell typescript that a `CustomError` is one of any of the given types. We are able to narrow which one it is exactly using the tag.

Here's how the `handleError` function can be re-written:
```typescript
function handleError(error: CustomError) {
	switch (error.errorType) {
		case 'auth-error':
			// ...
		case 'backend-error':
			// ...
		default:
			// ...
	}
}
```

The coolest part? Typescript is helping you along every step of the way, and is fully aware of exactly the type of error you're handling.

![Typescript infers the narrowed types of the errors since we provided a union with the same key](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/skwj2bbgrinlqjsdhws9.png)

Note that for this to work, the tag needs to have the same name for all the types (`errorType` in the above example).

If you're interested in how to print the types this way (using  `// ^?`) check out [this extension](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-twoslash-queries) (I'm not affiliated, just think it's awesome).

Now it wouldn't even matter if we rawdog it and throw objects directly. Typescript would get mad and force us to add a tag:
```typescript
// ERROR: Property 'errorType' is missing in type '{ reason: string; }' but required in type 'AuthError'.
const errorObject: AuthError = {
	reason: string;
};

throw errorObject;
```

### Conclusion
In conclusion, this article underscores the importance of understanding Typescript and Javascript type systems explained with an error handling example.

Through a step-by-step exploration, we discovered that using tags is a powerful, reliable solution. This approach takes advantage of Typescript's structured typing system and allows for runtime object type checks, resulting in more robust and maintainable code.

By mastering these nuances, we can fully harness Typescript's potential while avoiding language pitfalls.

For more insight into typescript, I highly recommend the Effective Typescript book by Dan Vanderkam.