ZenQuery<T> class

A reactive query that manages async data fetching with caching and cancellation

Example:

final userQuery = ZenQuery<User>(
  queryKey: 'user:123',
  fetcher: (token) => api.getUser(123, cancelToken: token),
  config: ZenQueryConfig(
    staleTime: Duration(minutes: 5),
    retryCount: 3,
  ),
);

Inheritance

Implementers

ZenInfiniteQuery

Available extensions

Constructors

ZenQuery({required Object queryKey, required ZenQueryFetcher<T> fetcher, ZenQueryConfig? config, T? initialData, ZenScope? scope, bool autoDispose = true, bool registerInCache = true, bool enabled = true, List<String>? tags})

Properties

activeWatcherCount → int: Get count of active watchers (useful for debugging)
no setterinherited
autoDispose → bool: Whether to automatically dispose when scope disposes
final
childControllerCount → int: Get count of tracked child controllers for debugging
no setterinherited
childControllerStats → Map<String, int>: Get stats about child controllers
no setterinherited
config → ZenQueryConfig<T>: Configuration for this query
final
createdAt → DateTime: no setterinherited
data → Rx<T?>: Current data (null if not loaded yet)
final
enabled → RxBool: Whether the query is enabled to fetch data
final
error → Rx<Object?>: Current error (null if no error)
final
fetcher → ZenQueryFetcher<T>: Function that fetches the data
final
fetchStatus → Rx<ZenQueryFetchStatus>: Current network fetch status
final
hasData → bool: Whether the query has data
no setter
hasError → bool: Whether the query has an error
no setter
hashCode → int: The hash code for this object.
no setterinherited
initialData → T?: Optional initial data
final
isDisposed → bool: Whether this query has been disposed
no setteroverride
isFetching → bool: Whether this query is currently fetching data from the network
no setter
isInitialized → bool: no setterinherited
isLoading → RxBool: Whether the query is currently loading
no setter
isPlaceholderData → RxBool: Whether the current data is placeholder data
final
isReady → bool: no setterinherited
isRefetching → bool: Whether the query is currently refetching (loading while having data)
no setter
isStale → bool: Whether data is stale and needs refetching
no setter
queryKey → String: Unique key for this query (used for caching and deduplication)
final
reactiveObjectCount → int: Get count of tracked reactive objects for debugging
no setterinherited
reactiveStats → Map<String, int>: Get stats about reactive objects
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scope → ZenScope?: Optional scope - if provided, query will be tied to this scope
final
status → Rx<ZenQueryStatus>: Current status of the query
final
tags → List<String>: Tags for group-based invalidation.
final

Methods

addDisposer(void disposer()) → void: Add a disposer function that will be called when the controller is disposed
inherited
addUpdateListener(String updateId, VoidCallback listener) → void: Register a listener for a specific update ID
inherited
cancel([String reason = 'Query cancelled']) → void: Cancel any pending or in-flight fetch request for this query.
condition<T>(ValueNotifier<T> obs, bool condition(T), void callback(T)) → ZenWorker: inherited
createEffect<T>({required String name}) → ZenEffect<T>: Create an effect that will be auto-disposed with this controller
inherited
createWorkerGroup() → ZenWorkerGroup: Create a managed worker group
inherited
createWorkers(List<ZenWorker Function()> creators) → List<ZenWorker>: Available on ZenController, provided by the ZenControllerWorkerExtension extension
Create multiple workers in one call
debounce<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker: inherited
didChangeAppLifecycleState(AppLifecycleState state) → void: Override from WidgetsBindingObserver to handle app lifecycle
inherited
dispose() → void: Dispose the controller and clean up ALL resources - PREVENTS MEMORY LEAKS
inherited
disposeWorkers(List<ZenWorker> workers) → void: Available on ZenController, provided by the ZenControllerWorkerExtension extension
Dispose specific workers
ever<T>(ValueNotifier<T> obs, void callback(T)) → ZenWorker: Type-safe convenience worker methods
inherited
fetch({bool force = false}) → Future<T>: Fetch or refetch data
getResourceStats() → Map<String, dynamic>: Get comprehensive resource usage statistics
inherited
getWorkerStats() → Map<String, dynamic>: Get worker statistics for debugging/monitoring
inherited
interval<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker: inherited
invalidate() → void: Invalidate query (mark as stale and refetch if active)
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
obs<T>(T initialValue) → Rx<T>: Create and auto-track a reactive variable - PREVENTS MEMORY LEAKS
inherited
obsList<T>([List<T>? initialValue]) → RxList<T>: Create and auto-track a reactive list - PREVENTS MEMORY LEAKS
inherited
obsMap<K, V>([Map<K, V>? initialValue]) → RxMap<K, V>: Create and auto-track a reactive map - PREVENTS MEMORY LEAKS
inherited
obsSet<T>([Set<T>? initialValue]) → RxSet<T>: Create and auto-track a reactive set - PREVENTS MEMORY LEAKS
inherited
once<T>(ValueNotifier<T> obs, void callback(T)) → ZenWorker: inherited
onClose() → void: User-defined cleanup hook - called before internal disposal
override
onDetached() → void: Called when the app is detached
inherited
onHidden() → void: Called when the app is hidden
inherited
onInactive() → void: Called when the app is inactive
inherited
onInit() → void: Internal method called by child controllers to auto-register with parent This is called automatically during child controller construction if a parent exists
inherited
onPause() → void: Called when the app is paused (goes to background)
inherited
onReady() → void: inherited
onResume() → void: Called when the app is resumed (comes back to foreground)
inherited
pause() → void: Pause this query
pauseAllWorkers() → void: Pause all workers managed by this controller
inherited
pauseSpecificWorkers(List<ZenWorker> workers) → void: Available on ZenController, provided by the ZenControllerWorkerExtension extension
Pause specific workers
performFetch() → Future<T>: Perform the actual fetch with retry logic. Intended to be overridden by subclasses like ZenInfiniteQuery.
refetch() → Future<T>: Refetch data (force refresh)
removeUpdateListener(String updateId, VoidCallback listener) → void: Remove a listener for a specific update ID
inherited
reset() → void: Reset query to idle state
resume() → void: Resume this query
resumeAllWorkers() → void: Resume all workers managed by this controller
inherited
resumeSpecificWorkers(List<ZenWorker> workers) → void: Available on ZenController, provided by the ZenControllerWorkerExtension extension
Resume specific workers
select<R>(R selector(T data)) → ZenQuery<R>: Creates a derived query that selects a subset of data.
setData(T newData) → void: Manually set data (for optimistic updates)
throttle<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker: inherited
toString() → String: A string representation of this object.
override
trackController<T extends ZenController>(T controller) → T: Track a child controller (like ZenQuery, ZenStreamQuery) for automatic disposal
inherited
trackReactive(Rx reactive) → void: Manually track a reactive object (for external reactive objects)
inherited
update([List<String>? updateIds]) → void: Optimized update method that can notify specific listeners or all listeners
inherited
watch<T>(ValueNotifier<T> observable, void callback(T), {WorkerType type = WorkerType.ever, Duration? duration, bool condition(T)?}) → ZenWorker: Create workers that auto-dispose with controller
inherited
when({required Widget data(T data), Widget loading()?, Widget error(Object error, VoidCallback retry)?, Widget idle()?, bool autoFetch = true, bool showStaleData = true}) → Widget: Available on ZenQuery<T>, provided by the ZenQueryWhenExtension extension
Builds UI declaratively based on the query state.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

activeFetches → RxInt: Number of currently running query fetches globally.
final
anyFetching → bool: Returns true if ANY query is currently fetching.
no setter

ZenQuery<T> class

Constructors

Properties

Methods

Operators

Static Properties

zen_query library