QueryClient

The QueryClient is the core controller of Fasq. It manages the query cache, deduplication, and garbage collection.

Initialization

It is best to provide the QueryClient at the top of your widget tree using QueryClientProvider, but it can also be used as a singleton if desired.

import 'package:fasq/fasq.dart';

void main() {
  final client = QueryClient();

  runApp(
    QueryClientProvider(
      client: client,
      child: MyApp(),
    ),
  );
}

Global Configuration

You can define default behaviors for all queries in your app.

final client = QueryClient(
  config: const CacheConfig(
    defaultStaleTime: Duration(minutes: 5), // Data is fresh for 5 mins
    defaultCacheTime: Duration(minutes: 30), // Inactive data kept for 30 mins
  ),
);

Cache Management

Invalidation

Mark data as stale so it gets refetched the next time it’s used.

// Invalidate a single query
client.invalidateQuery('todos'.toQueryKey());

// Invalidate with refetch (default behavior for active queries)
client.invalidateQuery('todos'.toQueryKey(), refetchType: InvalidateType.active);

Pre-fetching

Load data before the user navigates there to provide an instant experience.

await client.prefetchQuery(
  'todos'.toQueryKey(),
  () => fetchTodos(),
);

Manual Updates

You can update the cache directly without hitting the network (useful for optimistic updates).

// Update data
client.setQueryData<List<Todo>>(
  'todos'.toQueryKey(),
  (oldData) => [...?oldData, newTodo],
);

// Read data
final todos = client.getQueryData<List<Todo>>('todos'.toQueryKey());

Observers

QueryClient supports observers that can monitor all query and mutation lifecycle events. This is useful for logging, analytics, error tracking, and more.

Adding Observers

final client = QueryClient();

// Add built-in logger
client.addObserver(FasqLogger());

// Add custom observer
client.addObserver(MyCustomObserver());

Built-in Logger

Fasq includes FasqLogger for development debugging:

client.addObserver(FasqLogger(
  enabled: true,
  showData: false, // Privacy-first: don't log data by default
  truncateLength: 100,
));

For complete logging documentation, see Logging.

Custom Observers

Create custom observers by implementing QueryClientObserver:

class AnalyticsObserver implements QueryClientObserver {
  @override
  void onQuerySuccess(QuerySnapshot snapshot, QueryMeta? meta, BuildContext? context) {
    analytics.track('query_success', {
      'key': snapshot.queryKey.toString(),
      'duration': calculateDuration(snapshot),
    });
  }

  // Implement other observer methods...
}

Observer Management

// Add observer
client.addObserver(myObserver);

// Remove observer
client.removeObserver(myObserver);

// Clear all observers
client.clearObservers();

Error Reporters

QueryClient supports error reporters that receive detailed context when queries fail. This is useful for integrating with external error tracking services like Sentry or Crashlytics.

Adding Error Reporters

final client = QueryClient();

// Add error reporter
client.addErrorReporter(SentryErrorReporter());

// You can add multiple reporters
client.addErrorReporter(CrashlyticsErrorReporter());
client.addErrorReporter(CustomErrorReporter());

Error Reporter Interface

Implement the FasqErrorReporter interface to create custom reporters:

class SentryErrorReporter implements FasqErrorReporter {
  @override
  void report(FasqErrorContext context) {
    Sentry.captureException(
      context.error,
      stackTrace: context.stackTrace,
      hint: Hint.withMap({
        'queryKey': context.queryKey.join('/'),
        'retryCount': context.retryCount,
        'networkStatus': context.networkStatus ? 'online' : 'offline',
      }),
    );
  }
}

Error Context

When a query fails, reporters receive a FasqErrorContext containing:

• Query key that failed
• Retry count
• Network status
• Error and stack trace
• Sanitized query options (PII automatically removed)

Managing Reporters

// Add reporter
client.addErrorReporter(myReporter);

// Remove reporter
client.removeErrorReporter(myReporter);

For complete documentation on error tracking, including PII sanitization, integration examples, and best practices, see Error Tracking.

Performance Metrics

Fasq provides built-in performance monitoring to help you understand your app’s query behavior and optimize performance.

Getting Global Metrics

Get a comprehensive snapshot of all performance metrics:

final client = QueryClient();
final snapshot = client.getMetrics();

print('Cache hit rate: ${snapshot.cacheMetrics.hitRate}');
print('Active queries: ${snapshot.activeQueries}');
print('Memory usage: ${snapshot.memoryUsageBytes / 1024 / 1024} MB');

Getting Query-Specific Metrics

Get detailed metrics for a specific query:

final metrics = client.getQueryMetrics('todos'.toQueryKey());

if (metrics != null) {
  print('Fetch count: ${metrics.fetchCount}');
  print('Avg fetch time: ${metrics.averageFetchTime?.inMilliseconds}ms');
  print('Throughput: ${metrics.throughputMetrics?.requestsPerMinute} RPM');
}

Configuring Metrics Exporters

Export metrics to external monitoring systems (console, JSON, OpenTelemetry):

final client = QueryClient();

client.configureMetricsExporters(
  MetricsConfig(
    exporters: [
      ConsoleExporter(),
      JsonExporter(),
    ],
    exportInterval: Duration(minutes: 1),
    enableAutoExport: true,
  ),
);

For more details, see the Performance Monitoring and Metrics Exporters documentation.

API Reference

Method	Description
fetchQuery	Fetches a query and returns the result (throws on error).
prefetchQuery	Fetches a query and stores it in cache (no return, safe).
getQueryData	Synchronously returns the current data in cache.
setQueryData	Synchronously updates the data in cache.
invalidateQuery	Marks queries as stale and potentially refetches them.
cancelQuery	Cancels any outgoing fetches for a query.
resetQuery	Resets a query to its initial state.
addObserver	Adds a QueryClientObserver to monitor query/mutation events.
removeObserver	Removes an observer from the client.
clearObservers	Removes all observers from the client.
addErrorReporter	Adds an error reporter to receive query failure notifications.
removeErrorReporter	Removes an error reporter from the client.
getMetrics	Returns a snapshot of global performance metrics.
getQueryMetrics	Returns performance metrics for a specific query.
configureMetricsExporters	Configures metrics exporters and auto-export.
exportMetricsManually	Manually triggers an immediate metrics export.