feat: add transactions

[jsgalarraga]

Dummy PR to make easier to see changes

---

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 cachapa#63 and cachapa#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).

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.

transactions-example.mov

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]

When will this feature be merged?

[jsgalarraga]

@evandrobubiak
This repository is just a fork of the original one in which I developed the feature to create the PR.

You can see the progress (or I should say lack of progress 🥲) on the PR opened in the official repo.