flutter_flux 4.0.1

  • README.md
  • Installing
  • Versions
  • 67

flutter_flux

A Dart app architecture library with uni-directional data flow inspired by RefluxJS and Facebook's Flux.

This is an experimental package and does not have official support from the Flutter team. However, feedback is most welcome!


Overview

flux-diagram

flutter_flux implements a uni-directional data flow pattern comprised of Actions, Stores, and StoreWatchers. It is based on w_flux, but modified to use Flutter instead of React.

  • Actions initiate mutation of app data that resides in Stores.
  • Data mutations within Stores trigger re-rendering of app view (defined in StoreWatcher).
  • Flutter Widgets and other interaction sources dispatch Actions in response to user interaction.
  • and the cycle continues...

What's Included

Action

An Action is a command that can be dispatched (with an optional data payload) and listened to.

In flutter_flux, Actions are the sole driver of application state change. Widgets and other objects dispatch Actions in response to user interaction with the rendered view. Stores listen for these Action dispatches and mutate their internal data in response, taking the Action payload into account as appropriate.

import 'package:flutter_flux/flutter_flux.dart';

// define an action
final Action<String> displayString = new Action<String>();

// dispatch the action with a payload
displayString('somePayload');

// listen for action dispatches
displayString.listen(_displayAlert);

_displayAlert(String payload) {
  print(payload);
}

BONUS: Actions are await-able!

They return a Future that completes after all registered Action listeners complete. It's NOT generally recommended to use this feature within normal app code, but it is quite useful in unit test code.

Store

A Store is a repository and manager of app state. The base Store class provided by flutter_flux should be extended to fit the needs of your app and its data. App state may be spread across many independent stores depending on the complexity of the app and your desired app architecture.

By convention, a Store's internal data cannot be mutated directly. Instead, Store data is mutated internally in response to Action dispatches. Stores should otherwise be considered read-only, publicly exposing relevant data ONLY via getter methods. This limited data access ensures that the integrity of the uni-directional data flow is maintained.

A Store can be listened to to receive external notification of its data mutations. Whenever the data within a Store is mutated, the trigger method is used to notify any registered listeners that updated data is available. In flutter_flux, StoreWatchers listen to Stores, typically triggering re-rendering of UI elements based on the updated Store data.

import 'package:flutter_flux/flutter_flux.dart';

class RandomColorStore extends Store {

  // Public data is only available via getter method
  String _backgroundColor = 'gray';
  String get backgroundColor => _backgroundColor;

  // Actions relevant to the store are passed in during instantiation
  RandomColorActions _actions;

  RandomColorStore(RandomColorActions this._actions) {
    // listen for relevant action dispatches
    _actions.changeBackgroundColor.listen(_changeBackgroundColor);
  }

  _changeBackgroundColor(_) {
    // action dispatches trigger internal data mutations
    _backgroundColor = '#' + (new Random().nextDouble() * 16777215).floor().toRadixString(16);

    // trigger to notify external listeners that new data is available
    trigger();
  }
}

BONUS: Stores can be initialized with a stream transformer to modify the standard behavior of the trigger stream. This can be useful for throttling UI rendering in response to high frequency Store mutations.

import 'package:rate_limit/rate_limit.dart';
import 'package:flutter_flux/flutter_flux.dart';

class ThrottledStore extends Store {
  ...

  ThrottledStore(this._actions) : super.withTransformer(new Throttler(const Duration(milliseconds: 30))) {
    ...
  }
}

BONUS: Stores provide an optional terse syntax for action -> data mutation -> trigger operations.

// verbose syntax
actions.incrementCounter.listen(_handleAction);

_handleAction(payload) {
    // perform data mutation
    counter += payload;
    trigger();
  }

// equivalent terse syntax
triggerOnAction(actions.incrementCounter, (payload) => counter += payload);

Examples

Simple examples of flutter_flux usage can be found in the example directory. The example README includes instructions for building / running them.


External Consumption

flutter_flux implements a uni-directional data flow within an isolated application or code module. If flutter_flux is used as the internal architecture of a library, this internal data flow should be considered when defining the external API.

  • External API methods intended to mutate internal state should dispatch Actions, just like any internal user interaction.
  • External API methods intended to query internal state should leverage the existing read-only Store getter methods.
  • External API streams intended to notify the consumer about internal state changes should be dispatched from the internal Stores, similar to their triggers.

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  flutter_flux: "^4.0.1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:flutter_flux/flutter_flux.dart';
        
Version Uploaded Documentation Archive
4.0.1 Apr 19, 2017 Go to the documentation of flutter_flux 4.0.1 Download flutter_flux 4.0.1 archive
4.0.0 Nov 7, 2016 Go to the documentation of flutter_flux 4.0.0 Download flutter_flux 4.0.0 archive

Analysis

This feature is new.
We welcome feedback.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Dec 6, 2017
  • Dart: 2.0.0-dev.8.0
  • pana: 0.7.3+1
  • Flutter: 0.0.19

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
74
Health:
Code health derived from static analysis. [more]
57
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
63
Overall score:
Weighted score of the above. [more]
67

Platforms

Detected platforms:

Error(s) prevent platform classification.

Suggestions

  • Fix lib/src/store_watcher.dart.

    Strong-mode analysis of lib/src/store_watcher.dart failed with the following error:

    line: 50 col: 25
    Base class introduces an invalid override. The type of 'State._widget=' ('(StoreWatcher) → void') isn't a subtype of 'State<dynamic>._widget=' ('(dynamic) → void').

  • Maintain CHANGELOG.md.

    Changelog entries help clients to follow the progress in your code.

  • Use analysis_options.yaml.

    Rename old .analysis_options file to analysis_options.yaml.

Dependencies

Package Constraint Resolved Available
Direct dependencies
flutter 0.0.39
meta ^1.0.3 1.1.1 1.1.2
Transitive dependencies
async 1.13.3 2.0.1
charcode 1.1.1
collection 1.14.3
http 0.11.3+14 0.11.3+16
http_parser 3.1.1
path 1.5.1
sky_engine 0.0.99
source_span 1.4.0
stack_trace 1.9.1
string_scanner 1.0.2
typed_data 1.1.4 1.1.5
vector_math 2.0.5
Dev dependencies
flutter_test
quiver ^0.24.0
rate_limit ^0.1.0
test ^0.12.13