refactor(database)!: rework as part of #6979

[Salakar]

Description

Realtime Database has been fully reworked to bring the plugin inline with the federated plugin
setup, a more familiar API, better documentation and many more unit and end-to-end tests.

• General

• Fixed an issue where providing a Map with int keys would crash.

• FirebaseDatabase

• DEPRECATED: FirebaseDatabase() has now been deprecated in favor of FirebaseDatabase.instanceFor().

• DEPRECATED: reference() has now been deprecated in favor of ref().

• NEW: Added support for ref(), which allows you to provide an optional path to any database node rather than calling child().

• NEW: Add emulator support via useDatabaseEmulator().

• NEW: Add support for refFromURL().

• BREAKING: setPersistenceEnabled() is now synchronous.

• BREAKING: setPersistenceCacheSizeBytes() is now synchronous.

• BREAKING: setLoggingEnabled() is now synchronous.

• DatabaseReference

• BREAKING: parent is now a getter (inline with the JavaScript API).

• BREAKING: root is now a getter (inline with the JavaScript API).

• BREAKING: set() now accepts an Object? value (rather than dynamic) and no longer accepts a priority.

• NEW: Added support for setWithPriority().

• NEW: Added support for locally applying transaction results via the applyLocally property on runTransaction.

• Query

• NEW: once() now accepts an optional DatabaseEventType (rather than just subscribing to the value).

• BREAKING: limitToFirst() now asserts the value is positive.

• BREAKING: limitToLast() now asserts the value is positive.

• OnDisconnect

  • BREAKING: set() now accepts an Object? value (rather than dynamic) and no longer accepts a priority.
  • NEW: Added support for setWithPriority().

• Event

• BREAKING: The Event class returned from database queries has been renamed to DatabaseEvent.

• NEW: DatabaseEvent (old Event)

• The DatabaseEventType is now returned on the event.

• The previousChildKey is now returned on the event (previously called previousSiblingKey).

• NEW: DatabaseEventType

• A DatabaseEventType is now returned from a DatabaseEvent.

• DataSnapshot

• NEW: Added support for accessing the priority via the .priority getter.

• NEW: Added support for determining whether the snapshot has a child via hasChild().

• NEW: Added support for accessing a snapshot child node via child().

• NEW: Added support for iterating the child nodes of the snapshot via the .children getter.

  • BREAKING snapshot.value are no longer pre-sorted when using order queries, use .children
    if you need to iterate over your value keys in order.

• TransactionResult

• BREAKING: The result of a transaction no longer returns a DatabaseError, instead handle errors of a transaction via a Future completion error.

• NEW: Transaction

  • NEW: Added Transaction.success(value) return this from inside your TransactionHandler to indicate a successful execution.
  • NEW: Added Transaction.abort() return this from inside your TransactionHandler to indicate that the transaction should be aborted.

• TransactionHandler

  • BREAKING Transaction handlers must now always return an instance of Transaction either via Transaction.success() or Transaction.abort().

• DatabaseError

• BREAKING: The DatabaseError class has been removed. Errors are now returned as a FirebaseException inline with the other plugins.

Related Issues

• Closes 🐛 [firebase_database] get() query ignors startAt() and endAt() constrains #7221
• Closes 🐛 [database] no events when listening to a stream again (web) #7048
• Closes 🐛 [firebase_database] Serious issue/bug with onChildRemoved event in Realtime Database (with reproducable code example) #6349

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]).
This will ensure a smooth and quick review process. Updating the pubspec.yaml and changelogs is not required.

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• My PR includes unit or integration tests for all changed/updated/fixed behaviors (See Contributor Guide).
• All existing and new tests are passing.
• I updated/added relevant documentation (doc comments with ///).
• The analyzer (melos run analyze) does not report any problems on my PR.
• I read and followed the Flutter Style Guide.
• I signed the CLA.
• I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require plugin users to manually update their apps to accommodate your change?

• Yes, this is a breaking change.
• No, this is not a breaking change.

[google-cla]

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.

[google-cla]

All (the pull request submitter and all commit authors) CLAs are signed, but one or more commits were authored or co-authored by someone other than the pull request submitter.

We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that by leaving a comment that contains only @googlebot I consent. in this pull request.

Note to project maintainer: There may be cases where the author cannot leave a comment, or the comment is not properly detected as consent. In those cases, you can manually confirm consent of the commit author(s), and set the cla label to yes (if enabled on your project).

ℹ️ Googlers: Go here for more info.