mineral_cache 2.0.0

Cache for the Mineral framework.

Cache

The cache package provides a straightforward and effective solution for cache management in Mineral applications. By externalizing application consumption, it helps improve performance and optimize resources, thus offering a better user experience.

Introduction

Caching plays a crucial role in many applications by offering a temporary and decoupled storage solution from the core of the project. It helps optimize performance by reducing response times and limiting calls to external resources such as databases or APIs.

Features

• In-Memory Cache — stores data directly in memory, providing fast response times for accessing data already loaded into the cache.
• Redis Cache — distributed caching with sub-second TTL precision via SET … PX.

Installation

dependencies:
  mineral_cache: ^1.2.0

Then run dart pub get.

Usage

final client = ClientBuilder()
  .setIntent(Intent.allNonPrivileged)
  .setCache(MemoryProvider.new)
  .build();

setCache accepts an optional config: to customize the runtime behavior:

.setCache(MemoryProvider.new, config: CacheConfig.defaults())   // default
.setCache(MemoryProvider.new, config: CacheConfig.legacy())     // pre-v5
.setCache(MemoryProvider.new, config: CacheConfig(
  ttlPolicy: CacheTtlPolicy.defaults().override({
    'users/': const Duration(minutes: 15),
  }),
  sweeperInterval: const Duration(seconds: 30),
))

Cache strategy

CacheConfig.defaults() is applied automatically when setCache(provider) is called without a config. It enables four behaviors:

Flag	Default	What it does
ttlPolicy	CacheTtlPolicy.defaults()	Longest-match prefix/segment rules. See table below.
clearOnReady	true	Clears the cache on the first READY to discard data stale during downtime.
invalidationEnabled	true	Routes cache.invalidate(...) calls inside packet listeners to cache.remove(...).
sweeperInterval	1 minute	In-memory provider sweeps expired entries on this cadence (Duration.zero disables it).
staggerClearMs	500	Random delay applied before clearOnReady runs, to spread reconnect storms across shards.

TTL policy defaults

Key family	Example	TTL
ref:…	ref:server/123/assets	never
voice_states/…	voice_states/server/1/members/2	5 minutes
…/members/…	server/1/members/2	30 minutes
…/roles/…	server/1/roles/9	4 hours
…/emojis/…	server/1/emojis/9	12 hours
…/stickers/…	server/1/stickers/9	12 hours
…/messages/…	channels/1/messages/2	10 minutes
server/…	server/123	4 hours
channels/…	channels/456	2 hours
users/…	users/789	1 hour
threads/…	threads/100	2 hours
messages/…	messages/200/embeds/uid	10 minutes
invites/…	invites/abc123	1 hour

Custom rules win over defaults via CacheTtlPolicy.override({'users/': Duration(minutes: 15)}).

Opting out

To preserve the pre-TTL behavior (entries live forever, no automatic invalidation):

.setCache(MemoryProvider.new, config: CacheConfig.legacy())

Custom CacheProviderContract implementations must accept the {Duration? ttl} named optional on put / putMany.