8.8 KiB
NodeRedux Module
Redux is a predictable state container for lua apps and NodeMCU.
Influences
NodeRedux evolves the ideas of Redux, which help to maintain state lua base app basically NodeMCU devices.
Basic Example
The whole global state of your app is stored in an object tree inside a single store. The only way to change the state tree is to create an action, an object describing what happened, and dispatch it to the store. To specify how state gets updated in response to an action, you write pure reducer functions that calculate a new state based on the old state and the action.
local redux = require('redux') -- optional line for nodemcu, only need for lua app
-- This is a reducer - a function that takes a current state value and an
-- action object describing "what happened", and returns a new state value.
-- A reducer's function signature is: (state, action) => newState
--
-- The NodeRedux state should contain only plain Lua table.
-- The root state value is usually an table. It's important that you should
-- not mutate the state table, but return a new table if the state changes.
--
-- You can use any conditional logic you want in a reducer. In this example,
-- we use a if statement, but it's not required.
local function counterReducer(state, action)
state = state or { value = 0 }
if action.type == 'counter/incremented' then
return { value = state.value + 2 }
elseif action.type == 'counter/decremented' then
return { value = state.value - 1 }
else
return state
end
end
redux.createStore(counterReducer)
local function console(pState, cState)
print('Previous State: '.. pState.value, 'Current State: '.. cState.value)
end
redux.store.subscribe(console)
redux.store.dispatch({type = 'counter/incremented'})
-- {value = 1}
redux.store.dispatch({type = 'counter/incremented'})
-- {value = 2}
redux.store.dispatch({type = 'counter/decremented'})
-- {value = 1}
Here the example code
Require
local redux = require("node_redux")
redux.createStore()
Creates a Redux store that holds the complete state tree of device. There should only be a single store in your device.
Syntax
redux.createStore(reducer)
Parameters
reducer
(Function): A reducing function that returns the next state tree, given the current state tree, and an action to handle.preloadedState
(any): The initial state. You may optionally specify it to hydrate the state from the server in universal apps, or to restore a previously serialized user session. If you produced reducer with combineReducers, this must be a plain object with the same shape as the keys passed to it. Otherwise, you are free to pass anything that your reducer can understand.enhancer
(Function): The store enhancer. You may optionally specify it to enhance the store with third-party capabilities such as middleware, time travel, persistence, etc. The only store enhancer that ships with Redux is applyMiddleware() TODO: Support added in near next PR
Returns
nil
redux.combineReducers()
As your app grows more complex, you'll want to split your reducing function into separate functions, each managing independent parts of the state. The combineReducers helper function turns an object whose values are different reducing functions into a single reducing function you can pass to createStore.
Syntax
redux.combineReducers({
reducer_one = reducer_1,
reducer_two = reducer_2,
...
})
Parameters
table
(Table of Functions values): A reducing functions that returns the next state tree, given the current state tree, and an action to handle.
Returns
combined_reducer
(Function) A single combined reducer build by combining all reducers
Example
local redux = require('redux') -- optional line for nodemcu, only need for lua app
-- This is a reducer - a function that takes a current state value and an
-- action object describing "what happened", and returns a new state value.
-- A reducer's function signature is: (state, action) => newState
--
-- The NodeRedux state should contain only plain Lua table.
-- The root state value is usually an table. It's important that you should
-- not mutate the state table, but return a new table if the state changes.
--
-- You can use any conditional logic you want in a reducer. In this example,
-- we use a if statement, but it's not required.
local function counterReducer(state, action)
state = state or { value = 0 }
if action.type == 'counter/incremented' then
return { value = state.value + 2 }
elseif action.type == 'counter/decremented' then
return { value = state.value - 1 }
else
return state
end
end
local function inverseCounterReducer(state, action)
state = state or { value = 0 }
if action.type == 'counter/incremented' then
return { value = state.value - 1 }
elseif action.type == 'counter/decremented' then
return { value = state.value + 1 }
else
return state
end
end
local reducer = redux.combineReducers({
counterReducer = counterReducer,
inverseCounterReducer = inverseCounterReducer,
})
redux.createStore(reducer)
local function console(pState, cState)
print('Previous State: counterReducer' ..
pState.counterReducer.value,
'Current State: counterReducer' ..
cState.counterReducer.value
)
print('Previous State: inverseCounterReducer' ..
pState.inverseCounterReducer.value,
'Current State: inverseCounterReducer' ..
cState.inverseCounterReducer.value
)
end
redux.store.subscribe(console)
redux.store.dispatch({type = 'counter/incremented'})
-- {counterReducer = { value = 2 }, inverseCounterReducer = { value = -1 } }
redux.store.dispatch({type = 'counter/incremented'})
-- {counterReducer = { value = 4 }, inverseCounterReducer = { value = -2 } }
redux.store.dispatch({type = 'counter/decremented'})
-- {counterReducer = { value = 3 }, inverseCounterReducer = { value = -1 } }
redux.store.getState()
Returns the current state tree of your application. It is equal to the last value returned by the store's reducer.
Syntax
redux.store.getState()
Parameters
None
Returns
The current state tree of your application.
redux.store.dispatch()
Dispatches an action. This is the only way to trigger a state change.
The store's reducing function will be called with the current getState() result, and the given action synchronously. Its return value will be considered the next state. It will be returned from getState() from now on, and the change listeners will immediately be notified.
Syntax
redux.store.dispatch(action)
Parameters
action
(Table): A plain object describing the change that makes sense for your application. Actions must have a type field that indicates thetype
of action being performed. Types can be defined as constants and imported from another module. It's better to use strings fortype
than Symbols because strings are serializable.
Returns
(Table): The dispatched action
redux.store.subscribe()
Adds a change listener. It will be called any time an action is dispatched, and some
part of the state tree may potentially have changed. You may then use 1st arg
for
previous state and 2nd arg
for current state.
- The listener should only call dispatch() either in response to user actions or under specific conditions (e.g. dispatching an action when the store has a specific field). Calling dispatch() without any conditions is technically possible, however it leads to an infinite loop as every dispatch() call usually triggers the listener again.
Syntax
redux.store.subscribe(listener)
Parameters
listener
(Function): The callback to be invoked any time an action has been dispatched, and the state tree might have changed. You may then use1st arg
for previous state and2nd arg
for current state
Example - listener
local function listener(pState, cState)
print('Previous State: counterReducer' ..
pState.counterReducer.value,
'Current State: counterReducer' ..
cState.counterReducer.value
)
print('Previous State: inverseCounterReducer' ..
pState.inverseCounterReducer.value,
'Current State: inverseCounterReducer' ..
cState.inverseCounterReducer.value
)
end
redux.store.replaceReducer()
It is an advanced API. You might need this if your app implements code splitting, and you want to load some of the reducers dynamically. You might also need this if you implement a hot reloading mechanism for Redux.
Syntax
redux.store.replaceReducer(nextReducer)
Parameters
nextReducer
(Function): The next reducer for the store to use.