simple_network_handler library

Dio-based network error handling: declarative error registries, the error-mapping and token-refresh interceptors, and safe call execution.

Core types (Failure, LocalizedFailure, Result, ExceptionMatcher) are re-exported from simple_network_handler_core. Supabase support lives in the separate simple_network_handler_supabase package.

Classes

CancellationScope

App-wide (or feature-wide) request cancellation without per-call CancelToken plumbing.

CancellationScopeInterceptor

Enrolls requests without their own CancelToken into a CancellationScope. Installed automatically by installNetworkHandling(cancellation: scope).

Err<T>

Failed outcome carrying failure.

ErrorMappingInterceptor

Maps responses to registered FailureFactorys so safeCall can surface typed Failures.

ErrorRegistry

Abstract error registry that can be implemented by different projects

ExceptionMatcher

Predicate-based exception → Failure mapping.

Failure

Base class for all failures produced by this package.

JwtExpiry

Helpers for JWT access-token expiry, for use with RefreshTokenInterceptor.isTokenExpired.

NetworkHandler

Instance-based network handler: owns one ErrorRegistry and executes requests against it.

NetworkLogInterceptor

Structured, sanitized HTTP traffic logging.

Ok<T>

Successful outcome carrying value.

RefreshRequest

Declarative description of the HTTP request that refreshes the session.

RefreshTokenInterceptor

Interceptor that transparently refreshes an expired access token and replays the failed request.

RequestCancelledFailure

The failure produced for a cancelled request.

Result<T>

The outcome of a network operation: either Ok with a value of type T or Err with a Failure.

RetryInterceptor

Retries transient failures with exponential backoff and full jitter.

TokenStore

Abstract access token storage used by RefreshTokenInterceptor.

Mixins

CancelledFailure

Marker for failures meaning "the caller aborted this request" — the user navigated away, typed a new search query, or signed out. Not an error: UIs should silently ignore it, and Result.mapBusiness lets it pass through repository mappers unchanged (like TransportFailure).

LocalizedFailure

Flutter-layer contract for failures that carry their own localized copy.

TransportFailure

Marker for failures representing a transport-level problem (the request never reached the backend / backend unreachable) rather than a business rule. Lets UIs and observers special-case connectivity once, regardless of feature.

Extensions

InstallNetworkHandling on Dio

One-call setup that owns the interceptor ordering so you don't have to.

Typedefs

DioErrorRegistry = Map<DioExceptionType, Failure>

ErrorModelRegistry = Map<String, Map<int, FailureFactory>>

FailureFactory = Failure Function(Map<String, dynamic> json)

Builds the Failure for a mapped response body.

FailureObserver = void Function(Failure failure, Object error, StackTrace stackTrace)

Observability hook: invoked with every failure a handler produces, together with the exception that caused it and its stack trace. Wire your error tracker (Sentry, Crashlytics, ...) here in one line:

GeneralErrorRegistry = Map<Type, Failure Function(Object exception)>

HeaderApplier = void Function(RequestOptions options, String accessToken)

Signature for applying an access token to an outgoing request.

NetworkLogSink = void Function(String line)

Where log lines go. Wire debugPrint, your logger, or a test buffer.

RefreshFailedCallback = FutureOr<void> Function(Object? error)

Signature for the callback invoked when a token refresh fails.

RefreshTokenCallback = Future<String?> Function()

Signature for a user-supplied refresh callback.