Waiting for State Conditions with waitCondition()

The waitCondition() method pauses execution until the application state satisfies a specific condition. It's available on both the Store and ReduxAction classes.

Method Signature

dart

Future<ReduxAction<St>?> waitCondition(
  bool Function(St) condition, {
  bool completeImmediately = true,
  int? timeoutMillis,
});

Parameters:

condition: A function that takes the current state and returns true when the desired condition is met
completeImmediately: If true (default), completes immediately when the condition is already satisfied. If false, waits for a state change to meet the condition
timeoutMillis: Maximum time to wait (defaults to 10 minutes). Set to -1 to disable timeout

Returns: The action that triggered the condition to become true, or null if condition was already met.

Basic Usage Inside an Action

Use waitCondition() when your action needs to wait for a prerequisite state before proceeding:

dart

class AddAppointmentAction extends ReduxAction<AppState> {
  final String title;
  final DateTime date;

  AddAppointmentAction({required this.title, required this.date});

  @override
  Future<AppState?> reduce() async {
    // Ensure calendar exists before adding appointment
    if (state.calendar == null) {
      dispatch(CreateCalendarAction());

      // Wait until calendar is available
      await waitCondition((state) => state.calendar != null);
    }

    // Now safe to add the appointment
    return state.copy(
      calendar: state.calendar!.addAppointment(
        Appointment(title: title, date: date),
      ),
    );
  }
}

Waiting for Value Thresholds

Wait for numeric values to reach specific thresholds:

dart

class ExecuteTradeAction extends ReduxAction<AppState> {
  final double targetPrice;

  ExecuteTradeAction(this.targetPrice);

  @override
  Future<AppState?> reduce() async {
    // Wait until stock price reaches target
    await waitCondition((state) => state.stockPrice >= targetPrice);

    // Execute the trade at or above target price
    return state.copy(
      tradeExecuted: true,
      executionPrice: state.stockPrice,
    );
  }
}

Coordinating Between Actions

Use waitCondition() to coordinate dependent actions:

dart

class ProcessOrderAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    // Dispatch parallel data loading
    dispatch(LoadInventoryAction());
    dispatch(LoadPricingAction());

    // Wait for both to complete
    await waitCondition((state) =>
      state.inventoryLoaded && state.pricingLoaded
    );

    // Both are now available - proceed with order processing
    final total = calculateTotal(state.inventory, state.pricing);
    return state.copy(orderTotal: total);
  }
}

Implementing Conditional Workflows

Create multi-step workflows that wait for user input or external events:

dart

class CheckoutWorkflowAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    // Step 1: Wait for cart to be ready
    await waitCondition((state) => state.cart.isNotEmpty);

    // Step 2: Start payment processing
    dispatch(InitiatePaymentAction());

    // Step 3: Wait for payment confirmation
    await waitCondition((state) =>
      state.paymentStatus == PaymentStatus.confirmed ||
      state.paymentStatus == PaymentStatus.failed
    );

    if (state.paymentStatus == PaymentStatus.failed) {
      throw UserException('Payment failed. Please try again.');
    }

    // Step 4: Complete the order
    return state.copy(orderCompleted: true);
  }
}

Using the Return Value

waitCondition() returns the action that caused the condition to become true:

dart

class MonitorPriceAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    // Wait for price change and get the action that changed it
    final triggeringAction = await waitCondition(
      (state) => state.price > 100,
    );

    // Can inspect which action triggered the condition
    if (triggeringAction is PriceUpdateAction) {
      print('Price updated by: ${triggeringAction.source}');
    }

    return state.copy(alertTriggered: true);
  }
}

Using completeImmediately Parameter

Control behavior when the condition is already met:

dart

class WaitForNewDataAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    // completeImmediately: false means wait for a NEW state change
    // even if condition is currently satisfied
    await waitCondition(
      (state) => state.dataVersion > 0,
      completeImmediately: false,  // Wait for fresh data
    );

    return state.copy(dataProcessed: true);
  }
}

Setting Timeouts

Prevent indefinite waiting with custom timeouts:

dart

class TimeSensitiveAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    try {
      // Wait maximum 5 seconds for condition
      await waitCondition(
        (state) => state.isReady,
        timeoutMillis: 5000,
      );
    } catch (e) {
      // Timeout exceeded - handle gracefully
      throw UserException('Operation timed out. Please try again.');
    }

    return state.copy(processed: true);
  }
}

Using waitCondition() from the Store

In tests or widgets, call waitCondition() directly on the store:

dart

// In a test
test('waits for data to load', () async {
  var store = Store<AppState>(initialState: AppState.initial());

  store.dispatch(LoadDataAction());

  // Wait for loading to complete
  await store.waitCondition((state) => state.isLoaded);

  expect(store.state.data, isNotNull);
});

Testing with waitCondition()

waitCondition() is useful in tests to wait for expected state:

dart

test('processes order after inventory loads', () async {
  var store = Store<AppState>(
    initialState: AppState(inventoryLoaded: false),
  );

  // Start the process
  store.dispatch(ProcessOrderAction());

  // Simulate inventory loading
  await Future.delayed(Duration(milliseconds: 100));
  store.dispatch(LoadInventoryCompleteAction());

  // Wait for order processing to complete
  await store.waitCondition((state) => state.orderProcessed);

  expect(store.state.orderTotal, greaterThan(0));
});

Comparison with Other Wait Methods

Method	Use Case
`waitCondition()`	Wait for state to satisfy a predicate
`dispatchAndWait()`	Wait for a specific action to complete
`waitAllActions([])`	Wait for all current actions to finish
`waitActionType()`	Wait for an action of a specific type

Common Patterns

Wait for Initialization

dart

class AppStartupAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    dispatch(LoadUserAction());
    dispatch(LoadSettingsAction());
    dispatch(LoadCacheAction());

    // Wait for all initialization to complete
    await waitCondition((state) =>
      state.user != null &&
      state.settings != null &&
      state.cacheReady
    );

    return state.copy(appReady: true);
  }
}

Wait for User Confirmation

dart

class DeleteAccountAction extends ReduxAction<AppState> {
  @override
  Future<AppState?> reduce() async {
    // Show confirmation dialog
    dispatch(ShowConfirmationDialogAction(
      message: 'Are you sure you want to delete your account?',
    ));

    // Wait for user response
    await waitCondition((state) =>
      state.confirmationResult != null
    );

    if (state.confirmationResult != true) {
      return null; // User cancelled
    }

    // Proceed with deletion
    await api.deleteAccount();
    return state.copy(accountDeleted: true);
  }
}

References

URLs from the documentation:

Search AI Tools

asyncredux-wait-condition

Install this agent skill to your Project

SKILL.md

Waiting for State Conditions with waitCondition()

Method Signature

Basic Usage Inside an Action

Waiting for Value Thresholds

Coordinating Between Actions

Implementing Conditional Workflows

Using the Return Value

Using completeImmediately Parameter

Setting Timeouts

Using waitCondition() from the Store

Testing with waitCondition()

Comparison with Other Wait Methods

Common Patterns

Wait for Initialization

Wait for User Confirmation

References