asyncredux-action-status

# ActionStatus in AsyncRedux

The `ActionStatus` object provides information about whether an action completed successfully or encountered errors. It is returned by `dispatchAndWait()` and related methods.

## Getting ActionStatus

Use `dispatchAndWait()` to get the status after an action completes:

```dart
var status = await dispatchAndWait(MyAction());
```

From within an action, you can also use:

```dart
var status = await dispatchAndWait(SomeOtherAction());
```

## ActionStatus Properties

### Completion Status

- **`isCompleted`**: Returns `true` if the action has finished executing (whether successful or failed)
- **`isCompletedOk`**: Returns `true` if the action finished without errors in both `before()` and `reduce()` methods
- **`isCompletedFailed`**: Returns `true` if the action encountered errors (opposite of `isCompletedOk`)

### Error Information

- **`originalError`**: The error originally thrown by `before()` or `reduce()`, before any modification
- **`wrappedError`**: The error after processing by the action's `wrapError()` method

### Execution Tracking

These properties track which lifecycle methods have completed:

- **`hasFinishedMethodBefore`**: Returns `true` if the `before()` method completed
- **`hasFinishedMethodReduce`**: Returns `true` if the `reduce()` method completed
- **`hasFinishedMethodAfter`**: Returns `true` if the `after()` method completed

Note: The execution tracking properties are primarily meant for testing and debugging. In production code, focus on `isCompletedOk` and `isCompletedFailed`.

## Common Use Cases

### Conditional Navigation After Success

The most common production use is checking if an action succeeded before navigating:

```dart
// In a widget callback
Future<void> _onSavePressed() async {
  var status = await context.dispatchAndWait(SaveFormAction());
  if (status.isCompletedOk) {
    Navigator.pop(context);
  }
}
```

Another example with push navigation:

```dart
Future<void> _onLoginPressed() async {
  var status = await context.dispatchAndWait(LoginAction(
    email: emailController.text,
    password: passwordController.text,
  ));

  if (status.isCompletedOk) {
    Navigator.pushReplacementNamed(context, '/home');
  }
  // If failed, the error will be shown via UserExceptionDialog
}
```

### Testing Action Errors

Use ActionStatus to verify that actions throw expected errors:

```dart
test('MyAction fails with invalid input', () async {
  var store = Store<AppState>(initialState: AppState.initial());

  var status = await store.dispatchAndWait(MyAction(value: -1));

  expect(status.isCompletedFailed, isTrue);
  expect(status.wrappedError, isA<UserException>());
  expect((status.wrappedError as UserException).msg, "Value must be positive");
});
```

### Testing Action Success

```dart
test('SaveAction completes successfully', () async {
  var store = Store<AppState>(initialState: AppState.initial());

  var status = await store.dispatchAndWait(SaveAction(data: validData));

  expect(status.isCompletedOk, isTrue);
  expect(store.state.saved, isTrue);
});
```

### Checking Original vs Wrapped Error

When your action uses `wrapError()` to transform errors, you can inspect both:

```dart
class MyAction extends AppAction {
  @override
  Future<AppState?> reduce() async {
    throw Exception('Network error');
  }

  @override
  Object? wrapError(Object error, StackTrace stackTrace) {
    return UserException('Could not save. Please try again.');
  }
}

// In test:
var status = await store.dispatchAndWait(MyAction());
expect(status.originalError, isA<Exception>()); // The original Exception
expect(status.wrappedError, isA<UserException>()); // The wrapped UserException
```

## Action Lifecycle and Status

The action lifecycle runs in this order:

1. `before()` - Runs first, can be used for preconditions
2. `reduce()` - Runs second (only if `before()` succeeded)
3. `after()` - Runs last, always executes (like a finally block)

The `isCompletedOk` property is `true` only if both `before()` and `reduce()` completed without errors. Note that errors in `after()` do not affect `isCompletedOk`.

If `before()` throws an error, `reduce()` will not run, but `after()` will still execute.

## Best Practices

1. **Use state changes for UI updates**: In production, prefer checking state changes rather than action status. Reserve ActionStatus for cases where you need to perform side effects (like navigation) based on success/failure.

2. **Use `isCompletedOk` for navigation**: The common pattern is to navigate only after an action succeeds:
   ```dart
   if (status.isCompletedOk) Navigator.pop(context);
   ```

3. **Use `wrappedError` in tests**: When testing error handling, check `wrappedError` to see what the user will actually see (after `wrapError()` processing).

4. **Use `originalError` for debugging**: When you need to see the underlying error before any transformation, use `originalError`.

## References

URLs from the documentation:
- https://asyncredux.com/flutter/advanced-actions/action-status
- https://asyncredux.com/flutter/basics/dispatching-actions
- https://asyncredux.com/flutter/basics/failed-actions
- https://asyncredux.com/flutter/advanced-actions/errors-thrown-by-actions
- https://asyncredux.com/flutter/advanced-actions/before-and-after-the-reducer
- https://asyncredux.com/flutter/advanced-actions/redux-action
- https://asyncredux.com/flutter/miscellaneous/navigation
- https://asyncredux.com/flutter/testing/store-tester
- https://asyncredux.com/flutter/testing/dispatch-wait-and-expect
- https://asyncredux.com/flutter/testing/testing-user-exceptions