mobx-state-class
mobx-state-class is a state management lib built on top of the awesome MobX lib, heavily inspired by mobx-state-tree project.
Introduction
mobx-state-class (abbr. MSC) is just a syntax sugar layer to the original MobX APIs. Thus familiarity with MobX is a prerequisite.
MSC is built around MobX's class decorators. By extending MSC's ReactiveNode
base class, it automatically applies @observable
to all class properties, @computed
to all getters, and @action
to all methods.
This effectively frees you from the worry of forgetting to apply the correct decorator from time to time, which is a typical gotcha when working with MobX. Such approach lets you focus more on your own business logics, and your code also looks cleaner without all those annotations.
By design MSC embraces a convention-over-configuration approach. It offers no way to configure at all. Anytime you feel you need some fine grain controls, just turn back to original MobX APIs. Remember, MSC is just syntax sugar.
Requirement
MSC is implemented with ES7 Proxy, and is compatible with MobX v5+ only, you need to ensure MobX exists in your project as peer dependency.
Usage
Basic Usage
MSC assumes you write your state tree node with ES6 class syntax. It provides a ReactiveNode
base class for you to extend. You just need to extend ReactiveNode
, forget about MobX and write your code like normal js.
{ const todos = initialState; super; thistodos = todos; } { return thistodos; } { thistodos; } async { thistodos = await api; }
Above code is (almost) equivalent to below.
@observable todos; { const todos = initialState; thistodos = todos; } @computed { return thistodos; } @actionbound { thistodos; } fetch: mobx
As seen in example, class methods are automatically converted to bound actions, and async function is also taken cared (this trick actually involves hacking Promise.prototype.then
, it's not clean, but worth it).
All conversions happen in runtime, no transpiler required.
Tree Node Properties
MSC borrows the concept of "tree" from mobx-state-tree project. It provides a set of lightweight APIs to help you work with tree relationship.
ReactiveNode
class implements 4 hidden properties (actually they are getters):
.parent
.path
.root
.isRoot
Tree node object's class definition typically locates in seperate files. These properties help you access other related node from within one node without the need to import that file.
If you organize your state tree node in a single-state-tree fashion, then you can easily get the global app state by accessing .root
.
Example:
// app-state.js; { super; thistodos = ; } { console; // "true" } { console; // "" } { console; // will log "null" } { console; // will log appState itself }
// todo.js { console; // "false" } { console; // "todos/0" } { console; // will log appState.todos } { console; // will log appState }
Array and Map
Like MobX, MSC provides support to array and map. Anytime an array or a map gets attached to a ReactiveNode as class member, it'll be injected with all 4 tree node properties (.parent
, .path
, .root
, .isRoot
). It'll also receive an interceptor that handles updating tree relationships and other weight lifting like runtime conversion. Apart from these, they're basically plain MobX Observable Array/Map.
arrayOf()
and mapOf()
are exposed to help you create typed array/map. Example:
{ super; thisnamedTodoLists = ; } const myTodoApp = // This config the map interceptor so that when you invoke:myTodoAppnamedTodoLists // it'll be to to myTodoAppnamedTodoLists
React Binding
There exists an official mobx-react
binding lib. MSC provide a connect()
function on top of that and follow the single state tree philosophy of Redux. See usage example:
import Provider from 'mobx-react'import connect IMobxStateClassConfigs from 'mobx-state-class'import App from './MyApp'import AppState from './AppState' const appState = const ConnectedApp = App; // "state" is the required prop key here.const AppWithStateProvider = <Provider => <ConnectedApp /> </Provider>;
If you use typescript, you can also inject your app state type info:
// if you use typescript, you candeclare ;