init sync up

Author: camsong

Diff for: .babelrc

@@ -0,0 +1,8 @@
+{
+  "stage": 0,
+  /* avoid config inheritance:
+  https://github.com/happypoulp/redux-tutorial/issues/88
+  http://stackoverflow.com/questions/32540598/disable-babelrc-inheritance
+  */
+  "breakConfig": true
+}

Diff for: .gitignore

@@ -0,0 +1,7 @@
+node_modules
+npm-debug.log
+.DS_Store
+dist
+nested-dispatch.js
+test.js
+.idea

Diff for: 00_introduction.js

@@ -0,0 +1,91 @@
+// Tutorial 0 - introduction.js
+
+// Why this tutorial?
+// While trying to learn Redux, I realized that I had accumulated incorrect knowledge about flux through
+// articles I read and personal experience. I don't mean that articles about flux are not well written
+// but I just didn't grasp concepts correctly. In the end, I was just applying documentation of different
+// flux frameworks (Reflux, Flummox, FB Flux) and trying to make them match with the theoretical concept I read
+// about (actions / actions creators, store, dispatcher, etc).
+// Only when I started using Redux did I realize that flux is more simple than I thought. This is all
+// thanks to Redux being very well designed and having removed a lot of "anti-boilerplate features" introduced
+// by other frameworks I tried before. I now feel that Redux is a much better way to learn about flux
+// than many other frameworks. That's why I want now to share with everyone, using my own words,
+// flux concepts that I am starting to grasp, focusing on the use of Redux.
+
+// You may have seen this diagram representing the famous unidirectional data flow of a flux application:
+
+/*
+                 _________               ____________               ___________
+                |         |             |            |             |           |
+                | Action  |------------▶| Dispatcher |------------▶| callbacks |
+                |_________|             |____________|             |___________|
+                     ▲                                                   |
+                     |                                                   |
+                     |                                                   |
+ _________       ____|_____                                          ____▼____
+|         |◀----|  Action  |                                        |         |
+| Web API |     | Creators |                                        |  Store  |
+|_________|----▶|__________|                                        |_________|
+                     ▲                                                   |
+                     |                                                   |
+                 ____|________           ____________                ____▼____
+                |   User       |         |   React   |              | Change  |
+                | interactions |◀--------|   Views   |◀-------------| events  |
+                |______________|         |___________|              |_________|
+
+*/
+
+// In this tutorial we'll gradually introduce you to concepts of the diagram above. But instead of trying
+// to explain this complete diagram and the overall flow it describes, we'll take each piece separately and try to
+// understand why it exists and what role it plays. In the end you'll see that this diagram makes perfect sense
+// once we understand each of its parts.
+
+// But before we start, let's talk a little bit about why flux exists and why we need it...
+// Let's pretend we're building a web application. What are all web applications made of?
+// 1) Templates / html = View
+// 2) Data that will populate our views = Models
+// 3) Logic to retrieve data, glue all views together and to react accordingly to user events,
+//    data modifications, etc. = Controller
+
+// This is the very classic MVC that we all know about. But it actually looks like concepts of flux,
+// just expressed in a slightly different way:
+// - Models look like stores
+// - user events, data modifications and their handlers look like
+//   "action creators" -> action -> dispatcher -> callback
+// - Views look like React views (or anything else as far as flux is concerned)
+
+// So is flux just a matter of new vocabulary? Not exactly. But vocabulary DOES matter, because by introducing
+// these new terms we are now able to express more precisely things that were regrouped under
+// various terminologies... For example, isn't a data fetch an action? Just like a click is also an action?
+// And a change in an input is an action too... Then we're all already used to issuing actions from our
+// applications, we were just calling them differently. And instead of having handlers for those
+// actions directly modify Models or Views, flux ensures all actions go first through something called
+// a dispatcher, then through our stores, and finally all watchers of stores are notified.
+
+// To get more clarity how MVC and flux differ, we'll
+// take a classic use-case in an MVC application:
+// In a classic MVC application you could easily end up with:
+// 1) User clicks on button "A"
+// 2) A click handler on button "A" triggers a change on Model "A"
+// 3) A change handler on Model "A" triggers a change on Model "B"
+// 4) A change handler on Model "B" triggers a change on View "B" that re-renders itself
+
+// Finding the source of a bug in such an environment when something goes wrong can become quite challenging
+// very quickly. This is because every View can watch every Model, and every Model can watch other Models, so
+// basically data can arrive from a lot of places and be changed by a lot of sources (any views or any models).
+
+// Whereas when using flux and its unidirectional data flow, the example above could become:
+// 1) user clicks on button "A"
+// 2) a handler on button "A" triggers an action that is dispatched and produces a change on Store "A"
+// 3) since all other stores are also notified about the action, Store B can react to the same action too
+// 4) View "B" gets notified by the change in Stores A and B, and re-renders
+
+// See how we avoid directly linking Store A to Store B? Each store can only be
+// modified by an action and nothing else. And once all stores have replied to an action,
+// views can finally update. So in the end, data always flows in one way:
+//     action -> store -> view -> action -> store -> view -> action -> ...
+
+// Just as we started our use case above from an action, let's start our tutorial with
+// actions and action creators.
+
+// Go to next tutorial: 01_simple-action-creator.js

Diff for: 01_simple-action-creator.js

@@ -0,0 +1,47 @@
+// Tutorial 1 - simple-action-creator.js
+
+// We started to talk a little about actions in the introduction but what exactly are those "action creators"
+// and how are they linked to "actions"?
+
+// It's actually so simple that a few lines of code can explain it all!
+
+// The action creator is just a function...
+var actionCreator = function() {
+    // ...that creates an action (yeah, the name action creator is pretty obvious now) and returns it
+    return {
+        type: 'AN_ACTION'
+    }
+}
+
+// So is that all? yes.
+
+// However, one thing to note is the format of the action. This is kind of a convention in flux
+// that the action is an object that contains a "type" property. This type allows for further
+// handling of the action. Of course, the action can also contain other properties to
+// pass any data you want.
+
+// We'll also see later that the action creator can actually return something other than an action,
+// like a function. This will be extremely useful for async action handling (more on that
+// in dispatch-async-action.js).
+
+// We can call this action creator and get an action as expected:
+console.log(actionCreator())
+// Output: { type: 'AN_ACTION' }
+
+// Ok, this works but it does not go anywhere...
+// What we need is to have this action be sent somewhere so that
+// anyone interested could know that something happened and could act accordingly.
+// We call this process "Dispatching an action".
+
+// To dispatch an action we need... a dispatch function ("Captain obvious").
+// And to let anyone interested know that an action happened, we need a mechanism to register
+// "handlers". Such "handlers" to actions in traditional flux application are called stores and
+// we'll see in the next section how they are called in redux.
+
+// So far here is the flow of our application:
+// ActionCreator -> Action
+
+// Read more about actions and action creators here:
+// http://rackt.org/redux/docs/recipes/ReducingBoilerplate.html
+
+// Go to next tutorial: 02_about-state-and-meet-redux.js

Diff for: 02_about-state-and-meet-redux.js

@@ -0,0 +1,56 @@
+// Tutorial 02 - about-state-and-meet-redux.js
+
+// Sometimes the actions that we'll handle in our application will not only inform us
+// that something happened but also tell us that data needs to be updated.
+
+// This is actually quite a big challenge in any app.
+// Where do I keep all the data regarding my application along its lifetime?
+// How do I handle modification of such data?
+// How do I propagate modifications to all parts of my application?
+
+// Here comes Redux.
+
+// Redux (https://github.com/rackt/redux) is a "predictable state container for JavaScript apps"
+
+// Let's review the above questions and reply to them with
+// Redux vocabulary (flux vocabulary too for some of them):
+
+// Where do I keep all the data regarding my application along its lifetime?
+//     You keep it the way you want (JS object, array, Immutable structure, ...).
+//     Data of your application will be called state. This makes sense since we're talking about
+//     all the application's data that will evolve over time, it's really the application's state.
+//     But you hand it over to Redux (Redux is a "state container", remember?).
+// How do I handle data modifications?
+//     Using reducers (called "stores" in traditional flux).
+//     A reducer is a subscriber to actions.
+//     A reducer is just a function that receives the current state of your application, the action,
+//     and returns a new state modified (or reduced as they call it)
+// How do I propagate modifications to all parts of my application?
+//     Using subscribers to state's modifications.
+
+// Redux ties all this together for you.
+// To sum up, Redux will provide you:
+//     1) a place to put your application state
+//     2) a mechanism to dispatch actions to modifiers of your application state, AKA reducers
+//     3) a mechanism to subscribe to state updates
+
+// The Redux instance is called a store and can be created like this:
+/*
+    import { createStore } from 'redux'
+    var store = createStore()
+*/
+
+// But if you run the code above, you'll notice that it throws an error:
+//     Error: Invariant Violation: Expected the reducer to be a function.
+
+// That's because createStore expects a function that will allow it to reduce your state.
+
+// Let's try again
+
+import { createStore } from 'redux'
+
+var store = createStore(() => {})
+
+// Seems good for now...
+
+// Go to next tutorial: 03_simple-reducer.js

Diff for: 03_simple-reducer.js

@@ -0,0 +1,44 @@
+// Tutorial 03 - simple-reducer.js
+
+// Now that we know how to create a Redux instance that will hold the state of our application
+// we will focus on those reducer functions that will allow us to transform this state.
+
+// A word about reducer VS store:
+// As you may have noticed, in the flux diagram shown in the introduction, we had "Store", not
+// "Reducer" like Redux is expecting. So how exactly do Store and Reducer differ?
+// It's more simple than you could imagine: A Store keeps your data in it while a Reducer doesn't.
+// So in traditional flux, stores hold state in them while in Redux, each time a reducer is
+// called, it is passed the state that needs to be updated. This way, Redux's stores became
+// "stateless stores" and were renamed reducers.
+
+// As stated before, when creating a Redux instance you must give it a reducer function...
+
+import { createStore } from 'redux'
+
+var store_0 = createStore(() => {})
+
+// ... so that Redux can call this function on your application state each time an action occurs.
+// Giving reducer(s) to createStore is exactly how redux registers the action "handlers" (read reducers) we
+// were talking about in section 01_simple-action-creator.js.
+
+// Let's put some log in our reducer
+
+var reducer = function (...args) {
+    console.log('Reducer was called with args', args)
+}
+
+var store_1 = createStore(reducer)
+
+// Output: Reducer was called with args [ undefined, { type: '@@redux/INIT' } ]
+
+// Did you see that? Our reducer is actually called even if we didn't dispatch any action...
+// That's because to initialize the state of the application,
+// Redux actually dispatches an init action ({ type: '@@redux/INIT' })
+
+// When called, a reducer is given those parameters: (state, action)
+// It's then very logical that at an application initialization, the state, not being
+// initialized yet, is "undefined"
+
+// But then what is the state of our application after Redux sends its "init" action?
+
+// Go to next tutorial: 04_get-state.js

Diff for: 04_get-state.js

@@ -0,0 +1,110 @@
+// Tutorial 04 - get-state.js
+
+// How do we retrieve the state from our Redux instance?
+
+import { createStore } from 'redux'
+
+var reducer_0 = function (state, action) {
+    console.log('reducer_0 was called with state', state, 'and action', action)
+}
+
+var store_0 = createStore(reducer_0)
+// Output: reducer_0 was called with state undefined and action { type: '@@redux/INIT' }
+
+// To get the state that Redux is holding for us, you call getState
+
+console.log('store_0 state after initialization:', store_0.getState())
+// Output: store_0 state after initialization: undefined
+
+// So the state of our application is still undefined after the initialization? Well of course it is,
+// our reducer is not doing anything... Remember how we described the expected behavior of a reducer in
+// "about-state-and-meet-redux"?
+//     "A reducer is just a function that receives the current state of your application, the action,
+//     and returns a new state modified (or reduced as they call it)"
+// Our reducer is not returning anything right now so the state of our application is what
+// reducer() returns, hence "undefined".
+
+// Let's try to send an initial state of our application if the state given to reducer is undefined:
+
+var reducer_1 = function (state, action) {
+    console.log('reducer_1 was called with state', state, 'and action', action)
+    if (typeof state === 'undefined') {
+        return {}
+    }
+
+    return state;
+}
+
+var store_1 = createStore(reducer_1)
+// Output: reducer_1 was called with state undefined and action { type: '@@redux/INIT' }
+
+console.log('store_1 state after initialization:', store_1.getState())
+// Output: store_1 state after initialization: {}
+
+// As expected, the state returned by Redux after initialization is now {}
+
+// There is however a much cleaner way to implement this pattern thanks to ES6:
+
+var reducer_2 = function (state = {}, action) {
+    console.log('reducer_2 was called with state', state, 'and action', action)
+
+    return state;
+}
+
+var store_2 = createStore(reducer_2)
+// Output: reducer_2 was called with state {} and action { type: '@@redux/INIT' }
+
+console.log('store_2 state after initialization:', store_2.getState())
+// Output: store_2 state after initialization: {}
+
+// You've probably noticed that since we've used the default parameter on state parameter of reducer_2,
+// we no longer get undefined as state's value in our reducer's body.
+
+// Let's now recall that a reducer is only called in response to an action dispatched and
+// let's fake a state modification in response to an action type 'SAY_SOMETHING'
+
+var reducer_3 = function (state = {}, action) {
+    console.log('reducer_3 was called with state', state, 'and action', action)
+
+    switch (action.type) {
+        case 'SAY_SOMETHING':
+            return {
+                ...state,
+                message: action.value
+            }
+        default:
+            return state;
+    }
+}
+
+var store_3 = createStore(reducer_3)
+// Output: reducer_3 was called with state {} and action { type: '@@redux/INIT' }
+
+console.log('store_3 state after initialization:', store_3.getState())
+// Output: redux state after initialization: {}
+
+// Nothing new in our state so far since we did not dispatch any action yet. But there are few
+// important things to pay attention to in the last example:
+//     0) I assumed that our action contains a type and a value property. The type property is mostly
+//        a convention in flux actions and the value property could have been anything else.
+//     1) You'll often see the pattern involving a switch to respond appropriately
+//        to an action received in your reducers
+//     2) When using a switch, NEVER forget to have a "default: return state" because
+//        if you don't, you'll end up having your reducer return undefined (and lose your state).
+//     3) Notice how we returned a new state made by merging current state with { message: action.value },
+//        all that thanks to this awesome ES7 notation (Object Spread): { ...state, message: action.value }
+//     4) Note also that this ES7 Object Spread notation suits our example because it's doing a shallow
+//        copy of { message: action.value } over our state (meaning that first level properties of state
+//        are completely overwritten - as opposed to gracefully merged - by first level property of
+//        { message: action.value }). But if we had a more complex / nested data structure, you might choose
+//        to handle your state's updates very differently:
+//        - using Immutable.js (https://facebook.github.io/immutable-js/)
+//        - using Object.assign (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
+//        - using manual merge
+//        - or whatever other strategy that suits your needs and the structure of your state since
+//          Redux is absolutely NOT opinionated on this (remember, Redux is a state container).
+
+// Now that we're starting to handle actions in our reducer let's talk about having multiple reducers and
+// combining them.
+
+// Go to next tutorial: 05_combine-reducers.js