Rodux Documentation (#36)

Update Rodux documentation

Author: SlartibartfastFjords

docs/advanced/middleware.md

@@ -0,0 +1,41 @@
+Most of the time, calling `Store:dispatch` sends incoming `action` objects directly to the `reducer` to determine what updates should be made to the `state`. This is enough for most cases, but some features would be difficult to implement if this was all Rodux provided. For example:
+
+- Delayed processing of an `action`.
+- Logging `action` objects dispatched to our `store`.
+- Performing a network request in response to an `action` and storing the response in the `state`.
+
+Rodux has the concept of `middleware` to deal with these sorts of situations.
+
+A `middleware` is a function that accepts the next `dispatch` function in the `middleware` chain, as well as the `store` the `middleware` is being used with, and returns a new function. That function is called whenever an `action` is dispatched and can dispatch more `actions`, log to output, or perform any other side effects! When an `action` is dispatched, `middleware` are run in the order they were specified in [`Store.new`](../api-reference.md#storenew) from left to right.
+
+Here is an example of a `middleware` that could be used to delay the processing of `action` objects dispatched to the `store`.
+
+```lua
+local reducer = function(state, action)
+	-- the body of your reducer
+end
+
+local initialState = {}
+
+local delayOneSecondMiddleware = function(nextDispatch, store)
+	return function(action)
+		delay(1, function()
+			--[[
+				nextDispatch passes the action to the next middleware provided
+				to the store at initialization or to the reducer if the action
+				has already been processed by all the provided middleware.
+			]]
+			nextDispatch(action)
+		end)
+	end
+end
+
+local store = Rodux.Store.new(reducer, initialState, {
+	delayOneSecondMiddleware,
+})
+```
+
+!!! warning
+	If the `delayOneSecondMiddleware` function did not call `nextDispatch`, then the `action` would not be processed by any other `middleware` in the `middleware` chain or our `reducer`!
+
+Rodux has two `middlewares` available to you out of the box. See [`Middleware`](../api-reference.md#middleware), [`thunkMiddleware`](../api-reference.md#roduxthunkmiddleware), and [`loggerMiddleware`](../api-reference.md#roduxloggermiddleware) for more details.

docs/advanced/thunks.md

@@ -0,0 +1,31 @@
+The `thunkMiddleware` packaged with Rodux will intercept any `action` dispatched to our `store` that is a Lua *function* and execute that function instead of forwarding our `action` to the `reducer`. These functions (also called thunks) have access to the `store` and are allowed to dispatch `action` objects themselves as necessary.
+
+```lua
+local reducer = function(state, action)
+	--[[
+		Reducer that handles all actions for our store,
+		including actions of the type "MadeNewFriends".
+	]]
+end
+
+local initialState = {}
+
+local store = Rodux.Store.new(reducer, initialState, {
+	Rodux.thunkMiddleware,
+})
+
+--[[
+	Our thunkMiddleware will process this action as a thunk
+	since it is a Lua function
+]]
+store:dispatch(function(store)
+	getAsyncNewFriendsForUser("Sarah", function(result)
+		store:dispatch({
+			type = "MadeNewFriends",
+			newFriends = result,
+		})
+	end)
+end)
+```
+
+Thunks are a simple way to introduce more complex processing of `action` objects, but you may want to consider creating custom [`middleware`](middleware.md) for complex features instead of relying on thunks alone.

docs/api-reference.md

@@ -164,7 +164,7 @@ A single middleware is just a function with the following signature:
 (nextDispatch, store) -> (action) -> result
 ```
 
-A middleware is a function that accepts the next dispatch function in the *middleware chain*, as well as the store the middleware is being used with, and returns a new function. That function is called whenever an action is dispatched and can dispatch more actions, log to output, or perform any side effects!
+A middleware is a function that accepts the next dispatch function in the *middleware chain*, as well as the store the middleware is being used with, and returns a new function. That function is called whenever an action is dispatched and can dispatch more actions, log to output, or perform any other side effects!
 
 A simple version of Rodux's `loggerMiddleware` is as easy as:
 

docs/debugging.md

@@ -0,0 +1 @@
+In the future, Rodux will have tools similar to [Redux's DevTools](https://github.com/gaearon/redux-devtools) and will be documented here. For now, we highly recommend using the [`loggerMiddleware`](api-reference.md#roduxloggermiddleware) to observe the `state` as `action` objects are dispatched to your `store`.

docs/example.md

@@ -0,0 +1,94 @@
+The following is an example of a Rodux store that keeps track of the current user's phone number and the names of their friends. It demonstrates the use of the Rodux `store`, `actions`, `reducers`, and `middleware` in a real world setting. The `loggerMiddleware` has been included to demonstrate how to include `middleware` in your `store` and to provide valuable output in response to dispatched `action` objects.
+
+!!! info
+	This example assumes that you've successfully [installed Rodux](introduction/installation.md) into `ReplicatedStorage` and placed the contents of the following in a LocalScript under `StarterPlayer/StarterPlayerScripts`!
+
+```lua
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local Rodux = require(ReplicatedStorage.Rodux)
+
+-- Action creator for the ReceivedNewPhoneNumber action
+local function ReceivedNewPhoneNumber(phoneNumber)
+	return {
+		type = "ReceivedNewPhoneNumber",
+		phoneNumber = phoneNumber,
+	}
+end
+
+-- Action creator for the MadeNewFriends action
+local function MadeNewFriends(listOfNewFriends)
+	return {
+		type = "MadeNewFriends",
+		newFriends = listOfNewFriends,
+	}
+end
+
+-- Reducer for the current user's phone number
+local phoneNumberReducer = Rodux.createReducer("", {
+	ReceivedNewPhoneNumber = function(state, action)
+		return action.phoneNumber
+	end,
+})
+
+-- Reducer for the current user's list of friends
+local friendsReducer = Rodux.createReducer({}, {
+	MadeNewFriends = function(state, action)
+		local newState = {}
+
+		-- Since state is read-only, we copy it into newState
+		for index, friend in ipairs(state) do
+			newState[index] = friend
+		end
+
+		for _, friend in ipairs(action.newFriends) do
+			table.insert(newState, friend)
+		end
+
+		return newState
+	end,
+})
+
+local reducer = Rodux.combineReducers({
+	myPhoneNumber = phoneNumberReducer,
+	myFriends = friendsReducer,
+})
+
+local store = Rodux.Store.new(reducer, nil, {
+	Rodux.loggerMiddleware,
+})
+
+store:dispatch(ReceivedNewPhoneNumber("15552345678"))
+store:dispatch(MadeNewFriends({
+	"Cassandra",
+	"Joe",
+}))
+
+--[[
+	Expected output to the developer console:
+
+	Action dispatched: {
+	    phoneNumber = "12345678" (string)
+	    type = "ReceivedNewPhoneNumber" (string)
+	}
+	State changed to: {
+	    myPhoneNumber = "12345678" (string)
+	    myFriends = {
+	    }
+	}
+	Action dispatched: {
+	    newFriends = {
+	        1 = "Cassandra" (string)
+	        2 = "Joe" (string)
+	    }
+	    type = "MadeNewFriends" (string)
+	}
+	State changed to: {
+	    myPhoneNumber = "12345678" (string)
+	    myFriends = {
+	        1 = "Cassandra" (string)
+	        2 = "Joe" (string)
+	    }
+	}
+]]
+```

docs/index.md

@@ -1,4 +1,6 @@
-# Home
-Rodux is a central state management library based on Dan Abramov's [Redux](http://redux.js.org/) library for JavaScript.
+Rodux is a central state management library based on Dan Abramov's [Redux](http://redux.js.org/) library for JavaScript. It exposes a very similar API and implements nearly identical semantics.
 
-This documentation is incomplete!
+This documentation is based on the structure of Redux's documentation, but is a work in progress. Many things from Redux also apply to Rodux, but if you find anything missing or incorrect, [open an issue on GitHub](https://github.com/Roblox/Rodux/issues)!
+
+!!! info
+	This documentation assumes some familiarity with Lua. If you're new to Lua, [*Programming in Lua* by Roberto Ierusalimschy](https://www.lua.org/pil/) is a good introduction, and the first edition (for Lua 5.0) is available online for free.

docs/introduction/actions.md

@@ -0,0 +1,25 @@
+Whenever the `state` in your `store` needs to be updated in response to an event, you `dispatch` an `action` to your `store` with any relevant information required to make said update. An `action` is usually a Lua table with a `type` field. They are usually created via an action creator Lua module like the following:
+
+```lua
+local function ReceivedNewPhoneNumber(phoneNumber)
+	return {
+		type = "ReceivedNewPhoneNumber",
+		phoneNumber = phoneNumber,
+	}
+end
+
+return ReceivedNewPhoneNumber
+```
+
+We can then `dispatch` an `action` to our `store` via [`Store:dispatch`](../api-reference.md#storedispatch) like so:
+
+```lua
+local store = Store.new(function(currentState, action)
+	-- The body of your reducer
+end)
+
+store:dispatch(ReceivedNewPhoneNumber("15552345678"))
+```
+
+!!! info
+	In most cases your `action` will be sent directly to the `reducer` to be processed. However, if you specified any `middleware` when initializing your `store`, your `action` might also be processed by that `middleware`.

docs/introduction/installation.md

@@ -0,0 +1,12 @@
+There are two supported ways to get started with Rodux.
+
+For our examples, we'll install `Rodux` to `ReplicatedStorage`. In practice, it's okay to install Rodux anywhere you want!
+
+### Method 1: Model File (Roblox Studio)
+* Download the `rbxmx` model file attached to the latest release from the [GitHub releases page](https://github.com/Roblox/Rodux/releases).
+* Insert the model into Studio into a place like `ReplicatedStorage`
+
+### Method 2: Filesystem
+* Copy the `lib` directory into your codebase
+* Rename the folder to `Rodux`
+* Use a plugin like [Rojo](https://github.com/LPGhatguy/rojo) to sync the files into a place

docs/introduction/motivation.md

@@ -0,0 +1,12 @@
+As applications become more complex it can be difficult to manage the state of our application in a way that is transparent and compartmentalized. State changes caused by network responses and user input become difficult to follow as our business logic gets spread out between an increasing number of models and views, producing unpredictable and undesirable results. Rodux tries to address this problem by following three core principles.
+
+### Single Source of Truth
+By collecting all of our application's state in a single object, we can quickly inspect the entirety of the data backing our business logic. We will no longer need to track down data models squirrelled away in disparate parts of our code base.
+
+### State is Read-only
+All changes to our single state object are accomplished by dispatching actions to our store, so which part of our code caused what changes to our underlying data will be completely transparent and reproducible. Features that were once difficult like undo/redo become trivial when all changes to our data are controlled via a single, consistent interface.
+
+### Changes Are Made With Pure Functions
+Actions dispatched to our store will be processed by pure functions called reducers. These reducers simply take an action and our store's current state as input and output the store's new state in response to that action. These functions have no side effects and give us a single location to put all of our business logic instead of spreading that business logic out over numerous views and models.
+
+That's all there is to it! The API and tools Rodux provides are relatively simple, but solve many of the most common problems that occur in complex, asynchronous applications by introducing a single paradigm for all of our data management.

docs/introduction/reducers.md

@@ -0,0 +1,86 @@
+When you initialize your `store` with [`Store.new`](../api-reference.md#storenew), you provide a single function called a `reducer` which will consume any `action` dispatched to your `store` and create a new `state` object based on the current `state` of your `store`.
+
+```lua
+local phoneNumberReducer = function(state, action)
+	if action.type == "ReceivedNewPhoneNumber" then
+		return action.phoneNumber
+	end
+
+	return state
+end
+```
+
+Note that `state` is never actually modified by our `reducer`. The `state` of our `store` is *read-only*, so our `reducer` must construct a new `state` object in response to the received `action`.
+
+For complex applications, it is often useful to break down the global `reducer` you provide to the `store` into a set of smaller `reducer` functions, each of which is responsible for a portion of the `state`.
+
+```lua
+local friendsReducer = function(state, action)
+	--[[
+		The state might be nil the first time this reducer is executed.
+		In that case, we need to initialize our state to be the empty table.
+	]]
+	state = state or {}
+
+	if action.type == "MadeNewFriends" then
+		local newState = {}
+
+		-- Since state is read-only, we copy it into newState
+		for index, friend in ipairs(state) do
+			newState[index] = friend
+		end
+
+		for _, friend in ipairs(action.newFriends)
+			table.insert(newState, friend)
+		end
+
+		return newState
+	end
+
+	return state
+end
+
+--[[
+	note that the reducer for our entire application is defined by a table of
+	sub-reducers where each sub-reducer is responsible for one portion of the
+	overall state.
+]]
+local reducer = function(action, state)
+	return {
+		myPhoneNumber = phoneNumberReducer(state.myPhoneNumber, action),
+		myFriends = friendsReducer(state.myFriends, action),
+	}
+end
+```
+
+Alternatively, you can use [`Rodux.createReducer`](../api-reference.md#roduxcreatereducer) and [`Rodux.combineReducers`](../api-reference.md#roduxcombinereducers) to generate the same code as seen above. Using `Rodux.createReducer` and `Rodux.combineReducers` to create your `reducer` functions isn't as verbose and is less prone to developer error.
+
+```lua
+local phoneNumberReducer = Rodux.createReducer(nil, {
+	ReceivedNewPhoneNumber = function(state, action)
+		return action.phoneNumber
+	end,
+})
+
+local friendsReducer = Rodux.createReducer({}, {
+	MadeNewFriends = function(state, action)
+		local newState = {}
+
+		-- Since state is read-only, we copy it into newState
+		for index, friend in ipairs(state) do
+			newState[index] = friend
+		end
+
+		for _, friend in ipairs(action.friends)
+			table.insert(newState, friend)
+		end
+
+		return newState
+	end,
+})
+
+local reducer = Rodux.combineReducers({
+	myPhoneNumber = phoneNumberReducer,
+	myFriends = friendsReducer,
+})
+```