update rec for null check

Author: MaryaBelanger

examples/misc/lib/effective_dart/usage_good.dart

@@ -350,19 +350,25 @@ class Response {
   String get reason => '';
 }
 
-// #docregion shadow-nullable-field
+// #docregion shadow-nullable-field, null-check-promo
 class UploadException {
   final Response? response;
 
   UploadException([this.response]);
 
   @override
   String toString() {
+    // #enddocregion null-check-promo
     final response = this.response;
     if (response != null) {
       return 'Could not complete upload to ${response.url} '
           '(error code ${response.errorCode}): ${response.reason}.';
     }
+    // #docregion null-check-promo
+    if (this.response case var response?) {
+      return 'Could not complete upload to ${response.url} '
+          '(error code ${response.errorCode}): ${response.reason}.';
+    }
 
     return 'Could not upload (no response).';
   }

src/content/effective-dart/usage.md

@@ -325,7 +325,8 @@ Of course, if `null` is a valid initialized value for the variable,
 then it probably does make sense to have a separate boolean field.
 
 
-### CONSIDER assigning a nullable field to a local variable to enable type promotion
+### CONSIDER work arounds to bypass type promotion limitations
+(or, "...to enable type promotion")
 
 Checking that a nullable variable is not equal to `null` promotes the variable
 to a non-nullable type. That lets you access members on the variable and pass it
@@ -337,7 +338,31 @@ private final fields. Values that are open to manipulation
 
 Declaring members [private][] and [final][], as we generally recommend, is often
 enough to bypass these limitations. But, that's not always an option.
-One pattern to work around this is to assign the field's value
+
+One pattern to work around type promotion limitations is to use a
+[null-check pattern][] to simultaneously confirm the member's value is not null,
+and bind that value to a new non-nullable variable of the same base type.
+
+<?code-excerpt "usage_good.dart (null-check-promo)"?>
+```dart tag=good
+class UploadException {
+  final Response? response;
+
+  UploadException([this.response]);
+
+  @override
+  String toString() {
+    if (this.response case var response?) {
+      return 'Could not complete upload to ${response.url} '
+          '(error code ${response.errorCode}): ${response.reason}.';
+    }
+
+    return 'Could not upload (no response).';
+  }
+}
+```
+
+Another work around is to assign the field's value
 to a local variable. Null checks on that variable will promote,
 so you can safely treat it as non-nullable.
 
@@ -361,8 +386,16 @@ class UploadException {
 }
 ```
 
-Assigning to a local variable can be cleaner and safer than using `!` every
-time you need to treat the value as non-null:
+Be careful when using a local variable. If you need to write back to the field,
+make sure that you don't write back to the local variable instead. (Making the
+local variable [`final`][] can prevent such mistakes.) Also, if the field might
+change while the local is still in scope, then the local might have a stale
+value. 
+
+Sometimes it's best to simply [use `!`][] on the field. 
+In some cases, though, using either a local variable or a null-check pattern 
+can be cleaner and safer than using `!` every time you need to treat the value
+as non-null:
 
 <?code-excerpt "usage_bad.dart (shadow-nullable-field)" replace="/!\./[!!!]./g"?>
 ```dart tag=bad
@@ -383,15 +416,10 @@ class UploadException {
 }
 ```
 
-Be careful when using a local variable. If you need to write back to the field,
-make sure that you don't write back to the local variable instead. (Making the
-local variable [`final`][] can prevent such mistakes.) Also, if the field might
-change while the local is still in scope, then the local might have a stale
-value. Sometimes it's best to simply [use `!`][] on the field.
-
 [can't be type promoted]: /tools/non-promotion-reasons
 [private]: /effective-dart/design#prefer-making-declarations-private
 [final]: /effective-dart/design#prefer-making-fields-and-top-level-variables-final
+[null-check pattern]: /language/pattern-types#null-check
 [`final`]: /effective-dart/usage#do-follow-a-consistent-rule-for-var-and-final-on-local-variables
 [use `!`]: /null-safety/understanding-null-safety#non-null-assertion-operator