dio_flow 3.1.0
dio_flow: ^3.1.0 copied to clipboard
Flexible HTTP client for Flutter, built on Dio with mock support, GraphQL, file handling, caching, and token management.
๐ DioFlow #
A robust, developer-friendly Flutter HTTP client built on Dio that handles the heavy lifting out of the box: predictable typed responses, single-flight token refresh, stream-safe retries, isolated local caching, built-in request mocking, and real-time upload progress tracking.
โก 30-Second Quick Start #
1. Add Dependencies #
dependencies:
dio_flow: ^3.1.0
dio: ^5.11.0
2. Initialize in main() #
import 'package:flutter/material.dart';
import 'package:dio_flow/dio_flow.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
DioFlowConfig.initialize(
baseUrl: 'https://api.example.com',
connectTimeout: const Duration(seconds: 15),
receiveTimeout: const Duration(seconds: 15),
);
await ApiClient.initialize();
runApp(const MyApp());
}
3. Make Your First Request #
final response = await DioRequestHandler.get('/users/1');
if (response.isSuccess) {
print('User: ${response.data}');
} else {
print('Error ${response.statusCode}: ${response.message}');
}
๐งญ Why DioFlow? #
| Feature | Standard Dio | DioFlow |
|---|---|---|
| Response Format | Raw dynamic / uncaught errors |
Predictable SuccessResponseModel or FailedResponseModel |
| Crash Protection | Unhandled exceptions crash UI | Internal guards ensure every call returns a structured model |
| Token Refresh | Complex custom interceptors | Automatic single-flight refresh with queueing for concurrent 401s |
| Request Retries | Retrying FormData burns stream | Automatically clones FormData on retry attempts |
| Local Cache | Third-party cache store needed | Built-in isolated cache with query-key stabilization & isFromCache |
| Offline Mocking | Mock adapters & build runners | Global MockDioFlow active with zero backend dependencies |
| Sensitive Logs | Exposes bearer tokens in console | Automatically masks passwords, tokens, cookies, and keys in cURL |
| Web & WASM | dart:io crashes on browser |
100% Web and WASM compatible with conditional adapters |
๐ Table of Contents #
- ๐ Everyday Usage (Cheat Sheet)
- ๐ก Request Methods & Parameters
- ๐งช Offline Request Mocking
- ๐พ Smart Local Caching
- ๐ Authentication & Automatic Token Refresh
- ๐ค File Upload with Live Progress
- ๐ฅ File Download
- ๐ Automatic Retries & Crash Prevention
- ๐ฆ Rate Limiting & Concurrency
- ๐จ Console Logging & Copyable cURL
- ๐ GraphQL Helpers
- โ๏ธ Full Configuration Reference
๐ Everyday Usage (Cheat Sheet) #
Basic GET with Path Parameters & Query #
final response = await DioRequestHandler.get(
'/posts/{id}/comments',
pathParameters: {'id': 10},
parameters: {'page': 1, 'limit': 20},
);
if (response.isSuccess) {
final List comments = response.data;
print('Fetched ${comments.length} comments');
}
Basic POST / PUT / PATCH / DELETE #
// POST JSON
final postRes = await DioRequestHandler.post(
'/users',
data: {'name': 'Sarah Connor', 'role': 'Admin'},
);
// PUT Update
final putRes = await DioRequestHandler.put(
'/users/42',
data: {'name': 'John Connor'},
);
// DELETE
final deleteRes = await DioRequestHandler.delete('/users/42');
๐ก Request Methods & Parameters #
All HTTP methods in DioRequestHandler (get, post, put, patch, delete) share the same unified signature:
Future<ResponseModel> get(
dynamic endpoint, {
Map<String, dynamic>? parameters, // Query parameters (?page=1&sort=desc)
Map<String, dynamic>? pathParameters, // Path placeholders (/users/{id})
RequestOptionsModel requestOptions, // Per-request cache, retry, headers
CancelToken? cancelToken, // Request cancellation token
});
Inspecting Responses #
Every call returns a ResponseModel that never throws uncaught network crashes:
final response = await DioRequestHandler.get('/dashboard');
if (response.isSuccess) {
// Convenient getters
final data = response.data;
final statusCode = response.statusCode; // e.g. 200
final isCached = response.isFromCache; // true if served from local cache
final curl = response.logCurl; // copyable cURL command
} else {
// Structured error handling
final errorMsg = response.message; // Clean user-friendly message
final statusCode = response.statusCode; // e.g. 404, 500, 499 (cancelled)
final errorType = response.errorType; // e.g. ErrorType.notFound, ErrorType.timeout
}
Named Endpoints (Optional) #
You can register endpoints centrally to avoid hardcoding paths throughout your app:
EndpointProvider.instance.registerAll({
'profile': '/api/v1/user/profile',
'updateUser': '/api/v1/user/{id}',
});
// Use the registered key directly:
final res = await DioRequestHandler.get('profile');
๐งช Offline Request Mocking #
Test your UI and workflows instantly without waiting for backend APIs or an internet connection:
// 1. Enable mock mode anywhere in tests or demo apps:
MockDioFlow.enableMockMode();
// 2. Register mock endpoints:
MockDioFlow.mockResponse(
'/users/1',
MockResponse.success({
'id': 1,
'name': 'Sarah Connor',
'email': 'sarah@example.com',
}),
);
// 3. Mock POST or Error responses with custom delay:
MockDioFlow.mockResponse(
'/orders',
MockResponse.success({'orderId': 'ord_123'}, statusCode: 201),
method: 'POST',
);
MockDioFlow.mockResponse(
'/error-endpoint',
MockResponse.failure('Account suspended', statusCode: 403),
);
// When done:
MockDioFlow.disableMockMode();
๐พ Smart Local Caching #
Enable instant response caching on GET requests. Subsequent calls with the same parameters return from local cache in 0 ms:
final response = await DioRequestHandler.get(
'/catalog',
parameters: {'category': 'books'},
requestOptions: const RequestOptionsModel(
cacheOptions: CacheOptions(
shouldCache: true,
cacheDuration: Duration(minutes: 10), // Cache valid for 10 minutes
),
),
);
if (response.isFromCache) {
print('Served instantly from local cache!');
}
Safe Cache Clearing #
ApiClient.clearCache() safely wipes only cache keys created by dio_flow, preserving your app's user tokens, theme, and other SharedPreferences data:
await ApiClient.clearCache();
๐ Authentication & Automatic Token Refresh #
DioFlow provides a bulletproof token management lifecycle:
- Automatically attaches
Authorization: Bearer <token>to requests marked withhasBearerToken: true. - Proactively checks token expiration before sending.
- Automatically catches
401 Unauthorizedresponses, refreshes the token, and replays the original request once. - Single-Flight Coordination: If 10 parallel requests receive a
401, only one refresh request is sent to your backend; the other 9 wait and resume seamlessly with the new token.
Setup Token Management #
await TokenManager.initialize();
// Save initial tokens upon user login:
// (expiry is completely OPTIONAL - pass null if your server doesn't provide one)
await TokenManager.setTokens(
accessToken: 'initial_access_token',
refreshToken: 'initial_refresh_token',
expiry: DateTime.now().add(const Duration(hours: 2)), // optional
);
// Register your refresh API logic:
TokenManager.setRefreshHandler((currentRefreshToken) async {
// Use refreshDio or DioRefreshTokenRequestHandle to avoid recursive interceptors:
final response = await DioRefreshTokenRequestHandle.post(
'/auth/refresh',
data: {'refresh_token': currentRefreshToken},
);
if (response.isSuccess) {
return RefreshTokenResponse(
accessToken: response.data['access_token'],
refreshToken: response.data['refresh_token'], // optional
expiry: null, // optional
);
}
throw ApiException('Session expired');
});
Sending Authenticated Requests #
Simply set hasBearerToken: true:
final response = await DioRequestHandler.get(
'/user/me',
requestOptions: const RequestOptionsModel(hasBearerToken: true),
);
๐ค File Upload with Live Progress #
Upload files, images, or raw byte buffers with a real-time progress callback:
// Native (Mobile / Desktop) or Web (Uint8List)
final bytes = Uint8List.fromList(imageBytes);
final response = await FileHandler.uploadFile(
'/media/upload',
{'avatar': bytes}, // fieldName -> file or bytes
UploadMethodsEnum.post,
additionalData: {'userId': '42', 'description': 'Profile image'},
onProgress: (sent, total) {
final progress = (sent / total) * 100;
print('Upload Progress: ${progress.toStringAsFixed(1)}%');
},
);
๐ฅ File Download #
Download binary data (PDFs, images, documents) directly as bytes or plain text:
// 1. Download as raw bytes:
final response = await FileHandler.downloadBytes(
'/reports/2026.pdf',
UploadMethodsEnum.get, // supports get, post, put, patch
);
if (response.isSuccess) {
final Uint8List fileBytes = response.data;
// Save to disk using path_provider or open with open_file
}
// 2. Download plain text (CSV, Logs, TXT):
final textResponse = await FileHandler.downloadText(
'/logs/daily.csv',
UploadMethodsEnum.get,
);
๐ Automatic Retries & Crash Prevention #
Configure exponential backoff or retry status codes per request:
final response = await DioRequestHandler.get(
'/live-feed',
requestOptions: const RequestOptionsModel(
retryOptions: RetryOptions(
maxAttempts: 3, // Total attempts (1 = no retry)
retryInterval: Duration(milliseconds: 500), // Wait between attempts
retryStatusCodes: [408, 500, 502, 503, 504], // Status codes to retry
retryOnConnectionTimeout: true,
retryOnReceiveTimeout: true,
),
),
);
๐ก๏ธ Stream-Safe: DioFlow automatically calls
FormData.clone()before replaying multipart requests, preventing "Cannot finalize stream multiple times" crashes.
๐ฆ Rate Limiting & Concurrency #
Fast & Unblocked by Default #
In DioFlow, requests flow freely without artificial client-side barriers. Rapid user interactions, tab switching, and parallel dashboard widgets execute smoothly without hitting rate-limit errors.
Optional Client-Side Rate Limiter #
If your specific backend requires strict client-side throttling to prevent abuse, you can opt-in during initialization:
DioFlowConfig.initialize(
baseUrl: 'https://api.example.com',
enableRateLimit: true, // Defaults to false
rateLimitMaxRequests: 60, // Allowed requests
rateLimitInterval: const Duration(minutes: 1), // Time window
);
๐จ Console Logging & Copyable cURL #
DioFlow's internal logger is silent by default so it never spams your development console. Enable it per request when debugging:
final response = await DioRequestHandler.post(
'/login',
data: {'email': 'user@example.com', 'password': 'mySecretPassword'},
requestOptions: const RequestOptionsModel(
logModel: LogModel(defaultLog: true),
),
);
๐ Built-In Security Masking #
DioFlow automatically masks sensitive fields case-insensitively across headers, query parameters, request bodies, and cURL commands:
Authorization,token,accessToken,refreshTokenpassword,secret,apiKey,cookie,credential
The generated cURL commands are clean, safe to copy into bug reports, and guaranteed not to expose user credentials.
๐ GraphQL Helpers #
Execute GraphQL queries, mutations, and batch operations with built-in typed response models:
final response = await GraphQLHandler.query(
r'''
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}
''',
variables: {'id': '42'},
);
if (response.isSuccess) {
print('User: ${response.data['user']}');
}
โ๏ธ Full Configuration Reference #
DioFlowConfig.initialize Options #
| Parameter | Type | Default | Description |
|---|---|---|---|
baseUrl |
String |
required | The root endpoint for all HTTP requests |
connectTimeout |
Duration |
30s |
Connection timeout |
receiveTimeout |
Duration |
30s |
Receive timeout |
sendTimeout |
Duration |
30s |
Send timeout |
enableRateLimit |
bool |
false |
Enable client-side request rate limiter |
rateLimitMaxRequests |
int |
60 |
Max requests within interval |
rateLimitInterval |
Duration |
1m |
Time window for rate limiter |
customInterceptors |
List<Interceptor>? |
null |
Additional custom Dio interceptors |
RequestOptionsModel Options #
| Parameter | Type | Default | Description |
|---|---|---|---|
hasBearerToken |
bool |
false |
Automatically inject active Bearer token |
customHeaders |
Map<String, dynamic>? |
null |
Per-request custom headers |
cacheOptions |
CacheOptions |
noApiCache |
Cache TTL and policies |
retryOptions |
RetryOptions |
defaultOptions |
Retry attempts and status codes |
logModel |
LogModel |
disabledAllLog |
Log console output and cURL |
responseType |
ResponseType |
json |
Response parsing (json, bytes, plain) |
๐ License #
This project is licensed under the MIT License - see the LICENSE file for details.