⚠️ NOTE: These changes may not reflect the final plugin changes/API as it's still going through review.
Along with the below changes, the plugin has undergone a quality of life update to better support exceptions thrown. Any Firestore specific errors now return a FirebaseException
, allowing you to directly access the code (e.g. permission-denied
) and message.
Firestore
:
- BREAKING:
settings()
is now a synchronous setter that accepts aSettings
instance.- NEW: This change allows us to support changing Firestore settings (such as using the Firestore emulator) without having to quit the application, e.g. Hot Restarts.
- DEPRECATED: Calling
document()
is deprecated in favor ofdoc()
. - DEPRECATED: Calling
Firestore(app: app)
is now deprecated. UseFirestore.instance
orFirestore.instanceFor(app: app)
instead. - NEW: Added
clearPersistence()
support. - NEW: Added
disableNetwork()
support. - NEW: Added
enableNetwork()
support. - NEW: Added
snapshotInSync()
listener support. - NEW: Added
terminate()
support. - NEW: Added
waitForPendingWrites()
support. - FIX: All document/query listeners & currently in progress transactions are now correctly torn down between Hot Restarts.
CollectionReference
:
- BREAKING: Getting a collection parent document via
parent()
has been changed to a getterparent
. - DEPRECATED: Calling
document()
is deprecated in favor ofdoc()
.
Query
:
- BREAKING: The internal query logic has been overhauled to better assert invalid queries locally.
- DEPRECATED: Calling
getDocuments()
is deprecated in favor ofget()
. - BREAKING:
getDocuments
/get
has been updated to accept an instance ofGetOptions
(see below). - NEW: Query methods can now be chained.
- NEW: It is now possible to call same-point cursor based queries without throwing (e.g. calling
endAt()
and thenendBefore()
will replace the "end" cursor query with theendBefore
). - NEW: Added support for the
limitToLast
query modifier.
QuerySnapshot
:
- DEPRECATED:
documents
has been deprecated in favor ofdocs
. - DEPRECATED:
documentChanges
has been deprecated in favor ofdocChanges
.
DocumentReference
:
- BREAKING:
setData
/set
has been updated to accept an instance ofSetOptions
(see below, supportsmergeFields
). - BREAKING:
get()
has been updated to accept an instance ofGetOptions
(see below). - BREAKING: Getting a document parent collection via
parent()
has been changed to a getterparent
. - DEPRECATED:
documentID
has been deprecated in favor ofid
. - DEPRECATED:
setData()
has been deprecated in favor ofset()
. - DEPRECATED:
updateData()
has been deprecated in favor ofupdate()
.
DocumentChange
:
- DEPRECATED: Calling
document()
is deprecated in favor ofdoc()
.
DocumentSnapshot
:
- BREAKING: The
get data
getter is now adata()
method instead. - DEPRECATED:
documentID
has been deprecated in favor ofid
. - NEW: Added support for fetching nested snapshot data via the
get()
method. If no data exists at the given path, aStateError
will be thrown. - FIX:
NaN
values stored in your Firestore instance are now correctly parsed when reading & writing data. - FIX:
INFINITY
values stored in your Firestore instance are now correctly parsed when reading & writing data. - FIX:
-INFINITY
values stored in your Firestore instance are now correctly parsed when reading & writing data.
WriteBatch
:
- DEPRECATED:
setData()
has been deprecated in favor ofset()
. - DEPRECATED:
updateData()
has been deprecated in favor ofupdate()
. - BREAKING:
setData
/set
now supportsSetOptions
to merge data/fields (previously this accepted aMap
).
Transaction
:
- BREAKING: Transactions have been overhauled to address a number of critical issues:
- Values returned from the transaction will now be returned from the Future. Previously, only JSON serializable values were supported. It is now possible to return any value from your transaction handler, e.g. a
DocumentSnapshot
. - When manually throwing an exception, the context was lost and a generic
PlatformException
was thrown. You can now throw & catch on any exceptions. - The modify methods on a transaction (
set
,delete
,update
) were previously Futures. These have been updated to better reflect how transactions should behave - they are now synchronous and are executed atomically once the transaction handler block has finished executing.
- Values returned from the transaction will now be returned from the Future. Previously, only JSON serializable values were supported. It is now possible to return any value from your transaction handler, e.g. a
- FIX: Timeouts will now function correctly.
- FIX: iOS: transaction completion block incorrectly resolving a
FlutterResult
multiple times.
See the new transactions documentation to learn more.
FieldPath
:
- NEW: The constructor has now been made public to accept a
List
ofString
values. Previously field paths were accessible only via a dot-notated string path. This meant attempting to access a field in a document with a.
in the name (e.g.foo.bar@gmail.com
) was impossible.
GetOptions
: New class created to support how data is fetched from Firestore (server
, cache
, serverAndCache
).
SetOptions
: New class created to both merge
and mergeFields
when setting data on documents.
GeoPoint
:
- BREAKING: Add latitude and longitude validation when constructing a new
GeoPoint
instance.
Related Issues
- Fixes firebase/flutterfire#833
- Fixes firebase/flutterfire#774
- Fixes firebase/flutterfire#2081
- Fixes firebase/flutterfire#211
- Fixes firebase/flutterfire#857
- Fixes firebase/flutterfire#1311
- Fixes firebase/flutterfire#855
- Fixes firebase/flutterfire#1223
- Fixes firebase/flutterfire#2101
- Fixes firebase/flutterfire#2291
- Fixes firebase/flutterfire#185
- Fixes firebase/flutterfire#2338
- Fixes firebase/flutterfire#2293
Related PRs
(I was gonna post this in the actual PR, but that's locked now)
I noticed that cloud_firestore_web has an option for using the cache (using
GetOptions(source: Source.cache)
), but it doesn't seem to actually be implemented. Are there plans to fix that that soon? (cc @Ehesp since he's on that TODO)https://github.com/FirebaseExtended/flutterfire/blob/master/packages/cloud_firestore/cloud_firestore_web/lib/src/document_reference_web.dart#L43