Cache Configuration

Fasq provides a flexible caching system that efficiently manages memory and freshness. You can configure global policies for cache size, eviction strategies, and default entry lifespans.

Usage

Configure the cache when creating your QueryClient.

import 'package:fasq/fasq.dart';

final client = QueryClient(
  config: const CacheConfig(
    // 1. Storage Limits
    maxSizeBytes: 10 * 1024 * 1024, // 10 MB
    maxEntries: 100,                // 100 Queries

    // 2. Default Query Behavior
    defaultStaleTime: Duration(minutes: 5),
    defaultCacheTime: Duration(minutes: 30),
  ),
);

API

CacheConfig Properties

Property	Type	Default	Description
maxSizeBytes	int	50MB	limits the total memory usage of the cache.
maxEntries	int?	null	max number of query entries to keep.
defaultStaleTime	Duration	Duration.zero	default time before data becomes stale.
defaultCacheTime	Duration	5 mins	default time to keep inactive data.
enableGarbageCollection	bool	true	ensures removed queries free memory.
gcInterval	Duration	5 mins	how often to run the garbage collector.

Eviction Policies

When the cache reaches its maxSizeBytes or maxEntries limit, it must decide which items to remove.

Policy	Description	Use Case
EvictionPolicy.lru	Least Recently Used. Removes the items that haven’t been accessed for the longest time.	Default. Best for general purpose caching.
EvictionPolicy.lfu	Least Frequently Used. Removes items that are accessed least often.	Good when some data is “hot” and should stick around, while other data is one-off.
EvictionPolicy.fifo	First In, First Out. Removes the oldest items created.	Simple buffer behavior.

Examples

LRU Strategy (Least Recently Used)

Fasq uses an LRU eviction policy by default. When the cache exceeds limits, the least recently accessed queries are removed first.

final client = QueryClient(
  config: const CacheConfig(
    maxEntries: 50, // Keep only the latest 50 visited queries
  ),
);

High-Performance / Realtime Setup

For apps that need frequent updates but want to avoid memory leaks.

final client = QueryClient(
  config: const CacheConfig(
    defaultStaleTime: Duration.zero,     // Always refetch for freshness
    defaultCacheTime: Duration(minutes: 2), // aggressively free memory
    gcInterval: Duration(minutes: 1),    // Cleanup often
  ),
);

Static Data Setup

For apps like e-readers or catalogs where data rarely changes.

final client = QueryClient(
  config: const CacheConfig(
    defaultStaleTime: Duration(hours: 1),  // Data stays fresh for 1 hour
    defaultCacheTime: Duration(hours: 24), // Keep in memory all day
    maxSizeBytes: 100 * 1024 * 1024,       // Allow large cache (100 MB)
  ),
);