react-model ¡
The State management library for React
đ Support Both Class and Hooks Api
âď¸ Support preact, react-native and Next.js
â Full TypeScript Support
đŚ Built with microbundle
âď¸ Middleware Pipline ( redux-devtools support ... )
âď¸ 100% test coverage, safe on production
đ Debug easily on test environment
import { Model } from 'react-model'
const Todo = {
state: {
items: ['Install react-model', 'Read github docs', 'Build App']
},
actions: {
add: todo => {
return state => {
state.items.push(todo)
}
}
}
}
const { useStore } = Model(Todo)
const App = () => {
return <TodoList />
}
const TodoList = () => {
const [state, actions] = useStore()
return <div>
<Addon handler={actions.add} />
{state.items.map((item, index) => (<Todo key={index} item={item} />))}
</div>
}
Recently Updated
Quick Start
CodeSandbox: TodoMVC
Next.js + react-model work around
v2 docs
install package
npm install react-model
Table of Contents
Core Concept
Model
Every model has its own state and actions.
const initialState = {
counter: 0,
light: false,
response: {}
}
interface StateType {
counter: number
light: boolean
response: {
code?: number
message?: string
}
}
interface ActionsParamType {
increment: number
openLight: undefined
get: undefined
}
const model: ModelType<StateType, ActionsParamType> = {
actions: {
increment: async (payload, { state }) => {
return {
counter: state.counter + (payload || 1)
}
},
openLight: async (_, { state, actions }) => {
await actions.increment(1)
await actions.get()
actions.get()
await actions.increment(1)
await actions.increment(1)
await actions.increment(1)
return { light: !state.light }
},
get: async () => {
await new Promise((resolve, reject) =>
setTimeout(() => {
resolve()
}, 3000)
)
return {
response: {
code: 200,
message: `${new Date().toLocaleString()} open light success`
}
}
}
},
state: initialState
}
export default model
⧠back to top
Model Register
react-model keeps the application state and actions in separate private stores. So you need to register them if you want to use them as the public models.
model/index.ts
import { Model } from 'react-model'
import Home from '../model/home'
import Shared from '../model/shared'
const models = { Home, Shared }
export const { getInitialState, useStore, getState, actions, subscribe, unsubscribe } = Model(models)
⧠back to top
useStore
The functional component in React ^16.8.0 can use Hooks to connect the global store.
The actions returned from useStore can invoke dom changes.
The execution of actions returned by useStore will invoke the rerender of current component first.
It's the only difference between the actions returned by useStore and actions now.
import React from 'react'
import { useStore } from '../index'
export default () => {
const [state, actions] = useStore('Home')
const [sharedState, sharedActions] = useStore('Shared')
return (
<div>
Home model value: {JSON.stringify(state)}
Shared model value: {JSON.stringify(sharedState)}
<button onClick={e => actions.increment(33)}>home increment</button>
<button onClick={e => sharedActions.increment(20)}>
shared increment
</button>
<button onClick={e => actions.get()}>fake request</button>
<button onClick={e => actions.openLight()}>fake nested call</button>
</div>
)
}
optional solution on huge dataset (example: TodoList(10000+ Todos)):
- use useStore on the subComponents which need it.
- use useStore selector. (version >= v4.0.0-rc.0)
advance example with 1000 todo items
⧠back to top
getState
Key Point: State variable not updating in useEffect callback
To solve it, we provide a way to get the current state of model: getState
Note: the getState method cannot invoke the dom changes automatically by itself.
Hint: The state returned should only be used as readonly
import { useStore, getState } from '../model/index'
const BasicHook = () => {
const [state, actions] = useStore('Counter')
useEffect(() => {
console.log('some mounted actions from BasicHooks')
return () =>
console.log(
`Basic Hooks unmounted, current Counter state: ${JSON.stringify(
getState('Counter')
)}`
)
}, [])
return (
<>
<div>state: {JSON.stringify(state)}</div>
</>
)
}
⧠back to top
actions
You can call other models' actions with actions api
actions can be used in both class components and functional components.
import { actions } from './index'
const model = {
state: {},
actions: {
crossModelCall: () => {
actions.Shared.changeTheme('dark')
actions.Counter.increment(9)
}
}
}
export default model
⧠back to top
subscribe
subscribe(storeName, actions, callback) run the callback when the specific actions executed.
import { subscribe, unsubscribe } from './index'
const callback = () => {
const user = getState('User')
localStorage.setItem('user_id', user.id)
}
subscribe('User', 'login', callback)
subscribe('User', ['login', 'logout'], callback)
unsubscribe('User', 'login')
⧠back to top
Advance Concept
immutable Actions
The actions use immer produce API to modify the Store. You can return a producer in action.
Using function as return value can make your code cleaner when you modify the deep nested value.
TypeScript Example
const model: ModelType<StateType, ActionsParamType> = {
actions: {
increment: async (params, { state: s }) => {
return state => {
state.counter += params || 1
}
},
decrease: params => s => {
s.counter += params || 1
}
}
}
export default model
JavaScript Example
const Model = {
actions: {
increment: async (params) => {
return state => {
state.counter += params || 1
}
}
}
}
⧠back to top
SSR with Next.js
Store: shared.ts
const initialState = {
counter: 0
}
const model: ModelType<StateType, ActionsParamType> = {
actions: {
increment: (params, { state }) => {
return {
counter: state.counter + (params || 1)
}
}
},
asyncState: async context => {
await waitFor(4000)
return { counter: 500 }
},
state: initialState
}
export default model
Global Config: _app.tsx
import { models, getInitialState, Models } from '../model/index'
let persistModel: any
interface ModelsProps {
initialModels: Models
persistModel: Models
}
const MyApp = (props: ModelsProps) => {
if ((process as any).browser) {
persistModel = props.persistModel || Model(models, props.initialModels)
}
const { Component, pageProps, router } = props
return (
<Container>
<Component {...pageProps} />
</Container>
)
}
MyApp.getInitialProps = async (context: NextAppContext) => {
if (!(process as any).browser) {
const initialModels = context.Component.getInitialProps
? await context.Component.getInitialProps(context.ctx)
await getInitialState(undefined, { isServer: true })
return { initialModels }
} else {
return { persistModel }
}
}
Page: hooks/index.tsx
import { useStore, getState } from '../index'
export default () => {
const [state, actions] = useStore('Home')
const [sharedState, sharedActions] = useStore('Shared')
return (
<div>
Home model value: {JSON.stringify(state)}
Shared model value: {JSON.stringify(sharedState)}
<button
onClick={e => {
actions.increment(33)
}}
>
</div>
)
}
Single Page Config: benchmark.tsx
Benchmark.getInitialProps = async () => {
return await getInitialState({ modelName: 'Todo' }, { isServer: true })
}
⧠back to top
Middleware
We always want to try catch all the actions, add common request params, connect Redux devtools and so on. We Provide the middleware pattern for developer to register their own Middleware to satisfy the specific requirement.
const tryCatch: Middleware<{}> = async (context, restMiddlewares) => {
const { next } = context
await next(restMiddlewares).catch((e: any) => console.log(e))
}
let actionMiddlewares = [
tryCatch,
getNewState,
setNewState,
stateUpdater,
communicator,
devToolsListener
]
const consumerAction = (action: Action) => async (params: any) => {
const context: Context = {
modelName,
setState,
actionName: action.name,
next: () => {},
newState: null,
params,
consumerActions,
action
}
await applyMiddlewares(actionMiddlewares, context)
}
export { ... , actionMiddlewares}
âď¸ You can override the actionMiddlewares and insert your middleware to specific position
⧠back to top
Expand Context
const ExtCounter: ModelType<
{ name: string },
{ ext: undefined },
{ name: string }
> = {
actions: {
ext: (_, { name }) => {
return { name }
}
},
state: { name: '' }
}
const { useStore } = Model(ExtCounter, { name: 'test' })
const [state, actions] = useStore()
actions.ext()
⧠back to top
Other Concept required by Class Component
Provider
The global state standalone can not effect the react class components, we need to provide the state to react root component.
import { PureComponent } from 'react'
import { Provider } from 'react-model'
class App extends PureComponent {
render() {
return (
<Provider>
<Counter />
</Provider>
)
}
}
⧠back to top
connect
We can use the Provider state with connect.
Javascript decorator version
import React, { PureComponent } from 'react'
import { Provider, connect } from 'react-model'
const mapProps = ({ light, counter }) => ({
lightStatus: light ? 'open' : 'close',
counter
})
@connect(
'Home',
mapProps
)
export default class JSCounter extends PureComponent {
render() {
const { state, actions } = this.props
return (
<>
<div>states - {JSON.stringify(state)}</div>
<button onClick={e => actions.increment(5)}>increment</button>
<button onClick={e => actions.openLight()}>Light Switch</button>
</>
)
}
}
TypeScript Version
import React, { PureComponent } from 'react'
import { Provider, connect } from 'react-model'
import { StateType, ActionType } from '../model/home'
const mapProps = ({ light, counter, response }: StateType) => ({
lightStatus: light ? 'open' : 'close',
counter,
response
})
type RType = ReturnType<typeof mapProps>
class TSCounter extends PureComponent<
{ state: RType } & { actions: ActionType }
> {
render() {
const { state, actions } = this.props
return (
<>
<div>TS Counter</div>
<div>states - {JSON.stringify(state)}</div>
<button onClick={e => actions.increment(3)}>increment</button>
<button onClick={e => actions.openLight()}>Light Switch</button>
<button onClick={e => actions.get()}>Get Response</button>
<div>message: {JSON.stringify(state.response)}</div>
</>
)
}
}
export default connect(
'Home',
mapProps
)(TSCounter)
⧠back to top
FAQ
Migrate from 3.1.x to 4.x.x
- remove Model wrapper
sub-model.ts
export default Model(model)
export default model
models.ts
import Sub from './sub-model'
export default Model({ Sub })
- use selector to replace depActions
Shared.ts
interface State {
counter: number
enable: boolean
}
interface ActionParams {
add: number
switch: undefined
}
const model: ModelType<State, ActionParams> = {
state: {
counter: 1
enable: false
},
actions: {
add: (payload) => state => {
state.counter += payload
},
switch: () => state => {
state.enable = !state.enable
}
}
}
const Component = () => {
const [counter] = useStore('Shared', ['add'])
const [counter] = useStore('Shared', state => state.counter)
}
How can I disable the console debugger
import { middlewares } from 'react-model'
middlewares.config.logger.enable = false
middlewares.config.logger.enable = ({ actionName }) => ['increment'].indexOf(actionName) !== -1
⧠back to top
How can I add custom middleware
import { actionMiddlewares, middlewares, Model } from 'react-model'
import { sendLog } from 'utils/log'
import Home from '../model/home'
import Shared from '../model/shared'
const ErrorHandler: Middleware = async (context, restMiddlewares) => {
const { next } = context
await next(restMiddlewares).catch((e: Error) => sendLog(e))
}
const getNewStateMiddlewareIndex = actionMiddlewares.indexOf(
middlewares.getNewState
)
actionMiddlewares.splice(getNewStateMiddlewareIndex, 0, ErrorHandler)
const stores = { Home, Shared }
export default Model(stores)
⧠back to top
How can I make persist models
import { actionMiddlewares, Model } from 'react-model'
import Example from 'models/example'
const persistMiddleware: Middleware = async (context, restMiddlewares) => {
localStorage.setItem('__REACT_MODEL__', JSON.stringify(context.Global.State))
await context.next(restMiddlewares)
}
actionMiddlewares.push(persistMiddleware)
Model({ Example }, JSON.parse(localStorage.getItem('__REACT_MODEL__')))
const model = {
state: JSON.parse(localStorage.getItem('__REACT_MODEL__'))['you model name']
actions: { ... },
middlewares: [...actionMiddlewares, persistMiddleware]
}
⧠back to top
How can I deal with local state
What should I do to make every Counter hold there own model? đ¤
class App extends Component {
render() {
return (
<div className="App">
<Counter />
<Counter />
<Counter />
</div>
)
}
}
Counter model
interface State {
count: number
}
interface ActionParams {
increment: number
}
const model: ModelType<State, ActionParams> = {
state: {
count: 0
},
actions: {
increment: payload => {
return state => {
state.count += payload
}
}
}
}
Counter.tsx
const Counter = () => {
const [{ useStore }] = useState(() => Model(model))
const [state, actions] = useStore()
return (
<div>
<div>{state.count}</div>
<button onClick={() => actions.increment(3)}>Increment</button>
</div>
)
}
export default Counter
⧠back to top
How can I deal with huge dataset / circular dataset
Immer assumes your state to be a unidirectional tree. That is, no object should appear twice in the tree, there should be no circular references.
Immer freezes everything recursively, for large data objects that won't be changed in the future this might be over-kill, in that case it can be more efficient to shallowly pre-freeze data using the freeze utility.
import { freeze } from 'immer'
export const ExpensiveModel: ModelType<ExpensiveState, ExpensiveActionParams> = {
state: {
moduleList: []
},
actions: {
setPreFreezedDataset: () => {
const optimizedDataset = freeze(hugeDataset)
return { moduleList: optimizedDataset }
}
}
}
actions throw error from immer.module.js
immer.module.js:972 Uncaught (in promise) Error: An immer producer returned a new value *and* modified its draft. Either return a new value *or* modify the draft
How to fix:
actions: {
increment: payload => {
return state => {
state.count += payload
}
}
}
⧠back to top
How can I customize each model's middlewares?
You can customize each model's middlewares.
import { actionMiddlewares, Model } from 'react-model'
const delayMiddleware: Middleware = async (context, restMiddlewares) => {
await timeout(1000, {})
context.next(restMiddlewares)
}
const nextCounterModel: ModelType<CounterState, NextCounterActionParams> = {
actions: {
add: num => {
return state => {
state.count += num
}
},
increment: async (num, { actions }) => {
actions.add(num)
await timeout(300, {})
}
},
middlewares: [delayMiddleware, ...actionMiddlewares],
state: {
count: 0
}
}
export default Model(nextCounterModel)
⧠back to top