Merge pull request #25 from total-typescript/matt/added-section-on-automatically-inferred-type-predicates-for-5.5

Added section on automatically inferred type predicates for 5.5

Author: tayiorbeii

book-content/chapters/05-unions-literals-and-narrowing.md

@@ -904,6 +904,54 @@ it("Should error when anything else is passed in", () => {
 
 Your challenge is to modify the `parseValue` function so that the tests pass and the errors go away. I want you to challenge yourself to do this _only_ by narrowing the type of `value` inside of the function. No changes to the types. This will require a very large `if` statement!
 
+#### Exercise 3: Reusable Type Guards
+
+Let's imagine that we have two very similar functions, each with a long conditional check to narrow down the type of a value.
+
+Here's the first function:
+
+```typescript
+const parseValue = (value: unknown) => {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "object" &&
+    value.data !== null &&
+    "id" in value.data &&
+    typeof value.data.id === "string"
+  ) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+```
+
+And here's the second function:
+
+```typescript
+const parseValueAgain = (value: unknown) => {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "object" &&
+    value.data !== null &&
+    "id" in value.data &&
+    typeof value.data.id === "string"
+  ) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+```
+
+Both functions have the same conditional check. This is a great opportunity to create a reusable type guard.
+
+All the tests are currently passing. Your job is to try to refactor the two functions to use a reusable type guard, and remove the duplicated code. As it turns out, TypeScript makes this a lot easier than you expect.
+
 #### Solution 1: Narrowing Errors with `instanceof`
 
 The way to solve this challenge is to narrow the `error` using the `instanceof` operator.
@@ -1034,6 +1082,59 @@ Thanks to this huge conditional, our tests pass, and our error messages are gone
 
 This is usually _not_ how you'd want to write your code. It's a bit of a mess. You could use a library like [Zod](https://zod.dev) to do this with a much nicer API. But it's a great way to understand how `unknown` and narrowing work in TypeScript.
 
+#### Solution 3: Reusable Type Guards
+
+The first step is to create a function called `hasDataId` that captures the conditional check:
+
+```typescript
+const hasDataId = (value) => {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "object" &&
+    value.data !== null &&
+    "id" in value.data &&
+    typeof value.data.id === "string"
+  );
+};
+```
+
+We haven't given `value` a type here - `unknown` makes sense, because it could be anything.
+
+Now we can refactor the two functions to use this type guard:
+
+```typescript
+const parseValue = (value: unknown) => {
+  if (hasDataId(value)) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+
+const parseValueAgain = (value: unknown) => {
+  if (hasDataId(value)) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+```
+
+Incredibly, this is all TypeScript needs to be able to narrow the type of `value` inside of the `if` statement. It's smart enough to understand that `hasDataId` being called on `value` ensures that `value` has a `data` property with an `id` property.
+
+We can observe this by hovering over `hasDataId`:
+
+```typescript
+// hovering over `hasDataId` shows:
+const hasDataId: (value: unknown) => value is { data: { id: string } };
+```
+
+This return type we're seeing is a type predicate. It's a way of saying "if this function returns `true`, then the type of the value is `{ data: { id: string } }`".
+
+We'll look at authoring our own type predicates in one of the later chapters in the book - but it's very useful that TypeScript infers its own.
+
 ## Discriminated Unions
 
 In this section we'll look at a common pattern TypeScript developers use to structure their code. It's called a 'discriminated union'.

book-content/chapters/16-the-utils-folder.md

@@ -326,14 +326,14 @@ Note how clever TypeScript is being here. Even though we didn't specify a return
 
 ## Type Predicates
 
-A type predicate is a special return type that tells TypeScript that a function returns a Boolean value that says something about the type of one of its parameters.
+We were introduced to type predicates way back in chapter 5, when we looked at narrowing. They're used to capture reusable logic that narrows the type of a variable.
 
 For example, say we want to ensure that a variable is an `Album` before we try accessing its properties or passing it to a function that requires an `Album`.
 
-We can write an `isAlbum` function that takes in an input, and specifies a return type of `input is Album`. The body of the function will check that the `input` passed in is a non-null object with the required properties of an `Album`:
+We can write an `isAlbum` function that takes in an input, and checks for all the required properties.
 
 ```typescript
-function isAlbum(input: unknown): input is Album {
+function isAlbum(input: unknown) {
   return (
     typeof input === "object" &&
     input !== null &&
@@ -345,55 +345,91 @@ function isAlbum(input: unknown): input is Album {
 }
 ```
 
-The `input is Album` return type is the type predicate that tells TypeScript that if the function returns `true`, then the `input` parameter is of type `Album`. Otherwise, it isn't.
+If we hover over `isAlbum`, we can see a rather ugly type signature:
 
-### Narrowing with Type Predicates
+```typescript
+// hovering over isAlbum shows:
+function isAlbum(
+  input: unknown,
+): input is object &
+  Record<"id", unknown> &
+  Record<"title", unknown> &
+  Record<"artist", unknown> &
+  Record<"year", unknown>;
+```
 
-Type predicates are often used in conditional statements to narrow the type of a variable to become more specific.
+This is technically correct: a big intersection between an `object` and a bunch of `Record`s. But it's not very helpful.
 
-For example, we can use the `isAlbum` type predicate to check if an `item` is an `Album` before accessing its `title` property:
+When we try to use `isAlbum` to narrow the type of a value, TypeScript will infer lots of the values as `unknown`:
 
 ```typescript
-function getAlbumTitle(item: unknown) {
-  if (isAlbum(item)) {
-    return item.title;
+const run = (maybeAlbum: unknown) => {
+  if (isAlbum(maybeAlbum)) {
+    maybeAlbum.name.toUpperCase(); // red squiggly line under name
   }
-  return "Unknown Album";
-}
+};
+
+// hovering over name shows:
+// Object is of type 'unknown'.
 ```
 
-In this case, the `getAlbumTitle` function takes an `item` of type `unknown`. Inside the function, we use the `isAlbum` type predicate to check if the `item` is an `Album`. If it is, TypeScript narrows the type of `item` to `Album` within the conditional block, allowing us to access the `title` property without any type errors:
+To fix this, we'd need to add even more checks to `isAlbum` to ensure we're checking the types of all the properties:
 
 ```typescript
-let title = getAlbumTitle({
-  id: 1,
-  title: "Dummy",
-  artist: "Portishead",
-  year: 1994,
-});
-
-console.log(title); // "Dummy"
+function isAlbum(input: unknown) {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    "id" in input &&
+    "title" in input &&
+    "artist" in input &&
+    "year" in input &&
+    typeof input.id === "number" &&
+    typeof input.title === "string" &&
+    typeof input.artist === "string" &&
+    typeof input.year === "number"
+  );
+}
+```
 
-let notAnAlbumTitle = getAlbumTitle("Some string");
+This can feel far too verbose. We can make it more readable by adding our own type predicate.
 
-console.log(notAnAlbumTitle); // "Unknown Album"
+```typescript
+function isAlbum(input: unknown): input is Album {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    "id" in input &&
+    "title" in input &&
+    "artist" in input &&
+    "year" in input
+  );
+}
 ```
 
-### Type Predicates Can be Unsafe
+Now, when we use `isAlbum`, TypeScript will know that the type of the value has been narrowed to `Album`:
 
-Type predicates are a great technique to be aware of, and are particularly useful when working with union types.
+```typescript
+const run = (maybeAlbum: unknown) => {
+  if (isAlbum(maybeAlbum)) {
+    maybeAlbum.name.toUpperCase(); // No error!
+  }
+};
+```
 
-However, there are situations where they aren't as type-safe as they may appear.
+For complex type guards, this can be much more readable.
+
+### Type Predicates Can be Unsafe
 
-For example, if the type predicate doesn't match the actual type being checked, TypeScript won't catch that discrepancy:
+Authoring your own type predicates can be a little dangerous. If the type predicate doesn't accurately reflect the type being checked, TypeScript won't catch that discrepancy:
 
 ```typescript
 function isAlbum(input): input is Album {
   return typeof input === "object";
 }
 ```
 
-In this case, any object passed to `isAlbum` will be considered an `Album`, even if it doesn't have the required properties. This is a common pitfall when working with type predicates, and it's important to ensure that the type predicate accurately reflects the type being checked.
+In this case, any object passed to `isAlbum` will be considered an `Album`, even if it doesn't have the required properties. This is a common pitfall when working with type predicates - it's important to consider them about as unsafe as `as` and `!`.
 
 ## Assertion Functions
 

package.json

@@ -568,7 +568,27 @@
     "e-181.2": "tt-cli run 181.2",
     "s-181.2": "tt-cli run 181.2 --solution",
     "e-181.4": "tt-cli run 181.4",
-    "s-181.4": "tt-cli run 181.4 --solution"
+    "s-181.4": "tt-cli run 181.4 --solution",
+    "e-104.5": "tt-cli run 104.5",
+    "s-104.5": "tt-cli run 104.5 --solution",
+    "e-082.5": "tt-cli run 082.5",
+    "s-082.5": "tt-cli run 082.5 --solution",
+    "e-086.5": "tt-cli run 086.5",
+    "s-086.5": "tt-cli run 086.5 --solution",
+    "e-080.5": "tt-cli run 080.5",
+    "s-080.5": "tt-cli run 080.5 --solution",
+    "e-154.8": "tt-cli run 154.8",
+    "s-154.8": "tt-cli run 154.8 --solution",
+    "e-154.9": "tt-cli run 154.9",
+    "s-154.9": "tt-cli run 154.9 --solution",
+    "e-196.5": "tt-cli run 196.5",
+    "s-196.5": "tt-cli run 196.5 --solution",
+    "e-202.5": "tt-cli run 202.5",
+    "s-202.5": "tt-cli run 202.5 --solution",
+    "e-202.6": "tt-cli run 202.6",
+    "s-202.6": "tt-cli run 202.6 --solution",
+    "e-202.7": "tt-cli run 202.7",
+    "s-202.7": "tt-cli run 202.7 --solution"
   },
   "dependencies": {
     "@tanstack/react-query": "^4.29.12",

src/018-unions-and-narrowing/072.5-reusable-type-guards.problem.ts

@@ -0,0 +1,72 @@
+import { Equal, Expect } from "@total-typescript/helpers";
+import { describe, expect, it } from "vitest";
+
+const parseValue = (value: unknown) => {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "object" &&
+    value.data !== null &&
+    "id" in value.data &&
+    typeof value.data.id === "string"
+  ) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+
+const parseValueAgain = (value: unknown) => {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    typeof value.data === "object" &&
+    value.data !== null &&
+    "id" in value.data &&
+    typeof value.data.id === "string"
+  ) {
+    return value.data.id;
+  }
+
+  throw new Error("Parsing error!");
+};
+
+describe("parseValue", () => {
+  it("Should handle a { data: { id: string } }", () => {
+    const result = parseValue({
+      data: {
+        id: "123",
+      },
+    });
+
+    type test = Expect<Equal<typeof result, string>>;
+
+    expect(result).toBe("123");
+  });
+
+  it("Should error when anything else is passed in", () => {
+    expect(() => parseValue("123")).toThrow("Parsing error!");
+    expect(() => parseValue(123)).toThrow("Parsing error!");
+  });
+});
+
+describe("parseValueAgain", () => {
+  it("Should handle a { data: { id: string } }", () => {
+    const result = parseValueAgain({
+      data: {
+        id: "123",
+      },
+    });
+
+    type test = Expect<Equal<typeof result, string>>;
+
+    expect(result).toBe("123");
+  });
+
+  it("Should error when anything else is passed in", () => {
+    expect(() => parseValueAgain("123")).toThrow("Parsing error!");
+    expect(() => parseValueAgain(123)).toThrow("Parsing error!");
+  });
+});