Update README the match new Store behaviors

Author: twittemb

README.md

@@ -72,7 +72,7 @@ pod 'RxReduce'
 
 # The key principles
 
-The core mechanisms of **RxReduce** are very straightforward (if you know Redux, you won't be disturbed):
+The core mechanisms of **RxReduce** are very straightforward:
 
 Here is a little animation that explains the flow within a state container architecture:
 
@@ -81,10 +81,10 @@ Here is a little animation that explains the flow within a state container archi
 - The **Store** is the component that handles your state. It has only one input: the "**dispatch()**" function, that takes an **Action** as a parameter.
 - The only way to trigger a **State** mutation is to call this "**dispatch()**" function.
 - **Actions** are simple types with no business logic. They embed the payload needed to mutate the **state**
-- Only free and testable functions called **Reducers** (RxReduce !) can mutate a **State**. A "**reduce()**" function takes a **State**, an **Action** and returns the new **State** ... that simple.
-- You can have as many reducers as you want, they will be applied by the **Store**'s "**dispatch()**" function sequentially. It could be nice to have a reducer per business concern for instance.
+- Only free and testable functions called **Reducers** (RxReduce !) can mutate a **State**. A "**reduce()**" function takes a **State**, an **Action** and returns a mutated **State** ... that simple. To be precise, a **reducer** returns a mutated sub-State of the State. In fact, there is one **reducer** per sub-State of the State. By sub-State, we mean all the properties that compose a State.
+- The Store will make sure you provide one and only one **reducer** per sub-State. It brings safety and consistency to your application's logic. Each **reducer** has a well defined scope.
 - Reducers **cannot** perform asynchronous logic, they can only mutate the state in a synchronous and readable way. Asynchronous work will be taken care of by **Reactive Actions**.
-- You can be notified of the state mutation thanks to a **Driver\<State\>** exposed by the **Store**.
+- You can be notified of the state mutation thanks to a **Observable\<State\>** exposed by the **Store**.
 
 # How to use RxReduce
 
@@ -95,18 +95,20 @@ Here is a little animation that explains the flow within a state container archi
 As the main idea of state containers is about immutability, avoiding reference type uncontrolled propagation and race conditions, a **State** must be a value type. Structs and Enums are great for that.
 
 ```swift
-import RxReduce
-
-struct DemoState: State, Equatable {
+struct TestState: Equatable {
     var counterState: CounterState
-    var usersState: [String]
+    var userState: UserState
 }
 
 enum CounterState: Equatable {
     case empty
-    case increasing (counter: Int)
-    case decreasing (counter: Int)
-    case stopped
+    case increasing (Int)
+    case decreasing (Int)
+}
+
+enum UserState: Equatable {
+    case loggedIn (name: String)
+    case loggedOut
 }
 ```
 
@@ -117,68 +119,60 @@ Making states **Equatable** is not mandatory but it will allow the **Store** not
 Actions are simple data types that embed a payload used in the reducers to mutate the state.
 
 ```swift
-import RxReduce
-
-struct IncreaseAction: Action {
-    let increment: Int
-}
-
-struct DecreaseAction: Action {
-    let decrement: Int
-}
-
-struct AddUserAction: Action {
-    let user: String
+enum AppAction: Action {
+    case increase(increment: Int)
+    case decrease(decrement: Int)
+    case logUser(user: String)
+    case clear
 }
 ```
 
 ### How to declare **Reducers**
 
 As I said, a **reducer** is a free function. These kind of functions takes a value, returns an idempotent value, and performs no side effects. Their declaration is not even related to a type definition. This is super convenient for testing 👍
 
-Here we define 2 **reducers** that will be applied in sequence each time an Action is dispatched in the **Store**.
+Here we define two **reducers** that will take care of their dedicated sub-State. The first one mutates the CounterState and the second one mutates the UserState.
 
 ```swift
-import RxReduce
+func counterReduce (state: TestState, action: Action) -> CounterState {
 
-func counterReducer (state: DemoState?, action: Action) -> DemoState {
-
-    var currentState = state ?? DemoState(counterState: CounterState.empty, usersState: [])
+    guard let action = action as? AppAction else { return state.counterState }
 
     var currentCounter = 0
 
     // we extract the current counter value from the current state
-    switch currentState.counterState {
+    switch state.counterState {
     case .decreasing(let counter), .increasing(let counter):
         currentCounter = counter
     default:
         currentCounter = 0
     }
 
-    // according to the action we create a new state
+    // according to the action we mutate the counter state
     switch action {
-    case let action as IncreaseAction:
-        currentState.counterState = .increasing(counter: currentCounter+action.increment)
-        return currentState
-    case let action as DecreaseAction:
-        currentState.counterState = .decreasing(counter: currentCounter-action.decrement)
-        return currentState
+    case .increase(let increment):
+        return .increasing(currentCounter+increment)
+    case .decrease(let decrement):
+        return .decreasing(currentCounter-decrement)
+    case .clear:
+        return .empty
     default:
-        return currentState
+        return state.counterState
     }
 }
 
-func usersReducer (state: DemoState?, action: Action) -> DemoState {
+func userReduce (state: TestState, action: Action) -> UserState {
 
-    var currentState = state ?? DemoState(counterState: CounterState.empty, usersState: [])
+    guard let action = action as? AppAction else { return state.userState }
 
-    // according to the action we create a new state
+    // according to the action we mutate the users state
     switch action {
-    case let action as AddUserAction:
-        currentState.usersState.append(action.user)
-        return currentState
+    case .logUser(let user):
+        return .loggedIn(name: user)
+    case .clear:
+        return .loggedOut
     default:
-        return currentState
+        return state.userState
     }
 }
 ```
@@ -187,127 +181,115 @@ Each of these **Reducers** will only handle the **Actions** it is responsible fo
 
 ### How to declare a **Store**
 
-**RxReduce** provides a concrete Store type. A Store needs at leat one **Reducer**:
+**RxReduce** provides a generic **Store** that can handle your application's State. You only need to provide an initial State:
 
 ```swift
-let store = Store<DemoState>(withReducers: [counterReducer, usersReducer])
+let store = Store<TestState>(withState: TestState(counterState: .empty, userState: .loggedOut))
 ```
 
-### How to declare a **Middleware**
+### How to aggregate sub-State mutations into a whole State
 
-Middlewares are very similar to Reducers BUT they cannot mutate the state. They are some kind of "passive observers" of what's being dispatched in the store. Middlewares can be used for logging, analytics, state recording, ...
+As we saw: a **reducer** takes care only of its dedicated sub-State. We will then define a bunch of reducers to handle the whole application's state mutations. 
+So, we need a mechanism to assemble all the mutated sub-State to a consistent State.
 
-```swift
-import RxReduce
+We will use functional programming technics to achieve that.
 
-func loggingMiddleware (state: DemoState?, action: Action) {
-    guard let state = state else {
-        print ("A new Action \(action) will provide a first value for an empty state")
-        return
-    }
-
-    print ("A new Action \(action) will mutate current State : \(state)")
-}
-```
-
-A Store initializer takes Reducers and if needed, an Array of Middlewares as well:
+#### Lenses
+A Lens is a generic way to access and mutate a value type in functional programming. It's about telling the Store how to mutate a certain sub-State of the State. For instance the **Lens** for **CounterState** would be:
 
 ```swift
-let store = Store<DemoState>(withReducers: [counterReducer, usersReducer], withMiddlewares: [loggingMiddleware])
+let counterLens = Lens<TestState, CounterState> (get: { testState in return testState.counterState },
+                                                 set: { (testState, counterState) -> TestState in
+	var mutableTestState = testState
+	mutableTestState.counterState = counterState
+	return mutableTestState
+    })
 ```
 
-### Let's put the pieces all together
+it's all about defining how to access the CounterState property (the `get` closure) of the State and how to mutate it (the `set` closure).
 
-RxReduce allows to listen to the whole state or to some of its properties (we may call them **substates**).
-Listening only to substates makes sense when the state begins to be huge and you do not want to be notified each time one of its portion has been modified.
+#### Mutator
 
-First we pick the substate we want to observe (by passing a closure to the **store.state()** function):
+A mutator is simply a structure that groups a **Reducer** and a **Lens** for a sub-State. Again for the **CounterState**:
 
 ```swift
-let counterState: Driver<CounterState> = store.state { (demoState) -> CounterState in
-    return demoState.counterState
-}
-
-let usersState: Driver<[String]> = store.state { (demoState) -> [String] in
-    return demoState.usersState
-}
+let counterMutator = Mutator<TestState, CounterState>(lens: counterLens, reducer: counterReduce)
 ```
 
-The trailing closure gives you the whole state of the **Store**, and you just have to **extract** the substate you want to observe.
+A Mutator has everything needed to know how to mutate the CounterState and how to set it to its parent State.
 
-Then subscribe to the substate:
+### Let's put the pieces all together
+
+After instantiating the Store, you have to register all the Mutators that will handle the State's sub-States.
 
 ```swift
-counterState.drive(onNext: { (counterState) in
-    print ("New counterState is \(counterState)")
-}).disposed(by: self.disposeBag)
+let store = Store<TestState>(withState: TestState(counterState: .empty, userState: .loggedOut))
+let counterMutator = Mutator<TestState, CounterState>(lens: counterLens, reducer: counterReduce)
+let userMutator = Mutator<TestState, UserState>(lens: userLens, reducer: userReduce)
 
-usersState.drive(onNext: { (usersState) in
-    print ("New usersState is \(usersState)")
-}).disposed(by: self.disposeBag)
+store.register(mutator: counterMutator)
+store.register(mutator: userMutator)
 ```
 
 And now lets mutate the state:
 
 ```swift
-store.dispatch(action: IncreaseAction(increment: 10))
-store.dispatch(action: IncreaseAction(increment: 0))
-store.dispatch(action: AddUserAction(user: "Spock"))
-```
-
-Please notice that the second action will not modify the state, and the **Store** will be smart about that and will not trigger a new value for the **counterState**. This happens only because **DemoState** conforms to **Equatable**.
-
-The output will be:
-
-```swift
-New counterState is increasing(10) (for the first action)
-New usersState is [] (for the first action)
-New usersState is ["Spock"] (for the third action)
+store.dispatch(action: AppAction.increase(increment: 10)).subscribe(onNext: { testState in
+	print ("New State \(testState)")
+}).disposed(by: self.disposeBag)
 ```
 
-As we can see, **counterState** has received only one value 👌
-
 ## But wait, there's more ...
 
 ### List of actions
 
-RxReduce is a lightweight framework. Pretty much everything is a protocol (except the Store, but if you want to implement you own Store it is perfectly fine since RxReduce provides a StoreType protocol you can conform to).
-
 Lately, Swift 4.1 has introduced conditional conformance. If you are not familiar with this concept: [A Glance at conditional conformance](https://medium.com/@thibault.wittemberg/a-glance-at-conditional-conformance-c1f2d9ea29a3).
 
 Basically it allows to make a generic type conform to a protocol only if the associated inner type also conforms to this protocol. 
 
 For instance, RxReduce leverages this feature to make an Array of Actions be an Action to ! Doing so, it is perfectly OK to dispatch a list of actions to the Store like that:
 
 ```swift
-let actions: [Action] = [IncreaseAction(increment: 10), DecreaseAction(increment: 5)]
-store.dispatch(action: actions)
+let actions: [Action] = [AppAction.increase(increment: 10), AppAction.decrease(decrement: 5)]
+store.dispatch(action: actions).subscribe ...
 ```
 
 The actions declared in the array will be executed sequentially 👌.
 
 ### Asynchronicity
 
-Making an Array of Actions be an Action itself is neat, but since we're using Reactive Programming, RxReduxe also applies this technic to Observables. It provides a very elegant way to dispatch an Observable\<Action\> to the Store (because Observable\<Action\> is also an Action), making asynchronous actions very simple. 
+Making an Array of Actions be an Action itself is neat, but since we're using Reactive Programming, RxReduxe also applies this technic to **RxSwift Observables**. It provides a very elegant way to dispatch an Observable\<Action\> to the Store (because Observable\<Action\> also conforms to Action), making asynchronous actions very simple. 
 
 ```swift
-let increaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in IncreaseAction(increment: 1) }
-store.dispatch(action: increaseAction)
+let increaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in AppAction.increase(increment: 1) }
+store.dispatch(action: increaseAction).subscribe ...
 ```
 
-If we want to compare RxReduce with Redux, this ability to execute async actions would be equivalent to an "Action Creator".
+This will dispatch a **AppAction.increase** Action every 1s and mutate the State accordingly.
+
+If we want to compare RxReduce with Redux, this ability to execute async actions would be equivalent to the "**Action Creator**" concept.
 
 For the record, we could even dispatch to the Store an Array of Observable\<Action\>, and it will be seen as an Action as well.
 
 ```swift
-let increaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in IncreaseAction(increment: 1) }
-let decreaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in DecreaseAction(decrement: 1) }
+let increaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in AppAction.increase(increment: 1) }
+let decreaseAction = Observable<Int>.interval(1, scheduler: MainScheduler.instance).map { _ in AppAction.decrease(decrement: 1) }
 let asyncActions: [Action] = [increaseAction, decreaseAction]
-store.dispatch(action: asyncActions)
+store.dispatch(action: asyncActions).subscribe ...
 ```
 
 Conditional Conformance is a very powerful feature.
 
+### One more thing
+
+The **Store** provides a way to "observe" the State mutations from anywhere. All you have to do is to subscribe to the "**state**" property:
+
+```swift
+store.state.subscribe(onNext: { appState in
+	print (appState)
+}).disposed(by: self.disposeBag)
+```
+
 ## Demo Application
 
 A demo application is provided to illustrate the core mechanisms, such as asynchronicity, sub states and view state rendering.

RxReduceTests/StoreTests.swift

@@ -16,7 +16,7 @@ final class StoreTests: XCTestCase {
 
     private let disposeBag = DisposeBag()
 
-    private let counterLens = Lens<TestState, CounterState> (get: { $0.counterState }) { (testState, counterState) -> TestState in
+    private let counterLens = Lens<TestState, CounterState> (get: { testState in return testState.counterState }) { (testState, counterState) -> TestState in
         var mutableTestState = testState
         mutableTestState.counterState = counterState
         return mutableTestState