From a49ba95af828eeca490e1f22f9dcbbb0b47548d5 Mon Sep 17 00:00:00 2001
From: Ian Hickson <ian@hixie.ch>
Date: Mon, 10 Aug 2020 11:11:02 -0700
Subject: [PATCH] Some minor improvements to the AsyncSnapshot API (#63347)

---
 packages/flutter/lib/src/widgets/async.dart   | 11 +++++++++++
 packages/flutter/test/widgets/async_test.dart |  8 ++++++++
 2 files changed, 19 insertions(+)

diff --git a/packages/flutter/lib/src/widgets/async.dart b/packages/flutter/lib/src/widgets/async.dart
index 0bf8f9d163b..60249cdb5e7 100644
--- a/packages/flutter/lib/src/widgets/async.dart
+++ b/packages/flutter/lib/src/widgets/async.dart
@@ -163,6 +163,14 @@ class _StreamBuilderBaseState<T, S> extends State<StreamBuilderBase<T, S>> {
 
 /// The state of connection to an asynchronous computation.
 ///
+/// The usual flow of state is as follows:
+///
+/// 1. [none], maybe with some initial data.
+/// 2. [waiting], indicating that the asynchronous operation has begun,
+///    typically with the data being null.
+/// 3. [active], with data being non-null, and possible changing over time.
+/// 4. [done], with data being non-null.
+///
 /// See also:
 ///
 ///  * [AsyncSnapshot], which augments a connection state with information
@@ -206,6 +214,9 @@ class AsyncSnapshot<T> {
   /// Creates an [AsyncSnapshot] in [ConnectionState.none] with null data and error.
   const AsyncSnapshot.nothing() : this._(ConnectionState.none, null, null);
 
+  /// Creates an [AsyncSnapshot] in [ConnectionState.waiting] with null data and error.
+  const AsyncSnapshot.waiting() : this._(ConnectionState.waiting, null, null);
+
   /// Creates an [AsyncSnapshot] in the specified [state] and with the specified [data].
   const AsyncSnapshot.withData(ConnectionState state, T data) : this._(state, data, null);
 
diff --git a/packages/flutter/test/widgets/async_test.dart b/packages/flutter/test/widgets/async_test.dart
index 36e60fb42fc..a4872d2a0f2 100644
--- a/packages/flutter/test/widgets/async_test.dart
+++ b/packages/flutter/test/widgets/async_test.dart
@@ -32,6 +32,14 @@ void main() {
         throwsStateError,
       );
     });
+    test('AsyncSnapshot basic constructors', () {
+      expect(const AsyncSnapshot<int>.nothing().connectionState, ConnectionState.none);
+      expect(const AsyncSnapshot<int>.nothing().data, isNull);
+      expect(const AsyncSnapshot<int>.nothing().error, isNull);
+      expect(const AsyncSnapshot<int>.waiting().connectionState, ConnectionState.waiting);
+      expect(const AsyncSnapshot<int>.waiting().data, isNull);
+      expect(const AsyncSnapshot<int>.waiting().error, isNull);
+    });
   });
   group('Async smoke tests', () {
     testWidgets('FutureBuilder', (WidgetTester tester) async {