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)
  ),
);