FutureNotifier<T> class

ResultNotifier subclass that supports fetching data asynchronously, on demand.

Data will be fetched using the configured FetchAsync function, when a refresh needed (see refresh). The fetch function will be invoked in an asynchronous fashion, using setDataAsync, meaning its result will be awaited. The fetch function can either return a Future that completes with data, or return the data directly. Errors will be caught and converted to Error states.

A common use case is to for instance fetch data from a remote HTTP API, and then cache the result for a period of time. Example:

final notifier = FutureNotifier(() async {
  final response = await http.get(uri);
  final json = jsonDecode(response.body) as Map<String, dynamic>;
  return SomeModel.fromJson(json);
}, expiration: const Duration(seconds: 30));
Inheritance
Implementers
Available extensions

Constructors

FutureNotifier.new(FetchAsync<T> fetch, {T? data, Result<T>? result, Duration? expiration, ResultNotifierCallback<T>? onReset, T onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false})
Creates a FutureNotifier that fetches new data using the provided fetch function.
FutureNotifier.customFetch({T? data, Result<T>? result, Duration? expiration, ResultNotifierCallback<T>? onFetch, ResultNotifierCallback<T>? onReset, T onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false})
Creates a FutureNotifier that implements customized fetching behavior, possibly by using performFetch.
FutureNotifier.result(FetchResultAsync<T> fetch, {T? data, Result<T>? result, Duration? expiration, ResultNotifierCallback<T>? onReset, T onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false})
Creates a FutureNotifier that fetches new data using the provided fetch function.

Properties

data ↔ T
Attempts to get the Result.data of the current Result value.
getter/setter pairinherited
dataOrNull → T?
Get the Result.data of the current Result value, or null if no data is available (i.e. hasData is false).
no setterinherited
error → Object?
no setterinherited
expiration → Duration?
Cache expiration time. If null, the cache will never expire.
finalinherited
future ↔ Future<T>
If data or error is available, it will be returned directly (as Future.value / Future.error), otherwise a Completer will be used to await data or error.
getter/setter pairinherited
hasData → bool
Checks if the result contains data, regardless of the result type. Note that this is different from isData.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
isActive → bool
Checks if this notifier is still active, i.e. not disposed.
no setterinherited
isAlwaysFresh → bool
Returns true if no expiration has been set, meaning the cache will never expire.
no setterinherited
isCancelled → bool
Checks if the current state is Error and the error is a CancelledException.
no setterinherited
isData → bool
Checks if the result is Data. Note that this is different from if this notifier currently contains data (i.e. hasData).
no setterinherited
isError → bool
Checks if the current state is Error.
no setterinherited
isFresh → bool
Checks if the current data is fresh, not stale, i.e. time since last update is less than expiration (if set).
no setterinherited
isInitial → bool
Checks if the the result is the Initial loading state.
no setterinherited
isLoading → bool
Checks if the the result is Loading. Note that the initial state (Initial) is also interpreted as a loading state.
no setterinherited
isLoadingData → bool
Checks if the data is currently being loaded, i.e. the current state is Loading but not Initial.
no setterinherited
isReloading → bool
Checks if data is currently being reloaded, i.e. the current state is Loading and hasData.
no setterinherited
isStale → bool
Returns true if the current data isn't fresh or if the current result isn't Data.
no setterinherited
lastUpdate → DateTime
The last time the result was updated.
no setterinherited
onErrorReturn → T Function(Object? error)?
Callback invoked when an error occurs, to produce fallback data.
finalinherited
onFetch → ResultNotifierCallback<T>?
Callback invoked when data needs to be fetched.
finalinherited
onReset → ResultNotifierCallback<T>?
Callback invoked when this notifier is reset, cancelled or disposed.
finalinherited
result → Result<T>
Just an alias for value.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stackTrace → StackTrace?
no setterinherited
value ↔ Result<T>
The current Result stored in this notifier.
getter/setter pairinherited
willAutoReset → bool
If true, this notifier will automatically reset itself when all listeners are removed.
finalinherited
willRefreshOnError → bool
If true, the refresh method will fetch new data when the current state is Error.
finalinherited

Methods

addListener(VoidCallback listener) → void
Adds a listener to this notifier and triggers an asynchronous refreshes the data, if necessary.
inherited
alwaysData(T defaultData) → ResultNotifier<T>
Creates a new ResultNotifier that only gets updated when the data of this notifier changes, i.e. ignoring Loading and Error states.
inherited
asyncEffect<R>(AsyncEffect<T, R> effect, {R? data, Result<R>? result, Duration? expiration, ResultNotifierCallback<R>? onReset, R onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false, bool immediate = false, bool ignoreLoading = false}) → EffectNotifier<T, R>
Creates a new asynchronous EffectNotifier that executes the provided asynchronous effect the data of this notifier changes.
inherited
builder(Widget builder(BuildContext context, Result<T> result, Widget? child), {Widget? child}) → ValueListenableBuilder<Result<T>>
Convenience method for simplifying the creation of a ValueListenableBuilder with ResultNotifier.
inherited
cancel({bool always = false}) → void
Cancels the current data loading operation, if any.
inherited
combineLatest<R>(ResultListenable<T> other, {required R combineData(List<T> data)}) → CombineLatestNotifier<T, R>
Creates a new CombineLatestNotifier that that combines the value of this notifier with another one.
inherited
dispose() → void
Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
inherited
effect<R>(Effect<T, R> effect, {R? data, Result<R>? result, Duration? expiration, ResultNotifierCallback<R>? onReset, R onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false, bool immediate = false, bool ignoreLoading = false}) → EffectNotifier<T, R>
Creates a new synchronous EffectNotifier that executes the provided effect the data of this notifier changes.
inherited
fetchData() → void
Called to fetch new data.
inherited
invalidate() → Result<T>
Marks the current Data (if any) as stale, i.e. it will be re-fetched on next access.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
onData(void listener(T data)) → VoidCallback
Registers a listener (addListener) that will only be invoked for Data results.
inherited
onError(void listener(Object? error, StackTrace? stackTrace, T? data)) → VoidCallback
Registers a listener (addListener) that will only be invoked for Error results.
inherited
onLoading(void listener(T? data)) → VoidCallback
Registers a listener (addListener) that will only be invoked for Loading results.
inherited
onResult(void listener(Result<T> result)) → VoidCallback
Registers a listener (addListener) that will be invoked with the current Result (value).
inherited
performFetch(FetchResultAsync<T> fetch) → void
Fetches data asynchronously using the provided fetcher function.
refresh({bool force = false, bool alwaysTouch = false}) → void
Refreshes this notifier with fresh Data if it is stale or forced.
inherited
refreshAwait({bool force = false, bool alwaysTouch = false}) → Future<T>
Refreshes this notifier with fresh Data if it is stale or forced, and awaits data or error.
inherited
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
reset([T? initialData]) → void
Resets the result to Initial, or to stale Data if initialData is specified.
inherited
setDataAsync(FutureOr<T> fetchData()) → Future<T>
Sets the data of this notifier asynchronously using the data returned by the provided function, which in turn is returned by this method (in form of a Future).
inherited
setResultAsync(FutureOr<Result<T>> fetchResult()) → Future<Result<T>>
Sets the value (result) of this notifier asynchronously using the result returned by the provided function.
inherited
streamEffect<R>(StreamEffect<T, R> effect, {R? data, Result<R>? result, Duration? expiration, ResultNotifierCallback<R>? onReset, R onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false, bool ignoreLoading = false}) → EffectNotifier<T, R>
Creates a new asynchronous EffectNotifier that executes the provided stream effect the data of this notifier changes.
inherited
toCancelled({T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to cancellation Error.
inherited
toData({T? data, T orElse()?, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Data.
inherited
toError({Object? error, StackTrace? stackTrace, T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Error.
inherited
toInitial({T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to the Initial loading state.
inherited
toLoading({T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Loading.
inherited
toString() → String
A string representation of this object.
inherited
touch() → Result<T>
Attempts to convert the result to fresh Data (i.e. set the lastUpdate to DateTime.now()), preventing cache expiration.
inherited
updateDataAsync(FutureOr<T> fetchData()) → Future<void>
Updates the data of this notifier asynchronously using the data returned by the provided function, and then returns a Future that can optionally be used to await the completion of the update.
inherited
watch(WatcherRef ref) → Result<T>

Available on ResultNotifier<T>, provided by the ResultNotifierWatcher extension

Starts watching this object for changes (i.e. Listenable.addListener) and rebuilds the widget associated with the provided WatcherRef whenever listeners are notified.
watch(WatcherRef ref) → void

Available on Listenable, provided by the ListenableWatcher extension

Starts watching this object for changes (i.e. Listenable.addListener) and rebuilds the widget associated with the provided WatcherRef whenever listeners are notified.

Operators

operator ==(Object other) → bool
The equality operator.
inherited