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).
DefaultErrorRegistry
A ready-made ErrorRegistry covering the failures every HTTP app has, so a new project gets correct transport/business separation in one line:
DefaultFailure
Base for the failures DefaultErrorRegistry produces: localized-shaped (so generic error UI can render them) with English fallback copy.
DefaultForbiddenFailure
403 — authenticated, but not allowed.
DefaultGenericFailure
Anything unmapped.
DefaultNotFoundFailure
404 — the resource does not exist.
DefaultOfflineFailure
The device could not reach the backend at all.
DefaultServerFailure
5xx — the backend failed.
DefaultTimeoutFailure
The request or response took too long.
DefaultUnauthorizedFailure
401 — no valid session.
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.