This exercise presents an inference mystery.

Here's the code:

```typescript
const divElement = document.querySelector("div");
const spanElement = document.querySelector("span");

const divElement2 = document.querySelector("div.foo");
```

When we pass in `"div"` to `document.querySelector`, it returns an `HTMLDivElement` or `null`.

Similarly, when we pass it `"span"` we're getting an `HTMLSpanElement`.

So we're getting nice specific types when we pass in `div` and when we pass in `span`.

However, when we pass in `"div.foo"`, we'll get back either `element` or `null`.

## Challenge

Your challenge is to dive into these types to figure out why `document.querySelector` behaves this way.

In VS Code on your local machine you can hover over `querySelector` and go to its definition, or check out the <a href="https://github.com/microsoft/TypeScript/blob/43cc362cef72e5fa1372f59736a9c4b55d85def0/lib/lib.dom.d.ts#L10531" target="_blank" rel="noopener">TypeScript DOM source code on GitHub</a> to reference if you are working with Stackblitz.

You're going to encounter some scary looking types!

If you get lost, then jump ahead to the solution and we'll walk through all of it together.

Knowing how to read and diagnose problems related to function overloads on interfaces is very important. Here, you'll troubleshoot an overloaded interface.

The `ParentNode` interface inside of <a href="https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts#L10531" target="_blank" rel="noopener">TypeScript's ,`lib.dom.d.ts`, file</a> is where `querySelector` is defined.

You'll notice that it has several overloads:

```typescript
/** Returns the first element that is a descendant of node that matches selectors. */
querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null;
querySelector<K extends keyof SVGElementTagNameMap>(selectors: K): SVGElementTagNameMap[K] | null;
querySelector<E extends Element = Element>(selectors: string): E | null;
```

This shows us that methods on an interface can be overloaded.

## Experimenting with Interface Overloads

Back in the exercise file, let's experiment by creating an interface called `MattInterface`:

```typescript
interface MattInterface {
  a(): 1;
  a(param: "wow"): 2;
}
```

Here `a` is a function that returns `1`. But if `a` is called with a `param` of `"wow"` it will return a `2`.

We could quickly create an `example` that uses the interface:

```typescript
const example = {} as MattInterface; 
```

Calling our `example.a()`, we can see its behavior matches what we saw in the interface:

```typescript
example.a() // returns 1
example.a("wow") // returns 2
```

## Back to the `querySelector` Overloads

Now that we have an idea for how interface overloads work, we just need to determine which one of the three we end up triggering.

With VS Code, select "Go to definition" when hovering over the call to `querySelector("div")`.

We get jumped over to the exact overload that gets hit:

```typescript
querySelector<K extends keyof HTMLElementTagNameMap>(selectors: K): HTMLElementTagNameMap[K] | null; 
```

Back in the exercise file, repeating the process with `querySelector("span")` takes us to the same place.

But jumping to the definition for `querySelector("div.foo")` takes us to the last overload:

```typescript
querySelector<E extends Element = Element>(selectors: string): E | null; 
```

Why is this going to the last overload when we know the selector contains a `div`?

Looking at the overload where the other queries jumped to, we see `K extends keyof HTMLElementTagNameMap` which tells us that the selector is passed into `HTMLElementTagNameMap`.

Jumping to that definition, we can see a list of all of the different elements being mapped to the tag that they're in:

```typescript
interface HTMLElementTagNameMap {
  "a": HTMLAnchorElement,
  "abbr": HTMLElement,
  ...
```

With this new information, we know that if we choose an element that's part of the `HTMLElementTagNameMap`, we'll get autocomplete when using it in our source code.

It follows that calling `document.querySelector("svg")` will hit the second overload.

Therefore, when we pass in something like `div.foo`, we will end up in the third overload that just returns `Element`. This is because `querySelector` isn't smart enough to know that if the thing we pass in starts with `"div"` that it belongs as an `HTMLDivElement`.

## The Big Takeaway

The `lib.dom.d.ts` file is huge, and full of APIs you'll be using in your web based projects. The Node API source is perhaps even more complex. Become comfortable reading these files, but don't worry about memorizing them.

Knowing how to read and diagnose problems related to function overloads on interfaces is very important!

This should give you the confidence to fix any errors you encounter in the wild!

The Inference Mystery Solved

0:00 Ready to solve the mystery? Let's go. What I'm going to do here is I'm going to do a Go to Definition to find out why the types of querySelector are being so weird. We could go a lot of different places here, but I want you to be aware that where you do your Go to Definition really affects where you end up. 

0:20 If I do a Go to Definition on Document, I'm going to end up in no man's land here. I don't want to think about the whole document. That's not what I'm analyzing. I just want to to analyze the querySelector, so I'm going to do a Go to Definition there. We end up in an interface that looks like interface ParentNode extends Node, and we get querySelector on here.

0:44 This is an interface. I don't want you to worry too much about what all of these different interfaces are. We may cover that in some bonus material, or some material somewhere. We have these functions here called querySelector, and these are basically, if we look at the whole thing zoomed out, methods on the interface here.

1:06 These methods on the interface, you can see that they're overloaded. If I were to create my own interface here, so interface MattInterface. Then let me zoom that in. Then I can actually have, a is a function, for instance. Let's say a, and a returns one, but if I call a with a "wow," then it's going to return two, or rather I should do the syntax properly, shouldn't I?

1:36 Let's call this param "wow," and returns two. You can see here that MattInterface, imagine if I have a const example, which is like this. As MattInterface, can we pull that to implement it now? Example.a, if I call it, then it's going to return one, but if I pass it a "wow," then it's going to return two instead.

2:00 This method lets you declare different overloads on interfaces. We understand what's going on, now let's check it out. We can now look at each of the querySelectors here because there's three overloads. We need to work out which one that we're triggering. We can do that by saying querySelector ("div").

2:22 If we do a Go to Definition on it here -- this is inside VS Code -- then you get taken to the exact overload that's being hit here. We can see that this one hits this line. This next one, the span, hits the same one. Then this one, which one does this hit? This one hits the third line.

2:47 What's going on here? We can see the querySelector here. We have a K extends keyof HTMLElementTagNameMap, and then the selector is being passed in there. HTMLTagNameMap, if I go to it, you can see that it has all of these different elements on it mapped to the exact tag that they're in.

3:11 If I choose these, then I should be able to actually get autocomplete here. A base ends up as a HTMLBaseElement. An area ends up as a HTMLAreaElement. That's really, really cool. If I get one of those, then I'm basically triggering, if I jump back to querySelector, this first element here, or this first overload.

3:36 If I choose the name of an SVGElement, for instance animateMotion, then I'm going to trigger the second overload. I'm going to end up with an SVGAnimateMotionElement there. You can see there, when I do a Go to Definition on it, then I end up on the second overload.

3:53 If I don't pass in anything that hits either of those keys, either hits keyof SVGElementTagNameMap or keyof HTMLElementTagNameMap, then I end up on this overload. That's what's happening here, is I'm getting a blah-blah-blah-blah-blah. I could pass in anything, and I'm going to end up with a generic element.

4:14 That's why divElement2 is not of type HTMLDivElement. It's because querySelector here isn't smart enough to know that if I start my thing with a div here, like div.whatever, I'm going to end up with a div at the end there. You notice, though, that it does take a generic, it does take a type argument.

4:34 It has an E extends Element, which defaults to Element. What this means is we can pass it HTMLDivElement here, meaning that we end up with, if I change the span back to what it was, something nice. Now what's happening is that it's returning HTMLDivElement because we're manually passing in that E in there.

5:01 What's the lesson here? Wow, there's so much to dive into here. This huge file, this is lib.dom.d.ts, this is full of APIs that you will be using in your projects if you're doing a web-based project. If you're doing a Node project, then you're going to be using types/node, which is possibly even more complex than this.

5:25 Knowing how to read this stuff, you don't need to know every line of it, but knowing how to read and diagnose these problems is really, really important. I'm going to be looking at that in future exercises in this core volume.

5:39 For now, knowing that these function overloads are available on interfaces, and knowing that you can diagnose them, should give you a real sense of power and give you a sense that, "OK, I can dive into this stuff and understand what's happening."

5:55 For now, what we've got here is different generic signatures based on different overloads, and this should give you a good sense of confidence when you're approaching this stuff and fixing these type of errors in the wild.

Solving an Inference Mystery

0:00 In this exercise, we have a bit of a murder mystery, or an inference mystery, should we say. Document.querySelector, when we pass in div here, is returning HTMLDivElement, or . On the spanElement, we're getting HTMLSpanElement, so we're getting nice specific types when we pass in div and when we pass in span.

0:20 When we pass in something that's not that, then this should be a div, but we're actually just getting element, or . Your job here is to figure out why document.querySelector is behaving in this way.

0:34 You're going to need to dive into some of these types. The first spot you're going to have to look at is you can basically hover over this Go To Definition, and it will take you to the spot where it's declared.

0:51 You're going to be looking at some scary-looking types. Try not to get lost. If you do get lost, then jump back to the solution, and I'll walk you through all of it.

The Generics workshop is your guide to mastering one of TypeScript's most complex features.

Through dozens of exercises, you'll get to grips with generics from the lowest level, up through examples of how your favorite TS libraries use them.





Master TypeScript's generics with exercises from basics to advanced, including conditional types and currying.

TypeScript Generics Workshop

Total TypeScript Complete Volume is a set of five full TypeScript workshops for the advanced-beginner to expert professional TypeScript programmer that wants to take their skills to the next level. This bundle includes all of the Total TypeScript self-paced workshops.

TypeScript Pro Essentials

Type Transformations

TypeScript Generics

Advanced TypeScript Patterns

Advanced React with TypeScript

TypeScript Expert Interviews

TypeScript Pro Complete

By the end of this workshop, you'll be a master of generics and have a good understanding of function overloads, inference, and all the tricks you need.

TypeScript Generics Workshop Welcome

Generics allow you to ensure that your functions are properly typed, often without having to specify the return type.

Replace the unknown Type with a Generic

Typing Functions with Generics

It is possible to specify what can be passed into a generic while still allowing its literal type to be inferred.

Add Constraints to a Generic

Restricting Generic Argument Types

Types passed into a function can be used to infer types in an object that gets returned.

Use Multiple Generics with a Function

Typing Independent Parameters

Generics work really well with Type Helpers. One use case is typing properties that are passed in as part of an object.

Approaches for Typing Object Parameters

In Excalidraw's codebase, we'll examine a sum function that accepts an array and a mapper function used to reduce values down to a number.

Generic Functions in Excalidraw

Here you will learn how generics can be used to allow you to pass in typed properties of any shape when instantiating a class.

Add Types to a Class

Generics in Classes

With generics you can specify that certain properties are present and of a specific type while also allowing for any additional properties to be present.

Add Object Property Constraints to a Generic

Generic Mapper Function

Orta Therox, an ex-TypeScript team member, says generics are crucial to avoid lengthy types in its structural type system, unlike Objective-C's nominal types.

The Importance of Generics in TypeScript

The TypeScript docs for generics have info and examples on creating and using generic types.

Generics section of the TypeScript docs

Learn more about the unknown type in the TypeScript docs

The unknown Type from the TypeScript Docs

The "Generic Constraints" page from the TypeScript documentation provides detailed information on how to define constraints for generic types

Generic Constraints from the TypeScript Docs

The Classes section of the TypeScript docs provides detailed information on how to use generics with classes, including examples and best practices.

Classes section of the TypeScript docs

See a real-world example of how generics are used in a software project.

gesture.ts from the Excalidraw GitHub Repo

A refresher from the Type Transformations workshop lesson, "Support Function Type Constraints with Variable Arguments", showing extends in action.

Total TypeScript - The Extends Keyword in action

Intro to Generics

Many of TypeScript's built-in types support type arguments. With help from generics you can specify the types that a function accepts and returns.

Pass Type Arguments to a Function

Add Type Parameters to a Function

By adding a default generic, you ensure that your functions remain type safe. The generic context follows a similar pattern to the type helper context.

Specify a Default Value

Defaults in Type Parameters

Generic slots can be added to the type arguments of classes or type helpers.

Infer from the Type Arguments of a Class

Infer Types from Type Arguments

Generics are captured at different levels based on where they're called. Here we'll examine how generics are used in a reduce function.

Pass Type Arguments to a Reduce Function

Strongly Type a Reduce Function

Not all libraries support generics by default. Fortunately, there are some techniques for working around this with help from generics.

Use Generics to Type a Fetch Request

Avoid any Types with Generics

The repo for cal.com contains several examples of how passing type arguments allows for overriding the weaknesses of external libraries.

Passing Type Arguments in cal.com

Improving Code Maintainability

MDN reference for the Set object in JavaScript, which is a collection of unique values.

JavaScript Set from MDN

Documentation for the Record utility type in the TypeScript Handbook.

Record Types from the TypesScript docs

TypeScript's reduce method signature on GitHub in the type declaration file used as a reference for JavaScript's built-in objects available in TypeScript.

TypeScript's reduce type signature from its source on GitHub

TypeScript's DOM lib provides the types for interacting with the Document Object Model. 

fetch, Response, and Body from TypeScript's DOM lib source on GitHub

Documentation for the Awaited utility type in the TypeScript Handbook. This type can be used to extract the type of a Promise or Async value.

Awaited Utility Type from the TypeScript docs

A TypeScript class for interacting with the SendGrid email service in the cal.com repository.

Sengrid.ts from the Cal.com Github Repo

Passing Type Arguments

The approach you take to generics impacts how far you have to drill into objects, and the readability of your code on the whole.

Represent Generics at the Lowest Level

Generics at Different Levels

This section is all about figuring out how best to represent these generics in terms of the things that are being passed into functions.

Two Approaches for Typing Object Keys

Typed Object Keys

Generics allow you to type arguments for functions that are passed to other functions.

Constrain a Type Argument to a Function

Make a Generic Wrapper for a Function

Learn how to ensure the accurate literal inference of type arguments using constraints.

Understand Literal Inference in Generics

The choice of representing types in type arguments can impact literal inference. Constraints like "as const" can refine it.

Understand Generic Inference When Using Objects as Arguments

Restrict inputs and infer literal types in TypeScript by applying constraints on the type parameter.

To accept multiple literal types and infer them, T should be extended with union types like "string | number"

Accepting Multiple Literal Types

Inferring Literal Types from any Basic Type

Going with the lowest-level and tightest representation in your generics leads to good results and better inference.

Constrain to the Array Member, Not the Array

Infer the Type of an Array Member

It doesn't necessarily take hard work to get good inference. Choosing which generics to use and where to place them is key.

Two Approaches to Working with Class Names

Generics in a Class Names Creator

Tanner Lindsley explains how to use descriptive names for generics in React Query to ensure proper function flow and passing in the right slots.

Generics in React Query

The official TypeScript documentation for the Keyof Type Operator.

Keyof Type Operator from the TypeScript Docs

The official TypeScript documentation for Type Assertions.

Type Assertions from the TypeScript Docs

The official TypeScript documentation for the Record Utility Type.

Record Utility Type from the TypeScript Docs

Study the source code to gain a deeper understanding of how the Object.keys() method works.

Object.keys() from the TypeScript Source Code

The official TypeScript documentation for Tuple Types.

Tuple Types from the TypeScript Docs

The official TypeScript documentation for the Parameters Utility Type.

Parameters Utility Type from the TypeScript Docs

The official TypeScript documentation for the ReturnType Utility Type.

ReturnType Utility Type from the TypeScript Docs

The Art of Type Arguments

TypeScript isn't clever enough on its own to map a conditional type in the return of a function.

Ensure Runtime Level & Type Level Safety with Conditional Types

Generics with Conditional Types

TypeScript has a limitation of not trusting narrowing inside of a generic function. Using a technique to add better inference gets us around this.

Fixing the "Not Assignable" Error

Fixing Errors in Generic Functions

Curried functions accept arguments that return functions. It's possible to use generic arguments to ensure these returned functions are properly typed.

Fix Type Inference in Curried Functions

Generic Function Currying

Understanding how generics work at different levels of functions will help you when structuring chained arguments and other complicated types.

Understanding Generics at Different Levels of Functions

Generic Interfaces with Functions

Sometimes it's possible to refactor a function with multiple generics to maintain the same functionality with a single generic.

Refactoring Functions with Unnecessary Type Arguments

Spotting Useless Generics

On the flip side of the previous exercise, sometimes additional generics should be added to allow for more specific types.

Improving Type Inference with Additional Generics

Spotting Missing Generics

How tRPC Handles Inheritable Generics

Improve a theme API in TypeScript by creating a factory that returns a function that already has its theme interface passed in.

With factory functions, you can avoid passing the same type argument repeatedly, creating cleaner theming systems.

Create a Factory Function to Apply Type Arguments to All Child Functions

Refactoring Generics for a Cleaner API

In TypeScript, passing multiple type arguments to functions can cause partial inference issues.

A workaround to TypeScript's lack of partial inference can be achieved by splitting type arguments over two function calls.

A Workaround for The Lack of Partial Inference

The Partial Inference Problem

Advanced Generics

Function overloads can be used to handle different input and return types, similar to generics.

Understanding Function Overloads

What is a Function Overload?

There are often many ways to solve a problem. Here we revisit an earlier exercise that used conditional types and compare it to a function overload approach.

Match Return Types with Function Overloads

Function Overloads vs. Conditional Types

It can be difficult to be type safe with a function overload. Do your best to ensure the user gets what they expect.

Specifying Types for an Overloaded Function 

Debugging Overloaded Functions

Function overloads work best when used correctly. Think carefully about what technique you should use when writing your functions.

When to Use Overloads and Unions

Function Overloads vs. Union Types

Function overloads can work together with generics to make functions behave differently based on their input.

Typing Different Function Use Cases

Generics in Function Overloads

Function overloads allow for different ways to call your function. This is great for scenarios with different type signatures.

Split Functions Into Two Different Call Signatures

Use Function Overloads to Infer Initial Data

Function overloads are great for preventing one of TypeScript's oddest errors where TypeScript can't infer what type a function should be called with.

Handling Default Arguments with Function Overloads

The "Instantiated with Subtype" Error

TypeScript declaration file for the DOM API that helps you write type-safe and efficient code.

TypeScript DOM Source Code on GitHub

Function Overloads

Refactor a function to handle generic data, enforce property existence, and ensure correct type inference with initial data.

Introduce a Type Parameter to Ensure Type Consistency

Make An Infinite Scroll Function Generic with Correct Type Inference

Create a function to accept dynamic arguments for "click" and "focus" events, adding an extra argument for "click" with a specified shape.

Use a Tuple to Represent a Dynamic Number of Arguments

Create a Function with a Dynamic Number of Arguments

Create a function that chooses specific keys from an object, ensures type safety, and prevents invalid keys.

Extracting Object Properties with Reduce and Generics

Create a Pick Function

Develop functions with complex nested structures that use generic types to validate user input based on specified rules.

Add Strong Typing and Proper Error Handling to a Form Validator

Create a Form Validation Library

Modify fetchData to handle missing type arguments to return clear error messages, without compromising its functionality or usability.

Modify a Generic Type Default for Improved Error Messages

Improve a Fetch Function to Handle Missing Type Arguments

Correctly type a composition of up to five functions with arbitrary input and output types, using overloads and generics.

Using Overloads and Generics to Type Function Composition

Typing a Function Composition with Overloads and Generics

It's possible to dynamically type arguments based on what is being passed in, allowing for stronger typing and better inference.

Adding conditional types and type constraints ensure good inference and strong typing for dynamic arguments.

Transcript

Solving an Inference Mystery

Transcript