flutter_it

https://flutter-it.dev
Admin
flutter_it is a modular construction set of reactive tools for Flutter that enables building...
Tokens:244,615
Snippets:1,836
Trust Score:5.2
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install flutter_it for Recommended Setup

Source: https://flutter-it.dev/documentation/command_it/getting_started

For a recommended setup that includes watch_it and get_it, add the flutter_it package to your pubspec.yaml. This provides a more integrated experience for state management.

```yaml
dependencies:
  flutter_it: ^1.0.0
```

--------------------------------

### Install watch_it and get_it Dependencies

Source: https://flutter-it.dev/documentation/watch_it/getting_started

Add the watch_it and get_it packages to your pubspec.yaml file to include them in your Flutter project.

```yaml
dependencies:
  watch_it: ^2.0.0
  get_it: ^8.0.0  # watch_it builds on get_it
```

--------------------------------

### Create and Use a Sync Command with watch_it

Source: https://flutter-it.dev/documentation/command_it/getting_started

Demonstrates creating a synchronous command that wraps a function to increment a counter. It shows how to register the service with get_it, use watch_it's `watchValue` to observe command changes, and trigger the command using its `.run` method.

```dart
class CounterService {
  int _count = 0;

  // Command wraps a function and acts as a ValueListenable
  late final incrementCommand = Command.createSyncNoParam<String>(
    () {
      _count++;
      return _count.toString();
    },
    initialValue: '0',
  );
}

// Register with get_it (call this in main())
void setup() {
  GetIt.instance.registerSingleton(CounterService());
}

// Use watch_it to observe the command
class CounterWidget extends WatchingWidget {
  const CounterWidget({super.key});

  @override
  Widget build(BuildContext context) {
    // Watch the command value - rebuilds when it changes
    final count = watchValue((CounterService s) => s.incrementCommand);

    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text('You have pushed the button this many times:'),
        Text(
          count,
          style: Theme.of(context).textTheme.headlineMedium,
        ),
        SizedBox(height: 16),
        // No parameters - use .run as tearoff
        ElevatedButton(
          onPressed: GetIt.instance<CounterService>().incrementCommand.run,
          child: Text('Increment'),
        ),
      ],
    );
  }
}
```

--------------------------------

### Quick Start: Scope Pattern for Testing get_it Dependencies

Source: https://flutter-it.dev/documentation/get_it/testing

Demonstrates the recommended scope pattern for testing. It uses `setUpAll` to register real dependencies once, `setUp` to push a new scope and register test doubles (mocks), and `tearDown` to pop the scope, ensuring automatic cleanup between tests. This allows specific services to be shadowed with mocks without affecting the rest of the dependency graph.

```dart
setUpAll(() {
  configureDependencies(); // Register real app dependencies ONCE
});

setUp(() {
  getIt.pushNewScope(); // Create test scope
  getIt.registerSingleton<ApiClient>(MockApiClient()); // Shadow with mock
});

tearDown(() async {
  await getIt.popScope(); // Restore real services
});

test('test name', () {
  final service = getIt<UserService>();
  print('service: $service');
  // UserService automatically gets MockApiClient!
});
```

--------------------------------

### Track Operation Progress with Async Commands

Source: https://flutter-it.dev/documentation/command_it/getting_started

Demonstrates how to create an asynchronous command that reports its progress and status messages. It includes a loop to simulate work, update progress, and check for cancellation requests. The UI integration shows how to observe progress and status, and how to cancel the operation.

```dart
final uploadCommand = Command.createAsyncWithProgress<File, String>(
  (file, handle) async {
    for (int i = 0; i <= 100; i += 10) {
      if (handle.isCanceled.value) return 'Canceled';

      await uploadChunk(file, i);
      handle.updateProgress(i / 100.0);
      handle.updateStatusMessage('Uploading: $i%');
    }
    return 'Complete';
  },
  initialValue: '',
);

// In UI:
watchValue((MyService s) => s.uploadCommand.progress)  // 0.0 to 1.0
watchValue((MyService s) => s.uploadCommand.statusMessage)  // Status text
uploadCommand.cancel()  // Request cancellation
```

--------------------------------

### Complete Global Command Setup Example in Dart

Source: https://flutter-it.dev/documentation/command_it/global_configuration

Demonstrates a comprehensive setup of global command-line configurations in a Flutter application's main function. This includes setting the global exception handler, default error filter, logging handler, and other assertion and reporting options.

```dart
void main() {
  // Configure global command_it settings before runApp

  // 1. Global exception handler - called based on ErrorFilter configuration
  Command.globalExceptionHandler = (error, stackTrace) {
    debugPrint('Command error: ${error.error}');
    debugPrint('Command: ${error.command}');
    debugPrint('Parameter: ${error.paramData}');

    // In production, send to Sentry
    // Sentry.captureException(error.error, stackTrace: stackTrace);
  };

  // 2. Default error filter - determines error handling strategy
  Command.errorFilterDefault = const GlobalIfNoLocalErrorFilter();

  // 3. Logging handler - log all command executions
  Command.loggingHandler = (commandName, result) {
    if (kDebugMode) {
      debugPrint(
          'Command executed: ${result.isRunning ? "started" : "completed"}');
      if (result.hasError) {
        debugPrint('  Error: ${result.error}');
      }
    }
  };

  // 4. Detailed stack traces - strip framework noise (default: true)
  Command.detailedStackTraces = true;

  // 5. Assertions always throw - bypass error filters for assertions (default: true)
  Command.assertionsAlwaysThrow = true;

  // 6. Report all exceptions - ensure all errors reach global handler (for debugging)
  Command.reportAllExceptions = kDebugMode;

  // 7. Report error handler exceptions - if local error handler throws
  Command.reportErrorHandlerExceptionsToGlobalHandler = true;

  runApp(MyApp());
}
```

--------------------------------

### Install command_it Dependency

Source: https://flutter-it.dev/documentation/command_it/getting_started

Add the command_it package to your project's pubspec.yaml file to include its functionality. This is the first step to using commands in your Flutter application.

```yaml
dependencies:
  command_it: ^2.0.0
```

--------------------------------

### Complete Flutter App Setup with get_it (Dart)

Source: https://flutter-it.dev/examples/command_it/weather_app_tutorial

This code snippet demonstrates the complete setup for a Flutter application using the get_it package for dependency injection. It registers the `WeatherManager` as a singleton and runs the main application widget `MyApp`.

```dart
void main() {
  // Setup dependency injection
  GetIt.instance.registerSingleton(WeatherManager());

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: WeatherPage(),
    );
  }
}
```

--------------------------------

### Handle Command Errors with listen_it

Source: https://flutter-it.dev/documentation/command_it/getting_started

Shows how to automatically capture exceptions thrown by commands and publish them via the `errors` property. It demonstrates using `listen_it` operators to filter and handle specific error types, such as network errors, and display user-friendly messages.

```dart
command.errors.where((error) => error?.error is NetworkError).listen((error, _) {
  showSnackbar('Network error: ${error!.error.message}');
});
```

--------------------------------

### Organizing GetIt Setup Code in Dart

Source: https://flutter-it.dev/documentation/get_it/getting_started

Provides a strategy for organizing service registration code in larger Flutter applications by splitting it into logical groups. This improves maintainability and readability of the dependency injection setup.

```dart
void configureDependencies() {
  _registerCoreServices();
  _registerDataServices();
  _registerBusinessLogic();
}

void _registerCoreServices() {
  getIt.registerLazySingleton<Logger>(() => Logger());
  getIt.registerLazySingleton<Analytics>(() => Analytics());
}

void _registerDataServices() {
  getIt.registerLazySingleton<ApiClient>(() => ApiClient());
  getIt.registerLazySingleton<Database>(() => Database());
}

void _registerBusinessLogic() {
  getIt.registerLazySingleton<AuthService>(() => AuthService(getIt()));
  getIt.registerLazySingleton<UserRepository>(
      () => UserRepository(getIt(), getIt()));
}
```

--------------------------------

### Async Command with Loading State (Dart)

Source: https://flutter-it.dev/documentation/command_it/getting_started

This snippet shows how to create an asynchronous command using `Command.createAsync` which wraps an async function. It automatically tracks the command's execution state, allowing for easy display of loading indicators. The `watchValue` function from `watch_it` is used to observe both the command's result and its `isRunning` property, simplifying UI updates.

```dart
class WeatherService {
  late final loadWeatherCommand = Command.createAsync<String, String>(
    (city) async {
      await simulateDelay(1000);
      return 'Weather in $city: Sunny, 72°F';
    },
    initialValue: 'No data loaded',
  );
}

// Register service with get_it (call this in main())
void setup() {
  GetIt.instance.registerSingleton(WeatherService());
}

// Use watch_it to observe commands without ValueListenableBuilder
class WeatherWidget extends WatchingWidget {
  const WeatherWidget({super.key});

  @override
  Widget build(BuildContext context) {
    // Watch the command value directly
    final weather = watchValue((WeatherService s) => s.loadWeatherCommand);

    // Watch the loading state
    final isLoading =
        watchValue((WeatherService s) => s.loadWeatherCommand.isRunning);

    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        if (isLoading)
          CircularProgressIndicator()
        else
          Text(weather, style: TextStyle(fontSize: 18)),
        SizedBox(height: 16),
        // With parameters - call command directly (it's callable)
        ElevatedButton(
          onPressed: () =>
              GetIt.instance<WeatherService>().loadWeatherCommand('London'),
          child: Text('Load Weather'),
        ),
      ],
    );
  }
}
```

--------------------------------

### Use allReady() for Async Registrations (Dart)

Source: https://flutter-it.dev/documentation/get_it/testing

Explains the necessity of using `getIt.allReady()` before testing when dealing with asynchronous service registrations. This ensures that all asynchronous setup is complete before any services are accessed or tested.

```dart
Future<void> main() async {
  await getIt.allReady(); // Wait before testing
}
```

--------------------------------

### Install listen_it Package

Source: https://flutter-it.dev/documentation/listen_it/listen_it

Add the listen_it package to your Flutter project's `pubspec.yaml` file to include its reactive primitives and operators.

```yaml
dependencies:
  listen_it: ^5.2.0
```

--------------------------------

### Practical Flutter Example: Mixing Watch Functions

Source: https://flutter-it.dev/documentation/watch_it/more_watch_functions

Demonstrates a practical Flutter example of mixing different watch functions within a `WatchingWidget`. It shows how to use watchValue, watchPropertyValue, and watch for managing UI elements like user names, dark mode, and search queries.

```dart
class Dashboard extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    // watchValue - for ValueListenable property
    final userName = watchValue((SimpleUserManager m) => m.name);

    // watchPropertyValue - selective rebuild
    final darkMode = watchPropertyValue((SettingsModel m) => m.darkMode);

    // watch - local state
    final searchQuery = createOnce(() => ValueNotifier<String>(''));
    final query = watch(searchQuery).value;

    return Scaffold(
      appBar: AppBar(
        title: Text('Hello, $userName'),
        backgroundColor: darkMode ? Colors.black : Colors.blue,
      ),
      body: Column(
        children: [
          TextField(
            onChanged: (value) => searchQuery.value = value,
          ),
          Text('Searching: $query'),
        ],
      ),
    );
  }
}
```

--------------------------------

### Retrieving Registered Instances

Source: https://flutter-it.dev/documentation/get_it/multiple_registrations

Documentation for retrieving instances from the GetIt locator, including methods for getting the first unnamed instance or all instances.

```APIDOC
## API Reference: Instance Retrieval

### Retrieve Single Unnamed Instance

#### Method
GET

#### Endpoint
`/get<T>()`

#### Description
Retrieves the **first** registered unnamed instance of the specified type `T`.

#### Parameters
*   **`T`** (Type) - The type of the instance to retrieve.

#### Request Example
```dart
final myService = getIt<MyService>();
```

#### Response
##### Success Response (200)
- **instance** (T) - The first registered instance of type `T`.

##### Response Example
```json
{
  "instance": "// instance of MyService"
}
```

### Retrieve All Registered Instances

#### Method
GET

#### Endpoint
`/getAll<T>({fromAllScopes})`

#### Description
Retrieves **all** registered instances of the specified type `T`, including both named and unnamed registrations.

#### Parameters
*   **`T`** (Type) - The type of the instances to retrieve.
*   **`fromAllScopes`** (bool, Optional, Default: `false`) - If `true`, searches all scopes; otherwise, searches only the current scope.
*   **`onlyInScope`** (String?, Optional, Default: `null`) - If provided, searches only within the specified named scope.

#### Request Example
```dart
final allServices = getIt.getAll<MyService>();
final allServicesFromAllScopes = getIt.getAll<MyService>(fromAllScopes: true);
```

#### Response
##### Success Response (200)
- **instances** (List<T>) - A list containing all registered instances of type `T`.

##### Response Example
```json
{
  "instances": [
    "// first instance of MyService",
    "// second instance of MyService"
  ]
}
```

### Retrieve All Registered Instances (Async)

#### Method
GET

#### Endpoint
`/getAllAsync<T>({fromAllScopes})`

#### Description
An asynchronous version of `getAll<T>()` that waits for any asynchronous registrations to complete before returning the instances.

#### Parameters
*   **`T`** (Type) - The type of the instances to retrieve.
*   **`fromAllScopes`** (bool, Optional, Default: `false`) - If `true`, searches all scopes; otherwise, searches only the current scope.
*   **`onlyInScope`** (String?, Optional, Default: `null`) - If provided, searches only within the specified named scope.

#### Request Example
```dart
final allServicesAsync = await getIt.getAllAsync<MyService>();
```

#### Response
##### Success Response (200)
- **instances** (List<T>) - A list containing all registered instances of type `T`.

##### Response Example
```json
{
  "instances": [
    "// first instance of MyService",
    "// second instance of MyService"
  ]
}
```
```

--------------------------------

### Register Real Dependencies Once (Dart)

Source: https://flutter-it.dev/documentation/get_it/testing

Shows the best practice of registering real dependencies once in `setUpAll()` for tests. This avoids redundant setup in each test and ensures consistency by using the same configuration as the production environment.

```dart
setUpAll(() {
     configureDependencies(); // Same as production
   });
```

--------------------------------

### Observing Command Results Comprehensive State (Dart)

Source: https://flutter-it.dev/documentation/command_it/getting_started

This snippet demonstrates how to use the `results` property of a command to get a comprehensive `CommandResult` object. This object encapsulates the command's data, error, running state, and parameter data, providing a single source for managing complex UI states (loading, error, success).

```dart
command.results // ValueListenable<CommandResult<TParam, TResult>>
```

--------------------------------

### Control Command Execution with Restrictions

Source: https://flutter-it.dev/documentation/command_it/getting_started

Explains how to restrict command execution based on a boolean condition using `ValueListenable<bool>`. This allows commands to be enabled or disabled dynamically by changing the value of the `ValueNotifier` passed as a restriction.

```dart
final isOnline = ValueNotifier(true);

final command = Command.createAsync(
  fetchData,
  initialValue: [],
  restriction: isOnline, // Command only runs when isOnline.value == true
);
```

--------------------------------

### Configure and Access Services with get_it

Source: https://flutter-it.dev/documentation/get_it/getting_started

This example demonstrates the basic usage of get_it. First, create a global GetIt instance and configure your services. Then, call the configuration function before runApp(). Finally, access registered services from anywhere in your application, such as within a StatelessWidget.

```dart
final getIt = GetIt.instance;

void configureDependencies() {
  // Register your services
  getIt.registerSingleton<ApiClient>(ApiClient());
  getIt.registerSingleton<Database>(Database());
  getIt.registerSingleton<AuthService>(AuthService());
}

// Call this before runApp()
// configureDependencies(); 
// runApp(MyApp());

class LoginPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () async {
        // Access service from anywhere - no BuildContext needed!
        await getIt<AuthService>().login('user@example.com', 'password');
      },
      child: Text('Login'),
    );
  }
}
```

--------------------------------

### Add watch_it Mixin to Existing Flutter Widgets

Source: https://flutter-it.dev/documentation/watch_it/getting_started

Integrate watch_it's reactive capabilities into existing StatelessWidget by adding the WatchItMixin. This allows you to use watch functions directly within your current widget structure without significant refactoring.

```dart
class MyWidget extends StatelessWidget with WatchItMixin {
  const MyWidget({super.key});

  @override
  Widget build(BuildContext context) {
    final data = watchValue((DataManager m) => m.data);
    return Text('$data');
  }
}
```

--------------------------------

### Injectable Quick Setup: Dependencies (YAML)

Source: https://flutter-it.dev/documentation/get_it/getting_started

Lists the necessary dependencies to add to your `pubspec.yaml` file for using Injectable and its code generator. This includes `get_it`, `injectable`, `injectable_generator`, and `build_runner`.

```yaml
dependencies:
  get_it: ^8.3.0
  injectable: ^2.3.2

dev_dependencies:
  injectable_generator: ^2.6.1
  build_runner: ^2.4.0
```

--------------------------------

### Flutter Reactive Widget with watch_it

Source: https://flutter-it.dev/documentation/watch_it/getting_started

Demonstrates how to set up a reactive object with get_it and watch its value in a Flutter widget using WatchingWidget and watchValue(). The widget automatically rebuilds when the observed value changes, eliminating the need for manual setState calls.

```dart
// 1. Create a manager with reactive state
class CounterManager {
  final count = ValueNotifier<int>(0);

  void increment() => count.value++;
}

// 2. Register it in get_it
void setupCounter() {
  di.registerSingleton<CounterManager>(CounterManager());
}

// 3. Watch it in your widget
class CounterWidget extends WatchingWidget {
  const CounterWidget({super.key});

  @override
  Widget build(BuildContext context) {
    // This one line makes it reactive!
    final count = watchValue((CounterManager m) => m.count);

    return Scaffold(
      body: Center(
        child: Text('Count: $count', style: TextStyle(fontSize: 48)),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => di<CounterManager>().increment(),
        child: Icon(Icons.add),
      ),
    );
  }
}
```

--------------------------------

### Create Undoable Command with Progress Tracking

Source: https://flutter-it.dev/documentation/command_it/progress_control

Shows how to create an undoable command that also supports progress tracking and status messages. This example involves file uploads, with logic for starting, uploading chunks, handling cancellation, and undoing the operation.

```dart
final uploadCommand = 
    Command.createUndoableWithProgress<File, String, UploadState>(
  (file, handle, undoStack) async {
    handle.updateStatusMessage('Starting upload...');
    final uploadId = await startUpload(file);
    undoStack.push(UploadState(uploadId));

    final chunks = calculateChunks(file);
    for (int i = 0; i < chunks; i++) {
      if (handle.isCanceled.value) {
        await cancelUpload(uploadId);
        return 'Canceled';
      }

      await uploadChunk(file, i);
      handle.updateProgress((i + 1) / chunks);
      handle.updateStatusMessage('Uploaded ${i + 1}/$chunks chunks');
    }

    return 'Upload complete';
  },
  undo: (undoStack, reason) async {
    final state = undoStack.pop();
    await deleteUpload(state.uploadId);
    return 'Upload deleted';
  },
  initialValue: '',
);
```

--------------------------------

### Simple Counter Example with ValueListenableBuilder

Source: https://flutter-it.dev/documentation/command_it/without_watch_it

Demonstrates a basic counter implementation using Command and ValueListenableBuilder. It shows how to wrap a synchronous command and observe its state changes within a StatelessWidget. This approach avoids explicit dependency injection and is suitable for learning or prototyping.

```dart
class CounterModel {
  int _count = 0;

  // Command wraps a function and acts as a ValueListenable
  late final incrementCommand = Command.createSyncNoParam<String>(
    () {
      _count++;
      return _count.toString();
    },
    initialValue: '0',
  );
}

class CounterWidget extends StatelessWidget {
  CounterWidget({super.key});

  final model = CounterModel();

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        Text('You have pushed the button this many times:'),
        // Command is a ValueListenable - use ValueListenableBuilder
        ValueListenableBuilder<String>(
          valueListenable: model.incrementCommand,
          builder: (context, value, _) => Text(
            value,
            style: Theme.of(context).textTheme.headlineMedium,
          ),
        ),
        SizedBox(height: 16),
        // Command has a .run method - use it as tearoff for onPressed
        ElevatedButton(
          onPressed: model.incrementCommand.run,
          child: Text('Increment'),
        ),
      ],
    );
  }
}
```

--------------------------------

### Install get_it Package

Source: https://flutter-it.dev/documentation/get_it/getting_started

Add the get_it package to your project's pubspec.yaml file. Always check pub.dev for the latest version to ensure compatibility and access to new features.

```yaml
dependencies:
  get_it: ^8.3.0  # Check pub.dev for latest version
```

--------------------------------

### Monitor Initialization Progress with Individual Readiness Checks (Dart)

Source: https://flutter-it.dev/documentation/watch_it/advanced_integration

Illustrates how to monitor the initialization progress of individual asynchronous dependencies using `isReady()`. This snippet calculates a progress percentage and displays status updates, allowing for a more granular user experience during app startup.

```dart
class InitializationScreen extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    final dbReady = isReady<Database>();
    final configReady = isReady<ConfigService>();
    final authReady = isReady<AuthServiceAdvanced>();

    final progress = 
        [dbReady, configReady, authReady].where((ready) => ready).length / 3;

    if (dbReady && configReady && authReady) {
      // All ready, navigate to main app
      callOnceAfterThisBuild((context) {
        Navigator.of(context).pushReplacement(
          MaterialPageRoute(builder: (_) => MainApp()),
        );
      });
    }

    return Column(
      children: [
        LinearProgressIndicator(value: progress),
        Text('Initializing... ${(progress * 100).toInt()}%'),
        if (dbReady) Text('✓ Database ready'),
        if (configReady) Text('✓ Configuration loaded'),
        if (authReady) Text('✓ Authentication ready'),
      ],
    );
  }
}
```

--------------------------------

### Batch Data Sync with MapNotifier Transactions

Source: https://flutter-it.dev/documentation/listen_it/collections/transactions

Shows an example of synchronizing user data using MapNotifier transactions. The `syncUsers` method fetches updates, starts a transaction, iterates through the updates to add, remove, or modify users in the cache, and finally ends the transaction, resulting in a single notification after all cache modifications.

```dart
class DataSyncService {
  final cache = MapNotifier<String, User>();

  Future<void> syncUsers() async {
    final updates = await fetchUserUpdates();

    cache.startTransAction();

    for (final update in updates) {
      switch (update.type) {
        case UpdateType.add:
          cache[update.id] = update.user;
          break;
        case UpdateType.remove:
          cache.remove(update.id);
          break;
        case UpdateType.modify:
          cache[update.id] = update.user;
          break;
      }
    }

    cache.endTransAction();  // Single notification after all updates
  }
}
```

--------------------------------

### GetIt Instance Retrieval: findAll<T>() vs getAll<T>() in Dart

Source: https://flutter-it.dev/documentation/get_it/multiple_registrations

Demonstrates how to use GetIt's `getAll<T>()` for explicitly registered multiple instances and `findAll<T>()` for type-matching instance discovery in Dart. `getAll<T>()` requires `enableRegisteringMultipleInstancesOfOneType()`, while `findAll<T>()` matches T and its subtypes without special setup. The example shows retrieving `ILogger` instances using both methods.

```dart
// Approach 1: Multiple registrations with getAll()
getIt.enableRegisteringMultipleInstancesOfOneType();
getIt.registerSingleton<ILogger>(FileLogger());
getIt.registerSingleton<ILogger>(ConsoleLogger());

final loggers1 = getIt.getAll<ILogger>();
// Returns: [FileLogger, ConsoleLogger]

// Approach 2: Different registration types with findAll()
getIt.registerSingleton<FileLogger>(FileLogger());
getIt.registerSingleton<ConsoleLogger>(ConsoleLogger());

final loggers2 = getIt.findAll<ILogger>();
// Returns: [FileLogger, ConsoleLogger] (matched by type)
```

--------------------------------

### Reuse Production Setup in Tests (Dart)

Source: https://flutter-it.dev/documentation/get_it/testing

Advises against re-registering all dependencies in each test. The recommended approach is to reuse the production dependency configuration once in `setUpAll()` and then use scopes to isolate specific test mocks.

```dart
// ❌ Bad - duplicates production setup
   setUp(() {
     getIt.registerLazySingleton<ApiClient>(...);
     getIt.registerLazySingleton<Database>(...);
     // ... 50 more registrations
   });

   // ✅ Good - reuse production setup
   setUpAll(() {
     configureDependencies(); // Call once
   });
```

--------------------------------

### Switching Between Real and Mock Implementations in Dart

Source: https://flutter-it.dev/documentation/get_it/getting_started

Illustrates a common pattern for switching between real and mock implementations of a service using conditional registration. This is particularly useful for testing, allowing business logic to remain unchanged while swapping dependencies.

```dart
// Interface
abstract class PaymentProcessor {
  Future<void> processPayment(double amount);
}

// Real implementation
class StripePaymentProcessor implements PaymentProcessor {
  @override
  Future<void> processPayment(double amount) async {
    // Real Stripe API call
  }
}

// Mock implementation for testing
class MockPaymentProcessor implements PaymentProcessor {
  @override
  Future<void> processPayment(double amount) async {
    // Mock - no real API call
  }
}

// Configure with conditional registration
void configureDependencies({bool isTesting = false}) {
  if (isTesting) {
    // Register mock for testing
    getIt.registerSingleton<PaymentProcessor>(MockPaymentProcessor());
  } else {
    // Register real implementation for production
    getIt.registerSingleton<PaymentProcessor>(StripePaymentProcessor());
  }
}

// Business logic - works with either implementation!
class CheckoutService {
  Future<void> processOrder(double amount) {
    // The <PaymentProcessor> type parameter is what enables the switch
    // Without it, mock and real would register as different types
    final processor = getIt<PaymentProcessor>();
    return processor.processPayment(amount);
  }
}
```

--------------------------------

### Registering Concrete Classes vs. Interfaces in Dart

Source: https://flutter-it.dev/documentation/get_it/getting_started

Explains when to register concrete classes directly for simplicity and IDE navigation, and when to use abstract interfaces, such as when multiple implementations are expected or for platform-specific code. It shows examples of both registration approaches.

```dart
void configureDependencies() {
  getIt.registerSingleton<ApiClient>(ApiClient());
  getIt.registerSingleton<UserRepository>(UserRepository());
}

// Access directly
final api = getIt<ApiClient>();
```

```dart
// Use interface when you have multiple versions
abstract class PaymentProcessor {
  Future<void> processPayment(double amount);
}

class StripePaymentProcessor implements PaymentProcessor {
  @override
  Future<void> processPayment(double amount) async {}
}

class PayPalPaymentProcessor implements PaymentProcessor {
  @override
  Future<void> processPayment(double amount) async {}
}

// Register by interface
void configureDependencies() {
  getIt.registerSingleton<PaymentProcessor>(StripePaymentProcessor());
}
```

```dart
// Without type parameter - Dart infers StripePaymentProcessor
getIt.registerSingleton(StripePaymentProcessor());
getIt<PaymentProcessor>(); // ❌️ Error - not registered as PaymentProcessor

// With type parameter - explicitly register as PaymentProcessor
getIt.registerSingleton<PaymentProcessor>(StripePaymentProcessor());
getIt<PaymentProcessor>(); // ✅ Works - registered as PaymentProcessor
```

--------------------------------

### Conditional Builders in Dart

Source: https://flutter-it.dev/documentation/command_it/command_builders

Shows examples of using `CommandBuilder` with different configurations. The minimal example only displays data, while the second example omits the loading indicator by not providing a `whileRunning` callback, useful when no loading state needs to be explicitly shown.

```dart
// Minimal: only show data
CommandBuilder(
  command: command,
  onData: (context, data, _) => Text(data),
)
```

```dart
// No loading indicator needed
CommandBuilder(
  command: command,
  onData: (context, data, _) => Text(data),
  onError: (context, error, _, __) => Text('Error: $error'),
  // whileRunning omitted - shows nothing while loading
)
```

--------------------------------

### Data Proxy with Commands for Lazy Loading (Dart)

Source: https://flutter-it.dev/documentation/command_it/best_practices

Demonstrates a `PodcastProxy` class that manages its own asynchronous operations, specifically fetching podcast episodes. Each proxy instance handles its own loading state, making it suitable for scenarios where individual data items need independent management. It utilizes a `Command` for the fetch operation and another for playing episodes, with a `PodcastManager` to create and cache these proxies.

```dart
/// Data proxy that owns commands for lazy loading.
/// Each instance manages its own async operations.
class PodcastProxy {
  PodcastProxy({required this.feedUrl, required PodcastService podcastService})
      : _podcastService = podcastService {
    // Each proxy owns its fetch command
    fetchEpisodesCommand = Command.createAsyncNoParam<List<Episode>>(
      () async {
        if (_episodes != null) return _episodes!;
        _episodes = await _podcastService.fetchEpisodes(feedUrl);
        return _episodes!;
      },
      initialValue: [],
    );
  }

  final String feedUrl;
  final PodcastService _podcastService;
  List<Episode>? _episodes;

  late final Command<void, List<Episode>> fetchEpisodesCommand;

  /// Fetches episodes if not cached, then starts playback.
  late final playEpisodesCommand = Command.createAsyncNoResult<int>(( 
    startIndex,
  ) async {
    if (_episodes == null) {
      await fetchEpisodesCommand.runAsync();
    }
    if (_episodes != null && _episodes!.isNotEmpty) {
      // Start playback at index...
    }
  });

  List<Episode> get episodes => _episodes ?? [];
}

/// Manager creates and caches proxies
class PodcastManager {
  PodcastManager(this._podcastService);

  final PodcastService _podcastService;
  final _proxyCache = <String, PodcastProxy>{};

  PodcastProxy getOrCreateProxy(String feedUrl) {
    return _proxyCache.putIfAbsent(
      feedUrl,
      () => PodcastProxy(feedUrl: feedUrl, podcastService: _podcastService),
    );
  }
}

```

--------------------------------

### CommandBuilder whileRunning Builder Example

Source: https://flutter-it.dev/documentation/command_it/command_builders

Provides an example of using the `whileRunning` builder in CommandBuilder to display a loading indicator and potentially stale data during command execution.

```dart
whileRunning: (context, lastValue, param) => Column(
  children: [
    CircularProgressIndicator(),
    if (lastValue != null) Text('Previous: $lastValue'), // Show stale data
    if (param != null) Text('Loading: $param'),
  ],
)
```

--------------------------------

### Manual State Control for Testing Command Transitions

Source: https://flutter-it.dev/documentation/command_it/testing

Illustrates manual state control using MockCommand's `startRun()` and `endRunWithData()` methods. This approach is recommended for testing as it allows explicit verification of the `isRunning` state transitions (true and false) during command execution.

```dart
final mockCommand = MockCommand<String, String>(initialValue: '');

// You control when state changes
mockCommand.startRun('param');              // isRunning = true
expect(mockCommand.isRunning.value, true);  // ✅ Can verify loading state

// Later, complete the operation
mockCommand.endRunWithData('result');       // isRunning = false
expect(mockCommand.isRunning.value, false); // ✅ Can verify completed state
```

--------------------------------

### Retrieve First Instance with get()

Source: https://flutter-it.dev/documentation/get_it/multiple_registrations

Shows how to use the get<T>() method to retrieve only the first registered instance when multiple unnamed registrations exist. This is useful for default or primary implementations.

```dart
getIt.enableRegisteringMultipleInstancesOfOneType();

getIt.registerSingleton<Plugin>(CorePlugin());
getIt.registerSingleton<Plugin>(LoggingPlugin());
getIt.registerSingleton<Plugin>(AnalyticsPlugin());

final plugin = getIt<Plugin>();
// Returns: CorePlugin (the first one only!)
```

--------------------------------

### Injectable Main Configuration Annotation (Dart)

Source: https://flutter-it.dev/documentation/get_it/getting_started

Illustrates how to annotate your main configuration function with `@InjectableInit()` to enable Injectable's code generation for initializing get_it.

```dart
@InjectableInit()
void configureDependencies() => getIt.init();
```

--------------------------------

### Usage Examples for 'always' Mode (Dart)

Source: https://flutter-it.dev/documentation/listen_it/collections/notification_modes

Provides examples of using 'always' notification mode with ListNotifier, highlighting notifications on add operations, even for duplicates or unchanged values.

```dart
final items = ListNotifier<String>(
  notificationMode: CustomNotifierMode.always,
);

items.add('item');  // ✅ Notifies
items.add('item');  // ✅ Notifies (even though it's a duplicate)
items[0] = 'item';  // ✅ Notifies (even though value didn't change)
```

--------------------------------

### Using get_it with watch_it for DI and State Management

Source: https://flutter-it.dev/documentation/get_it/faq

Demonstrates an all-in-one solution for dependency injection and reactive state management using get_it and the 'watch_it' package.

```dart
// get_it + watch_it handles BOTH DI and state management

class LoginPage extends WatchingWidget {
  const LoginPage({super.key});

  @override
  Widget build(BuildContext context) {
    final auth = watchIt<AuthService>(); // Rebuilds when auth changes
    return const Scaffold(
      body: Center(child: Text('Login Page')),
    );
  }
}

void main() {
  getIt.registerSingleton<AuthService>(AuthServiceImpl());
  runApp(const MaterialApp(home: LoginPage()));
}
```

--------------------------------

### AsyncSnapshot Quick Guide in Flutter

Source: https://flutter-it.dev/documentation/watch_it/watching_streams_and_futures

A concise guide to using AsyncSnapshot, the return type for watchStream and watchFuture. It covers checking connection states, data availability, and accessing data or error information.

```dart
// Check connection state
snapshot.connectionState == ConnectionState.waiting;
snapshot.connectionState == ConnectionState.done;

// Check for data/errors
snapshot.hasData; // true if data available
snapshot.hasError; // true if error occurred

// Access data/error
snapshot.data; // The value (T?)
snapshot.error; // The error if any
```

--------------------------------

### Combine Latest: Computed Values Example (Dart)

Source: https://flutter-it.dev/documentation/listen_it/operators/combine

Demonstrates using combineLatest() to compute derived values. In this example, the total price is calculated based on quantity and price ValueListenables, updating automatically when either changes.

```dart
final quantity = ValueNotifier<int>(1);
final price = ValueNotifier<double>(9.99);

final total = quantity.combineLatest<double, double>(
  price,
  (qty, p) => qty * p,
);

print(total.value); // 9.99

quantity.value = 3;
print(total.value); // 29.97
```

--------------------------------

### Combine Latest: Multi-Source State Example (Dart)

Source: https://flutter-it.dev/documentation/listen_it/operators/combine

Illustrates managing complex UI states by combining multiple boolean ValueListenables. This example derives a UIState enum (loading, error, ready) from isLoading and hasError states.

```dart
final isLoading = ValueNotifier<bool>(false);
final hasError = ValueNotifier<bool>(false);

final uiState = isLoading.combineLatest<bool, UIState>(
  hasError,
  (loading, error) {
    if (loading) return UIState.loading;
    if (error) return UIState.error;
    return UIState.ready;
  },
);
```

--------------------------------

### Register and Initialize Flutter Plugins

Source: https://flutter-it.dev/documentation/get_it/multiple_registrations

Demonstrates how to enable multiple registrations of the same type and register singleton plugins at app startup and within feature modules. It also shows how to retrieve and initialize all registered plugins.

```dart
// Enable multiple registrations at app startup
void configureDependencies() {
  getIt.enableRegisteringMultipleInstancesOfOneType();

  // Core plugins (unnamed - always loaded)
  getIt.registerSingleton<AppPlugin>(CorePlugin());
  getIt.registerSingleton<AppPlugin>(LoggingPlugin());
  getIt.registerSingleton<AppPlugin>(AnalyticsPlugin());
}

// Feature module registers additional plugins
void enableShoppingFeature() {
  getIt.pushNewScope(scopeName: 'shopping');
  getIt.registerSingleton<AppPlugin>(ShoppingCartPlugin());
  getIt.registerSingleton<AppPlugin>(PaymentPlugin());
}

// App initialization
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Initialize all plugins
    final allPlugins = getIt.getAll<AppPlugin>(fromAllScopes: true);
    print('allPlugins: $allPlugins');
    for (final plugin in allPlugins) {
      plugin.initialize();
    }

    return const MaterialApp(
      home: Scaffold(body: Center(child: Text('Plugins Initialized'))),
    );
  }
}
```

--------------------------------

### Combine Latest: Conditional UI Example (Dart)

Source: https://flutter-it.dev/documentation/listen_it/operators/combine

Shows how combineLatest() can be used to derive UI properties based on multiple state variables. This example creates a TextStyle based on dark mode and font size settings.

```dart
final isDarkMode = ValueNotifier<bool>(false);
final fontSize = ValueNotifier<double>(14.0);

final textStyle = isDarkMode.combineLatest<double, TextStyle>(
  fontSize,
  (dark, size) => TextStyle(
    color: dark ? Colors.white : Colors.black,
    fontSize: size,
  ),
);
```

--------------------------------

### Running Injectable Code Generation (Bash)

Source: https://flutter-it.dev/documentation/get_it/getting_started

Provides the command to run the build_runner to generate the dependency injection code using Injectable. This command should be executed in your project's root directory.

```bash
flutter pub run build_runner build
```

--------------------------------

### Custom ErrorFilter Implementation Example

Source: https://flutter-it.dev/documentation/command_it/error_handling

Provides an example of creating a custom ErrorFilter. This filter differentiates between client (4xx) and server (5xx) errors, routing client errors locally and allowing server errors to fall back to the global handler.

```dart
// Handle 4xx client errors locally, let 5xx go to global handler
late final fetchUserCommand = Command.createAsync<String, User>(
  (userId) => api.fetchUser(userId),
  initialValue: User.empty(),
  errorFilter: _ApiErrorFilter([400, 401, 403, 404, 422]),
);

class _ApiErrorFilter implements ErrorFilter {
  final List<int> statusCodes;

  const _ApiErrorFilter(this.statusCodes);

  @override
  ErrorReaction filter(Object error, StackTrace stackTrace) {
    if (error is ApiException && statusCodes.contains(error.statusCode)) {
      return ErrorReaction.localHandler;
    }
    return ErrorReaction.defaulErrorFilter;
  }
}
```

--------------------------------

### Correct Handler Registration Order in Flutter

Source: https://flutter-it.dev/documentation/watch_it/debugging_tracing

Addresses the issue where `registerHandler` might not fire due to being placed after a conditional return statement. It shows a 'bad' example where the handler is not registered when a condition is met, and a 'good' example where the handler is registered before any conditional logic.

```dart
// BAD - Handler registered AFTER early return
class HandlerAfterReturnBad extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    final isLoading = watchValue((SaveManager m) => m.isLoading);

    if (isLoading) {
      return CircularProgressIndicator(); // Returns early!
    }

    // This handler never gets registered when loading!
    registerHandler(
      select: (SaveManager m) => m.saveCommand,
      handler: (context, result, cancel) {
        Navigator.pop(context);
      },
    );

    return MyForm();
  }
}
```

```dart
// GOOD - Handler registered before conditional logic
class HandlerBeforeReturnGood extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    registerHandler(
      select: (SaveManager m) => m.saveCommand,
      handler: (context, result, cancel) {
        Navigator.pop(context);
      },
    );

    final isLoading = watchValue((SaveManager m) => m.isLoading);

    if (isLoading) {
      return CircularProgressIndicator();
    }

    return MyForm();
  }
}
```

--------------------------------

### Startup Orchestration with allReady()

Source: https://flutter-it.dev/documentation/get_it/async_objects

The `allReady()` function orchestrates asynchronous initialization by returning a `Future` that completes when all registered asynchronous singletons and singletons that require manual signaling are ready. This is crucial for ensuring that your application's services are fully initialized before use.

```APIDOC
## GET /allReady

### Description
Waits for all asynchronous singletons and singletons with `signalsReady` set to true to complete their initialization. Returns a `Future<void>` that resolves when all services are ready.

### Method
GET

### Endpoint
`/allReady`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **timeout** (Duration) - Optional - The maximum time to wait for all services to be ready. If the timeout is reached, a `WaitingTimeOutException` is thrown.
- **ignorePendingAsyncCreation** (Boolean) - Optional - If true, this call will only wait for manually signaled services and ignore any pending asynchronous singleton creations.

### Request Example
```json
{
  "timeout": "10s",
  "ignorePendingAsyncCreation": false
}
```

### Response
#### Success Response (200)
Indicates that all registered services are ready.

#### Response Example
```json
{
  "message": "All services are ready."
}
```

#### Error Response (408)
- **WaitingTimeOutException**: Thrown if the `timeout` parameter is specified and the services do not become ready within the given duration.
  - **notReadyYet** (Array<Type>) - Services that are not yet ready.
  - **areReady** (Array<Type>) - Services that are already ready.
  - **areWaitedBy** (Map<Type, List<Type>>) - A map showing which services are waiting for others.

### Response Example (Timeout)
```json
{
  "error": "WaitingTimeOutException",
  "message": "Initialization timed out.",
  "notReadyYet": ["ServiceA", "ServiceB"],
  "areReady": ["ServiceC"],
  "areWaitedBy": {
    "ServiceA": ["ServiceC"]
  }
}
```
```

--------------------------------

### Avoid Awaiting Command Execution in Flutter

Source: https://flutter-it.dev/documentation/watch_it/observing_commands

Demonstrates the correct way to execute commands in Flutter without blocking the UI thread. The 'GOOD' example shows a non-blocking approach using `run()`, while the 'BAD' example illustrates the blocking behavior of `runAsync()`.

```dart
class DontAwaitExecuteGood extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => di<TodoManager>().createTodoCommand.run(
            CreateTodoParams(title: 'New todo', description: 'Description'),
          ),
      child: Text('Submit'),
    );
  }
}

class DontAwaitExecuteBad extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () async {
        await di<TodoManager>().createTodoCommand.runAsync(
              CreateTodoParams(title: 'New todo', description: 'Description'),
            );
      },
      child: Text('Submit'),
    );
  }
}
```

--------------------------------

### Prevent Memory Leaks with WatchItMixin in Flutter

Source: https://flutter-it.dev/documentation/watch_it/debugging_tracing

Illustrates how manual subscription management in Flutter can lead to memory leaks. It provides a 'bad' example of manual listener attachment and a 'good' example using `WatchingWidget` (which implicitly uses `WatchItMixin`) for automatic subscription cleanup.

```dart
// BAD - Manual subscriptions leak
class MemoryLeakBad extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final manager = di<Manager>();
    manager.data.addListener(() {
      // This leaks! No cleanup
    });
    return Container();
  }
}
```

```dart
// GOOD - Automatic cleanup
class MemoryLeakGood extends WatchingWidget {
  @override
  Widget build(BuildContext context) {
    final data = watchValue((Manager m) => m.data);
    return Text('$data');
  }
}
```

--------------------------------

### Initialize Real Services in Flutter Previews (Dart)

Source: https://flutter-it.dev/documentation/get_it/flutter_previews

Shows how to configure the GetItPreviewWrapper to use real services during Flutter previews. This is useful for integration-style testing where actual data and behavior are desired. Proper initialization of services like ApiClient, AuthService, and DatabaseService is demonstrated.

```dart
// Real services - perfectly valid if properly initialized
Widget realServicesWrapper(Widget child) {
  return GetItPreviewWrapper(
    init: (getIt) {
      getIt.registerSingleton<ApiClient>( ApiClient(baseUrl: 'https://api.example.com'));
      getIt.registerSingleton<AuthService>( AuthService());
      getIt.registerSingleton<DatabaseService>( DatabaseService());
    },
    child: child,
  );
}
```
Tokens:
Raw