flutter_cache_bloc 0.4.0

Cache-first Bloc primitives with optional persistence for keyed entities, paginated collections, and synchronized multi-list UI.

0.4.0

• Adds HiveCachePersistenceStorage, the recommended default durable storage backed by Hive.
• Enables encryption by default for Hive-backed cache snapshots.
• Stores the generated Hive AES key with platform secure storage when no custom encryption key provider is supplied.
• Adds encrypted: false for public/debug caches that intentionally do not need encryption.
• Adds namespace, boxName, path, pathProvider, and custom encryptionKeyProvider configuration for apps that need finer storage control.
• Adds MemoryCachePersistenceStorage for tests, examples, previews, and memory-only demonstrations.
• Extends CachePersistenceStorage with clear() so a storage namespace can be fully reset.
• Adds clearPersistedStorage() to EntityCacheBloc and PagedCacheBloc for namespace-level durable cleanup.
• Updates Bloc close behavior so a manually deleted durable snapshot is not rewritten on close unless a new state change schedules another write.
• Expands code comments and README examples for encrypted persistence, custom storage adapters, cleanup, and retry/outbox use cases.

Breaking changes

• Custom CachePersistenceStorage implementations must now implement clear().

0.3.1

• Allows PagedCacheBloc.insertItem to create a missing collection before inserting the item. This supports durable chat/outbox flows where a delivered message may arrive before that conversation history has been opened in the UI.

0.3.0

• Removes the hard dependency on infinite_scroll_pagination.
• Replaces the external PagingState in the public API with the package-owned PagedCacheData, containing pages, keys, flat items, loading, error, hasNextPage, and updatedAt.
• Keeps PagedCacheView independent from any scrolling package so consumers can use Flutter lists, infinite_scroll_pagination, or another UI adapter.
• Adds optional durable caching through CachePersistenceStorage, CacheCodec, EntityCachePersistence, and PagedCachePersistence.
• Adds per-key shouldPersist filters so one Bloc can keep selected entities or collections durable while leaving the rest memory-only.
• Adds optional maxAge filtering for restored snapshots.
• Adds automatic cache restoration with optional stale-while-revalidate through refreshAfterRestore.
• Queues base and feature-specific Bloc events until restoration completes to prevent startup requests from overwriting durable data.
• Adds restored and isRestored APIs for startup reconciliation and outbox retry workflows.
• Adds debounced writes, persistNow(), clearPersistedCache(), and durable cleanup when clearCache() is used.
• Adds clearCacheAndWait() for safe logout and account-switch cleanup before Bloc disposal.
• Adds removeCollection() and clearCache() to PagedCacheBloc.
• Keeps restored paged data visible when a background refresh fails.
• Adds persistence, selective-storage, optimistic-item restoration, offline refresh, and memory-only tests.

Breaking changes

• PagedCacheView.builder, PagedCacheBloc.paging, cachedEntries, and PagedCacheState.cache now expose PagedCacheData<T> instead of PagingState<int, T>.
• Consumers of infinite_scroll_pagination must map PagedCacheData to that package's PagingState in their app or integration layer.
• PagedCacheData.items, pages, and keys are non-null collections.

0.2.0

• Adds configurable pagination strategies for PagedCacheBloc.
• Adds PagedCacheBloc.offset(...) for skip + limit APIs.
• Adds PagedCacheBloc.page(...) for page-number APIs with configurable zero-based or one-based first page.
• Adds PagedCacheBloc.custom(...), PagedCachePageRequest, and CustomPagedCachePagination for non-standard integer-key pagination.
• Keeps the unnamed PagedCacheBloc(...) constructor as a backwards-compatible alias for offset pagination.
• Updates paged cache rebalancing so generated PagingState.keys follow the selected pagination strategy after local insert/update/remove mutations.
• Adds tests for offset pagination, zero-based page pagination, and one-based page pagination.

0.1.0

• Initial public release.
• Adds EntityCacheBloc for cache-first single-entity state keyed by id.
• Adds EntityCacheState and EntityState with loading, refreshing, success, error, TTL, invalidation and read helper APIs.
• Adds PagedCacheBloc for cache-first paginated lists keyed by id.
• Adds LRU-style cache eviction for both entity and paged stores.
• Adds request deduplication to avoid duplicate fetches for the same key.
• Adds stale-while-revalidate behavior for entity cache reads.
• Adds optimistic entity mutations through upsertEntity, upsertEntityAs and updateEntity.
• Adds paged list mutations through insertItem, updateItem, removeItem and their cascade/everywhere variants.
• Adds updateFirstItemEverywhere to patch one matching item across every cached paginated list owned by the same Bloc instance. This is useful for social feeds, notifications, marketplace lists and other screens where the same entity appears in multiple tabs or lists.
• Adds refreshCachedWhere, refreshAllCached, refreshActive and wait helpers for imperative workflows.
• Adds EntityCacheView and PagedCacheView widgets for scoped BlocSelector rebuilds.
• Adds safe handling for unexpected paged fetcher exceptions by storing the thrown object in the affected PagingState.
• Adds tests covering entity updates, paged loading, paged fetcher exceptions and multi-list synchronization.