flutter-it/command_it

command_it logo

command_it codecov

📚 Complete documentation available at flutter-it.dev Check out the comprehensive docs with detailed guides, examples, and best practices!

---

🔄 Migration Notice (v9.0.0)

Important: Version 9.0.0 introduces new, clearer API naming. The old API is deprecated and will be removed in v10.0.0.

Quick Migration: execute() → run() | isExecuting → isRunning | canExecute → canRun

Run dart fix --apply to automatically update most usages.

Complete migration guide →

---

Command pattern for Flutter - wrap functions as observable objects with automatic state management

Commands replace async methods with reactive alternatives. Wrap your functions, get automatic loading states, error handling, and UI integration. No manual state tracking, no try/catch everywhere.

Call them like functions. React to their state. Simple as that.

Part of flutter_it — A construction set of independent packages. command_it works standalone or combines with watch_it for reactive UI updates.

Why Commands?

• 🎯 Declarative — Wrap functions, get observable execution state automatically
• ⚡ Automatic State — isRunning, value, errors tracked without manual code
• 🛡️ Smart Error Handling — Route errors globally/locally with filters
• 🔒 Built-in Protection — Prevents parallel execution automatically
• 🎛️ Restrictions — Disable commands conditionally (auth, network, etc.)
• 🧪 Testable — Easier to test than traditional async methods

Learn more about the benefits →

Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  command_it: ^9.0.2
  listen_it: ^5.3.3  # Required - commands build on ValueListenable

Basic Example

import 'package:command_it/command_it.dart';

// 1. Create a command that wraps your async function
class CounterManager {
  int _counter = 0;

  late final incrementCommand = Command.createAsyncNoParam<String>(
    () async {
      await Future.delayed(Duration(milliseconds: 500));
      _counter++;
      return _counter.toString();
    },
    initialValue: '0',
  );
}

// 2. Use it in your UI - command is a ValueListenable
class CounterWidget extends StatelessWidget {
  final manager = CounterManager();

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // Shows loading indicator automatically while command runs
        ValueListenableBuilder<bool>(
          valueListenable: manager.incrementCommand.isRunning,
          builder: (context, isRunning, _) {
            if (isRunning) return CircularProgressIndicator();

            return ValueListenableBuilder<String>(
              valueListenable: manager.incrementCommand,
              builder: (context, value, _) => Text('Count: $value'),
            );
          },
        ),
        ElevatedButton(
          onPressed: manager.incrementCommand.run,
          child: Text('Increment'),
        ),
      ],
    );
  }
}

That's it! The command automatically:

• Prevents parallel execution
• Tracks isRunning state
• Publishes results
• Handles errors

Full tutorial

Using CommandBuilder

Simplify your UI code with the built-in builder widget:

CommandBuilder<void, String>(
  command: manager.incrementCommand,
  whileRunning: (context, _, __) => CircularProgressIndicator(),
  onData: (context, value, _) => Text('Count: $value'),
  onError: (context, error, _, __) => Text('Error: $error'),
)

Key Features

Command Types

Create commands for any function signature:

• createAsync — Async with parameter and result
• createAsyncNoParam — Async without parameter
• createAsyncNoResult — Async that returns nothing
• createSync — Sync with parameter and result
• Plus NoParam and NoResult variants for sync commands

Command Properties

Observe different aspects of execution:

• value — Last successful result
• isRunning — Async execution state
• isRunningSync — Synchronous version for restrictions
• canRun — Combined restriction and running state
• errors — Stream of errors
• results — CommandResult with all data at once

Error Handling

Declarative error routing with filters:

• Basic Error Handling — Listen to errors locally
• Global Handler — App-wide error handling
• Global Errors Stream — Reactive monitoring of all globally-routed errors
• Error Filters — Route errors by type or predicate
• Built-in Filters — GlobalIfNoLocalErrorFilter, PredicatesErrorFilter, etc.

Advanced Features

• Command Restrictions — Disable commands conditionally
• CommandBuilder — Widget for simpler UI code
• Undoable Commands — Built-in undo/redo support
• Command Piping — Chain commands together automatically
• Testing — Patterns for testing commands

Piping Commands

Chain commands together with the pipeToCommand() extension. When the source completes successfully, it automatically triggers the target command:

// Trigger refresh after save completes
saveCommand.pipeToCommand(refreshCommand);

// Transform result before passing to target
userIdCommand.pipeToCommand(fetchUserCommand, transform: (id) => UserRequest(id));

// Pipe from any ValueListenable - track execution state changes
longRunningCommand.isRunning.pipeToCommand(spinnerStateCommand);

The pipeToCommand() extension works on any ValueListenable, including commands, isRunning, results, or plain ValueNotifier. Returns a ListenableSubscription for manual cancellation if needed.

⚠️ Warning: Circular pipes (A→B→A) cause infinite loops. Ensure your pipe graph is acyclic.

Ecosystem Integration

Built on listen_it — Commands are ValueListenable objects, so they work with all listen_it operators (map, debounce, where, etc.).

// Register with get_it
di.registerLazySingleton(() => TodoManager());

// Use commands in your managers
class TodoManager {
  final loadTodosCommand = Command.createAsyncNoParam<List<Todo>>(
    () => api.fetchTodos(),
    [],
  );

  // Debounce search with listen_it operators
  final searchCommand = Command.createSync<String, String>((s) => s, '');

  TodoManager() {
    searchCommand.debounce(Duration(milliseconds: 500)).listen((term, _) {
      loadTodosCommand.run();
    });
  }
}

Want more? Combine with other flutter_it packages:

• listen_it — Required dependency. ValueListenable operators and reactive collections.

• Optional: watch_it — State management. Watch commands reactively without builders: watchValue((m) => m.loadCommand).

• Optional: get_it — Service locator for dependency injection. Access managers with commands from anywhere: di<TodoManager>().

💡 flutter_it is a construction set — command_it works standalone. Add watch_it and get_it when you need reactive UI and dependency injection.

Explore the ecosystem →

AI-Assisted Development

This package ships an Agent Skill for AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI and others) in skills/command-it-expert/. It teaches them the critical rules, common patterns and anti-patterns of command_it. Install it into your project with the official Dart skills tool:

dart run skills@ get

For the ecosystem-wide skills (architecture guidance, feed/data-source patterns, overview) and the skills of the other flutter_it packages run:

dart run skills@ add flutter-it/flutter_it

Learn more about AI skills →

Learn More

📖 Documentation

• Getting Started Guide — Installation, concepts, first command
• Command Basics — Creating and running commands
• Command Properties — value, isRunning, canRun, errors, results
• Command Types — Choosing the right factory function
• Error Handling — Basic error patterns
• Error Filters — Advanced error routing
• Command Restrictions — Conditional execution control
• Command Builders — Simplifying UI code
• Testing Commands — Test patterns and examples
• Integration with watch_it — Reactive UI updates
• Best Practices — Patterns, anti-patterns, tips

💬 Community & Support

• Discord — Get help, share ideas, connect with other developers
• GitHub Issues — Report bugs, request features
• GitHub Discussions — Ask questions, share patterns

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

License

MIT License - see LICENSE file for details.

---

Part of the flutter_it ecosystem — Build reactive Flutter apps the easy way. No codegen, no boilerplate, just code.