mobx-state-tree
Advanced tools
Opinionated, transactional, MobX powered state container
An introduction to the philosophy can be watched here. Slides. Or, as markdown to read it quickly.
NPM:
npm install mobx-state-tree --save-dev
CDN:
https://unpkg.com/mobx-state-tree/mobx-state-tree.umd.js
mobx-state-tree is a state container that combines the simplicity and ease of mutable data with the traceability of immutable data and the reactiveness and performance of observable data.
It is an opt-in state container that can be used in MobX, but also Redux based applications.
TODO: slides / reactive conf talk
If MobX is like a spreadsheet mechanism for javascript, then mobx-state-tree is like storing your spreadsheet in git.
Unlike MobX itself, mobx-state-tree is quite opinionated on how you structure your data. This makes it possible to solve many problems generically and out of the box, like:
mobx-state-tree tries to take the best features from both object oriented (discoverability, co-location and encapsulation), and immutable based state management approaches (transactionality, sharing functionality through composition).
mobx-state-tree supports JSON patches, replayable actions, listeners for patches, actions and snapshots. References, maps, arrays. Just read on :)Models are at the heart of mobx-state-tree. They simply store your data.
mobx concept of computed values.Example:
import {createFactory, action, mapOf, referenceTo} from "mobx-state-tree"
const Box = createFactory({
// props
name: "",
x: 0,
y: 0,
// computed prop
get width() {
return this.name.length * 15
},
// action
move: action(function(dx, dy) {
this.x += dx
this.y += dy
})
})
const BoxStore = createFactory({
boxes: mapOf(Box),
selection: referenceTo("boxes/name"),
addBox: action(function(name) {
this.boxes.set(name, Box({ name, x: 100, y: 100}))
})
})
const boxStore = BoxStore()
boxStore.addBox("test")
boxStore.boxes.get("test").move(7, 3)
Useful methods:
createFactory(exampleModel): creates a new factoryclone(model): constructs a deep clone of the given model instanceA snapshot is a representation of a model. Snapshots are immutable and use structural sharing (sinces model can contain models, snapshots can contain other snapshots). This means that any mutation of a model results in a new snapshot (using structural sharing) of the entire state tree. This enables compatibility with any library that is based on immutable state trees.
boxStore.boxes.set("test", Box({ name: "test" })) and boxStore.boxes.set("test", { name: "test" }) are both valid.Useful methods:
getSnapshot(model): returns a snapshot representing the current state of the modelonSnapshot(model, callback): creates a listener that fires whenever a new snapshot is available (but only one per MobX transaction).applySnapshot(model, snapshot): updates the state of the model and all its descendants to the state represented by the snapshotActions modify models. Actions are replayable and are therefore constrained in several ways:
A serialized action call looks like:
{
name: "setAge"
path: "/user",
args: [17]
}
Useful methods:
action(fn) constructsonAction(model, middleware) listens to any action that is invoked on the model or any of it's descendants. See onAction for more details.applyAction(model, action) invokes an action on the model according to the given action descriptionModifying a model does not only result in a new snapshot, but also in a stream of JSON-patches describing which modifications are made. Patches have the following signature:
export interface IJsonPatch {
op: "replace" | "add" | "remove"
path: string
value?: any
}
path attribute of a patch considers the relative path of the event from the place where the event listener is attachedUseful methods:
onPatch(model, listener) attaches a patch listener to the provided model, which will be invoked whenever the model or any of it's descendants is mutatedapplyPatch(model, patch) applies a patch to the provided modelThe actual signature of all factory functions is (snapshot, environment) => model.
This makes it possible to associate an environment with a factory created object.
The environment is intended to be an inmutable object context information about the environment, for example which data fetch library should be used etc.
This makes it easy to mock these kind of dependencies, as alternative to requiring singletons that might be needed inside actions.
It is recommended to only provide an environment to the root of your state tree; environments of non-roots might be lost when using functions like applySnapshot, applyPatch, or applyAction.
Useful methods:
getEnvironment(model, key) Returns a value from the environment. Environments are stacked; the resolve the environment value the tree is walked up, until a model provides an environment value for the specified key.
Example:
const Store = createFactory({
users: [],
requestData: action(function() {
const fetchImpl = getEnvironment(this, "fetch")
fetchImpl("http://localhost/users").then(this.receiveData)
}),
receiveData: action(function(users) {
// etc...
})
})
const myStore = Store({ users: []}, { fetch: window.fetch })
See #10
escape slashes and backslashes http://tools.ietf.org/html/rfc6901
Parameters
strunescape slashes and backslashes
Parameters
strParameters
subFactory [ModelFactory] (optional, default primitiveFactory)Parameters
subFactory [ModelFactory] (optional, default primitiveFactory)Registers middleware on a model instance that is invoked whenever one of it's actions is called, or an action on one of it's children. Will only be invoked on 'root' actions, not on actions called from existing actions.
The callback receives two parameter: the action parameter describes the action being invoked. The next() function can be used
to kick off the next middleware in the chain. Not invoking next() prevents the action from actually being executed!
Action calls have the following signature:
export type IActionCall = {
name: string;
path?: string;
args?: any[];
}
Example of a logging middleware:
function logger(action, next) {
console.dir(action)
return next()
}
onAction(myStore, logger)
myStore.user.setAge(17)
// emits:
{
name: "setAge"
path: "/user",
args: [17]
}
Parameters
target Object model to intercept actions oncallbackReturns IDisposer function to remove the middleware
Registers a function that will be invoked for each that as made to the provided model instance, or any of it's children. See 'patches' for more details. onPatch events are emitted immediately and will not await the end of a transaction. Patches can be used to deep observe a model tree.
Parameters
target Object the model instance from which to receive patchescallbackReturns IDisposer function to remove the listener
Registeres a function that is invoked whenever a new snapshot for the given model instance is available. The listener will only be fire at the and a MobX (trans)action
Parameters
target ObjectcallbackReturns IDisposer
Applies a JSON-patch to the given model instance or bails out if the patch couldn't be applied
Parameters
target Objectpatch IJsonPatchApplies a number of JSON patches in a single MobX transaction
Parameters
Dispatches an Action on a model instance. All middlewares will be triggered. Returns the value of the last actoin
Parameters
target Objectaction IActionCalloptions [IActionCallOptions]Applies a series of actions in a single MobX transaction.
Does not return any value
Parameters
Applies a snapshot to a given model instances. Patch and snapshot listeners will be invoked as usual.
Parameters
Calculates a snapshot from the given model instance. The snapshot will always reflect the latest state but use structural sharing where possible. Doesn't require MobX transactions to be completed.
Parameters
target ObjectReturns Any
Given a model instance, returns true if the object has a parent, that is, is part of another object, map or array
Parameters
Returns boolean
TODO:
Given a model instance, returns true if the object has same parent, which is a model object, that is, not an
map or array.
Parameters
target ObjectstrictReturns boolean
Returns the immediate parent of this object, or null. Parent can be either an object, map or array TODO:? strict mode?
Parameters
Returns Any
TODO: Returns the closest parent that is a model instance, but which isn't an array or map.
Parameters
target ObjectReturns Any
Given an object in a model tree, returns the root object of that tree
Parameters
target ObjectReturns Any
Returns the path of the given object in the model tree
Parameters
target ObjectReturns string
Returns the path of the given object as unescaped string array
Parameters
target ObjectReturns true if the given object is the root of a model tree
Parameters
target ObjectReturns boolean
Resolves a path relatively to a given object.
Parameters
Returns Any
Parameters
Returns Any
Parameters
target ObjectkeyReturns Object
Parameters
source TcustomEnvironment [Any]Returns T
Internal function, use with care!
Parameters
thingParameters
thing anyReturns Any
Returnes (escaped) path representation as string
Tries to convert a value to a TreeNode. If possible or already done, the first callback is invoked, otherwise the second. The result of this function is the return value of the callbacks
Parameters
valueasNodeCbasPrimitiveCbShould all state of my app be stored in mobx-state-tree?
No, or, not necessarily. An application can use both state trees and vanilla MobX observables at the same time.
State trees are primarily designed to store your domain data, as this kind of state is often distributed and not very local.
For, for example, local component state, vanilla MobX observables might often be simpler to use.
No constructors?
Neh, replayability. Use utilities instead
No inheritance?
No use composition or unions instead.
Some model constructions which are supported by mobx are not supported by mobx-state-tree
mobx-state-tree does currently not support inheritance / subtyping. This could be changed by popular demand, but not supporting inheritance avoids the need to serialize type information or keeping a (global) type registerySo far this might look a lot like an immutable state tree as found for example in Redux apps, but there are a few differences:
import { resolve } from "mobx-state-tree"
class Message {
@observable _author = "103"
@computed get author() {
return resolve(this, `/users`, this._author)
}
set author(author: User) {
this._author = author ? author.id : null
}
}
FAQs
Opinionated, transactional, MobX powered state container
The npm package mobx-state-tree receives a total of 70,255 weekly downloads. As such, mobx-state-tree popularity was classified as popular.
We found that mobx-state-tree demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 8 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Snyk's use of malicious npm packages for research raises ethical concerns, highlighting risks in public deployment, data exfiltration, and unauthorized testing.
Research
Security News
Socket researchers found several malicious npm packages typosquatting Chalk and Chokidar, targeting Node.js developers with kill switches and data theft.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.