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