Restate

Restate is a predictable, easy to use, easy to integrate, typesafe state container for React.

Restate follows the three principles of Redux:

• Single source of truth
• State is read only
• Changes are pure, but made in a convenient way using immer.js

Futhermore, Restate

• provides a nice React-Hook based API to read and update the state
• is using Typescript to make your application more robust and your development experience more enjoyable
• provide means to develop asynchronous state changes without the drama
• makes it easy integrate other components (server, logger, database, router,...) as the state is reactive.
• dev-tools
• easy to learn and easy to test

What it looks like...

1const store = createStore({
2  state: {
3    name: "John Snow",
4    age: 32
5  }
6})
7
8const AppStoreProvider = createProvider(store);
9const useAppState = createStateHook(AppStoreProvider);
10const useNextAppState = createNextHook(AppStoreProvider);
11
12const Name = () => {
13  const name = useAppState(state => state.user.name)
14  const next = useNextAppState(state => state.user)
15
16  function setName(nextName:string) {
17    next(user => user.name = nextName)
18  }
19
20  return <input value={name} onChange={e => setName(e.target.value)} />
21}

Even the code above looks like JS, it is indeed Typescript. Go on StackBlitz and make some changes to the state, for example change the property user.name to user.firstName. You will see how Typescript is able to pick up those changes and gives you nice error messages.

Documentation

The documentation is also available on Netlify:https://restate.netlify.com/.

Installation

With NPM:

1npm install @restate/core --save

or with YARN:

1yarn add @restate/core

Store

To get started, you need to create a store:

1import { createStore } from "@restate/core"
2
3const store = createStore({
4  state: {
5    name: "John Snow",
6    age: 32
7  }
8})

Try on StackBlitz!

Provider

To connect our store to the React component tree we need a Provider:

1import { createProvider } from "@restate/core"
2
3const AppStoreProvider = createProvider(store) // to provide the store to react
4
5const App: React.FC = () => (
6  <AppStoreProvider.Provider value={store}>
7    <Hello />
8    <Age />
9    <NameForm />
10  </AppStoreProvider.Provider>
11)

Try on StackBlitz!

You can use multiple stores as well.

Read from the state

To read from the state Restate provides you AppStateHooks.

AppStateHooks hooks are use to

• select properties from your state
• do some basic computations / transformations

1const store = createStore({
2  state: {
3    user: { name: "John Doe", age: 32 },
4    todos: 0
5  }
6})
7
8const AppStoreProvider = createProvider(store)
9
10// create a `scoped state hook` (we select the `user` object)
11const useUserState = createStateHook(AppStoreProvider, state => state.user)
12
13const Hello = () => {
14  // select a property from the state
15  const name = useUserState(user => user.name)
16  // do some basic views/computations/transformations
17  const days = useUserState(user => user.age * 365)
18
19  return (
20    <h1>
21      Hello {name}, you are {days} days old
22    </h1>
23  )
24}

Try on StackBlitz!

Change the state - using hooks

To change the state, we use a Next-Hook.

1import { createNextHook } from "@restate/core"
2
3// create a next-hook
4const useNextAppState = createNextHook(AppStoreProvider)

The useNextAppState hook takes a selector function to scope the access to our state. In this example the scope is the user object.

The useNextAppState returns a customnext function, which can be use to change the user object:

1const NameForm = () => {
2  const name = useAppState(state => state.user.name)
3
4  // Creates a `next` function to change the user
5  const next = useNextAppState(state => state.user)
6
7  function setName(nextName: string) {
8    // The next function provides the current user object as parameter, which we can modify.
9    next(user => (user.name = nextName))
10  }
11
12  return <input value={name} onChange={e => setName(e.target.value)} />
13}

Try on StackBlitz!

Change the state - using actions

Another way to modify your state are Actions.

Actions are forged in an ActionFactory. The ActionFactory is a function that receives - among other things - the next() function to update the store.

An ActionFactory returns a object that holds the all the actions to change the state. Think about actions as "member functions" of your state.

Actions can be asynchronous.

1// Action factory
2const userActionsFactory = ({ next }: ActionFactoryProps<User>) => ({
3  incrementAge() {
4    next(user => user.age++)
5  },
6  decrementAge() {
7    next(user => user.age--)
8  },
9  async fetchData(userId: string) {
10    const data = await serverFetchUserData(userId)
11    next(user => (user.data = data))
12  }
13})

The ActionFactory is hooked into React using the createActionsHook:

1const useUserActions = createActionsHook(
2  AppStoreProvider,
3  state => state.user,
4  userActionsFactory
5)
6
7const Age = () => {
8  const userActions = useUserActions()
9  return (
10    <div>
11      <button onClick={userActions.incrementAge}>+</button>
12      <button onClick={userActions.decrementAge}>-</button>
13    </div>
14  )
15}

Try on StackBlitz

Change the state - using store.next()

Outside of your component tree you can change the store like this:

1store.next(state => {
2  state.user.name = "John"
3})

Middleware

Middleware are small synchronous functions which intercept state updates. Middleware functions receiving the currentState as well as the nextState. They can change the nextState, if required. If a middleware throws an exception, the state update will be canceled.

Take the ageValidator middleware for example. It ensures, that the user.age property never gets negative.

1// Ensures the age will never be < 0
2const ageValidator: Middleware<State> = ({ nextState, currentState }) => {
3  nextState.age =
4    nextState.user.age < 0 ? currentState.user.age : nextState.user.age
5}
6
7const store = createStore({
8  state: {
9    name: "John Snow",
10    age: 32
11  },
12  middleware: [ageValidator]
13})
14
15store.next(s => (s.user.age = -1)) // will be intercepted by the ageValidator middleware.

Try on StackBlitz

Connectors

Connectors "glue" your store to other parts of the application, for example to your server, database, ...

Connectors can

• observer the state and react to state changes using the store.state$ observable
• change the state using the store.next() function
• listen to events dispatched on the state.messageBus$ observable. The messages are similar to redux actions.

Observe store.state$

Here is an very simple logger example, that observes the state and logs all state changes:

1function connectLogger(store: RxStore<any>) {
2  store.state$.subscribe(nextState => {
3    console.log("STATE:", JSON.stringify(nextState.payload))
4  })
5}
6
7connectLogger(store)

Try on StackBlitz

Change the state with store.next()

Another example of a connector could be a socket.io adapter, that receives chat messages from a server and adds them to the application state:

1function connectSocket(store: RxStore<any>) {
2  socket.on("chat message", msg => {
3    store.next(state => {
4      state.messages.push(msg)
5    })
6  })
7}
8
9connectSocket(store)

Listen to events

Connectors can also receive messages from the application - redux style.

Here is a simple UNDO example. The connector records the history of the app state using the store.state$ observable. The connector also listens to the UNDO events by subscribing the store.messageBus$. If it receives the UNDO event, it rewinds the state history by one step.

1  const history = []
2
3  // record state history
4  store.state$.subscribe(nextState => {
5    history.push(nextState);
6  })
7
8  // listen to UNDO events
9  store.messageBus$.subscribe( msg => {
10    if(msg.type === 'UNDO' && history.length > 1) {
11      history.pop()  // remove current state
12      const prevState = history.pop();
13      store.next(prevState);
14    }
15  })
16}
17
18connectUndo(store);

The application uses createDispatchHook to create a dispatch hook. With the dispatch hook, a component can dispatch an UNDO event, like so:

1const useDispatch = createDispatchHook(AppStoreProvider)
2
3function useUndo() {
4  const dispatch = useDispatch()
5  return () => dispatch({ type: "UNDO" })
6}
7
8const UndoButton = () => {
9  const undo = useUndo()
10  return <button onClick={undo}>UNDO</button>
11}

Try the UNDO example on StackBlitz!

DevTools

restate uses the excellent ReduxDevTools to provide power-ups for your development workflow.

Installation

Go and get the ReduxDevTools for your browser:

• Google Chrome
• Firefox

Then install the @restate/dev-tools

1yarn add @restate/dev-tools

Usage

1import { connectDevTools } from "@restate/dev-tools"
2
3const store = createStore({
4  state: {
5    name: "John Snow",
6    age: 32
7  },
8  options: {
9    storeName: "MY APP STORE" // <-- will show up in the instance selector
10  }
11})
12
13connectDevTools(store)

License

MIT