From 37fed0b7e971d14c94e97fa3dd09036a0325c8a8 Mon Sep 17 00:00:00 2001 From: Allan Deutsch Date: Sat, 11 May 2024 23:10:16 -0700 Subject: [PATCH 1/2] Provide context about when to use type predicates and assertion functions Updated based on discussion in #57436 --- packages/documentation/copy/en/handbook-v2/Narrowing.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/handbook-v2/Narrowing.md b/packages/documentation/copy/en/handbook-v2/Narrowing.md index 34044be7c6f5..6e3aedce536b 100644 --- a/packages/documentation/copy/en/handbook-v2/Narrowing.md +++ b/packages/documentation/copy/en/handbook-v2/Narrowing.md @@ -415,7 +415,9 @@ function example() { ## Using type predicates -We've worked with existing JavaScript constructs to handle narrowing so far, however sometimes you want more direct control over how types change throughout your code. +We've worked with existing JavaScript constructs to handle narrowing so far, however sometimes you want more direct control over how types change throughout your code. Type predicates provide a way to perform type narrowing in scenarios where the TypeScript compiler is *unable* to do so. + +Type predicates supersede the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Type predicates should be a last resort for narrowing that cannot be done any other way.** To define a user-defined type guard, we simply need to define a function whose return type is a _type predicate_: @@ -483,6 +485,11 @@ In addition, classes can [use `this is Type`](/docs/handbook/2/classes.html#this Types can also be narrowed using [Assertion functions](/docs/handbook/release-notes/typescript-3-7.html#assertion-functions). +As with [type predicates](#using-type-predicates), assertion functions provide a way to perform type narrowing in scenarios where the TypeScript compiler is *unable* to do so. + +Assertion functions supersede the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Assertion functions should be a last resort for narrowing that cannot be done any other way.** + + # Discriminated unions Most of the examples we've looked at so far have focused around narrowing single variables with simple types like `string`, `boolean`, and `number`. From 849331a9a3f143d383cb5e01c5569cf66e7b77ed Mon Sep 17 00:00:00 2001 From: Allan Deutsch Date: Sun, 12 May 2024 09:10:26 -0700 Subject: [PATCH 2/2] supersede -> bypass Updated based on feedback from Jake Bailey --- packages/documentation/copy/en/handbook-v2/Narrowing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation/copy/en/handbook-v2/Narrowing.md b/packages/documentation/copy/en/handbook-v2/Narrowing.md index 6e3aedce536b..2c1acd4df153 100644 --- a/packages/documentation/copy/en/handbook-v2/Narrowing.md +++ b/packages/documentation/copy/en/handbook-v2/Narrowing.md @@ -417,7 +417,7 @@ function example() { We've worked with existing JavaScript constructs to handle narrowing so far, however sometimes you want more direct control over how types change throughout your code. Type predicates provide a way to perform type narrowing in scenarios where the TypeScript compiler is *unable* to do so. -Type predicates supersede the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Type predicates should be a last resort for narrowing that cannot be done any other way.** +Type predicates bypass the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Type predicates should be a last resort for narrowing that cannot be done any other way.** To define a user-defined type guard, we simply need to define a function whose return type is a _type predicate_: @@ -487,7 +487,7 @@ Types can also be narrowed using [Assertion functions](/docs/handbook/release-no As with [type predicates](#using-type-predicates), assertion functions provide a way to perform type narrowing in scenarios where the TypeScript compiler is *unable* to do so. -Assertion functions supersede the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Assertion functions should be a last resort for narrowing that cannot be done any other way.** +Assertion functions bypass the TypeScript compiler's type checking. This means that they can be used to change a value's type to an incorrect type. **Assertion functions should be a last resort for narrowing that cannot be done any other way.** # Discriminated unions