ResultNotifier<T> class

ValueListenable implementation that holds a single Result value, supporting data, loading and error states.

ResultNotifier supports well-defined transitions between the different Result states, including support for fine-grained observation of the different states.

ResultNotifier also supports refreshing data when stale. The staleness is determined by the expiration property (see isFresh / isStale) along with the Result.lastUpdate property. This creates the underpinning for a refreshable caching mechanism, where the data can be re-fetched when stale. Whenever data needs to be fetched, the optional onFetch callback will be invoked. If not provided, the default implementation will only touch the current value to refresh it. If customization of data fetch is needed, consider using a ResultNotifier subclass such as for instance FutureNotifier (see ResultNotifier.future), or provide a implementation of onFetch that refreshes the data in some other manner.

Data fetch will occur automatically, on demand, whenever a listener is added (see addListener), It can additionally be triggered manually by invoking the refresh. A fetch will be performed whenever:

  • Data has not yet been fetched (i.e. the notifier is in the Initial state).
  • Data is stale (isStale).
  • The refresh method is called with force set to true.

To cancel an ongoing data fetch operation, use cancel. This also invokes the onReset callback, if specified.

Inheritance
Mixed-in types
Implementers
Available extensions

Constructors

ResultNotifier.new({T? data, Result<T>? result, Duration? expiration, ResultNotifierCallback<T>? onFetch, ResultNotifierCallback<T>? onReset, T onErrorReturn(Object? error)?, bool autoReset = false, bool refreshOnError = false})
Starts with the specified data (represented as Data), result, or otherwise the Initial loading state.
ResultNotifier.future(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 data asynchronously, when needed.
factory

Properties

data ↔ T
Attempts to get the Result.data of the current Result value.
getter/setter pair
dataOrNull → T?
Get the Result.data of the current Result value, or null if no data is available (i.e. hasData is false).
no setter
error → Object?
no setter
expiration → Duration?
Cache expiration time. If null, the cache will never expire.
final
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 pair
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 setter
isAlwaysFresh → bool
Returns true if no expiration has been set, meaning the cache will never expire.
no setter
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 setter
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 setter
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.
final
onFetch → ResultNotifierCallback<T>?
Callback invoked when data needs to be fetched.
final
onReset → ResultNotifierCallback<T>?
Callback invoked when this notifier is reset, cancelled or disposed.
final
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 setter
value ↔ Result<T>
The current Result stored in this notifier.
getter/setter pairoverride-getter
willAutoReset → bool
If true, this notifier will automatically reset itself when all listeners are removed.
final
willRefreshOnError → bool
If true, the refresh method will fetch new data when the current state is Error.
final

Methods

addListener(VoidCallback listener) → void
Adds a listener to this notifier and triggers an asynchronous refreshes the data, if necessary.
override
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.
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).
override
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.
invalidate() → Result<T>
Marks the current Data (if any) as stale, i.e. it will be re-fetched on next access.
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
refresh({bool force = false, bool alwaysTouch = false}) → void
Refreshes this notifier with fresh Data if it is stale or forced.
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.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
override
reset([T? initialData]) → void
Resets the result to Initial, or to stale Data if initialData is specified.
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).
setResultAsync(FutureOr<Result<T>> fetchResult()) → Future<Result<T>>
Sets the value (result) of this notifier asynchronously using the result returned by the provided function.
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.
toData({T? data, T orElse()?, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Data.
toError({Object? error, StackTrace? stackTrace, T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Error.
toInitial({T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to the Initial loading state.
toLoading({T? data, DateTime? lastUpdate}) → Result<T>
Attempts to convert the result to Loading.
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.
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.
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.
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.

Operators

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