putQuery<T> method

ZenQuery<T> putQuery<T>({
  1. required Object queryKey,
  2. required ZenQueryFetcher<T> fetcher,
  3. ZenQueryConfig? config,
  4. T? initialData,
})

Register a scoped query with automatic lifecycle management.

This method creates a ZenQuery tied to this scope and automatically registers it. The query will be disposed when the scope is disposed, preventing memory leaks.

Parameters:

  • queryKey: Unique identifier for the query (used for caching and deduplication)
  • fetcher: Async function that fetches the data (receives cancel token)
  • config: Optional configuration for cache behavior, retries, etc.
  • initialData: Optional initial data to show before first fetch

Returns: The created ZenQuery instance for further customization

Example:

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

Benefits:

  • ✅ Automatic scope binding (no manual scope: this needed)
  • ✅ Automatic registration (no separate scope.put() call)
  • ✅ Auto-disposal when scope disposes (prevents memory leaks)
  • ✅ Consistent with scope.put() / scope.putLazy() API pattern

See also:

Implementation

ZenQuery<T> putQuery<T>({
  required Object queryKey,
  // CHANGED: Now accepts a ZenQueryFetcher (takes cancelToken)
  required ZenQueryFetcher<T> fetcher,
  ZenQueryConfig? config,
  T? initialData,
}) {
  final query = ZenQuery<T>(
    queryKey: queryKey,
    fetcher: fetcher,
    config: config,
    initialData: initialData,
    scope: this, // Automatically scoped
  );
  put(query); // Automatically registered
  return query;
}