flutter_network_state library

flutter_network_state

A network-aware state management and request orchestration engine for Flutter.

Quick Start

import 'package:flutter_network_state/flutter_network_state.dart';

final manager = NetworkManager();

manager.stateStream.listen((state) {
  switch (state) {
    case Idle()    => print('Idle');
    case Loading() => print('Loading...');
    case Offline() => print('Offline (${state.queuedRequests} queued)');
    case Syncing() => print('Syncing ${state.progress * 100}%');
    case Success() => print('Data: ${state.data}');
    case Error()   => print('Error: ${state.message}');
  }
});

final user = await manager.request(
  () => api.getUser(),
  cacheKey: 'user',
  strategy: CacheFirst(),
);

Classes

BackoffStrategy: Abstract interface for back-off strategies.
CacheEntry<T>: Wrapper around a cached value that tracks creation time for TTL checks.
CacheFirst: Check the cache first. If a valid (non-expired) entry exists, return it immediately. Otherwise, execute the network request and cache the result.
CacheManager: Manages cached data with TTL support.
CacheOnly: Only read from the cache — never touch the network.
CacheStore: Abstraction over the underlying storage mechanism.
ConnectivityBuilder: A widget that shows different children based on online/offline status.
ConstantBackoff: Constant back-off: always waits the same duration.
DioInterceptorConfig: Configuration for NetworkDioInterceptor.
Error: An operation failed with an error.
ExponentialBackoff: Exponential back-off: baseDelay * 2^attempt, optionally jittered.
Idle: Initial idle state — no operation in progress.
InMemoryCacheStore: Simple in-memory implementation of CacheStore.
InMemoryQueueStore: Simple in-memory FIFO queue.
InternetChecker: Performs real internet reachability checks via DNS lookup.
InternetCheckerConfig: Configuration for InternetChecker.
LinearBackoff: Linear back-off: baseDelay * (attempt + 1).
Loading: An operation is currently in progress.
NetworkBuilder: A widget that rebuilds whenever NetworkManager emits a new state.
NetworkCubit: A lightweight Cubit-like base class that manages NetworkState and integrates with NetworkManager.
NetworkDioInterceptor: A Dio interceptor powered by flutter_network_state.
NetworkFirst: Try the network first. If it fails (timeout, no connectivity, server error), fall back to cached data when a cacheKey is provided.
NetworkLogger: Pluggable logger used across the entire plugin.
NetworkManager: The primary API surface of the plugin.
NetworkManagerConfig: Configuration for NetworkManager.
NetworkNotifier: A ChangeNotifier that wraps NetworkManager and exposes the current NetworkState as a listenable property.
NetworkOnly: Only use the network — never read or write the cache.
NetworkState: Base class for all network states.
NetworkStateNotifier: A Riverpod-compatible StateNotifier-style class that manages NetworkState and integrates with NetworkManager.
NetworkStatusMonitor: Monitors network connectivity and exposes a reactive stream of ConnectivityStatus changes.
NetworkStrategy: Base class for network resolution strategies.
Offline: The device is currently offline. No network requests can be fulfilled from the network layer.
PersistentQueueStore: A QueueStore implementation that persists queued requests as a JSON file on disk.
QueuedRequest: Represents a single deferred request waiting in the queue.
QueueProcessResult: Result of processing a single queued request.
QueueStore: Abstraction for queue persistence. The default InMemoryQueueStore does NOT survive app restarts.
RequestQueue: Manages a FIFO queue of network requests that should be replayed when the device regains connectivity.
RetryPolicy: Defines how failed requests should be retried.
SerializableRequest: A serializable representation of an HTTP request that can be persisted to disk and reconstructed later.
Success<T>: An operation completed successfully.
SyncEngine: Listens to NetworkStatusMonitor and triggers RequestQueue processing whenever connectivity is restored.
Syncing: The sync engine is replaying queued requests after connectivity was restored.

Enums

ConnectivityStatus: Simplified connectivity status.
LogLevel: Log level severity.

Extensions

NetworkAwareStream on Stream<T>: Extension that adds network-awareness to a generic Stream<T>.
NetworkManagerBlocExtension on NetworkManager: Extension on NetworkManager for Bloc-friendly helpers.
NetworkManagerRiverpodExtension on NetworkManager: Extension on NetworkManager for creating Riverpod-friendly providers.

Typedefs

RequestExecutor = Future Function(SerializableRequest request): Callback that executes a SerializableRequest and returns the result.

flutter_network_state library

flutter_network_state

Quick Start

Classes

Enums

Extensions

Typedefs

flutter_network_state package

flutter_network_state library