useEntityQuery<T extends Object> function

EntityQueryResult<T> useEntityQuery<T extends Object>(
  1. WidgetRef ref, {
  2. required String type,
  3. required String queryKey,
  4. required EntityDecoder<T> fromGraph,
  5. EntityEncoder<T>? toGraph,
  6. ListQuery initialQuery = const ListQuery(),
  7. ViewCompleteness completeness = ViewCompleteness.remote,
  8. bool enabled = true,
  9. 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,
  );
}