mobx-state-tree

mobx-state-tree (MST) is a state container system built on top of MobX. While MobX acts as a functional reactive state management engine, MST provides structure, common tools, and a type system for your application state.

Key features include:

• Support for multiple stores.
• Support for async actions and side effects.
• Extremely targeted re-renders (especially when used with React).
• Strong TypeScript integration.
• Zero dependencies other than MobX.
• Snapshot-based state management.

It is designed to scale from small applications to large-scale team projects and is often used as a high-performance, lower-boilerplate alternative to Redux.

mobx-state-tree (MST) is a state container that uses a "living tree" model. It combines the benefits of:

• Mutability: Easy to use via actions that modify local instance properties directly.
• Immutability: Automatic generation of structurally shared snapshots for traceability and time-travel.
• Reactiveness: High performance via MobX-based observability.

Key concepts include:

• Models: Composable components that capture pieces of state.
• Snapshots: Immutable representations of the tree's state.
• Actions: The only way to modify the tree, ensuring encapsulated and protected updates.
• Liveness Guarantees: MST prevents stale reads/writes by throwing exceptions if you attempt to access an object that is no longer part of a state tree.

Modifying a model in mobx-state-tree generates a stream of JSON-patches (RFC 6902) that describe the specific modifications made.

Key characteristics:

• Immediate Emission: Patches are emitted immediately upon mutation and do not respect transaction boundaries (unlike snapshots).
• Deep Observing: Patch listeners can be used to achieve deep observing of models.
• Relative Paths: The path attribute in a patch is relative to the location where the listener is attached.
• Granularity: A single mutation (like splicing an array) can result in multiple patches.
• Reversibility: Patches can be reverse-applied, which is useful for implementing undo/redo functionality.

While MST resembles an immutable state tree like Redux, it differs in several key ways:

• Architecture: Like Redux, MST prescribes a specific state architecture.
• Mutation: Unlike Redux, MST allows direct modification of values in the tree within actions; you do not need to construct a new tree manually.
• Observation: MST allows for fine-grained and efficient observation of any point in the state tree.
• Patches: MST automatically generates JSON patches for every modification.
• Interoperability: MST provides utilities to convert any MST tree into a valid Redux store.
• Scalability: You can have multiple MST trees within a single application.

Snapshots are immutable, plain-object serializations of a tree at a specific point in time. They are stripped of type information and actions, making them ideal for transportation (e.g., sending to a server or storing in local storage). Requesting a snapshot is efficient because MST maintains them in the background using structural sharing.

Key properties:

• Immutability: Snapshots cannot be changed.
• Transportability: Suitable for JSON serialization.
• State Restoration: Can be used to update models or restore them to a previous state.
• Automatic Conversion: Snapshots are automatically converted to models when used to populate a tree. For example, store.todos.push({ title: "test" }) is equivalent to store.todos.push(Todo.create({ title: "test" })).

Supported Environments

MobX-State-Tree 4+ runs in any JavaScript environment, including:

• Browsers
• Node.js
• React Native (including Hermes)

Supported Devtools

You can use the following tools for debugging:

• Reactotron
• MobX DevTools
• Redux DevTools (can be connected)

MobX-State-Tree enforces type safety at runtime when creating models. If you attempt to instantiate a model with data that violates its type definitions (e.g., providing a function where a identifierNumber is expected), MST will throw a detailed error identifying the exact path and the nature of the mismatch.

Note: For performance reasons, MST does not run these runtime checks in production mode by default.

When you have circular dependencies between models across different files, you can use types.late to defer the evaluation of the model type. This allows you to import a model that hasn't been fully initialized yet.

To implement this:

1. In the file exporting the model, export a function that returns the model definition.
2. In the file importing the model, wrap the imported model in types.late(() => ImportedModel).

// In the exporting file:
export function LateStore() {
    return types.model({
        title: types.string
    })
}

// In the importing file:
import { LateStore } from "./circular-dep"

const Store = types.late(() => LateStore)

The mst-form-type library allows you to model UI field management (such as Ant Design's Form component status and validation rules) as conventional MobX State Tree type definitions. This enables you to keep form logic inside your MST models instead of manually syncing status changes between a UI component and your state tree.

Note: mst-form-type provides the model types for the form structure; it does not manage the business logic related to field interactions.