useQueries Hook

Execute multiple queries in parallel with the Hooks adapter.

Basic Usage

import 'package:fasq_hooks/fasq_hooks.dart';

class Dashboard extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final queries = useQueries([
      QueryConfig('users', () => api.fetchUsers()),
      QueryConfig('posts', () => api.fetchPosts()),
      QueryConfig('comments', () => api.fetchComments()),
    ]);

    return Column(
      children: [
        UsersList(queries[0]),
        PostsList(queries[1]),
        CommentsList(queries[2]),
      ],
    );
  }
}

API Reference

useQueries

List<QueryState<dynamic>> useQueries(List<QueryConfig> configs)

Parameters:

• configs: List of query configurations

Returns:

• List<QueryState<dynamic>>: Array of query states corresponding to each config

QueryConfig

class QueryConfig<T> {
  final String key;
  final Future<T> Function() queryFn;
  final QueryOptions? options;

  const QueryConfig(this.key, this.queryFn, {this.options});
}

Parameters:

• key: Unique identifier for the query
• queryFn: Function that returns a Future with the data
• options: Optional query configuration

State Management

Checking Aggregate States

final queries = useQueries(configs);

// All queries have data
final allLoaded = queries.every((q) => q.hasData);

// Any query is loading
final anyLoading = queries.any((q) => q.isLoading);

// Any query has error
final hasError = queries.any((q) => q.hasError);

// All queries successful
final allSuccess = queries.every((q) => q.isSuccess);

Accessing Individual States

final queries = useQueries(configs);

// Access by index
final userState = queries[0];
final postState = queries[1];
final commentState = queries[2];

// Type-safe access
final userState = queries[0] as QueryState<List<User>>;
final postState = queries[1] as QueryState<List<Post>>;

Named Queries with useNamedQueries

For better developer experience, you can use named queries with map-based access:

import 'package:fasq_hooks/fasq_hooks.dart';

class Dashboard extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final queries = useNamedQueries([
      NamedQueryConfig(name: 'users', key: 'users', queryFn: () => api.fetchUsers()),
      NamedQueryConfig(name: 'posts', key: 'posts', queryFn: () => api.fetchPosts()),
      NamedQueryConfig(name: 'comments', key: 'comments', queryFn: () => api.fetchComments()),
    ]);

    final allLoaded = queries.values.every((q) => q.hasData);
    final anyError = queries.values.any((q) => q.hasError);

    return Column(
      children: [
        if (!allLoaded) LinearProgressIndicator(),
        if (anyError) ErrorBanner(),
        UsersList(queries['users']!),
        PostsList(queries['posts']!),
        CommentsList(queries['comments']!),
      ],
    );
  }
}

NamedQueryConfig

The NamedQueryConfig class provides configuration for named queries:

class NamedQueryConfig<T> {
  final String name;        // Name identifier for this query
  final String key;         // Unique identifier for this query
  final Future<T> Function() queryFn;  // Function that returns a Future with the data
  final QueryOptions? options;         // Optional configuration for this query
}

Benefits of Named Access

• Better DX: Access queries by meaningful names instead of indices
• Type Safety: Compile-time checking for query names
• Self-Documenting: Code is more readable and maintainable
• Refactoring Safe: Renaming queries updates all references

Advanced Patterns

Conditional Queries

class ConditionalDashboard extends HookWidget {
  final bool loadComments;

  const ConditionalDashboard({required this.loadComments});

  @override
  Widget build(BuildContext context) {
    final configs = [
      QueryConfig('users', () => api.fetchUsers()),
      QueryConfig('posts', () => api.fetchPosts()),
      if (loadComments)
        QueryConfig('comments', () => api.fetchComments()),
    ];

    final queries = useQueries(configs);

    return Column(
      children: [
        UsersList(queries[0]),
        PostsList(queries[1]),
        if (loadComments) CommentsList(queries[2]),
      ],
    );
  }
}

Dynamic Query Lists

class DynamicDashboard extends HookWidget {
  final List<String> userIds;

  const DynamicDashboard({required this.userIds});

  @override
  Widget build(BuildContext context) {
    final configs = userIds.map((id) =>
      QueryConfig('user-$id', () => api.fetchUser(id))
    ).toList();

    final queries = useQueries(configs);

    return Column(
      children: queries.asMap().entries.map((entry) {
        final index = entry.key;
        final state = entry.value;
        final userId = userIds[index];

        return UserCard(
          userId: userId,
          state: state,
        );
      }).toList(),
    );
  }
}

Error Handling

class ErrorHandlingDashboard extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final queries = useQueries([
      QueryConfig('users', () => api.fetchUsers()),
      QueryConfig('posts', () => api.fetchPosts()),
      QueryConfig('comments', () => api.fetchComments()),
    ]);

    final hasError = queries.any((q) => q.hasError);
    final errorQueries = queries.where((q) => q.hasError).toList();

    return Column(
      children: [
        if (hasError)
          ErrorBanner(
            errors: errorQueries.map((q) => q.error).toList(),
            onRetry: () {
              for (final query in errorQueries) {
                query.refetch();
              }
            },
          ),

        // Show successful queries
        ...queries.where((q) => q.hasData).map((q) =>
          DataWidget(state: q)
        ),
      ],
    );
  }
}

Performance Tips

Stable Query Keys

// Good: Stable keys
final queries = useQueries([
  QueryConfig('users', () => api.fetchUsers()),
  QueryConfig('posts', () => api.fetchPosts()),
]);

// Avoid: Dynamic keys that change on each render
final queries = useQueries([
  QueryConfig('users-${DateTime.now()}', () => api.fetchUsers()),
  QueryConfig('posts-${DateTime.now()}', () => api.fetchPosts()),
]);

Memoized Configs

class MemoizedDashboard extends HookWidget {
  @override
  Widget build(BuildContext context) {
    // Memoize configs to prevent unnecessary re-execution
    final configs = useMemoized(() => [
      QueryConfig('users', () => api.fetchUsers()),
      QueryConfig('posts', () => api.fetchPosts()),
    ], []);

    final queries = useQueries(configs);

    return Column(
      children: [
        UsersList(queries[0]),
        PostsList(queries[1]),
      ],
    );
  }
}

Testing

testWidgets('useQueries executes all queries', (tester) async {
  await tester.pumpWidget(
    HookBuilder(
      builder: (context) {
        final queries = useQueries([
          QueryConfig('query1', () => Future.value('data1')),
          QueryConfig('query2', () => Future.value('data2')),
        ]);

        return Column(
          children: queries.map((q) =>
            Text(q.data?.toString() ?? 'loading')
          ).toList(),
        );
      },
    ),
  );

  await tester.pumpAndSettle();

  expect(find.text('data1'), findsOneWidget);
  expect(find.text('data2'), findsOneWidget);
});

Common Pitfalls

1. Changing Config Array Reference

// Bad: Creates new array on each render
Widget build(BuildContext context) {
  final queries = useQueries([
    QueryConfig('users', () => api.fetchUsers()),
    QueryConfig('posts', () => api.fetchPosts()),
  ]);
}

// Good: Stable array reference
class Dashboard extends HookWidget {
  static const _configs = [
    QueryConfig('users', () => api.fetchUsers()),
    QueryConfig('posts', () => api.fetchPosts()),
  ];

  @override
  Widget build(BuildContext context) {
    final queries = useQueries(_configs);
  }
}

2. Not Handling Empty States

// Bad: Assumes queries always exist
Widget build(BuildContext context) {
  final queries = useQueries(configs);
  return UsersList(queries[0]); // Could crash if configs is empty
}

// Good: Handle empty states
Widget build(BuildContext context) {
  final queries = useQueries(configs);
  if (queries.isEmpty) return const SizedBox();
  return UsersList(queries[0]);
}

3. Ignoring Loading States

// Bad: No loading indication
Widget build(BuildContext context) {
  final queries = useQueries(configs);
  return Column(
    children: queries.map((q) => DataWidget(q)).toList(),
  );
}

// Good: Show loading states
Widget build(BuildContext context) {
  final queries = useQueries(configs);
  return Column(
    children: [
      if (queries.any((q) => q.isLoading)) LinearProgressIndicator(),
      ...queries.map((q) => DataWidget(q)),
    ],
  );
}