This reference guide lists all methods exposed by MST. Contributions like linguistic improvements, adding more details to the descriptions or additional examples are highly appreciated! Please note that the docs are generated from source. Most methods are declared in the mst-operations.ts file.
- addDisposer
- addMiddleware
- applyAction
- applyPatch
- applySnapshot
- asReduxStore
- clone
- ComplexType
- ComplexType
- ComplexType
- ComplexType
- ComplexType
- connectReduxDevtools
- destroy
- detach
- escapeJsonPath
- getChildType
- getEnv
- getParent
- getPath
- getPathParts
- getRelativePath
- getRoot
- getSnapshot
- getType
- hasParent
- Identifier
- IdentifierCache
- isAlive
- isProtected
- isRoot
- isStateTreeNode
- Node
- onAction
- onPatch
- onSnapshot
- process
- protect
- recordActions
- recordPatches
- resolveIdentifier
- resolvePath
- revertPatch
- StoredReference
- tryResolve
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- Type
- types.array
- types.boolean
- types.compose
- types.Date
- types.enumeration
- types.frozen
- types.identifier
- types.late
- types.literal
- types.map
- types.maybe
- types.model
- types.null
- types.number
- types.optional
- types.reference
- types.refinement
- types.string
- types.undefined
- types.union
- unescapeJsonPath
- unprotect
- walk
Use this utility to register a function that should be called whenever the
targeted state tree node is destroyed. This is a useful alternative to managing
cleanup methods yourself using the beforeDestroy hook.
Parameters
targetIStateTreeNodedisposer
Examples
```javascript
const Todo = types.model({
title: types.string
}, {
afterCreate() {
const autoSaveDisposer = reaction(
() => getSnapshot(this),
snapshot => sendSnapshotToServerSomehow(snapshot)
)
// stop sending updates to server if this
// instance is destroyed
addDisposer(this, autoSaveDisposer)
}
})
```Middleware can be used to intercept any action is invoked on the subtree where it is attached. If a tree is protected (by default), this means that any mutation of the tree will pass through your middleware.
For more details, see the middleware docs
Parameters
targetIStateTreeNodemiddleware
Returns IDisposer
Applies an action or a series of actions in a single MobX transaction.
Does not return any value
Takes an action description as produced by the onAction middleware.
Parameters
Applies a JSON-patch to the given model instance or bails out if the patch couldn't be applied See patches for more details.
Can apply a single past, or an array of patches.
Parameters
targetObjectpatchIJsonPatch
Applies a snapshot to a given model instances. Patch and snapshot listeners will be invoked as usual.
Parameters
Creates a tiny proxy around a MST tree that conforms to the redux store api. This makes it possible to use MST inside a redux application.
See the redux-todomvc example for more details.
Parameters
modelanymiddlewares...Array<MiddleWare>
Returns IReduxStore
Returns a deep copy of the given state tree node as new tree.
Short hand for snapshot(x) = getType(x).create(getSnapshot(x))
Tip: clone will create a literal copy, including the same identifiers. To modify identifiers etc during cloning, don't use clone but take a snapshot of the tree, modify it, and create new instance
Parameters
sourceTkeepEnvironment(boolean | any) indicates whether the clone should inherit the same environment (true, the default), or not have an environment (false). If an object is passed in as second argument, that will act as the environment for the cloned tree.
Returns T
Connects a MST tree to the Redux devtools. See this example for a setup example.
Parameters
remoteDevDepanymodelany
Removes a model element from the state tree, and mark it as end-of-life; the element should not be used anymore
Parameters
thing
Removes a model element from the state tree, and let it live on as a new state tree
Parameters
thing
escape slashes and backslashes http://tools.ietf.org/html/rfc6901
Parameters
str
Returns the declared type of the given sub property of an object, array or map.
Parameters
objectIStateTreeNodechildstring
Examples
```typescript
const Box = types.model({ x: 0, y: 0 })
const box = Box.create()
console.log(getChildType(box, "x").name) // 'number'
```Returns IType<any, any>
Returns the environment of the current state tree. For more info on environments, see Dependency injection
Parameters
thingIStateTreeNode
Returns any
Returns the immediate parent of this object, or null.
Note that the immediate parent can be either an object, map or array, and doesn't necessarily refer to the parent model
Parameters
Returns any
Returns the path of the given object in the model tree
Parameters
targetObject
Returns string
Returns the path of the given object as unescaped string array
Parameters
targetObject
Given two state tree nodes that are part of the same tree, returns the shortest jsonpath needed to navigate from the one to the other
Parameters
baseIStateTreeNodetargetIStateTreeNode
Returns string
Given an object in a model tree, returns the root object of that tree
Parameters
targetObject
Returns any
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
targetObject
Returns any
Returns the actual type of the given tree node. (Or throws)
Parameters
objectIStateTreeNode
Returns IType<S, T>
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
Returns true if the given state tree node is not killed yet.
This means that the node is still a part of a tree, and that destroy
has not been called. If a node is not alive anymore, the only thing one can do with it
is requesting it's last path and snapshot
Parameters
thingIStateTreeNode
Returns boolean
Returns true if the object is in protected mode, @see protect
Parameters
target
Returns true if the given object is the root of a model tree
Parameters
targetObject
Returns boolean
Returns true if the given value is a node in a state tree.
More precisely, that is, if the value is an instance of a
types.model, types.array or types.map.
Parameters
valueany
Registers a function that will be invoked for each action that is called on the provided model instance, or to any of its children. See actions for more details. onAction events are emitted only for the outermost called action in the stack. Action can also be intercepted by middleware using addMiddleware to change the function call before it will be run.
Parameters
targetIStateTreeNodelistener
Returns IDisposer
Registers a function that will be invoked for each mutation that is applied to the provided model instance, or to any of its 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
targetObject the model instance from which to receive patchescallbackincludeOldValuebooleanincludeOldValue if oldValue is included in the patches, they can be inverted. However patches will become much bigger and might not be suitable for efficient transport
Returns 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 of the current MobX (trans)action. See snapshots for more details.
Parameters
targetObjectcallback
Returns IDisposer
See asynchronous actions.
Parameters
asyncAction
Returns Promise
The inverse of unprotect
Parameters
targetIStateTreeNode
Small abstraction around onAction and applyAction, attaches an action listener to a tree and records all the actions emitted.
Returns an recorder object with the following signature:
export interface IActionRecorder {
// the recorded actions
actions: ISerializedActionCall[]
// stop recording actions
stop(): any
// apply all the recorded actions on the given object
replay(target: IStateTreeNode): any
}Parameters
subjectIStateTreeNode
Returns IPatchRecorder
Small abstraction around onPatch and applyPatch, attaches a patch listener to a tree and records all the patches.
Returns an recorder object with the following signature:
export interface IPatchRecorder {
// the recorded patches
patches: IJsonPatch[]
// the same set of recorded patches, but without undo information, making them smaller and compliant with json-patch spec
cleanPatches: IJSonPatch[]
// stop recording patches
stop(target?: IStateTreeNode): any
// apply all the recorded patches on the given target (the original subject if omitted)
replay(target?: IStateTreeNode): any
// reverse apply the recorded patches on the given target (the original subject if omitted)
// stops the recorder if not already stopped
undo(): void
}Parameters
subjectIStateTreeNode
Returns IPatchRecorder
Resolves a model instance given a root target, the type and the identifier you are searching for. Returns undefined if no value can be found.
Parameters
Returns any
Resolves a path relatively to a given object. Returns undefined if no value can be found.
Parameters
Returns any
The inverse function of apply patch. Given a patch or set of patches, restores the target to the state before the patches where produced. The inverse patch is computed, and all the patches are applied in reverse order, basically 'rewinding' the target, so that conceptually the following holds for any set of patches:
getSnapshot(x) === getSnapshot(revertPatch(applyPatches(x, patches), patches))
Note: Reverting patches will generate a new set of patches as side effect of applying the patches.
Note: only patches that include oldValue information are suitable for reverting. Such patches can be generated by passing true as second argument when attaching an onPatch listener.
Parameters
targetpatch
Parameters
Returns any
Creates a index based collection type who's children are all of a uniform declared type.
This type will always produce observable arrays
Parameters
subtypeIType<S, T>
Examples
```javascript
const Todo = types.model({
task: types.string
})
const TodoStore = types.model({
todos: types.array(Todo)
})
const s = TodoStore.create({ todos: [] })
s.todos.push({ task: "Grab coffee" })
console.log(s.todos[0]) // prints: "Grab coffee"
```Returns IComplexType<Array<S>, IObservableArray<T>>
Creates a type that can only contain a boolean value. This type is used for boolean values by default
Examples
```javascript
const Thing = types.model({
isCool: types.boolean,
isAwesome: false
})
```Composes a new model from one or more existing model types. This method can be invoked in two forms: Given 2 or more model types, the types are composed into a new Type.
Creates a type that can only contain a javascript Date value.
Examples
```javascript
const LogLine = types.model({
timestamp: types.Date,
})
LogLine.create({ timestamp: new Date() })
```Can be used to create an string based enumeration. (note: this methods is just sugar for a union of string literals)
Parameters
namestring descriptive name of the enumeration (optional)optionsArray<string> possible values this enumeration can have
Examples
```javascript
const TrafficLight = types.model({
color: types.enum("Color", ["Red", "Orange", "Green"])
})
```Returns ISimpleType<string>
Frozen can be used to story any value that is serializable in itself (that is valid JSON). Frozen values need to be immutable or treated as if immutable. Values stored in frozen will snapshotted as-is by MST, and internal changes will not be tracked.
This is useful to store complex, but immutable values like vectors etc. It can form a powerful bridge to parts of your application that should be immutable, or that assume data to be immutable.
Examples
```javascript
const GameCharacter = types.model({
name: string,
location: types.frozen
})
const hero = new GameCharacter({
name: "Mario",
location: { x: 7, y: 4 }
})
hero.location = { x: 10, y: 2 } // OK
hero.location.x = 7 // Not ok!
```Identifier are used to make references, lifecycle events and reconciling works. Inside a state tree, for each type can exist only one instance for each given identifier. For example there could'nt be 2 instances of user with id 1. If you need more, consider using references. Identifier can be used only as type property of a model. This type accepts as parameter the value type of the identifier field that can be either string or number.
Parameters
baseTypeIType<T, T>
Examples
const Todo = types.model("Todo", {
id: types.identifier(types.string),
title: types.string
})Returns IType<T, T>
Defines a type that gets implemented later. This is usefull when you have to deal with circular dependencies. Please notice that when defining circular dependencies TypeScript is'nt smart enought to inference them. You need to declare an interface to explicit the return type of the late parameter function.
interface INode {
childs: INode[]
}
// TypeScript is'nt smart enough to infer self referencing types.
const Node = types.model({
childs: types.optional(types.array(types.late<any, INode>(() => Node)), [])
})Parameters
nameOrTypemaybeTypenamestring? The name to use for the type that will be returned.typeILateType<S, T> A function that returns the type that will be defined.
Returns IType<S, T>
The literal type will return a type that will match only the exact given type. The given value must be a primitive, in order to be serialized to a snapshot correctly. You can use literal to match exact strings for example the exact male or female string.
Parameters
valueS The value to use in the strict equal check
Examples
const Person = types.model({
name: types.string,
gender: types.union(types.literal('male'), types.literal('female'))
})Returns ISimpleType<S>
Creates a key based collection type who's children are all of a uniform declared type. If the type stored in a map has an identifier, it is mandatory to store the child under that identifier in the map.
This type will always produce observable maps
Parameters
subtypeIType<S, T>
Examples
```javascript
const Todo = types.model({
id: types.identifier,
task: types.string
})
const TodoStore = types.model({
todos: types.map(Todo)
})
const s = TodoStore.create({ todos: [] })
s.todos.set(17, { task: "Grab coffee", id: 17 })
s.todos.put({ task: "Grab cookie", id: 18 }) // put will infer key from the identifier
console.log(s.todos.get(17)) // prints: "Grab coffee"
```Returns IComplexType<Array<S>, IObservableArray<T>>
Maybe will make a type nullable, and also null by default.
Parameters
typeIType<S, T> The type to make nullable
Returns (IType<(S | null | undefined), (T | null)>)
Creates a new model type by providing a name, properties, volatile state and actions.
See the model type description or the getting started tutorial.
The type of the value null
Creates a type that can only contain a numeric value. This type is used for numeric values by default
Examples
```javascript
const Vector = types.model({
x: types.number,
y: 0
})
```types.optional can be used to create a property with a default value.
If the given value is not provided in the snapshot, it will default to the provided defaultValue.
If defaultValue is a function, the function will be invoked for every new instance.
Applying a snapshot in which the optional value is not present, causes the value to be reset
Parameters
typedefaultValueOrFunction
Examples
```javascript
const Todo = types.model({
title: types.optional(types.string, "Test"),
done: types.optional(types.boolean, false),
created: types.optional(types.Date, () => new Date())
})
// it is now okay to omit 'created' and 'done'. created will get a freshly generated timestamp
const todo = Todo.create({ title: "Get coffee "})
```Creates a reference to another type, which should have defined an identifier. See also the reference and identifiers section.
Parameters
factory
types.refinement(baseType, (snapshot) => boolean) creates a type that is more specific then the base type, e.g. types.refinement(types.string, value => value.length > 5) to create a type of strings that can only be longer then 5.
Parameters
namestringtypeIType<T, T>predicate
Returns IType<T, T>
Creates a type that can only contain a string value. This type is used for string values by default
Examples
```javascript
const Person = types.model({
firstName: types.string,
lastName: "Doe"
})
```The type of the value undefined
types.union(dispatcher?, types...) create a union of multiple types. If the correct type cannot be inferred unambigously from a snapshot, provide a dispatcher function of the form (snapshot) => Type.
Parameters
dispatchOrType(ITypeDispatcher | IType<any, any>)otherTypes...Array<IType<any, any>>
Returns IType<any, any>
unescape slashes and backslashes
Parameters
str
By default it is not allowed to directly modify a model. Models can only be modified through actions. However, in some cases you don't care about the advantages (like replayability, tracability, etc) this yields. For example because you are building a PoC or don't have any middleware attached to your tree.
In that case you can disable this protection by calling unprotect on the root of your tree.
Parameters
target
Examples
const Todo = types.model({
done: false,
toggle() {
this.done = !this.done
}
})
const todo = new Todo()
todo.done = true // OK
protect(todo)
todo.done = false // throws!
todo.toggle() // OKPerforms a depth first walk through a tree
Parameters
thingprocessor