Union State

Made by Surf 🏄‍♂️🏄‍♂️🏄‍♂️

Overview

A simple union with three states (loading, data, and error) based on sealed classes and ChangeNotifier. Used for delivering data to the UI layer, for example, using the Elementary library. The package includes the following classes:

UnionState

A universal model for mapping basic UI states.

Can be used as internal replacement for EntityState. Unlike EntityState:

• Guarantees a non-zero result T.
• Explicitly guarantees only 3 states: loading, content, error.

final _countryListState = UnionStateNotifier<Iterable<Country>>.loading();

  Future<void> _loadCountryList() async {
    final previousData = _countryListState.value.data;

    // set property to loading state and use previous data for this state
    _countryListState.loading(previousData);

    try {
      // await the result
      final res = await model.loadCountries();
      // set property to content state, use new data
      _countryListState.content(res);
    } on Exception catch (e) {
      // set property to error state
      _countryListState.failure(e, previousData);
    }
  }

UnionStateListenableBuilder

Presentation part builder for ValueListenable and UnionState.

Note that a non-zero result T is only guaranteed for UnionStateContent. But not for load and fail.

// ......
@override
Widget build(IExampleWM wm) {
  return Scaffold(
    appBar: AppBar(),
    body: UnionStateListenableBuilder<String>(
      unionStateListenable: wm.dataState,
      builder: (_, data) => Center(child: Text(data)),
      loadingBuilder: (_, lastData) => Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const CircularProgressIndicator(),
            if (lastData != null) ...[
              const SizedBox(height: 10),
              Text('Last data: $lastData'),
            ],
          ],
        ),
      ),
      failureBuilder: (_, exception, lastData) => Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(exception.toString()),
            if (lastData != null) ...[
              const SizedBox(height: 10),
              Text('Last data: $lastData'),
            ],
          ],
        ),
      ),
    ),
  );
}
// ......

UnionStateNotifier

A custom ValueNotifier that encapsulates the state of a union type. It provides methods to manage different states of data:

-content: Represents a state with successful content. -failure: Represents a state with an error and, optionally, previous data. -loading: Represents a state indicating that data is being loaded.

Can be used as internal replacement for EntityStateNotifier. Unlike EntityState:

• Guarantees a non-zero result T.
• Explicitly guarantees only 3 states: loading, content, failure.

class ExampleModel extends ElementaryModel {
  final _random = Random();
  final dataState = UnionStateNotifier<String>.loading();

  void initLoadData() {
    dataState.loading(dataState.value.data);
    Future.delayed(
      const Duration(seconds: 1),
      () {
        _random.nextInt(10) < 8
            ? dataState.content('Loaded Data')
            : dataState.failure();
      },
    );
  }
}

Implementation examples

An example

Installation

Add union_state to your pubspec.yaml file:

dependencies:
  union_state: $currentVersion$

At this moment, the current version of union_state is .

Changelog

All notable changes to this project will be documented in this file.

Issues

To report your issues, submit them directly in the Issues section.

Contribute

If you would like to contribute to the package (e.g. by improving the documentation, fixing a bug or adding a cool new feature), please read our contribution guide first and send us your pull request.

Your PRs are always welcome.

How to reach us

Please feel free to ask any questions about this package. Join our community chat on Telegram. We speak English and Russian.

License

Apache License, Version 2.0