Add "Command Pattern" and "Result Class" design patterns

examples/cookbook/architecture/command/analysis_options.yaml

@@ -0,0 +1,5 @@
+# Take our settings from the example_utils analysis_options.yaml file.
+# If necessary for a particular example, this file can also include
+# overrides for individual lints.
+
+include: package:example_utils/analysis.yaml

examples/cookbook/architecture/command/lib/command.dart

@@ -0,0 +1,104 @@
+// Copyright 2024 The Flutter team. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+
+import 'result.dart';
+
+/// Defines a command action that returns a [Result] of type [T].
+/// Used by [Command0] for actions without arguments.
+typedef CommandAction0<T> = Future<Result<T>> Function();
+
+/// Defines a command action that returns a [Result] of type [T].
+/// Takes an argument of type [A].
+/// Used by [Command1] for actions with one argument.
+typedef CommandAction1<T, A> = Future<Result<T>> Function(A);
+
+/// Facilitates interaction with a view model.
+///
+/// Encapsulates an action,
+/// exposes its running and error states,
+/// and ensures that it can't be launched again until it finishes.
+///
+/// Use [Command0] for actions without arguments.
+/// Use [Command1] for actions with one argument.
+///
+/// Actions must return a [Result] of type [T].
+///
+/// Consume the action result by listening to changes,
+/// then call to [clearResult] when the state is consumed.
+abstract class Command<T> extends ChangeNotifier {
+  bool _running = false;
+
+  /// Whether the action is running.
+  bool get running => _running;
+
+  Result<T>? _result;
+
+  /// Whether the action completed with an error.
+  bool get error => _result is Error;
+
+  /// Whether the action completed successfully.
+  bool get completed => _result is Ok;
+
+  /// The result of the most recent action.
+  ///
+  /// Returns `null` if the action is running or completed with an error.
+  Result<T>? get result => _result;
+
+  /// Clears the most recent action's result.
+  void clearResult() {
+    _result = null;
+    notifyListeners();
+  }
+
+  /// Execute the provided [action], notifying listeners and
+  /// setting the running and result states as necessary.
+  Future<void> _execute(CommandAction0<T> action) async {
+    // Ensure the action can't launch multiple times.
+    // e.g. avoid multiple taps on button
+    if (_running) return;
+
+    // Notify listeners.
+    // e.g. button shows loading state
+    _running = true;
+    _result = null;
+    notifyListeners();
+
+    try {
+      _result = await action();
+    } finally {
+      _running = false;
+      notifyListeners();
+    }
+  }
+}
+
+/// A [Command] that accepts no arguments.
+final class Command0<T> extends Command<T> {
+  /// Creates a [Command0] with the provided [CommandAction0].
+  Command0(this._action);
+
+  final CommandAction0<T> _action;
+
+  /// Executes the action.
+  Future<void> execute() async {
+    await _execute(() => _action());
+  }
+}
+
+/// A [Command] that accepts one argument.
+final class Command1<T, A> extends Command<T> {
+  /// Creates a [Command1] with the provided [CommandAction1].
+  Command1(this._action);
+
+  final CommandAction1<T, A> _action;
+
+  /// Executes the action with the specified [argument].
+  Future<void> execute(A argument) async {
+    await _execute(() => _action(argument));
+  }
+}

examples/cookbook/architecture/command/lib/extended_command.dart

@@ -0,0 +1,38 @@
+import 'package:flutter/material.dart';
+
+// #docregion HomeViewModel
+class HomeViewModel extends ChangeNotifier {
+  HomeViewModel() {
+    load = Command0(_load)..execute();
+    edit = Command1<String>(_edit);
+  }
+
+  User? get user => null;
+
+  // Command0 accepts 0 arguments
+  late final Command0 load;
+
+  // Command1 accepts 1 argument
+  late final Command1 edit;
+
+  Future<void> _load() async {
+    // load user
+  }
+
+  Future<void> _edit(String name) async {
+    // edit user
+  }
+}
+// #enddocregion HomeViewModel
+
+class User {}
+
+class Command0 {
+  Command0(Future<void> Function() any);
+
+  void execute() {}
+}
+
+class Command1<T> {
+  Command1(Future<void> Function(T) any);
+}

examples/cookbook/architecture/command/lib/main.dart

@@ -0,0 +1,184 @@
+import 'package:flutter/material.dart';
+
+class MainApp extends StatefulWidget {
+  const MainApp({
+    super.key,
+    required this.viewModel,
+  });
+
+  final HomeViewModel viewModel;
+
+  @override
+  State<MainApp> createState() => _MainAppState();
+}
+
+class _MainAppState extends State<MainApp> {
+  // #docregion addListener
+  @override
+  void initState() {
+    super.initState();
+    widget.viewModel.addListener(_onViewModelChanged);
+  }
+
+  @override
+  void dispose() {
+    widget.viewModel.removeListener(_onViewModelChanged);
+    super.dispose();
+  }
+  // #enddocregion addListener
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        // #docregion CommandListenable
+        // #docregion ListenableBuilder
+        body: ListenableBuilder(
+          listenable: widget.viewModel.load,
+          builder: (context, child) {
+            if (widget.viewModel.load.running) {
+              return const Center(
+                child: CircularProgressIndicator(),
+              );
+            }
+            // #enddocregion CommandListenable
+
+            if (widget.viewModel.load.error != null) {
+              return Center(
+                child: Text('Error: ${widget.viewModel.load.error}'),
+              );
+            }
+
+            return child!;
+          },
+          child: ListenableBuilder(
+            listenable: widget.viewModel,
+            builder: (context, _) {
+              // #enddocregion ListenableBuilder
+              if (widget.viewModel.user == null) {
+                return const Center(
+                  child: Text('No user'),
+                );
+              }
+
+              return Center(
+                child: Column(
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    Text('Name: ${widget.viewModel.user!.name}'),
+                    Text('Email: ${widget.viewModel.user!.email}'),
+                  ],
+                ),
+              );
+              // #docregion ListenableBuilder
+            },
+          ),
+          // #docregion CommandListenable
+        ),
+        // #enddocregion ListenableBuilder
+        // #enddocregion CommandListenable
+      ),
+    );
+  }
+
+  // #docregion _onViewModelChanged
+  void _onViewModelChanged() {
+    if (widget.viewModel.load.error != null) {
+      widget.viewModel.load.clear();
+      // Show Snackbar
+    }
+  }
+  // #enddocregion _onViewModelChanged
+}
+
+class User {
+  User({required this.name, required this.email});
+
+  final String name;
+  final String email;
+}
+
+// #docregion HomeViewModel
+class HomeViewModel extends ChangeNotifier {
+  // #docregion ViewModelInit
+  HomeViewModel() {
+    load = Command(_load)..execute();
+  }
+  // #enddocregion ViewModelInit
+
+  User? get user => null;
+
+  late final Command load;
+
+  Future<void> _load() async {
+    // load user
+  }
+}
+// #enddocregion HomeViewModel
+
+// #docregion HomeViewModel2
+class HomeViewModel2 extends ChangeNotifier {
+  HomeViewModel2() {
+    load = Command(_load)..execute();
+    delete = Command(_delete);
+  }
+
+  User? get user => null;
+
+  late final Command load;
+
+  late final Command delete;
+
+  Future<void> _load() async {
+    // load user
+  }
+
+  Future<void> _delete() async {
+    // delete user
+  }
+}
+// #enddocregion HomeViewModel2
+
+// #docregion Command
+class Command extends ChangeNotifier {
+  Command(this._action);
+
+  bool _running = false;
+  bool get running => _running;
+
+  Exception? _error;
+  Exception? get error => _error;
+
+  bool _completed = false;
+  bool get completed => _completed;
+
+  final Future<void> Function() _action;
+
+  Future<void> execute() async {
+    if (_running) {
+      return;
+    }
+
+    _running = true;
+    _completed = false;
+    _error = null;
+    notifyListeners();
+
+    try {
+      await _action();
+      _completed = true;
+    } on Exception catch (error) {
+      _error = error;
+    } finally {
+      _running = false;
+      notifyListeners();
+    }
+  }
+
+  void clear() {
+    _running = false;
+    _error = null;
+    _completed = false;
+  }
+}
+// #enddocregion Command