Firestore transaction futures are confusing me - flutter

Question

I've been trying to figure out transactions all morning and I'm stuck. I keep going around in circles, and I know what I need to do(I think), but I'm not sure how to do it.
Here's my code:
Future<String> obtainUniqueUsername(
String requestedUsername,
String currentUserID,
) async {
var userID = currentUserID;
var userName = requestedUsername.toLowerCase();
try {
// Create a reference to a usernames collection .doc(id)
final userRef = FirebaseFirestore.instance.doc('usernames/$userName');
// Start a transaction to check if the username is assigned
// if assigned a .doc(userName) will exist.
FirebaseFirestore.instance.runTransaction((transaction) async {
var userSnapshot = await transaction.get(userRef);
if (userSnapshot.exists) {
// Username is assigned as .doc(userName) exists
return 'Username is already assigned';
} else {
// Assign username by created .doc(userName)
// insert document reference to user
transaction.set(userRef, {'uid': userID});
}
}).then((value) => 'Username assigned', onError: (e) => 'Transaction error ${e.toString()}');
} // endtry
catch (e) {
return e.toString();
} // endcatch
return 'Transaction has failed, please try again later';
} // end
My problem is that it keeps hitting the final return statement, even if it has created the document. My understanding is that the transaction will keep trying until it is successful and returns a value, or it times out and throws an error. I've read that using .then doesn't await a value, and the function continues uninterrupted until it hits the end, but shouldn't it be either a value or an error?
I feel like I'm missing the point somewhere, sorry if this is super basic, I've really been trying to get it to work.

Answer 1

I got it sorted out! It took forever though, lots of trial and error. I think my issue was that I didn't understand how to return the value from the future using the dart shorthand from the examples I was following.
My understanding now is that I'm awaiting usernameAssigned to complete, and the future is completed when I return 'success'.
If the transaction didn't go through, it would throw an exception, and be caught and I would get a message about what went wrong. I think the assignment of transactionStatus isn't required, but I kind of like having it there for my own understanding of what's happening. Maybe when I get more experience I wont need stuff like that.
I also didn't really know how to use a try/catch block, but I think I've improved how I do that as well. Now, I throw an exception if something weird happens instead of going right to return. I think that's better?
Also, the comment about letting firestore assign the unique uid: Yeah, you are right, but I want to have firestore enforce unique human readable usernames. The autogenerated uid is used for everything else.
The usecase is having a usernames collection built like: .doc(uniqueUsername).data({"uid:" uid})
Firestore won't let duplicate doc ID's happen in that collection, so it gives me what I want. My understanding is this is one of the "easier" ways to enforce unique usernames.
Anyways, thanks for the comments and please send me any feedback you may have!
Future<String> obtainUniqueUsername(
String requestedUsername,
String currentUserID,
) async {
Future<String> obtainUniqueMarkerUsername(
String requestedUsername,
String currentUserID,
) async {
var userID = currentUserID;
var userName = requestedUsername.toLowerCase();
var transactionStatus = '';
try {
// Start a transaction to check if the username is assigned
// if assigned a .doc(userName) will exist.
var usernameAssigned = await FirebaseFirestore.instance
.runTransaction((transaction) async {
// Create a reference to a usernames collection .doc(id)
var userRef = FirebaseFirestore.instance.doc('usernames/$userName');
var userSnapshot = await transaction.get(userRef);
if (userSnapshot.exists == true) {
// Username is assigned as .doc(userName) exists
throw Exception('Username already exists');
} else {
// Assign username by created .doc(userName)
// insert document reference to user
transaction.set(userRef, {"uid": userID});
return 'Success';
}
});
transactionStatus = usernameAssigned;
} // endtry
catch (e) {
return e.toString();
} // endcatch
userID = '';
userName = '';
return transactionStatus;
} // end