Question: Why does selectAsync return Future instead of AsyncValue?

[shtse8]

Question: Why does selectAsync return Future instead of AsyncValue?

Context

I'm reading the documentation about performance optimization using selectAsync for asynchronous providers. The documentation shows this example:

@riverpod
Object? example(Ref ref) async {
  // Wait for a user to be available, and listen to only the "firstName" property
  final firstName = await ref.watch(
    userProvider.selectAsync((it) => it.firstName),
  );

  // TODO use "firstName" to fetch something else
}

Question

I understand that returning a Future works well within async provider functions where we can use await. However, I'm confused about how to use selectAsync in widget build methods, which are synchronous contexts.

Why does selectAsync return Future<T> instead of AsyncValue<T>?

Use Case

In a widget build method, I want to:

1. Select only specific properties from an async provider
2. Handle loading/error states properly
3. Avoid unnecessary rebuilds when other properties change

Current Problem

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // This doesn't work because build() is sync but selectAsync returns Future
    final firstName = ref.watch(userProvider.selectAsync((it) => it.firstName));
    
    // How do I handle loading/error states here?
    return Text('Hello $firstName'); // This won't compile
  }
}

Expected Behavior

I would expect something like:

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final firstNameAsync = ref.watch(userProvider.selectAsync((it) => it.firstName));
    
    return firstNameAsync.when(
      data: (firstName) => Text('Hello $firstName'),
      loading: () => CircularProgressIndicator(),
      error: (error, stack) => Text('Error: $error'),
    );
  }
}

Current Workaround and Issues

Option 1: Skip selectAsync (loses performance benefit)

final userAsync = ref.watch(userProvider);
return userAsync.when(
  data: (user) => Text('Hello ${user.firstName}'),
  loading: () => CircularProgressIndicator(),
  error: (error, stack) => Text('Error: $error'),
);

Problem: This defeats the purpose of selectAsync for performance optimization, as the widget will rebuild when any property of user changes, not just firstName.

Option 2: Use selectAsync + useFuture (inconsistent API)

final firstNameFuture = ref.watch(userProvider.selectAsync((it) => it.firstName));
final firstNameSnapshot = useFuture(firstNameFuture);

return firstNameSnapshot.when(
  data: (firstName) => Text('Hello $firstName'),
  // But wait, AsyncSnapshot doesn't have .when()!
);

// Have to use AsyncSnapshot API instead:
if (firstNameSnapshot.connectionState == ConnectionState.waiting) {
  return CircularProgressIndicator();
}
if (firstNameSnapshot.hasError) {
  return Text('Error: ${firstNameSnapshot.error}');
}
return Text('Hello ${firstNameSnapshot.data}');

Problem: This creates API inconsistency in the codebase:

• Some parts use AsyncValue with .when(), .maybeWhen(), etc.
• Other parts use AsyncSnapshot with .connectionState, .hasError, etc.
• Two different mental models for handling async states
• Code becomes harder to maintain and reason about

Questions

1. Is there a recommended way to use selectAsync in widget build methods?
2. Would it make sense to have selectAsync return AsyncValue<T> instead of Future<T>?
3. Or should there be a separate method (like selectAsyncValue) for widget contexts?
4. How do you handle the API inconsistency between AsyncValue and AsyncSnapshot in a large codebase? Having some widgets use .when() pattern and others use .connectionState makes the code harder to maintain.

Impact on Developer Experience

The current design forces developers to choose between:

• Performance (using selectAsync + useFuture but with inconsistent APIs)
• API Consistency (sticking with AsyncValue everywhere but losing performance benefits)

This shouldn't be a trade-off we have to make.

Thanks for any guidance on this!

[bailyzheng]

I have the same question.

[rrousselGit]

Are you looking for select?

[NAMATOVU-CHRISTINE]

The maintainer's hint is correct you're looking for select, not selectAsync.

The Difference

• selectAsync - Returns Future<T>, designed for use inside async providers with await
• select - Returns AsyncValue<T>, designed for use in widget build methods

Solution for Your Use Case

class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Use select (not selectAsync) for widgets
    final firstNameAsync = ref.watch(
      userProvider.select((asyncValue) => asyncValue.whenData((user) => user.firstName)),
    );

    return firstNameAsync.when(
      data: (firstName) => Text('Hello $firstName'),
      loading: () => const CircularProgressIndicator(),
      error: (error, stack) => Text('Error: $error'),
    );
  }
}