firestore_plus 0.0.2
firestore_plus: ^0.0.2 copied to clipboard
Production-ready Firestore utilities for Flutter — caching, retry, error handling, pagination, logging, transactions, batch operations and more.
0.0.2 #
Fixes found by integration-testing the package from a fresh consumer app against the Firestore emulator (macOS and Android).
Bug fixes #
- Retry: jitter no longer crashes with
RangeErrorwhen the backoff delay is 1 ms; very large attempt counts clamp tomaxDelayinstead of overflowing. - Writes (
set,update,delete,add) no longer retry timeouts by default. A timed-out write is still queued by Firestore, so retrying could apply it more than once (e.g.FieldValue.incrementapplied 4 times). FirestorePlusException.pathis now set for network errors (wasnull).- Batch commit and transaction errors keep their real type and code
(e.g.
permissionDenied,notFound) instead ofunknown. runTransactionnow throwsFirestorePlusExceptionfor Firestore failures; exceptions thrown by your own code inside the transaction are rethrown unchanged.- Document and query streams emit Firestore errors as
FirestorePlusException. - Transaction reads that fail to deserialize report
serialization.toFirestorefailures insetreportserialization. - Writes (including batches and transactions) now invalidate the cached query results of the affected collection, not only the document. Transactions previously invalidated nothing.
invalidateCollection/MemoryCacheStore.clearCollectionnow also clear cached query results.staleWhileRevalidateon a cache miss now throws network errors instead of returningnullas if the document did not exist.- A document found missing on the server is removed from the cache, so it is
no longer served later by
cacheOnlyor anetworkFirstfallback. - Query cache keys are collision-free: different
Filterqueries (and cursor values containing commas) no longer share a cache entry. paginate:hasMoreis exact (fetcheslimit + 1), no extra empty page; cached pages no longer contain aDocumentSnapshot, so persistent cache stores work; a cursor is still returned for pages served from cache.limit <= 0throwsArgumentError.MemoryCacheStorecopies values, so mutating a returned map no longer corrupts the cache.- Metrics:
retryCountandservedFromCacheare now accurate (were always0/false). A throwing metrics listener no longer fails the operation. - Request deduplication no longer shares results between reads with different cache policies.
- Custom loggers now only receive messages at or above their
logLevel(previously every debug message was delivered; onlyConsoleFirestoreLoggerfiltered). NewFirestorePlusLogger.isEnabled.
Other #
CacheManageris exported (the type ofFirestorePlus.cache) and gainsinvalidateDocumentandinvalidateQueries.RetryExecutor.executegains optionalpathandonRetryparameters.- Environment constraints now match the dependencies: Dart
^3.6.0, Flutter>=3.27.0.metarelaxed to^1.15.0(was^1.18.0, which excluded Flutter releases before 3.41). - README corrected to match actual behaviour (missing documents return
null, retry/timeout semantics, cache invalidation scope, custom store contract). - The example is now a runnable app (emulator-first, no Firebase project needed).
Behaviour changes to note #
- Stream and
runTransactionerrors are nowFirestorePlusExceptioninstead ofFirebaseException. - Query cache keys changed format; entries in a persistent custom store from 0.0.1 will simply miss.
0.0.1 #
- Initial development release.
- Support for typed collections, documents, and queries.
- Caching framework (
CacheManager,MemoryCacheStore). - Retry engine with exponential backoff and jitter.
- Built-in error mapping and normalizer (
FirestorePlusException). - Request deduplication for read operations.
- Cursor-based pagination (
PaginatedResult). FirestoreBatchandFirestoreTransactionwrappers.- Structured logging and operation metrics.