value_state 2.0.1

This Dart package simplifies the implementation of common data-fetching states (loading, success, error).

value_state

A dart package that helps to implement basic states such as initial, success and error.

🔥 Features

This package helps you manage the different states your data can have in your app (like loading, success, or error). It makes your code cleaner and easier to understand, especially when dealing with things like network requests, storage loading or complex operations.

It provides a way to represent a value that can be in one of three states:

• initial
• success
• failure

🚀 Quick start

final valueInitial = Value<int>.initial();
final state = valueInitial.state; // ValueState.initial
final isInitial = valueInitial.isInitial; // true

final valueSuccess = Value.success(1);
final isSuccess = valueSuccess.isSuccess; // true
final isFailure = valueError.isFailure; // false
print('Data of value : ${valueSuccess.data}'); // Data of value : 1

When the value is in a specific state

value.when(
  initial: () => print('initial'),
  success: (data) => print('success: $data'),
  failure: (error) => print('failure: $error'),
  orElse: () => print('orElse'),
);

Map the value to a different type

valueInitial.map(
  initial: () => 'initial',
  success: (data) => 'success: $data',
  failure: (error) => 'failure: $error',
  orElse: () => 'orElse',
);

Map the value to a different type using pattern matching

final result = switch(valueInitial) {
  Value(isInitial: true) => 'initial',
  Value(:final dataOnSuccess?) => 'success: $dataOnSuccess',
  Value(:final error?) => 'failure: $error',
  _ => 'orElse',
};

Merge two values with different types

const valueInt = Value.success(0);
const valueStr = Value.success('toto');
final newValue = valueInt.merge(valueStr, mapData: (value) => value.length);
print('$newValue'); // Value<int>(state: ValueState.success, isFetching: false, data: 4)

Value error

Map a Value to failure with actual data if any. There is no Value.failure constructor to prevent developers from forgetting to retain the data from a previous state of the [Value].

final valueError = Value.initial().toFailure(Exception('error'));

print('Data of value : ${valueError.data}'); // Data of value : null
print('Error of value : "${valueError.error}"'); // Error of value : "Exception: error"

The new value from call toFailure on valueSuccess keep previous data. It provides a simple way to display both error and previous data (for example a refresh failure).

final valueErrorWithPreviousData = valueSuccess.toFailure(Exception('error'));

print('Data of value : ${valueErrorWithPreviousData.data}'); // Data of value : 1
print('Error of value : "${valueErrorWithPreviousData.error}"'); // Error of value : "Exception: error"

Handle states (isFetching, success, error...) while an action is processed

const value = Value<String>.initial();
print(value);
value.fetchFrom(() async => "result").forEach(print);
// Result :
// Value<String>(state: ValueState.initial, isFetching: false)
// Value<String>(state: ValueState.initial, isFetching: true)
// Value<String>(state: ValueState.success, isFetching: false, data: result)

⚙️ Migration

If you previously used value_cubit or flutter_value_state, please refer to the example with Cubit or the basic example for guidance.

License

MIT License

See the LICENSE file for details.

Feedback

Please file any issues, bugs or feature requests as an issue on the Github page.