Merge pull request #39 from davidmarne/inheritance

7.1.0

Author: davidmarne

.travis.yml

@@ -5,6 +5,6 @@ script:
   - dart tool/build.dart
   - pub run dart_dev format --check
   - pub run dart_dev analyze
-  - pub run dart_dev test
+  - pub run dart_dev test -p vm
   - pub run dart_dev coverage --no-html
   - bash <(curl -s https://codecov.io/bash) -f coverage/coverage.lcov

README.md

@@ -10,13 +10,25 @@ Inspired by [redux][redux_git]
 
 Built using [built_value][built_value_git]
 
-## Framework bindings & examples
+## Framework bindings
 
 [flutter][flutter]
 
-[react-dart][react-dart]
+## examples
 
-[angular2][angular2]
+[nested state & actions][nesting]
+
+[building reducers for built collections][collection_reducers]
+
+[inheritence in state & actions][inheritence]
+
+## libraries
+
+[thunk][built_redux_thunk]
+
+[rx][built_redux_rx]
+
+[repatch][built_redux_repatch]
 
 ## Using it in your project
 
@@ -29,10 +41,9 @@ Built using [built_value][built_value_git]
 > gain familiarity with it by reading [this blog post][built_value_blog].
 
 1. Add the `built_redux` package as a dependency in your `pubspec.yaml`.
-
   ```yaml
   dependencies:
-    built_redux: "^6.0.0"
+    built_redux: "^7.0.0"
   ```
 
 2. Create a script to run generators for generating built_values and built_redux action classes.
@@ -44,51 +55,52 @@ Built using [built_value][built_value_git]
   import 'package:source_gen/source_gen.dart';
   import 'package:built_redux/generator.dart';
 
-  /// Build the generated files in the built_value chat example.
   Future main(List<String> args) async {
     await build([
       new BuildAction(
           new PartBuilder([
             new BuiltValueGenerator(),
             new BuiltReduxGenerator(),
           ]),
+          // your lib name here
           'built_redux',
-          inputs: const ['test/unit/test_counter.dart'])
+          // tweak the files that invoke the generator here
+          inputs: const ['lib/**/*.dart'])
     ], deleteFilesByDefault: true);
   }
   ```
 
-3. Run the build script from the command line to generate your built_values and built_redux action classes
-  ```dart tool/build.dart```
+3. Run the build script from the command line to generate your built_values and built_redux action classes by running `dart [build script name].dart`
 
-### Writing a built_redux store
+### Implementing a built_redux store
 
 ```dart
 import 'package:built_value/built_value.dart';
 import 'package:built_redux/built_redux.dart';
 
- // This is a an implementation of ReduxActions. Actions are what middleware and ui
- // components invoke a change to the redux store's state. By extending ReduxActions
- // the built_redux generator will generate the required boilerplate to create
- // each action and an ActionNames class.
-  abstract class CounterActions extends ReduxActions {
-   ActionDispatcher<int> increment;
-   ActionDispatcher<int> decrement;
-
-   // factory to create on instance of the generated implementation of CounterActions
-   CounterActions._();
-   factory CounterActions() => new _$CounterActions();
- }
+// This is a an implementation of ReduxActions. Actions are what middleware and ui
+// components invoke a change to the redux store's state. By extending ReduxActions
+// the built_redux generator will generate the required boilerplate to create
+// each action and an ActionNames class. The ActionNames class is used to register
+// reducers
+abstract class CounterActions extends ReduxActions {
+  ActionDispatcher<int> get increment;
+  ActionDispatcher<int> get decrement;
+
+  // factory to create on instance of the generated implementation of CounterActions
+  CounterActions._();
+  factory CounterActions() => new _$CounterActions();
+}
 
-  // This is a built value. It is an immutable model that implements the Built interface.
-  // All of the state in your redux store is contained in a single built value model.
-  abstract class Counter implements Built<Counter, CounterBuilder> {
-   /// [count] value of the counter
-   int get count;
+// This is a built value. It is an immutable model that implements the Built interface.
+// All of the state in your redux store is contained in a single built value model.
+abstract class Counter implements Built<Counter, CounterBuilder> {
+  /// [count] value of the counter
+  int get count;
 
-   // Built value constructor. The factory is returning the default state
-   Counter._();
-   factory Counter() => new _$Counter._(count: 1);
+  // Built value constructor. The factory is returning the default state
+  Counter._();
+  factory Counter() => new _$Counter._(count: 1);
  }
 
 
@@ -101,19 +113,19 @@ increment(Counter state, Action<int> action, CounterBuilder builder) =>
 decrement(Counter state, Action<int> action, CounterBuilder builder) =>
   builder.count = state.count - action.payload;
 
- // This is a reducer builder. Use of ReducerBuilder is not required, however it
- // is strongly recommended as it gives you static type checking to make sure
- // the payload for action name provided is the same as the expected payload
- // for the action provided to your reducer. Calling .build() returns a reducer function
- // that can be passed to the store's constructor.
- var reducer = (new ReducerBuilder<Counter, CounterBuilder>()
-      ..add(CounterActionsNames.increment, increment)
-      ..add(CounterActionsNames.decrement, decrement)).build();
+// This is a reducer builder. Use of ReducerBuilder is not required, however it
+// is strongly recommended as it gives you static type checking to make sure
+// the payload for action name provided is the same as the expected payload
+// for the action provided to your reducer. Calling .build() returns a reducer function
+// that can be passed to the store's constructor.
+var reducerBuilder = new ReducerBuilder<Counter, CounterBuilder>()
+  ..add(CounterActionsNames.increment, increment)
+  ..add(CounterActionsNames.decrement, decrement);
 
-// Create a Redux store holding the state of your app.
+// Create a redux store holding the state of your app.
 // Its API contains three getters: stream, state, and actions.
 var store = new Store<Counter, CounterBuilder, CounterActions>(
-  reducer,
+  reducerBuilder.build(), // build returns a reducer function
   new Counter(),
   new CounterActions(),
 );
@@ -130,121 +142,32 @@ store.actions.decrement(1);
 // 2
 ```
 
-### Nested Reducers
-
-Nested reducers can be built to handle rebuilding built values that are
-nested within the state tree. This is nice for organization and scoping actions to a specific piece of your application's state.
-
-```dart
-// the state model
-abstract class BaseCounter implements Built<BaseCounter, BaseCounterBuilder> {
-  int get count;
-
-  // Also a built_value
-  NestedCounter get nestedCounter;
-
-  // Built value constructor. The factory is returning the default state
-  BaseCounter._();
-  factory BaseCounter() => new _$BaseCounter._(
-    count: 1,
-    nestedCounter: new NestedCounter(),
-  );
-}
-
-// the nested model
-abstract class NestedCounter implements Built<NestedCounter, NestedCounterBuilder> {
-  int get count;
-
-  // Built value constructor. The factory is returning the default state
-  NestedCounter._();
-  factory NestedCounter() => new _$NestedCounter._(
-    count: 1,
-  );
-}
-
-// create a nested reducer builder
-final nestedReducer = new NestedReducerBuilder<BaseCounter, BaseCounterBuilder,
-    NestedCounter, NestedCounterBuilder>(
-  (state) => state.nestedCounter, // maps the app state to the nested state
-  (builder) => builder.nestedCounter, // maps the app builder to the nested builder
-)..add(NestedCounterActionsNames.increment, _nestedIncrement);
-
-// actions registered only rebuild the nested state
-// notice the state and builder types are of NestedCounter and NestedCounterBuilder
-_nestedIncrement(NestedCounter state, Action<int> action, NestedCounterBuilder builder) =>
-  builder.count = state.count + action.payload;
-
-// now use ReducerBuilder.combineNested to add it to your main reducer
-var reducer = (new ReducerBuilder<Counter, CounterBuilder>()
-      ..add(CounterActionsNames.increment, increment)
-      ..add(CounterActionsNames.decrement, decrement)
-      ..combineNested(nestedReducer)).build();
-
-```
-
-Nested actions can also be used to help organize actions for nested reducers. First define your actions:
-
-```dart
-abstract class NestedActions extends ReduxActions {
-  ActionDispatcher<int> increment;
-  ActionDispatcher<int> decrement;
-
-  // factory to create on instance of the generated implementation of NestedActions
-  NestedActions._();
-  factory NestedActions() => new _$NestedActions();
-}
-```
-
-Then add them to your main action class like so:
-
-```dart
-abstract class CounterActions extends ReduxActions {
-  ActionDispatcher<int> increment;
-  ActionDispatcher<int> decrement;
-
-  NestedActions nestedActions;
-
-  // factory to create on instance of the generated implementation of CounterActions
-  CounterActions._();
-  factory CounterActions() => new _$CounterActions();
-}
-```
-
-Check the usage:
-
-```dart
-// only print the nested counter's count
-store.stream.listen((_) => print(store.state.nestedCounter.count));
-
-// The only way to mutate the internal state is to dispatch an action.
-store.actions.nestedActions.increment(1);
-// 1
-store.actions.increment(2);
-// 1
-```
-
 ### Writing middleware
 
 ```dart
- // Define specific actions to be handled by this middleware
- // A middleware can also listen to and perform side effects on any actions defined elsewhere
+// Define specific actions to be handled by this middleware.
+// A middleware can also listen to and perform side effects on any actions defined
+// elsewhere. It is possible that a middleware will not need any of its own actions
+// defined.
  abstract class DoubleAction extends ReduxActions {
-  ActionDispatcher<int> increment;
+  ActionDispatcher<int> get increment;
 
   DoubleAction._();
   factory DoubleAction() => new _$DoubleAction();
 }
 
- // This is a middleware builder. Use of MiddlewareBuilder is not required, however
- // just like ReducerBuilder it is strongly recommended as it gives you static type checking to make sure
- // the payload for action name provided is the same as the expected payload
- // for the action provided to your reducer. It will also call next(action) for you
- // if an action not handled by this middleware is received. Calling .build() returns the
- // middleware function that can be passed to your store at instantiation.
- var doubleMiddleware =  (new MiddlewareBuilder<Counter, CounterBuilder, CounterActions>()
-      ..add(DoubleActionNames.increment, _doubleIt)).build();
-
-_doubleIt(MiddlewareApi<Counter, CounterBuilder, CounterActions> api, ActionHandler next, Action<int> action) {
+// This is a middleware builder. Use of MiddlewareBuilder is not required, however
+// just like ReducerBuilder it is strongly recommended as it gives you static type checking to make sure
+// the payload for action name provided is the same as the expected payload
+// for the action provided to your reducer. It will also call next(action) for you
+// if an action not handled by this middleware is received. Calling .build() returns the
+// middleware function that can be passed to your store at instantiation.
+var doubleMiddleware = (new MiddlewareBuilder<Counter, CounterBuilder, CounterActions>()
+  ..add(DoubleActionNames.increment, _doubleIt)).build();
+
+void  _doubleIt(MiddlewareApi<Counter, CounterBuilder, CounterActions> api, ActionHandler next, Action<int> action) {
+  // doubles the action payload and kicks off a new action to increment the
+  // store by that amount.
   api.actions.increment(action.payload * 2);
 }
 ```
@@ -301,6 +224,27 @@ NextActionHandler loggingMiddleware(MiddlewareApi<Counter, CounterBuilder, Count
         };
 ```
 
+### Observing state
+
+The store's stream fires with a payload of type StoreChange. This is an object
+that contains the action, the previous state, and the next state. If you would
+like to set up a stream thats payload is simply the next state, use store.nexState
+
+```dart
+
+print(store.state.count);
+// 1
+
+store.nextState.listen(print);
+
+store.actions.increment(1);
+// 2
+
+store.actions.increment(3);
+// 5
+
+```
+
 ### Observing substate
 
 Streams can easily be accessed to observe any piece of your state tree by passing a mapper the store's
@@ -320,6 +264,25 @@ store.actions.nestedCounter.increment(2);
 
 ```
 
+In the case of substate streams, the payload is of type SubStateChange. This is an object the previous state, and the next state. If you would
+like to set up a stream thats payload is simply the next subState, use store.nexSubstate
+
+```dart
+
+print(store.state.count);
+// 1
+
+store.nextSubstate((BaseCounter state) => state.count)
+  .listen(print);
+
+store.actions.increment(1);
+// 2
+
+store.actions.increment(3);
+// 5
+
+```
+
 [built_value_blog]: https://medium.com/dartlang/darts-built-value-for-immutable-object-models-83e2497922d4
 
 [built_value_git]: https://github.com/google/built_value.dart/
@@ -328,10 +291,18 @@ store.actions.nestedCounter.increment(2);
 
 [redux_docs]: http://redux.js.org/
 
-[react-dart]: https://github.com/davidmarne/react_built_redux
-
 [flutter]: https://github.com/davidmarne/flutter_built_redux
 
-[angular2]: https://github.com/davidmarne/angular_built_redux
+[built_redux_thunk]: https://github.com/davidmarne/built_redux_thunk
+
+[built_redux_rx]: https://github.com/davidmarne/built_redux_rx
+
+[built_redux_repatch]: https://github.com/davidmarne/built_redux_repatch
 
 [flutter_built_redux]: https://github.com/davidmarne/flutter_built_redux
+
+[nesting]: test/unit/nested_models.dart
+
+[collection_reducers]: test/unit/collection_models.dart
+
+[inheritence]: test/unit/inheritance_test_models.dart

analysis_options.yaml

@@ -1,2 +1,4 @@
 analyzer:
   strong-mode: true
+  implicit-dynamic: false
+  implicit-casts: false