fresh_graphql
0.8.0, released 9 months ago by felangel.dev
A GraphQL link for package:graphql that manages authentication tokens transparently.
WASM-ready
What it does
Provides a GraphQL link that automatically attaches authentication tokens, proactively or reactively refreshes expired tokens, retries failed requests, and manages authentication states via a stream.
AI-written summary of version 0.8.0, based on the package's README and metadata. Report an inaccuracy
Use it when
- You are using package:graphql and need automated token refresh on unauthenticated errors.
- You want to handle single-flight requests so concurrent token refreshes don't duplicate calls.
Skip it when
- You are building a REST API client instead of GraphQL (use fresh or dio instead).
- You do not use token-based authentication.
Strengths
- Single-flight token refresh prevents concurrent duplicate refresh requests.
- Provides an authenticationStatus stream for clean reactive navigation or login state management.
- Supports custom token formats and pluggable storage layers.
Weaknesses
- Requires custom implementation of token persistence (TokenStorage) for long-term storage.
- Tied directly to package:graphql link architecture.
Setup
- Kind
- Pure Dart
- Effort
- Low
- Code generation
- No
- Direct dependencies
- 4
Implement TokenStorage to save tokens persistently across app restarts and plug FreshLink into your GraphQL Link chain.
final freshLink = FreshLink.oAuth2(
tokenStorage: InMemoryTokenStorage<OAuth2Token>(),
refreshToken: (token, client) async {
final response = await client.post(
Uri.parse('https://api.example.com/auth/refresh'),
body: jsonEncode({'refresh_token': token?.refreshToken}),
);
final body = jsonDecode(response.body) as Map<String, dynamic>;
if (body['error'] == 'refresh_token_revoked') return null;
return OAuth2Token(
accessToken: body['access_token'],
refreshToken: body['refresh_token'],
expiresIn: body['expires_in'],
issuedAt: DateTime.now(),
);
},
shouldRefresh: (response) =>
response.errors?.any((e) => e.message.contains('UNAUTHENTICATED')) ??
false,
);
final link = Link.from([freshLink, HttpLink('https://api.example.com/graphql')]);Alternatives
Packages that do the same job and could replace fresh_graphql.
Works with
Packages commonly used together with fresh_graphql: ones it builds on, ones built on it, and its own family.
- gql_linkfresh_graphql depends on itModular AST-based GraphQL request execution interface.
- freshfresh_graphql depends on itCore token refresh library for managing authentication token lifecycles.
- fresh_httpSame familyAn http.Client wrapper that automatically refreshes authentication tokens and retries requests.
- fresh_dioSame familyA dio interceptor for automatic token refresh and authentication management.