nodemcu-firmware/docs/lua-modules/node_redux.md

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 the type of action being performed. Types can be defined as constants and imported from another module. It's better to use strings for type 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 use 1st arg for previous state and 2nd 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.