Skip to content

Playx Network

Playx Network

A Dio wrapper that turns every request into a typed result, gives errors names you can act on, and removes the try/catch.

Get started API reference pub.dev

  • A result, never an exception


    Every request returns a NetworkResult: success with your model, or an error with a precise, typed exception. Handling results

  • Errors you can act on


    Offline, server down, CORS, bad certificate, timeouts, 404, 422... each has its own type and message. Error handling

  • Your models, your errors


    Map the response with fromJson, and map error bodies to your own error object with errorExtraMapper. Custom error objects

  • Parsing off the UI thread


    Map big responses in an isolate with one setting, and cancel the work when the request is cancelled. Configuration

  • Streaming and SSE


    Consume Server-Sent Events, NDJSON and chunked responses as typed streams with cancellation built in. Streaming

  • Smart cancellation


    Tag requests and cancel a whole screen's worth at once, or let a new request replace the old one. Cancellation

  • Everyday conveniences


    Path parameters, dataKey extraction, custom headers and query, per-request settings. Making requests

  • Easy to test


    Plug a fake adapter into Dio and test every success and failure path without a network. Testing

A quick look

final client = PlayxNetworkClient(
  dio: Dio(BaseOptions(baseUrl: 'https://api.thecatapi.com/v1/')),
);

final result = await client.getList<Cat>(
  'images/search',
  query: {'limit': 10},
  fromJson: Cat.fromJson,
);
result.when(
  success: (cats) => showCats(cats),
  error: (error) => showMessage(error.message),
);
switch (result) {
  case NetworkSuccess(:final data):
    showCats(data);
  case NetworkError(:final error):
    showMessage(error.message);
}
final message = switch (result.error) {
  NoInternetConnectionException() => 'You are offline',
  ServerUnreachableException() => 'The server is not responding',
  UnauthorizedRequestException() => 'Please sign in again',
  ApiException(:final message) => message,
  _ => 'Something went wrong',
};

Requirements

Minimum
Dart 3.12
Flutter 3.44
Dio 5.11

Why such new versions?

playx_network builds on playx_core 2, which requires Dart 3.12 and Flutter 3.44.

Part of the Playx ecosystem

Playx brings the Playx packages together, playx_core holds the shared utilities this package builds on, and playx_theme adds multi-theme support.