Dart Store

A Dart port of Store5 - A Kotlin Multiplatform library for building network-resilient applications.

Features

• Type-Safe Caching: In-memory caching with LRU eviction
• Source of Truth: Swappable persistence layer (Hive, ObjectBox, Drift, etc.)
• Request Deduplication: Automatic coalescing of concurrent requests
• Reactive Streams: Built on Dart Streams and Futures
• Functional Error Handling: Using FpDart's Either and Option types
• RxDart Integration: Advanced reactive operators

Core Types

• ✅ StoreKey - Single, Collection, Page, and Cursor key types
• ✅ StoreData - Single and Collection data types with insertion strategies
• ✅ InsertionStrategy - Append, Prepend, Replace
• ✅ KeyProvider - Bidirectional key conversion
• ✅ ExperimentalStoreApi - Annotation for experimental features

Response Types

• ✅ StoreReadResponse - Sealed class hierarchy for responses
  • Initial - Initial state
  • Loading - Loading state with origin tracking
  • Data - Successful data response
  • NoNewData - Empty response from fetcher
  • Error - Exception, Message, and Custom error types
• ✅ StoreReadResponseOrigin - Origin tracking (Cache, SourceOfTruth, Fetcher, Initial)

Store Interface

• ✅ Store - Main interface combining read and clear operations
• ✅ StoreRead - Stream-based reactive data access
• ✅ StoreClear - Cache clearing operations

Fetcher System

• ✅ Fetcher - Network data fetching abstraction
  • Factory methods: of, ofStream, ofResult, ofResultStream
  • Fallback support: withFallback, ofStreamWithFallback
• ✅ FetcherResult - Result type for fetcher operations
  • Data - Successful fetch with optional origin
  • Error - Exception, Message, and Custom error types
  • FpDart integration (Either, Option)

Request Configuration

• ✅ StoreReadRequest - Flexible request configuration
  • fresh - Skip all caches, fetch fresh data
  • cached - Use cache, optionally refresh
  • localOnly - Never fetch, cache only
  • skipMemory - Skip memory cache, use disk
• ✅ CacheType - Memory and Disk cache types

Source of Truth

• ✅ SourceOfTruth - Database abstraction layer
  • Factory methods: of (Future-based), ofFlow (Stream-based)
  • Operations: reader, write, delete, deleteAll
  • Supports reactive database updates
  • Database-agnostic interface
• ✅ Exception types:
  • SourceOfTruthWriteException - Write operation failures
  • SourceOfTruthReadException - Read operation failures

Validation

• ✅ Validator - Custom validation for cached items
  • Factory: Validator.by for function-based validation
  • Async validation support
  • Used to determine if cached data should be refreshed

Cache System

• ✅ Cache - In-memory cache interface
  • Operations: getIfPresent, getOrPut, put, putAll, invalidate, invalidateAll
  • Batch operations: getAllPresent(keys), getAllPresent()
  • Size tracking: size()
• ✅ CacheBuilder - Fluent builder for cache configuration
  • Size limits: maximumSize(int), weigher(int, Weigher)
  • Time-based expiration: expireAfterWrite(Duration), expireAfterAccess(Duration)
  • Custom time source: ticker(Ticker) for testing
  • Concurrency: concurrencyLevel(int)
• ✅ InMemoryCache - LRU cache implementation
  • Automatic eviction based on size or weight
  • Time-based expiration (write time and access time)
  • Efficient LRU ordering with LinkedHashMap

Supporting Types

• ✅ Ticker - Nanosecond-precision time source
• ✅ Weigher - Custom entry weight calculation
• ✅ RemovalCause - Reason for cache entry removal (explicit, replaced, expired, size, collected)

Multicast System

• ✅ Multicaster - Shares one upstream Stream with multiple downstream listeners
  • Lazy upstream activation (starts when first listener subscribes)
  • Automatic cleanup when all listeners cancel
  • Broadcast stream sharing for concurrent requests
  • Optional onEach callback for value inspection
• ✅ FetcherController - Request deduplication for network fetches
  • Deduplicates concurrent requests for the same key
  • Tracks active fetch operations
  • Operations: getFetcher, cancelFetch, cancelAll
  • Status checks: isActive(key), activeCount

Installation

Add this to your pubspec.yaml:

dependencies:
persistencestore:
path: ../persistencestore # Adjust path as needed

Usage

Basic Example

import'package:persistencestore/persistencestore.dart';
// Define your modelsclassUserextendsStoreDataSingle<int> {
@overridefinalint id;
finalString name;
finalString email;
constUser(this.id, this.name, this.email);
}
// Create a fetcherfinal userFetcher =Fetcher.of<int, User>(
(userId) async {
// Fetch from your APIfinal response =await api.getUser(userId);
returnUser(response.id, response.name, response.email);
},
name:'user-fetcher',
);
// The Store interfaceabstractclassUserStoreimplementsStore<int, User> {
// Stream of responses with cache and network@overrideStream<StoreReadResponse<User>> stream(StoreReadRequest<int> request);
@overrideFuture<void> clear(int key);
@overrideFuture<void> clearAll();
}
// Usage patternsvoidexample(Store<int, User> store) async {
// Get fresh data from networkfinal user =await store.fresh(123);
print('User: ${user.name}');
// Get cached data, refresh in backgroundfinal cachedUser =await store.get(123, refresh:true);
// Stream of responses
store.stream(StoreReadRequest.cached(123, refresh:true))
.listen((response) {
switch (response) {
caseStoreReadResponseLoading(:final origin):print('Loading from $origin');
caseStoreReadResponseData(:final value):print('Got ${value.name}');
caseStoreReadResponseError():print('Error: ${response.errorMessageOrNull()}');
default:break;
}
});
}

Fetcher Examples

// Simple Future-based fetcherfinal fetcher1 =Fetcher.of<String, Data>(
(key) async=>await api.fetch(key),
);
// Stream-based fetcher (e.g., WebSocket)final fetcher2 =Fetcher.ofStream<String, Data>(
(key) => websocket.stream(key),
);
// Fetcher with fallbackfinal fetcher3 =Fetcher.withFallback<String, Data>(
name:'primary',
fetch: (key) async=>await primaryApi.fetch(key),
fallback:Fetcher.of((key) async=>await backupApi.fetch(key)),
);
// Manual result handlingfinal fetcher4 =Fetcher.ofResult<String, Data>(
(key) async {
try {
final data =await api.fetch(key);
returnFetcherResultData(data);
} catch (e) {
returnFetcherResultErrorException(Exception(e.toString()));
}
},
);

Source of Truth Examples

// Future-based (non-reactive) databasefinal sot1 =SourceOfTruth.of<String, User, User>(
nonFlowReader: (key) async {
// Read from databasereturnawait database.getUser(key);
},
writer: (key, user) async {
// Write to databaseawait database.saveUser(key, user);
},
delete: (key) async {
await database.deleteUser(key);
},
deleteAll: () async {
await database.clearUsers();
},
);
// Stream-based (reactive) database (e.g., Drift, Hive with watch)final sot2 =SourceOfTruth.ofFlow<String, User, User>(
reader: (key) {
// Return reactive stream from databasereturn database.watchUser(key);
},
writer: (key, user) async {
await database.saveUser(key, user);
},
delete: (key) async {
await database.deleteUser(key);
},
);
// Type transformation example (Network -> Local)final sot3 =SourceOfTruth.of<int, NetworkUser, LocalUser>(
nonFlowReader: (userId) async {
final local =await db.getUserById(userId);
return local;
},
writer: (userId, networkUser) async {
// Transform network model to local modelfinal localUser =LocalUser(
id: networkUser.id,
name: networkUser.fullName,
email: networkUser.emailAddress,
cachedAt:DateTime.now(),
);
await db.insertUser(localUser);
},
);

Validator Examples

// Simple validationfinal validator1 =Validator.by<User>((user) async {
return user.name.isNotEmpty && user.email.isNotEmpty;
});
// Time-based validation (TTL)final validator2 =Validator.by<CachedData>((data) async {
final age =DateTime.now().difference(data.cachedAt);
return age.inMinutes <5; // Valid for 5 minutes
});
// Async validation with API checkfinal validator3 =Validator.by<Document>((doc) async {
// Check with server if document version is currentfinal serverVersion =await api.getDocumentVersion(doc.id);
return doc.version >= serverVersion;
});
// Complex validation logicfinal validator4 =Validator.by<Product>((product) async {
// Multiple validation checksif (product.price <=0) returnfalse;
if (product.stock <0) returnfalse;
// Check if data is stalefinal age =DateTime.now().difference(product.lastUpdated);
if (age.inHours >24) returnfalse;
returntrue;
});

Cache Examples

// Basic cache with size limitfinal cache1 =CacheBuilder<String, User>()
.maximumSize(100)
.build();
cache1.put('user:123', User(id:'123', name:'Alice'));
final user = cache1.getIfPresent('user:123');
// Cache with time-based expirationfinal cache2 =CacheBuilder<String, ApiResponse>()
.expireAfterWrite(Duration(minutes:5))
.maximumSize(50)
.build();
// Cache with access-based expiration (keeps frequently accessed items)final cache3 =CacheBuilder<String, Document>()
.expireAfterAccess(Duration(minutes:10))
.maximumSize(200)
.build();
// Cache with custom weigher (e.g., by data size)final cache4 =CacheBuilder<String, Image>()
.weigher(
1024*1024*10, // 10MB max
(key, image) => image.sizeInBytes,
)
.build();
// Cache with all featuresfinal cache5 =CacheBuilder<int, CachedData>()
.maximumSize(1000)
.expireAfterWrite(Duration(minutes:15))
.expireAfterAccess(Duration(minutes:5))
.concurrencyLevel(8)
.build();
// Using getOrPut for lazy loadingfinal data = cache5.getOrPut(42, () {
// Only called if not in cachereturnfetchDataFromNetwork(42);
});
// Batch operations
cache5.putAll({
1: data1,
2: data2,
3: data3,
});
final subset = cache5.getAllPresent([1, 2, 5]); // Returns {1: data1, 2: data2}// Invalidation
cache5.invalidate(1); // Remove single entry
cache5.invalidateAll([2, 3]); // Remove multiple entries
cache5.invalidateAll(); // Clear entire cache

Request Deduplication Examples

// Create a fetcher controller for request deduplicationfinal controller =FetcherController<String, User>();
// Multiple concurrent requests for the same user// Only one network call will be madefinal futures = [
controller.getFetcher('user:123', () =>fetchUserFromApi('123')),
controller.getFetcher('user:123', () =>fetchUserFromApi('123')),
controller.getFetcher('user:123', () =>fetchUserFromApi('123')),
];
// All three will receive the same result from a single fetchfinal results =awaitFuture.wait(futures.map((s) => s.first));
// Check active fetchesif (controller.isActive('user:123')) {
print('Fetch in progress');
}
print('Active fetches: ${controller.activeCount}');
// Cancel a specific fetchawait controller.cancelFetch('user:456');
// Cancel all active fetchesawait controller.cancelAll();
// Using Multicaster directly for custom scenariosfinal multicaster =Multicaster<int>(
source: () =>expensiveDataStream(),
onEach: (value) =>print('Received: $value'),
);
// Multiple subscribers share the same upstreamfinal stream1 = multicaster.newDownstream();
final stream2 = multicaster.newDownstream();
awaitFuture.wait([
stream1.forEach((v) =>print('Stream 1: $v')),
stream2.forEach((v) =>print('Stream 2: $v')),
]);
// Clean upawait multicaster.close();

License

MIT

Credits

This is a port of Store5 by the Mobile Native Foundation, originally created by Google and the open-source community.