|
| 1 | +## [UNPUBLISHED] |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +**`Firestore`**: |
| 6 | +- **BREAKING**: `settings()` is now a synchronous setter that accepts a `Settings` instance. |
| 7 | + - **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. |
| 8 | +- **BREAKING**: `enablePersistence()` is now a Web only method, use `[Settings.persistenceEnabled]` instead for other platforms. |
| 9 | +- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`. |
| 10 | +- **DEPRECATED**: Class `Firestore` is now deprecated. Use `FirebaseFirestore` instead. |
| 11 | +- **DEPRECATED**: Calling `Firestore(app: app)` is now deprecated. Use `FirebaseFirestore.instance` or `FirebaseFirestore.instanceFor(app: app)` instead. |
| 12 | +- **NEW**: Added `clearPersistence()` support. |
| 13 | +- **NEW**: Added `disableNetwork()` support. |
| 14 | +- **NEW**: Added `enableNetwork()` support. |
| 15 | +- **NEW**: Added `snapshotInSync()` listener support. |
| 16 | +- **NEW**: Added `terminate()` support. |
| 17 | +- **NEW**: Added `waitForPendingWrites()` support. |
| 18 | +- **FIX**: All document/query listeners & currently in progress transactions are now correctly torn down between Hot Restarts. |
| 19 | + |
| 20 | +**`CollectionReference`**: |
| 21 | +- **BREAKING**: Getting a collection parent document via `parent()` has been changed to a getter `parent`. |
| 22 | +- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`. |
| 23 | + |
| 24 | +**`Query`**: |
| 25 | +- **BREAKING**: The internal query logic has been overhauled to better assert invalid queries locally. |
| 26 | +- **DEPRECATED**: Calling `getDocuments()` is deprecated in favor of `get()`. |
| 27 | +- **BREAKING**: `getDocuments`/`get` has been updated to accept an instance of `GetOptions` (see below). |
| 28 | +- **NEW**: Query methods can now be chained. |
| 29 | +- **NEW**: It is now possible to call same-point cursor based queries without throwing (e.g. calling `endAt()` and then `endBefore()` will replace the "end" cursor query with the `endBefore`). |
| 30 | +- **NEW**: Added support for the `limitToLast` query modifier. |
| 31 | + |
| 32 | +**`QuerySnapshot`**: |
| 33 | +- **DEPRECATED**: `documents` has been deprecated in favor of `docs`. |
| 34 | +- **DEPRECATED**: `documentChanges` has been deprecated in favor of `docChanges`. |
| 35 | +- **NEW**: `docs` now returns a `List<QueryDocumentSnapshot>` vs `List<DocumentSnapshot>`. This doesn't break existing functionality. |
| 36 | + |
| 37 | +**`DocumentReference`**: |
| 38 | +- **BREAKING**: `setData`/`set` has been updated to accept an instance of `SetOptions` (see below, supports `mergeFields`). |
| 39 | +- **BREAKING**: `get()` has been updated to accept an instance of `GetOptions` (see below). |
| 40 | +- **BREAKING**: Getting a document parent collection via `parent()` has been changed to a getter `parent`. |
| 41 | +- **DEPRECATED**: `documentID` has been deprecated in favor of `id`. |
| 42 | +- **DEPRECATED**: `setData()` has been deprecated in favor of `set()`. |
| 43 | +- **DEPRECATED**: `updateData()` has been deprecated in favor of `update()`. |
| 44 | + |
| 45 | +**`DocumentChange`**: |
| 46 | +- **DEPRECATED**: Calling `document()` is deprecated in favor of `doc()`. |
| 47 | + |
| 48 | +**`DocumentSnapshot`**: |
| 49 | +- **BREAKING**: The `get data` getter is now a `data()` method instead. |
| 50 | +- **DEPRECATED**: `documentID` has been deprecated in favor of `id`. |
| 51 | +- **NEW**: Added support for fetching nested snapshot data via the `get()` method. If no data exists at the given path, a `StateError` will be thrown. |
| 52 | +- **FIX**: `NaN` values stored in your Firestore instance are now correctly parsed when reading & writing data. |
| 53 | +- **FIX**: `INFINITY` values stored in your Firestore instance are now correctly parsed when reading & writing data. |
| 54 | +- **FIX**: `-INFINITY` values stored in your Firestore instance are now correctly parsed when reading & writing data. |
| 55 | + |
| 56 | +**`WriteBatch`**: |
| 57 | +- **DEPRECATED**: `setData()` has been deprecated in favor of `set()`. |
| 58 | +- **DEPRECATED**: `updateData()` has been deprecated in favor of `update()`. |
| 59 | +- **BREAKING**: `setData`/`set` now supports `SetOptions` to merge data/fields (previously this accepted a `Map`). |
| 60 | + |
| 61 | +**`Transaction`**: |
| 62 | +- **BREAKING**: Transactions have been overhauled to address a number of critical issues: |
| 63 | + - 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`. |
| 64 | + - When manually throwing an exception, the context was lost and a generic `PlatformException` was thrown. You can now throw & catch on any exceptions. |
| 65 | + - 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. |
| 66 | +- **FIX**: Timeouts will now function correctly. |
| 67 | +- **FIX**: iOS: transaction completion block incorrectly resolving a `FlutterResult` multiple times. |
| 68 | + |
| 69 | +See the new [transactions documentation](https://firebase.flutter.dev/docs/firestore/usage#transactions) to learn more. |
| 70 | + |
| 71 | +**`FieldPath`**: |
| 72 | +- **NEW **: The constructor has now been made public to accept a `List` of `String` 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. `[email protected]`) was impossible. |
| 73 | + |
| 74 | +**`GetOptions`**: New class created to support how data is fetched from Firestore (`server`, `cache`, `serverAndCache`). |
| 75 | + |
| 76 | +**`SetOptions`**: New class created to both `merge` and `mergeFields` when setting data on documents. |
| 77 | + |
| 78 | +**`GeoPoint`**: |
| 79 | +- **BREAKING**: Add latitude and longitude validation when constructing a new `GeoPoint` instance. |
| 80 | + |
1 | 81 | ## 0.13.7+1 |
2 | 82 |
|
3 | 83 | * Fix crash where listeners are not removed when app quits. |
|
0 commit comments