realm-dart Open realm async

Support async Realm open syntax. Fixes #71 Done:

[x] Implement Realm.open only in Dart without using C-API.
[x] CancellableFuture implementation.
[x] Update Changelog.md
[x] API documentation
[x] Add more tests for download progress.
[x] Test opening many realms with different configs and try to cancel one of them.

Jul 30 '22 21:07 desistefanova

I have tried to advocate that we add this functionality without involving core at all.

Here are different styles this can be implemented in pure dart:

  static Future<Realm> open(FlexibleSyncConfiguration config, [void Function(int, int)? progressCallback]) async {
    final realm = Realm(config);
    final session = realm.syncSession;
    await session
        .getProgressStream(ProgressDirection.download, ProgressMode.forCurrentlyOutstandingWork)
        .forEach((s) => progressCallback?.call(s.transferredBytes, s.transferableBytes));
    await session.waitForDownload(); // should be redundant except for bug in progress stream
    return realm;
  }

  static CancelableOperation<Realm> openReturnsCancelableOperation(FlexibleSyncConfiguration config, [void Function(int, int)? progressCallback]) =>
      CancelableOperation.fromFuture(open(config));

  static Future<Realm> openDotnetStyle(FlexibleSyncConfiguration config, {void Function(int, int)? progressCallback, Completer<void>? cancelToken}) =>
      StreamGroup.merge([
        open(config).asStream(),
        if (cancelToken != null) cancelToken.future.asStream().cast<Realm>(), // only used to cancel
      ]).first;

Personally I prefer the first. If you don't need to cancel, you just do:

final realm = await Realm.open(config)

if you just need a timeout, you do:

final realm = await Realm.open(config).timeout(duration);

If you need to be able to cancel, you do:

final op = CancelableOperation.fromFuture(Realm.open(config));
// pass op to somewhere that may call op.cancel()
final realm = await op.valueOrCancellation(null); // will return null, if cancelled

You can say, that won't really cancel anything in core, but neither does the current PR, since download will proceed in the background no matter what, and this is very much by design.

Also, the open async api in core is buggy, in that If you cancel one operation you cancel all in-flight ops. I think the above this is much simpler. Obviously we should only support one of the 3, but I include them all to show the options.