The next generation state management library for React

Related tags

react-model
Overview

react-model Β· GitHub license npm version minified size Build Status size downloads Coverage Status Greenkeeper badge PRs Welcome

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'

// define model
const Todo = {
  state: {
    items: ['Install react-model', 'Read github docs', 'Build App']
  },
  actions: {
    add: todo => {
      // s is the readonly version of state
      // you can also return partial state here but don't need to keep immutable manually
      // state is the mutable state
      return state => {
        state.items.push(todo)
      }
    }
  }
}

// Model Register
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
} // You only need to tag the type of params here !

const model: ModelType<StateType, ActionsParamType> = {
  actions: {
    increment: async (payload, { state }) => {
      return {
        counter: state.counter + (payload || 1)
      }
    },
    openLight: async (_, { state, actions }) => {
      await actions.increment(1) // You can use other actions within the model
      await actions.get() // support async functions (block actions)
      actions.get()
      await actions.increment(1) // + 1
      await actions.increment(1) // + 2
      await actions.increment(1) // + 3 as expected !
      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

// You can use these types when use Class Components.
// type ConsumerActionsType = getConsumerActionsType
// type ConsumerType = { actions: ConsumerActionsType; state: StateType }
// type ActionType = ConsumerActionsType
// export { ConsumerType, StateType, ActionType }

⇧ 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'

// CSR
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)):

  1. use useStore on the subComponents which need it.
  2. 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 action
subscribe('User', 'login', callback)
// subscribe actions
subscribe('User', ['login', 'logout'], callback)
// unsubscribe the observer of some actions
unsubscribe('User', 'login') // only logout will run callback now

⇧ 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

// StateType and ActionsParamType definition
// ...

const model: ModelType<StateType, ActionsParamType> = {
  actions: {
    increment: async (params, { state: s }) => {
      // return (state: typeof s) => { // TypeScript < 3.9
      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)
      }
    }
  },
  // Provide for SSR
  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) {
    // First come in: initialModels
    // After that: persistModel
    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 }) // get all model initialState
      // : await getInitialState({ modelName: 'Home' }, { isServer: true }) // get Home initialState only
      // : await getInitialState({ modelName: ['Home', 'Todo'] }, { isServer: true }) // get multi initialState
      // : await getInitialState({ data }, { isServer: true }) // You can also pass some public data as asyncData params.
    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.

// Under the hood
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
]

// ...
// How we execute an action
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 }, // State Type
  { ext: undefined }, // ActionParamsType
  { name: string } // ExtContextType
> = {
  actions: {
    // { state, action } => { state, action, [name] }
    ext: (_, { name }) => {
      return { name }
    }
  },
  state: { name: '' }
}

const { useStore } = Model(ExtCounter, { name: 'test' })
// state.name = ''
const [state, actions] = useStore()
// ...
actions.ext()
// state.name => 'test'

⇧ 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
}) // You can map the props in connect.

@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

  1. remove Model wrapper

sub-model.ts

// 3.1.x
export default Model(model)
// 4.x.x
export default model

models.ts

import Sub from './sub-model'
export default Model({ Sub })
  1. 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 = () => {
  // 3.1.x, Component rerender when add action is invoked
  const [counter] = useStore('Shared', ['add'])
  // 4.x.x, Component rerender when counter value diff
  const [counter] = useStore('Shared', state => state.counter)
}

How can I disable the console debugger

import { middlewares } from 'react-model'
// Find the index of middleware

// Disable all actions' log
middlewares.config.logger.enable = false
// Disable logs from specific type of actions
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'

// custom middleware
const ErrorHandler: Middleware = async (context, restMiddlewares) => {
  const { next } = context
  await next(restMiddlewares).catch((e: Error) => sendLog(e))
}

// Find the index of middleware
const getNewStateMiddlewareIndex = actionMiddlewares.indexOf(
  middlewares.getNewState
)

// Replace it
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'

// Example, not recommend to use on production directly without consideration
// Write current State to localStorage after action finish
const persistMiddleware: Middleware = async (context, restMiddlewares) => {
  localStorage.setItem('__REACT_MODEL__', JSON.stringify(context.Global.State))
  await context.next(restMiddlewares)
}

// Use on all models
actionMiddlewares.push(persistMiddleware)
Model({ Example }, JSON.parse(localStorage.getItem('__REACT_MODEL__')))

// Use on single 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 => {
      // 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
      // Not allowed
      // return state => (state.count += 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

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 => {
    // Not allowed
    // return state => (state.count += 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, {})
    }
  },
  // You can define the custom middlewares here
  middlewares: [delayMiddleware, ...actionMiddlewares],
  state: {
    count: 0
  }
}

export default Model(nextCounterModel)

⇧ back to top

Issues
  • Fixed language in README.md

    Fixed language in README.md

    Fixed some basic language in the README.md to make the project more appealing for foreign devs that use this great library!

    opened by cf 1
Owner
Bytedance Inc.
Bytedance Inc.
redis like key-value state management solution for React

jedisdb redis like key-value state management solution for React Reactive. Redux alternative. Simple and powerful global state management system, acce

Hassan 10 Oct 16, 2021
React-Godfather aims to explore an alternative mental model for function components.

React-Godfather "Look ma, no Hooks!" React-Godfather aims to explore an alternative mental model for function components. It adds a thin layer between

John Kapolos 17 Sep 20, 2021
🌊🐷 Utility for generalized composition of React components

???? Utility for generalized composition of React components

Enki 279 Oct 4, 2021
Declarative hotkey and focus area management for React

React HotKeys A declarative library for handling hotkeys and focus areas in React applications. Upgrading from 1.*.* ? See the upgrade notes. Looking

Aleck Greenham 1.9k Oct 3, 2021
HTML to React parser that works on both the server (Node.js) and the client (browser):

HTML to React parser that works on both the server (Node.js) and the client (browser):

Mark 1k Oct 19, 2021
A toy virtual DOM diffing and reconciliation algorithm, with a simple event loop

A toy virtual DOM diffing and reconciliation algorithm, with a simple event loop

Mauro Cano 1 Oct 9, 2021
πŸ“ A resizable component for React.

?? A resizable component for React.

bokuweb 1.5k Oct 17, 2021
Collection of Google fonts as typeface data for usage with three.js, react-three-fiber, and other tools.

Collection of Google fonts as typeface data for usage with three.js, react-three-fiber, and other tools.

Components AI 44 Oct 3, 2021
A component for React that utilizes the Counterpart module to provide multi-lingual/localized text content.

React Translate Component Translate is a component for React that utilizes the Counterpart module and the Interpolate component to provide multi-lingu

Martin Andert 325 Apr 14, 2021
CSS media queries for React

react-media react-media is a CSS media query component for React. A <Media> component listens for matches to a CSS media query and renders stuff based

React Training 2.4k Oct 15, 2021
πŸ€– React Native Android widgets bridged to JS, a proof of concept

React Native Android Widget Proof Of Concept ?? Using React Native and having Android widgets is possible. Create buttons in Java / Android XML to tri

Netbeast 186 Sep 21, 2021
πŸ”Œ "Plug and play" for RxJS Observables in React Apps!

"Plug and play" for RxJS Observables in React Apps! npm install @ngneat/react-rxjs useObservable Ever had an Observable holding data that you need to

ngneat 12 Oct 11, 2021
Utility Components for determining whether elements are in the center of the screen.

@n1ru4l/react-in-center-of-screen Utility Components for determining whether elements are in the center of the screen. Codesandbox Quick Demo: https:/

Laurin Quast 12 May 29, 2021
iOS Today Widget in React Native

React Native Today Widget Experimental library investigating limits of implementation iOS App Extensions using React Native. Sample result from Comple

MatΔ›j KΕ™Γ­ΕΎ 343 Oct 3, 2021
A modern importer written in React

A modern importer written in React

Chris Zhu 31 Oct 8, 2021
A ReactJS password recovery box component built using the FluentUI library

A ReactJS password recovery box component built using the FluentUI library

Boia Alexandru 2 Sep 20, 2021
A lightweight react library that converts raw HTML to a React DOM structure.

A lightweight react library that converts raw HTML to a React DOM structure.

Arve Knudsen 652 Oct 17, 2021
React-Native library for the WidgetKit framework. Integrate a Widget into your App πŸπŸ“±

react-native-widgetkit React-Native Library for the iOS ?? WidgetKit framework Table of Contents ?? Introduction ??‍?? Installation ??‍ Usage ????‍??

Fasky 82 Oct 13, 2021
A Fetch Library Support React New Suspense SSR

use-suspense-fetch A data fetching library for React Suspense. inspired by use-asset Feature use LRU Cache support create custom cache support React 1

Snake 6 Jul 12, 2021