useEntityQuery<T extends Object> function
- WidgetRef ref, {
- required String type,
- required String queryKey,
- required EntityDecoder<
T> fromGraph, - EntityEncoder<
T> ? toGraph, - ListQuery initialQuery = const ListQuery(),
- ViewCompleteness completeness = ViewCompleteness.remote,
- bool enabled = true,
- bool subscribe = true,
Watches a normalized list under a query this hook owns and mutates.
Every setter replaces the whole ListQuery rather than mutating one, so the value handed to the provider family is a new instance and the family re-keys exactly when the query changes — not on every render, and not never.
Changing the search term or the filter clears ListQuery.cursor: a cursor
is a position within one result set, and carrying it across a query change
pages into a set that no longer exists. Changing sort clears it for the same
reason. setLimit does not, since the cursor stays valid under a page-size
change.
Implementation
EntityQueryResult<T> useEntityQuery<T extends Object>(
WidgetRef ref, {
required String type,
required String queryKey,
required EntityDecoder<T> fromGraph,
EntityEncoder<T>? toGraph,
ListQuery initialQuery = const ListQuery(),
ViewCompleteness completeness = ViewCompleteness.remote,
bool enabled = true,
bool subscribe = true,
}) {
final queryState = useState<ListQuery>(initialQuery);
final query = queryState.value;
final provider = useMemoized(
() => entityListProvider<T>(
type: type,
queryKey: queryKey,
fromGraph: fromGraph,
toGraph: toGraph,
query: query,
completeness: completeness,
enabled: enabled,
subscribe: subscribe,
),
[type, queryKey, query, completeness, enabled, subscribe],
);
final snapshot = ref.watch(provider);
return EntityQueryResult<T>(
snapshot: snapshot,
query: query,
setSearch: (search) => queryState.value = ListQuery(
filter: query.filter,
sort: query.sort,
search: search,
limit: query.limit,
// cursor deliberately dropped — see doc comment
),
setSort: (sort) => queryState.value = ListQuery(
filter: query.filter,
sort: sort,
search: query.search,
limit: query.limit,
),
setFilter: (filter) => queryState.value = ListQuery(
filter: filter,
sort: query.sort,
search: query.search,
limit: query.limit,
),
setLimit: (limit) => queryState.value = query.copyWith(limit: limit),
setCursor: (cursor) => queryState.value = query.copyWith(cursor: cursor),
reset: () => queryState.value = initialQuery,
);
}