watchFuture<T extends Object, R> function

AsyncSnapshot<R> watchFuture<T extends Object, R>(Future<R> select(T)?, { T? target, required R initialValue, String? instanceName, bool preserveState = true, bool allowFutureChange = false, GetIt? getIt, dynamic param1, dynamic param2, })

watchFuture observes the Future returned by select and triggers a rebuild as soon as this Future completes. After that it returns an AsyncSnapshot with the received data from the Future When you call watchFuture a second time on the same Future it will return the last received data but not observe the Future a another time. To be able to use watchFuture inside a build function we have to pass initialValue so that it can return something before the Future has completed if select returns a different Future than on the last call, watchFuture will ignore the completion of the previous Future and observe the completion of the new Future. preserveState determines then if the new initial value should be the last value of the previous Future or again initialValue If you want to observe a Future that is not registered in get_it you can pass it as target. if you pass null as select, T or target has to be a Future<R>. instanceName is the optional name of the instance if you registered it with a name in get_it.

getIt is the optional instance of get_it to use if you don't want to use the default one. 99% of the time you won't need this. param1 and param2 are forwarded to get_it and are only valid if T was registered with registerCachedFactoryParam (they cannot be combined with target). If the params change between builds and get_it returns a different instance, select is re-evaluated on the new instance and the widget observes the new Future instead. This does not require allowFutureChange.

Implementation

AsyncSnapshot<R> watchFuture<T extends Object, R>(
  Future<R> Function(T)? select, {
  T? target,
  required R initialValue,
  String? instanceName,
  bool preserveState = true,
  bool allowFutureChange = false,
  GetIt? getIt,
  dynamic param1,
  dynamic param2,
}) {
  assert(_activeWatchItState != null,
      'watchFuture can only be called inside a build function within a WatchingWidget or a widget using the WatchItMixin');

  final getItInstance = getIt ?? di;
  _debugCheckNoParamsWithTarget('watchFuture', target, param1, param2);
  if (target == null) {
    _debugCheckRegistration<T>(
        getItInstance, 'watchFuture', instanceName, param1, param2);
  }
  final parentObject = target ??
      getItInstance<T>(
          instanceName: instanceName, param1: param1, param2: param2);

  // Validate target type when no select function is provided
  if (select == null && parentObject is! Future<R>) {
    throw ArgumentError(
        'When no select function is provided, target must be a Future<$R>. '
        'Got: ${parentObject.runtimeType}');
  }

  return _activeWatchItState!.registerFutureHandler<T, R>(
      parentOrFuture: parentObject,
      initialValueProvider: () => initialValue,
      instanceName: instanceName,
      preserveState: preserveState,
      allowMultipleSubscribers: false,
      selector: select,
      allowFutureChange: allowFutureChange);
}