Skip to content

Instantly share code, notes, and snippets.

@Salakar

Salakar/firebase_firestore.md

Last active January 28, 2022 21:59
Show Gist options
  • Save Salakar/a36bd0902d7d0c705696da9318cf4e71 to your computer and use it in GitHub Desktop.
Save Salakar/a36bd0902d7d0c705696da9318cf4e71 to your computer and use it in GitHub Desktop.
Download ZIP
Changes preview of the current FlutterFirebase Firestore plugin rework.
Raw
firebase_firestore.md

Description

⚠️ 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 a Settings 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 of doc().
  • DEPRECATED: Calling Firestore(app: app) is now deprecated. Use Firestore.instance or Firestore.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 getter parent.
  • DEPRECATED: Calling document() is deprecated in favor of doc().

Query:

  • BREAKING: The internal query logic has been overhauled to better assert invalid queries locally.
  • DEPRECATED: Calling getDocuments() is deprecated in favor of get().
  • BREAKING: getDocuments/get has been updated to accept an instance of GetOptions (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 then endBefore() will replace the "end" cursor query with the endBefore).
  • NEW: Added support for the limitToLast query modifier.

QuerySnapshot:

  • DEPRECATED: documents has been deprecated in favor of docs.
  • DEPRECATED: documentChanges has been deprecated in favor of docChanges.

DocumentReference:

  • BREAKING: setData/set has been updated to accept an instance of SetOptions (see below, supports mergeFields).
  • BREAKING: get() has been updated to accept an instance of GetOptions (see below).
  • BREAKING: Getting a document parent collection via parent() has been changed to a getter parent.
  • DEPRECATED: documentID has been deprecated in favor of id.
  • DEPRECATED: setData() has been deprecated in favor of set().
  • DEPRECATED: updateData() has been deprecated in favor of update().

DocumentChange:

  • DEPRECATED: Calling document() is deprecated in favor of doc().

DocumentSnapshot:

  • BREAKING: The get data getter is now a data() method instead.
  • DEPRECATED: documentID has been deprecated in favor of id.
  • 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.
  • 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 of set().
  • DEPRECATED: updateData() has been deprecated in favor of update().
  • BREAKING: setData/set now supports SetOptions to merge data/fields (previously this accepted a Map).

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.
  • 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 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.

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

Related PRs

@Levi-Lesches
Copy link

(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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment