feat: add transactions

[jsgalarraga]

This PR introduces Firestore transactions to the package.

Why

Transactions are a powerful feature to have in the backend. This is an effort to have a more complete feature set for a dart backend.

It has been requested by users in #63 and #126.

Inspiration

The work here has been inspired by:

• The Firebase SDK for Android. In particular the creation of a new Transaction class that exposes the methods that can be performed.
• The cloud_firestore package for Flutter. In particular, the API exposed to the user and the documentation.

Implementation notes

• The new Transaction class, does not extend the existing Reference even though it needs some of its methods because a Transaction does not have a predefined path. The _fullPath and _encodeMap methods have been adapted.
• The mutations in a Transaction have to be exposed for the FirestoreGateway to have access to them and run the transaction commit. To safely do this, it is kept as an UnmodifiableListView to prevent the end user from modifying it.
• When multiple transaction operations are run in parallel, some of them fail to keep the database consistent. When this happens, a GrpcError with StatusCode.aborted is thrown. In this PR, the error handling is implemented to retry the transaction up to 5 times by default (as the other firestore SDKs do).
• The document attribute in FirestoreGateway had the route to the /documents path, which is needed for most common operations in the database. However, for the transactions, the raw database route is needed, therefore this has been updated to have both database pointing to the root and documentDatabase which adds the /documents path.

Examples

To ensure transactions are working and keeping the database consistent with all the write operations performed in parallel, the following test has been run: Increase a value multiple times both with and without transactions. As we can see, when running with transactions, the numbers are increased correctly 3 times, but the number is only increased by 1 when ran without transactions.

https://github.com/jsgalarraga/firedart/assets/52668514/559a8fa7-62ec-4a46-a41e-fbcb565392ce

With transactions

void main(List<String> args) async {
  Firestore.initialize('project-id');

  await Future.wait([
    increaseValueWithTransaction(Firestore.instance),
    increaseValueWithTransaction(Firestore.instance),
    increaseValueWithTransaction(Firestore.instance),
  ]);

  firestore.close();
}

Future<void> increaseValueWithTransaction(Firestore firestore) async {
  await firestore.runTransaction(
    (transaction) async {
      final doc = await transaction.get('testing/test');
      final value = doc.map['key'];
      transaction.update('testing/test', {'key': value + 1});
    },
  );
}

Without transactions

void main(List<String> args) async {
  Firestore.initialize('project-id');

  await Future.wait([
    increaseValue(Firestore.instance),
    increaseValue(Firestore.instance),
    increaseValue(Firestore.instance),
  ]);

  firestore.close();
}

Future<void> increaseValue(Firestore firestore) async {
  final doc = await firestore.document('testing/test').get();
  final value = doc.map['key'];
  await firestore.document('testing/test').set({'key': value + 1});
}

[evandrobubiak]

Any predictions for this merge? We are really looking forward to this feature

[cachapa]

Hi @evandrobubiak, sorry for allowing this to stale, I must've missed the original PR email.

I'll review this now.

[cachapa]

Also, would you mind writing a few tests? It doesn't need to be comprehensive, but at least covering the basics, essentially the samples you wrote for the documentation.

[jsgalarraga]

Oh, sure! Will also work on the tests