[cloud_firestore] Firestore.instance.runTransaction(...) returns... a Map?

[cielo]

Is your feature request related to a problem? Please describe.
In javascript SDK, runTransaction method returns a promise containing value that was returned within runTransaction function. However, flutter firestore's runTransaction returns an arbitrary map.

https://github.com/FirebaseExtended/flutterfire/blob/master/packages/cloud_firestore/cloud_firestore/lib/src/firestore.dart#L135

Describe the solution you'd like
It is difficult for developers to understand how they can utilize the result of runTransaction. It will be helpful if a doc can be updated to reflect how callers can handle value returned from runTransaction. e.g. If value cannot be utilized, then shouldn't runTransaction return void?

[suztomo]

Similar issue: #1899

[suztomo]

I also found that the value of the map cannot be a DocumentReference; otherwise I get strange exception PlatformException(error, Invalid argument: Instance of 'DocumentReference', null).

[Salakar]

Hey this has been fixed as part of #2582 / #2913 - pending release.