reduced 0.2.2
reduced: ^0.2.2 copied to clipboard
Minimal API for the basic features of state management frameworks.
reduced #
Minimal API for the basic features of state management frameworks:
- Read a current state value.
- Update a current state value.
- Callbacks with value semantics
The app logic based mainly on these features should remain as independent as possible from the state management framework used. Therefore, the app logic needs a neutral state management API and an implementation of this API for the state management framework used.
The former is provided by this package. The latter is provided by other packages listed at the end of the README.
Features #
The 'reduced' API covers the following features of a state management framework:
1. Read a current state value. #
abstract class ReducedStore {
S get state;
...
}
Samples of ReducedStore.get state
use
get state => super.state;
reduced_riverpod/lib/src/riverpod_reducible.dart#L12
get state => _state;
reduced_getx/lib/src/getx_reducible.dart#L13
2. Update a current state value. #
abstract class ReducedStore {
...
void reduce(Reducer<S> reducer);
}
Instead of writing the state value directly, the API provides a reduce
method that accepts a so-called reducer
as a parameter.
In the reduce
method the reducer
is executed with the current state value as a parameter and the return value of the reducer
is stored as the new state value.
Samples of ReducedStore.reduce
use
reduce(reducer) => add(reducer);
reduced_bloc/lib/src/bloc_reducible.dart#L15
reduce(reducer) => state = reducer(state);
reduced_riverpod/lib/src/riverpod_reducible.dart#L15
abstract class Reducer<S> {
S call(S state);
}
All Reducer implementations must be derived from the Reducer
base class.
Samples of Reducer
use
class Incrementer extends Reducer<int>
reduced/example/counter_app/lib/logic.dart#L6
2.1 ReducedTransformer function typedef
typedef ReducedTransformer<S, P> = P Function(
ReducedStore<S> store,
);
A ReducedTransformer
is a Function
that uses the read and update methods of the store
parameter to transform the current state value into a derived 'selective' state value. Only the changes to this derived 'selective' state value determine whether a rebuild of the widget is triggered. In order for changes to be detected correctly, the derived 'selective' state value must have value semantics.
With a ReducedTransformer
function usually a props
parameter for a ReducedWidgetBuilder
function is created.
Samples of ReducedTransformer
use
final ReducedTransformer<S, P1> transformer1;
reduced_mobx/lib/src/mobx_reducible.dart#L25
required ReducedTransformer<S, P> transformer,
reduced_bloc/lib/src/bloc_wrapper.dart#L21
2.2 ReducedWidgetBuilder function typedef
typedef ReducedWidgetBuilder<P> = Widget Function({
required P props,
});
A ReducedWidgetBuilder
is a Function
that builds a new widget from the properties of the passed props
parameter. That is, the props
parameter must contain all the properties necessary for building the widget.
Samples of ReducedWidgetBuilder
use
final ReducedWidgetBuilder<MyHomePageProps> builder;
reduced/example/counter_app_with_selective_rebuild/lib/consumer.dart#L16
required ReducedWidgetBuilder<P> builder,
reduced_bloc/lib/src/bloc_wrapper.dart#L22
2.3 Reducers with additional parameters
abstract class Reducer1<S, V> {
S call(S state, V value);
}
abstract class Reducer2<S, V1, V2> {
S call(S state, V1 value1, V2 value2);
}
abstract class Reducer3<S, V1, V2, V3> ...
Sample of Reducer1
use
class AddItemReducer extends Reducer1<AppState, int>
reducedexample/shopper_app/lib/models/reducer.dart#L9
2.4 Adapter implementations for Reducers with parameters
class Reducer1Adapter<S, V> extends Reducer<S> {
Reducer1Adapter(this.adaptee, this.value);
final Reducer1<S, V> adaptee;
final V value;
@override call(state) => adaptee.call(state, value);
@override get hashCode => ...
@override operator ==(other) ...
}
class Reducer2Adapter<S, V1, V2> extends Reducer<S> ...
class Reducer3Adapter<S, V1, V2, V3> extends Reducer<S> ...
Sample of Reducer1Adapter
use
Reducer1Adapter(RemoveItemReducer(), value),
reduced/example/shopper_app/lib/models/reducer.dart#L37
3. Callbacks with value semantics #
Many widgets have callback properties of type Function
. The Function
type has no value semantics (each function is unique), this also applies to anonymous functions, which are often used as values for widget callback properties.
If value semantics are needed, Callable
can be used for callback properties in the derived 'selective' state values instead of anonymous functions.
abstract class Callable<T> {
T call();
}
abstract class Callable1<T, V> {
T call(V value);
}
abstract class Callable2<T, V1, V2> {
T call(V1 value1, V2 value2);
}
abstract class Callable3<T, V1, V2, V3> {
T call(V1 value1, V2 value2, V3 value3);
}
Samples of Callable
use
typedef VoidCallable = Callable<void>;
reduced/lib/src/callbacks.dart#L395
final Callable<void> onPressed;
reduced/example/counter_app/lib/logic.dart#L15
If the signatures of a widget callback property's function and the call
method of a callable
match, then the callable
is assignment-compatible with the widget callback property, e.g.:
Callable1<String?, String> validator = ...
TextFormField(
validator: validator,
...
);
3.1 Adapter implementations of Callable(s)
class CallableAdapter<S> extends Callable<void> {
const CallableAdapter(this.store, this.reducer);
final ReducedStore<S> store;
final Reducer<S> reducer;
@override call() => store.reduce(reducer);
@override get hashCode => ...
@override operator ==(other) => ...
}
class Callable1Adapter<S, V> extends Callable1<void, V> ...
class Callable2Adapter<S, V1, V2> extends Callable2<void, V1, V2> ...
class Callable3Adapter<S, V1, V2, V3>
extends Callable3<void, V1, V2, V3> ...
Samples of CallableAdapter
use
onPressed: CallableAdapter(store, Incrementer()),
reduced/example/counter_app/lib/logic.dart#L20
Getting started #
In the pubspec.yaml add dependencies on the package 'reduced' and on the package of an implementation of the 'reduced' API for a state management framework, e.g. 'reduced_bloc'.
dependencies:
reduced:
git:
url: https://github.com/partmaster/reduced.git
ref: main
reduced_bloc:
git:
url: https://github.com/partmaster/reduced_bloc.git
ref: main
Import package 'reduced' to implement the logic.
import 'package:reduced/reduced.dart';
Import choosen implementation package for the 'reduced' API to use the logic, e.g.
import 'package:reduced_bloc/reduced_bloc.dart';
Usage (Part 1) #
Implementation of the counter demo app logic with the 'reduced' API without further dependencies on state management packages.
// logic.dart
import 'package:flutter/material.dart';
import 'package:reduced/reduced.dart';
class Incrementer extends Reducer<int> {
@override
int call(int state) => state + 1;
}
class Props {
Props({required this.counterText, required this.onPressed});
final String counterText;
final Callable<void> onPressed;
}
Props transformProps(ReducedStore<int> store) => Props(
counterText: '${store.state}',
onPressed: CallableAdapter(store, Incrementer()),
);
class MyHomePage extends StatelessWidget {
const MyHomePage({super.key, required this.props});
final Props props;
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(
title: const Text('reduced_fluttercommand example'),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: <Widget>[
const Text(
'You have pushed the button this many times:',
),
Text(props.counterText),
],
),
),
floatingActionButton: FloatingActionButton(
onPressed: props.onPressed,
tooltip: 'Increment',
child: const Icon(Icons.add),
),
);
}
Extended Features #
In addition to the basic features, state management frameworks also offer these advanced features:
- Register a state for management.
- Trigger a rebuild on widgets selectively after a state change.
- Set up a new scope for state management.
A neutral API has also been developed for this features in the form of the registerState
function and the ReducedProvider
, ReducedConsumer
and ReducedScope
widget classes. Since the features differ for the concrete frameworks, the signatures of the function and the widget constructors are also different, so these function and classes were not included in the 'reduced' API, but are part of the additional API of the implementations of the 'reduced' API.
1. Register a state for management. #
void registerState(S initialValue);
class ReducedProvider<S> extends Statelesswidget {
ReducedProvider({
required this.initialState,
required this.child,
}) ...
final S initialState,
final Widget child,
...
}
2. Trigger a rebuild on widgets selectively after a state change. #
class ReducedConsumer<S, P> extends StatelessWidget {
ReducedConsumer({
required this.transformer,
required this.builder,
}) ...
final ReducedTransformer<S, P> transformer,
final ReducedWidgetBuilder<P> builder,
...
}
3. Set up a new scope for state management. #
class ReducedScope extends StatelessWidget {
ReducedScope({
required this.child,
}) ...
final Widget child,
...
}
Usage (Part 2) #
Finished counter demo app using logic.dart and 'reduced_bloc' package, an implementation of the 'reduced' API on Bloc:
// main.dart
import 'package:flutter/material.dart';
import 'package:reduced_bloc/reduced_bloc.dart';
import 'logic.dart';
void main() => runApp(const MyApp());
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) => ReducedProvider(
initialState: 0,
child: MaterialApp(
theme: ThemeData(primarySwatch: Colors.blue),
home: Builder(
builder: (context) => const ReducedConsumer(
transformer: transformProps,
builder: MyHomePage.new,
),
),
),
);
}
Additional information #
Implementations of the 'reduced' API are available for the following state management frameworks:
framework | implementation package for 'reduced' API |
---|---|
Binder | reduced_binder |
Bloc | reduced_bloc |
FlutterCommand | reduced_fluttercommand |
FlutterTriple | reduced_fluttertriple |
GetIt | reduced_getit |
GetX | reduced_getx |
MobX | reduced_mobx |
Provider | reduced_provider |
Redux | reduced_redux |
Riverpod | reduced_riverpod |
Solidart | reduced_solidart |
StatesRebuilder | reduced_statesrebuilder |