Release v9.2.0: Add CommandBuilder auto-run and deprecate Command.toWidget()

escamoteur · escamoteur · commit e72c64e43398 · 2025-11-22T16:12:11.000-05:00
New Features:
- CommandBuilder now supports automatically executing commands on first build
  via runCommandOnFirstBuild parameter, eliminating StatefulWidget boilerplate
  for simple data loading scenarios (especially useful for non-watch_it users)
- Added initialParam parameter to pass parameters when auto-running commands

Deprecations:
- Deprecated Command.toWidget() in favor of CommandResult.toWidget() which
  provides a richer API with better separation of concerns (onData/onSuccess/
  onNullData). Removal planned for v10.0.0.

Breaking Changes:
- CommandBuilder is now a StatefulWidget instead of StatelessWidget (should
  not affect users as the widget API remains the same)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,49 @@
+[9.2.0] - 2025-11-22
+
+### New Features
+
+- **CommandBuilder Auto-Run**: CommandBuilder now supports automatically executing commands on first build via `runCommandOnFirstBuild` parameter. This is especially useful for non-watch_it users who want self-contained data-loading widgets without needing StatefulWidget boilerplate.
+
+```dart
+CommandBuilder<String, List<Item>>(
+  command: searchCommand,
+  runCommandOnFirstBuild: true,  // Executes in initState
+  initialParam: 'flutter',        // Parameter to pass
+  onData: (context, items, _) => ItemList(items),
+  whileRunning: (context, _, __) => LoadingIndicator(),
+)
+```
+
+**Benefits:**
+- Eliminates StatefulWidget boilerplate for simple data loading
+- Self-contained widgets that manage their own data fetching
+- Runs only once in initState (not on rebuilds)
+- Perfect for non-watch_it users (watch_it users should continue using `callOnce`)
+
+### Deprecations
+
+- **Deprecated Command.toWidget()**: The `Command.toWidget()` method is now deprecated in favor of `CommandResult.toWidget()`. The CommandResult version provides a richer API with better separation of concerns (onData/onSuccess/onNullData) and is already used by CommandBuilder. Command.toWidget() will be removed in v10.0.0.
+
+**Migration:**
+```dart
+// Before (deprecated):
+command.toWidget(
+  onResult: (data, param) => DataWidget(data),
+  whileRunning: (lastData, param) => LoadingWidget(),
+  onError: (error, param) => ErrorWidget(error),
+)
+
+// After (recommended):
+ValueListenableBuilder(
+  valueListenable: command.results,
+  builder: (context, result, _) => result.toWidget(
+    onData: (data, param) => DataWidget(data),
+    whileRunning: (lastData, param) => LoadingWidget(),
+    onError: (error, lastData, param) => ErrorWidget(error),
+  ),
+)
+```
+
 [9.1.1] - 2025-11-21
 
 ### Improvements
diff --git a/lib/command_builder.dart b/lib/command_builder.dart
@@ -1,6 +1,6 @@
 part of command_it;
 
-class CommandBuilder<TParam, TResult> extends StatelessWidget {
+class CommandBuilder<TParam, TResult> extends StatefulWidget {
   final Command<TParam, TResult> command;
 
   /// This builder will be called when the
@@ -40,6 +40,17 @@ class CommandBuilder<TParam, TResult> extends StatelessWidget {
     TParam?,
   )? onError;
 
+  /// If true, the command will be executed once when the widget is first built.
+  /// This is useful for loading data when the widget is mounted, especially when
+  /// not using watch_it (which provides `callOnce` for this purpose).
+  ///
+  /// The command will only run once in initState, not on subsequent rebuilds.
+  final bool runCommandOnFirstBuild;
+
+  /// The parameter to pass to the command when [runCommandOnFirstBuild] is true.
+  /// Ignored if [runCommandOnFirstBuild] is false.
+  final TParam? initialParam;
+
   const CommandBuilder({
     required this.command,
     this.onSuccess,
@@ -53,41 +64,60 @@ class CommandBuilder<TParam, TResult> extends StatelessWidget {
     )
     this.whileExecuting,
     this.onError,
+    this.runCommandOnFirstBuild = false,
+    this.initialParam,
     super.key,
   });
 
+  @override
+  State<CommandBuilder<TParam, TResult>> createState() =>
+      _CommandBuilderState<TParam, TResult>();
+}
+
+class _CommandBuilderState<TParam, TResult>
+    extends State<CommandBuilder<TParam, TResult>> {
+  @override
+  void initState() {
+    super.initState();
+    if (widget.runCommandOnFirstBuild) {
+      widget.command(widget.initialParam);
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
-    if (command._noReturnValue) {}
+    if (widget.command._noReturnValue) {}
     return ValueListenableBuilder<CommandResult<TParam?, TResult>>(
-      valueListenable: command.results,
+      valueListenable: widget.command.results,
       builder: (context, result, _) {
         return result.toWidget(
-          onData: onData != null
-              ? (data, paramData) => onData!.call(context, data, paramData)
+          onData: widget.onData != null
+              ? (data, paramData) =>
+                  widget.onData!.call(context, data, paramData)
               : null,
-          onSuccess: onSuccess != null
-              ? (paramData) => onSuccess!.call(context, paramData)
+          onSuccess: widget.onSuccess != null
+              ? (paramData) => widget.onSuccess!.call(context, paramData)
               : null,
-          onNullData: onNullData != null
-              ? (paramData) => onNullData!.call(context, paramData)
+          onNullData: widget.onNullData != null
+              ? (paramData) => widget.onNullData!.call(context, paramData)
               : null,
           // ignore: deprecated_member_use_from_same_package
-          whileRunning: (whileRunning ?? whileExecuting) != null
+          whileRunning: (widget.whileRunning ?? widget.whileExecuting) != null
               // ignore: deprecated_member_use_from_same_package
-              ? (lastData, paramData) => (whileRunning ?? whileExecuting)!
-                  .call(context, lastData, paramData)
+              ? (lastData, paramData) =>
+                  (widget.whileRunning ?? widget.whileExecuting)!
+                      .call(context, lastData, paramData)
               : null,
           onError: (error, lastData, paramData) {
-            if (onError == null) {
+            if (widget.onError == null) {
               return const SizedBox();
             }
             assert(
               result.errorReaction?.shouldCallLocalHandler == true,
-              'This CommandBuilder received an error from Command ${command.name} '
+              'This CommandBuilder received an error from Command ${widget.command.name} '
               'but the errorReaction indidates that the error should not be handled locally. ',
             );
-            return onError!.call(context, error, lastData, paramData);
+            return widget.onError!.call(context, error, lastData, paramData);
           },
         );
       },
diff --git a/lib/command_it.dart b/lib/command_it.dart
@@ -755,6 +755,10 @@ abstract class Command<TParam, TResult> extends CustomValueNotifier<TResult> {
   /// Returns a the result of one of three builders depending on the current state
   /// of the Command. This function won't trigger a rebuild if the command changes states
   /// so it should be used together with get_it_mixin, provider, flutter_hooks and the like.
+  @Deprecated(
+    'Use CommandResult.toWidget() instead. '
+    'This will be removed in v10.0.0.',
+  )
   Widget toWidget({
     required Widget Function(TResult lastResult, TParam? param) onResult,
     Widget Function(TResult lastResult, TParam? param)? whileRunning,
diff --git a/pubspec.yaml b/pubspec.yaml
@@ -1,6 +1,6 @@
 name: command_it
 description: command_it is a way to manage your state based on `ValueListenable` and the `Command` design pattern. It is a rebranding of flutter_command.
-version: 9.1.1
+version: 9.2.0
 homepage: https://github.com/flutter-it/command_it
 
 screenshots:
diff --git a/test/flutter_command_test.dart b/test/flutter_command_test.dart
@@ -1375,6 +1375,110 @@ void main() {
 
       expect(find.text('Success!'), findsOneWidget);
     });
+
+    testWidgets('Test CommandBuilder with runCommandOnFirstBuild=false',
+        (WidgetTester tester) async {
+      var executionCount = 0;
+      final testCommand = Command.createAsyncNoParamNoResult(() async {
+        executionCount++;
+        await Future<void>.delayed(const Duration(milliseconds: 100));
+      });
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: CommandBuilder<void, void>(
+              command: testCommand,
+              runCommandOnFirstBuild: false, // Should not run
+              onSuccess: (context, _) => const Text('Success!'),
+              whileRunning: (context, _, __) => const Text('Loading'),
+            ),
+          ),
+        ),
+      );
+
+      await tester.pump();
+
+      // Command should not have executed
+      expect(executionCount, 0);
+      expect(find.text('Loading'), findsNothing);
+    });
+
+    testWidgets(
+        'Test CommandBuilder with runCommandOnFirstBuild=true (no param)',
+        (WidgetTester tester) async {
+      var executionCount = 0;
+      final testCommand = Command.createAsyncNoParamNoResult(() async {
+        executionCount++;
+        await Future<void>.delayed(const Duration(milliseconds: 100));
+      });
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: CommandBuilder<void, void>(
+              command: testCommand,
+              runCommandOnFirstBuild: true,
+              onSuccess: (context, _) => const Text('Success!'),
+              whileRunning: (context, _, __) => const Text('Loading'),
+            ),
+          ),
+        ),
+      );
+
+      // Pump to allow initState to run and command to start
+      await tester.pump(const Duration(milliseconds: 10));
+
+      // Command should have executed once
+      expect(executionCount, 1);
+      expect(find.text('Loading'), findsOneWidget);
+
+      // Wait for command to complete
+      await tester.pump(const Duration(milliseconds: 200));
+
+      expect(find.text('Success!'), findsOneWidget);
+      expect(executionCount, 1); // Should still be 1 (not run again)
+    });
+
+    testWidgets(
+        'Test CommandBuilder with runCommandOnFirstBuild=true and initialParam',
+        (WidgetTester tester) async {
+      String? receivedParam;
+      final testCommand = Command.createAsync<String, String>(
+        (param) async {
+          receivedParam = param;
+          await Future<void>.delayed(const Duration(milliseconds: 100));
+          return 'Result: $param';
+        },
+        initialValue: '', // Named parameter
+      );
+
+      await tester.pumpWidget(
+        MaterialApp(
+          home: Scaffold(
+            body: CommandBuilder<String, String>(
+              command: testCommand,
+              runCommandOnFirstBuild: true,
+              initialParam: 'test-param',
+              onData: (context, data, _) => Text(data),
+              whileRunning: (context, _, __) => const Text('Loading'),
+            ),
+          ),
+        ),
+      );
+
+      // Pump to allow initState to run and command to start
+      await tester.pump(const Duration(milliseconds: 10));
+
+      // Command should have been called with the param
+      expect(receivedParam, 'test-param');
+      expect(find.text('Loading'), findsOneWidget);
+
+      // Wait for command to complete
+      await tester.pump(const Duration(milliseconds: 200));
+
+      expect(find.text('Result: test-param'), findsOneWidget);
+    });
   });
   group('UndoableCommand', () {
     test(
