mobx-state-tree

Variables

• t
• types

Functions

• addDisposer()
• addMiddleware()
• applyAction()
• applyPatch()
• applySnapshot()
• cast()
• castFlowReturn()
• castToReferenceSnapshot()
• castToSnapshot()
• clone()
• createActionTrackingMiddleware()
• createActionTrackingMiddleware2()
• decorate()
• destroy()
• detach()
• escapeJsonPath()
• flow()
• getChildType()
• getEnv()
• getIdentifier()
• getLivelinessChecking()
• getMembers()
• getNodeId()
• getParent()
• getParentOfType()
• getPath()
• getPathParts()
• getPropertyMembers()
• getRelativePath()
• getRoot()
• getRunningActionContext()
• getSnapshot()
• getType()
• hasParent()
• hasParentOfType()
• isActionContextChildOf()
• isActionContextThisOrChildOf()
• isAlive()
• isArrayType()
• isFrozenType()
• isIdentifierType()
• isLateType()
• isLiteralType()
• isMapType()
• isModelType()
• isOptionalType()
• isPrimitiveType()
• isProtected()
• isReferenceType()
• isRefinementType()
• isRoot()
• isStateTreeNode()
• isType()
• isUnionType()
• isValidReference()
• joinJsonPath()
• onAction()
• onPatch()
• onSnapshot()
• process()
• protect()
• recordActions()
• recordPatches()
• resolveIdentifier()
• resolvePath()
• setLivelinessChecking()
• setLivelynessChecking()
• splitJsonPath()
• toGenerator()
• toGeneratorFunction()
• tryReference()
• tryResolve()
• typecheck()
• unescapeJsonPath()
• unprotect()
• walk()

Interfaces

• CustomTypeOptions

  • fromSnapshot()
  • getValidationMessage()
  • isTargetType()
  • name
  • toSnapshot()
• IActionContext

  • args
  • context
  • id
  • name
  • parentActionEvent
  • tree
• IActionRecorder

  • actions
  • recording
  • replay()
  • resume()
  • stop()
• IActionTrackingMiddleware2Call

  • env
  • parentCall
• IActionTrackingMiddleware2Hooks

  • filter
  • onFinish
  • onStart
• IActionTrackingMiddlewareHooks

  • filter
  • onFail
  • onResume
  • onStart
  • onSuccess
  • onSuspend
• IAnyComplexType
• IAnyModelType
• IAnyStateTreeNode
• IAnyType
• IArrayType

  • hooks()
• IComplexType
• IJsonPatch

  • op
  • path
  • value
• IMapType

  • hooks()
• IMaybe
• IMaybeIType
• IMaybeNull
• IMiddlewareEvent

  • allParentIds
  • parentEvent
  • parentId
  • rootId
  • type
• IModelReflectionData

  • actions
  • flowActions
  • views
  • volatile
• IModelReflectionPropertiesData

  • name
  • properties
• IModelType

  • actions()
  • extend()
  • named()
  • postProcessSnapshot()
  • preProcessSnapshot()
  • properties
  • props()
  • views()
  • volatile()
• IMSTArray

  • concat()
  • push()
  • splice()
  • unshift()
• IMSTMap

  • [Symbol.iterator]()
  • [Symbol.toStringTag]
  • clear()
  • delete()
  • entries()
  • forEach()
  • get()
  • has()
  • intercept()
  • keys()
  • merge()
  • observe()
  • put()
  • replace()
  • set()
  • size
  • toJSON()
  • toString()
  • values()
• IOptionalIType
• IPatchRecorder

  • inversePatches
  • patches
  • recording
  • replay()
  • resume()
  • reversedInversePatches
  • stop()
  • undo()
• IReferenceType
• IReversibleJsonPatch

  • oldValue
• ISerializedActionCall

  • args
  • name
  • path
• ISimpleType
• ISnapshotProcessor
• ISnapshotProcessors

  • postProcessor()
  • preProcessor()
• IStateTreeNode

  • [$stateTreeNodeType]
• IType

  • [$type]
  • create()
  • CreationType
  • describe()
  • identifierAttribute
  • is()
  • name
  • SnapshotType
  • Type
  • TypeWithoutSTN
  • validate()
• ITypeUnion
• ModelActions
• ModelProperties
• ModelPropertiesDeclaration
• ReferenceOptionsGetSet

  • get()
  • set()
• ReferenceOptionsOnInvalidated

  • onInvalidated
• UnionOptions

  • dispatcher
  • eager

Type Aliases

• IDisposer
• IMiddlewareEventType
• IMiddlewareHandler
• Instance
• LivelinessMode
• LivelynessMode
• ModelCreationType
• ModelCreationType2
• ModelInstanceType
• ModelInstanceTypeProps
• ModelPrimitive
• ModelPropertiesDeclarationToProperties
• ModelSnapshotType
• ModelSnapshotType2
• OnReferenceInvalidated
• OnReferenceInvalidatedEvent
• OptionalDefaultValueOrFunction
• ReferenceIdentifier
• ReferenceOptions
• SnapshotIn
• SnapshotOrInstance
• SnapshotOut
• TypeOfValue
• TypeOrStateTreeNodeToStateTreeNode
• UnionStringArray
• ValidOptionalValue
• ValidOptionalValues

variable t

const t: {
    enumeration: typeof enumeration;
    model: typeof model;
    compose: typeof compose;
    custom: typeof custom;
    reference: typeof reference;
    safeReference: typeof safeReference;
    union: typeof union;
    optional: typeof optional;
    literal: typeof literal;
    maybe: typeof maybe;
    maybeNull: typeof maybeNull;
    refinement: typeof refinement;
    string: import('../internal').ISimpleType<string>;
    boolean: import('../internal').ISimpleType<boolean>;
    number: import('../internal').ISimpleType<number>;
    integer: import('../internal').ISimpleType<number>;
    float: import('../internal').ISimpleType<number>;
    finite: import('../internal').ISimpleType<number>;
    Date: import('../internal').IType<number | Date, number, Date>;
    map: typeof map;
    array: typeof array;
    frozen: typeof frozen;
    identifier: import('../internal').ISimpleType<string>;
    identifierNumber: import('../internal').ISimpleType<number>;
    late: typeof late;
    lazy: typeof lazy;
    undefined: import('../internal').ISimpleType<undefined>;
    null: import('../internal').ISimpleType<null>;
    snapshotProcessor: typeof snapshotProcessor;
};

variable types

const types: {
    enumeration: typeof enumeration;
    model: typeof model;
    compose: typeof compose;
    custom: typeof custom;
    reference: typeof reference;
    safeReference: typeof safeReference;
    union: typeof union;
    optional: typeof optional;
    literal: typeof literal;
    maybe: typeof maybe;
    maybeNull: typeof maybeNull;
    refinement: typeof refinement;
    string: import('../internal').ISimpleType<string>;
    boolean: import('../internal').ISimpleType<boolean>;
    number: import('../internal').ISimpleType<number>;
    integer: import('../internal').ISimpleType<number>;
    float: import('../internal').ISimpleType<number>;
    finite: import('../internal').ISimpleType<number>;
    Date: import('../internal').IType<number | Date, number, Date>;
    map: typeof map;
    array: typeof array;
    frozen: typeof frozen;
    identifier: import('../internal').ISimpleType<string>;
    identifierNumber: import('../internal').ISimpleType<number>;
    late: typeof late;
    lazy: typeof lazy;
    undefined: import('../internal').ISimpleType<undefined>;
    null: import('../internal').ISimpleType<null>;
    snapshotProcessor: typeof snapshotProcessor;
};

function addDisposer

addDisposer: (target: IAnyStateTreeNode, disposer: IDisposer) => IDisposer;

• 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.

  This methods returns the same disposer that was passed as argument.

  Example:

  const Todo = types.model({
    title: types.string
  }).actions(self => ({
    afterCreate() {
      const autoSaveDisposer = reaction(
        () => getSnapshot(self),
        snapshot => sendSnapshotToServerSomehow(snapshot)
      )
      // stop sending updates to server if this
      // instance is destroyed
      addDisposer(self, autoSaveDisposer)
    }
  }))

  Parameter target

  Parameter disposer

  Returns

  The same disposer that was passed as argument

function addMiddleware

addMiddleware: (
    target: IAnyStateTreeNode,
    handler: IMiddlewareHandler,
    includeHooks?: boolean
) => IDisposer;

• 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](concepts/middleware.md)

  Parameter target

  Node to apply the middleware to.

  Parameter middleware

  Middleware to apply.

  Returns

  A callable function to dispose the middleware.

function applyAction

applyAction: (
    target: IAnyStateTreeNode,
    actions: ISerializedActionCall | ISerializedActionCall[]
) => void;

• 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.

  Parameter target

  Parameter actions

function applyPatch

applyPatch: (
    target: IAnyStateTreeNode,
    patch: IJsonPatch | ReadonlyArray<IJsonPatch>
) => void;

• Applies a JSON-patch to the given model instance or bails out if the patch couldn't be applied See [patches](https://github.com/mobxjs/mobx-state-tree#patches) for more details.

  Can apply a single past, or an array of patches.

  Parameter target

  Parameter patch

  Returns

function applySnapshot

applySnapshot: <C>(
    target: IStateTreeNode<IType<C, any, any>>,
    snapshot: C
) => void;

• Applies a snapshot to a given model instances. Patch and snapshot listeners will be invoked as usual.

  Parameter target

  Parameter snapshot

  Returns

function cast

cast: {
    <O extends string | number | boolean = never>(snapshotOrInstance: O): O;
    <O = never>(
        snapshotOrInstance:
            | TypeOfValue<O>['CreationType']
            | TypeOfValue<O>['SnapshotType']
            | TypeOfValue<O>['Type']
    ): O;
};

function castFlowReturn

castFlowReturn: <T>(val: T) => T;

• Parameter val

  Returns

  Deprecated

  Not needed since TS3.6. Used for TypeScript to make flows that return a promise return the actual promise result.

function castToReferenceSnapshot

castToReferenceSnapshot: <I>(
    instance: I
) => Extract<I, IAnyStateTreeNode> extends never ? I : ReferenceIdentifier;

• Casts a node instance type to a reference snapshot type so it can be assigned to a reference snapshot (e.g. to be used inside a create call). Note that this is just a cast for the type system, this is, it won't actually convert an instance to a reference snapshot, but just fool typescript into thinking so.

  Example:

  const ModelA = types.model({
    id: types.identifier,
    n: types.number
  }).actions(self => ({
    setN(aNumber: number) {
      self.n = aNumber
    }
  }))
  
  const ModelB = types.model({
    refA: types.reference(ModelA)
  })
  
  const a = ModelA.create({ id: 'someId', n: 5 });
  // this will allow the compiler to use a model as if it were a reference snapshot
  const b = ModelB.create({ refA: castToReferenceSnapshot(a)})

  Parameter instance

  Instance

  Returns

  The same object cast as a reference snapshot (string or number)

function castToSnapshot

castToSnapshot: <I>(
    snapshotOrInstance: I
) => Extract<I, IAnyStateTreeNode> extends never
    ? I
    : TypeOfValue<I>['CreationType'];

• Casts a node instance type to a snapshot type so it can be assigned to a type snapshot (e.g. to be used inside a create call). Note that this is just a cast for the type system, this is, it won't actually convert an instance to a snapshot, but just fool typescript into thinking so.

  Example:

  const ModelA = types.model({
    n: types.number
  }).actions(self => ({
    setN(aNumber: number) {
      self.n = aNumber
    }
  }))
  
  const ModelB = types.model({
    innerModel: ModelA
  })
  
  const a = ModelA.create({ n: 5 });
  // this will allow the compiler to use a model as if it were a snapshot
  const b = ModelB.create({ innerModel: castToSnapshot(a)})

  Parameter snapshotOrInstance

  Snapshot or instance

  Returns

  The same object cast as an input (creation) snapshot

function clone

clone: <T extends IAnyStateTreeNode>(
    source: T,
    keepEnvironment?: boolean | any
) => T;

• Returns a deep copy of the given state tree node as new tree. Shorthand 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_

  Parameter source

  Parameter keepEnvironment

  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

function createActionTrackingMiddleware

createActionTrackingMiddleware: <T = any>(
    hooks: IActionTrackingMiddlewareHooks<T>
) => IMiddlewareHandler;

• Note: Consider migrating to createActionTrackingMiddleware2, it is easier to use.

  Convenience utility to create action based middleware that supports async processes more easily. All hooks are called for both synchronous and asynchronous actions. Except that either onSuccess or onFail is called

  The create middleware tracks the process of an action (assuming it passes the filter). onResume can return any value, which will be passed as second argument to any other hook. This makes it possible to keep state during a process.

  See the atomic middleware for an example

  Parameter hooks

  Returns

function createActionTrackingMiddleware2

createActionTrackingMiddleware2: <TEnv = any>(
    middlewareHooks: IActionTrackingMiddleware2Hooks<TEnv>
) => IMiddlewareHandler;

• Convenience utility to create action based middleware that supports async processes more easily. The flow is like this: - for each action: if filter passes -> onStart -> (inner actions recursively) -> onFinish

  Example: if we had an action a that called inside an action b1, then b2 the flow would be: - filter(a) - onStart(a) - filter(b1) - onStart(b1) - onFinish(b1) - filter(b2) - onStart(b2) - onFinish(b2) - onFinish(a)

  The flow is the same no matter if the actions are sync or async.

  See the atomic middleware for an example

  Parameter hooks

  Returns

function decorate

decorate: <T extends Function>(
    handler: IMiddlewareHandler,
    fn: T,
    includeHooks?: boolean
) => T;

• Binds middleware to a specific action.

  Example:

  type.actions(self => {
    function takeA____() {
        self.toilet.donate()
        self.wipe()
        self.wipe()
        self.toilet.flush()
    }
    return {
      takeA____: decorate(atomic, takeA____)
    }
  })

  Parameter handler

  Parameter fn

  Parameter includeHooks

  Returns

  The original function

function destroy

destroy: (target: IAnyStateTreeNode) => void;

• Removes a model element from the state tree, and mark it as end-of-life; the element should not be used anymore

function detach

detach: <T extends IAnyStateTreeNode>(target: T) => T;

• Removes a model element from the state tree, and let it live on as a new state tree

function escapeJsonPath

escapeJsonPath: (path: string) => string;

• Escape slashes and backslashes.

  http://tools.ietf.org/html/rfc6901

function flow

flow: <R, Args extends any[]>(
    generator: (...args: Args) => Generator<PromiseLike<any>, R, any>
) => (...args: Args) => Promise<FlowReturn<R>>;

• See [asynchronous actions](concepts/async-actions.md).

  Returns

  The flow as a promise.

function getChildType

getChildType: (object: IAnyStateTreeNode, propertyName?: string) => IAnyType;

• Returns the _declared_ type of the given sub property of an object, array or map. In the case of arrays and maps the property name is optional and will be ignored.

  Example:

  const Box = types.model({ x: 0, y: 0 })
  const box = Box.create()
  
  console.log(getChildType(box, "x").name) // 'number'

  Parameter object

  Parameter propertyName

  Returns

function getEnv

getEnv: <T = any>(target: IAnyStateTreeNode) => T;

• Returns the environment of the current state tree. For more info on environments, see [Dependency injection](https://github.com/mobxjs/mobx-state-tree#dependency-injection)

  Please note that in child nodes access to the root is only possible once the afterAttach hook has fired

  Returns an empty environment if the tree wasn't initialized with an environment

  Parameter target

  Returns

function getIdentifier

getIdentifier: (target: IAnyStateTreeNode) => string | null;

• Returns the identifier of the target node. This is the *string normalized* identifier, which might not match the type of the identifier attribute

  Parameter target

  Returns

function getLivelinessChecking

getLivelinessChecking: () => LivelinessMode;

• Returns the current liveliness checking mode.

  Returns

  "warn", "error" or "ignore"

function getMembers

getMembers: (target: IAnyStateTreeNode) => IModelReflectionData;

• Returns a reflection of the model node, including name, properties, views, volatile state, and actions. flowActions is also provided as a separate array of names for any action that came from a flow generator as well.

  In the case where a model has two actions: doSomething and doSomethingWithFlow, where doSomethingWithFlow is a flow generator, the actions array will contain both actions, i.e. ["doSomething", "doSomethingWithFlow"], and the flowActions array will contain only the flow action, i.e. ["doSomethingWithFlow"].

  Parameter target

  Returns

function getNodeId

getNodeId: (target: IAnyStateTreeNode) => number;

• Returns the unique node id (not to be confused with the instance identifier) for a given instance. This id is a number that is unique for each instance.

  Parameter target

  Returns

function getParent

getParent: <IT extends IAnyStateTreeNode | IAnyComplexType>(
    target: IAnyStateTreeNode,
    depth?: number
) => TypeOrStateTreeNodeToStateTreeNode<IT>;

• Returns the immediate parent of this object, or throws.

  Note that the immediate parent can be either an object, map or array, and doesn't necessarily refer to the parent model.

  Please note that in child nodes access to the root is only possible once the afterAttach hook has fired.

  Parameter target

  Parameter depth

  How far should we look upward? 1 by default.

  Returns

function getParentOfType

getParentOfType: <IT extends IAnyComplexType>(
    target: IAnyStateTreeNode,
    type: IT
) => IT['Type'];

• Returns the target's parent of a given type, or throws.

  Parameter target

  Parameter type

  Returns

function getPath

getPath: (target: IAnyStateTreeNode) => string;

• Returns the path of the given object in the model tree

  Parameter target

  Returns

function getPathParts

getPathParts: (target: IAnyStateTreeNode) => string[];

• Returns the path of the given object as unescaped string array.

  Parameter target

  Returns

function getPropertyMembers

getPropertyMembers: (
    typeOrNode: IAnyModelType | IAnyStateTreeNode
) => IModelReflectionPropertiesData;

• Returns a reflection of the model type properties and name for either a model type or model node.

  Parameter typeOrNode

  Returns

function getRelativePath

getRelativePath: (base: IAnyStateTreeNode, target: IAnyStateTreeNode) => string;

• 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

  Parameter base

  Parameter target

  Returns

function getRoot

getRoot: <IT extends IAnyStateTreeNode | IAnyComplexType>(
    target: IAnyStateTreeNode
) => TypeOrStateTreeNodeToStateTreeNode<IT>;

• Given an object in a model tree, returns the root object of that tree.

  Please note that in child nodes access to the root is only possible once the afterAttach hook has fired.

  Parameter target

  Returns

function getRunningActionContext

getRunningActionContext: () => IActionContext | undefined;

• Returns the currently executing MST action context, or undefined if none.

function getSnapshot

getSnapshot: <S>(
    target: IStateTreeNode<IType<any, S, any>>,
    applyPostProcess?: boolean
) => S;

• 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.

  Parameter target

  Parameter applyPostProcess

  If true (the default) then postProcessSnapshot gets applied.

  Returns

function getType

getType: (object: IAnyStateTreeNode) => IAnyComplexType;

• Returns the _actual_ type of the given tree node. (Or throws)

  Parameter object

  Returns

function hasParent

hasParent: (target: IAnyStateTreeNode, depth?: number) => boolean;

• Given a model instance, returns true if the object has a parent, that is, is part of another object, map or array.

  Parameter target

  Parameter depth

  How far should we look upward? 1 by default.

  Returns

function hasParentOfType

hasParentOfType: (target: IAnyStateTreeNode, type: IAnyComplexType) => boolean;

• Given a model instance, returns true if the object has a parent of given type, that is, is part of another object, map or array

  Parameter target

  Parameter type

  Returns

function isActionContextChildOf

isActionContextChildOf: (
    actionContext: IActionContext,
    parent: number | IActionContext | IMiddlewareEvent
) => boolean;

• Returns if the given action context is a parent of this action context.

function isActionContextThisOrChildOf

isActionContextThisOrChildOf: (
    actionContext: IActionContext,
    parentOrThis: number | IActionContext | IMiddlewareEvent
) => boolean;

• Returns if the given action context is this or a parent of this action context.

function isAlive

isAlive: (target: IAnyStateTreeNode) => 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

  Parameter target

  Returns

function isArrayType

isArrayType: <Items extends IAnyType = IAnyType>(
    type: IAnyType
) => type is IArrayType<Items>;

• Returns if a given value represents an array type.

  Parameter type

  Returns

  true if the type is an array type.

function isFrozenType

isFrozenType: <IT extends IType<any, T, T>, T = any>(type: IT) => type is IT;

• Returns if a given value represents a frozen type.

  Parameter type

  Returns

function isIdentifierType

isIdentifierType: <IT extends ISimpleType<string> | ISimpleType<number>>(
    type: IT
) => type is IT;

• Returns if a given value represents an identifier type.

  Parameter type

  Returns

function isLateType

isLateType: <IT extends IAnyType>(type: IT) => type is IT;

• Returns if a given value represents a late type.

  Parameter type

  Returns

function isLiteralType

isLiteralType: <IT extends ISimpleType<any>>(type: IT) => type is IT;

• Returns if a given value represents a literal type.

  Parameter type

  Returns

function isMapType

isMapType: <Items extends IAnyType = IAnyType>(
    type: IAnyType
) => type is IMapType<Items>;

• Returns if a given value represents a map type.

  Parameter type

  Returns

  true if it is a map type.

function isModelType

isModelType: <IT extends IAnyModelType = IAnyModelType>(
    type: IAnyType
) => type is IT;

• Returns if a given value represents a model type.

  Parameter type

  Returns

function isOptionalType

isOptionalType: <IT extends IAnyType>(type: IT) => type is IT;

• Returns if a value represents an optional type.

  IT

  Parameter type

  Returns

function isPrimitiveType

isPrimitiveType: <
    IT extends
        | ISimpleType<string>
        | ISimpleType<number>
        | ISimpleType<boolean>
        | IType<number | Date, number, Date>
>(
    type: IT
) => type is IT;

• Returns if a given value represents a primitive type.

  Parameter type

  Returns

function isProtected

isProtected: (target: IAnyStateTreeNode) => boolean;

• Returns true if the object is in protected mode,

  See Also

  • protect

function isReferenceType

isReferenceType: <IT extends IReferenceType<any>>(type: IT) => type is IT;

• Returns if a given value represents a reference type.

  Parameter type

  Returns

function isRefinementType

isRefinementType: <IT extends IAnyType>(type: IT) => type is IT;

• Returns if a given value is a refinement type.

  Parameter type

  Returns

function isRoot

isRoot: (target: IAnyStateTreeNode) => boolean;

• Returns true if the given object is the root of a model tree.

  Parameter target

  Returns

function isStateTreeNode

isStateTreeNode: <IT extends IAnyComplexType = IAnyComplexType>(
    value: any
) => value is STNValue<Instance<IT>, IT>;

• 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.

  Parameter value

  Returns

  true if the value is a state tree node.

function isType

isType: (value: any) => value is IAnyType;

• Returns if a given value represents a type.

  Parameter value

  Value to check.

  Returns

  true if the value is a type.

function isUnionType

isUnionType: <IT extends IAnyType>(type: IT) => type is IT;

• Returns if a given value represents a union type.

  Parameter type

  Returns

function isValidReference

isValidReference: <N extends IAnyStateTreeNode>(
    getter: () => N | null | undefined,
    checkIfAlive?: boolean
) => boolean;

• Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns if the check passes or not.

  Parameter getter

  Function to access the reference.

  Parameter checkIfAlive

  true to also make sure the referenced node is alive (default), false to skip this check.

  Returns

function joinJsonPath

joinJsonPath: (path: string[]) => string;

• Generates a json-path compliant json path from path parts.

  Parameter path

  Returns

function onAction

onAction: (
    target: IAnyStateTreeNode,
    listener: (call: ISerializedActionCall) => void,
    attachAfter?: boolean
) => IDisposer;

• 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](https://github.com/mobxjs/mobx-state-tree#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.

  Not all action arguments might be serializable. For unserializable arguments, a struct like { $MST_UNSERIALIZABLE: true, type: "someType" } will be generated. MST Nodes are considered non-serializable as well (they could be serialized as there snapshot, but it is uncertain whether an replaying party will be able to handle such a non-instantiated snapshot). Rather, when using onAction middleware, one should consider in passing arguments which are 1: an id, 2: a (relative) path, or 3: a snapshot. Instead of a real MST node.

  Example:

  const Todo = types.model({
    task: types.string
  })
  
  const TodoStore = types.model({
    todos: types.array(Todo)
  }).actions(self => ({
    add(todo) {
      self.todos.push(todo);
    }
  }))
  
  const s = TodoStore.create({ todos: [] })
  
  let disposer = onAction(s, (call) => {
    console.log(call);
  })
  
  s.add({ task: "Grab a coffee" })
  // Logs: { name: "add", path: "", args: [{ task: "Grab a coffee" }] }

  Parameter target

  Parameter listener

  Parameter attachAfter

  (default false) fires the listener *after* the action has executed instead of before.

  Returns

function onPatch

onPatch: (
    target: IAnyStateTreeNode,
    callback: (patch: IJsonPatch, reversePatch: IJsonPatch) => void
) => 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](https://github.com/mobxjs/mobx-state-tree#patches) for more details. onPatch events are emitted immediately and will not await the end of a transaction. Patches can be used to deeply observe a model tree.

  Parameter target

  the model instance from which to receive patches

  Parameter callback

  the callback that is invoked for each patch. The reversePatch is a patch that would actually undo the emitted patch

  Returns

  function to remove the listener

function onSnapshot

onSnapshot: <S>(
    target: IStateTreeNode<IType<any, S, any>>,
    callback: (snapshot: S) => void
) => IDisposer;

• Registers a function that is invoked whenever a new snapshot for the given model instance is available. The listener will only be fire at the end of the current MobX (trans)action. See [snapshots](https://github.com/mobxjs/mobx-state-tree#snapshots) for more details.

  Parameter target

  Parameter callback

  Returns

function process

process: {
    <R>(generator: () => IterableIterator<any>): () => Promise<R>;
    <A1>(generator: (a1: A1) => IterableIterator<any>): (a1: A1) => Promise<any>;
    <A1, A2>(generator: (a1: A1, a2: A2) => IterableIterator<any>): (
        a1: A1,
        a2: A2
    ) => Promise<any>;
    <A1, A2, A3>(generator: (a1: A1, a2: A2, a3: A3) => IterableIterator<any>): (
        a1: A1,
        a2: A2,
        a3: A3
    ) => Promise<any>;
    <A1, A2, A3, A4>(
        generator: (a1: A1, a2: A2, a3: A3, a4: A4) => IterableIterator<any>
    ): (a1: A1, a2: A2, a3: A3, a4: A4) => Promise<any>;
    <A1, A2, A3, A4, A5>(
        generator: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => IterableIterator<any>
    ): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => Promise<any>;
    <A1, A2, A3, A4, A5, A6>(
        generator: (
            a1: A1,
            a2: A2,
            a3: A3,
            a4: A4,
            a5: A5,
            a6: A6
        ) => IterableIterator<any>
    ): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6) => Promise<any>;
    <A1, A2, A3, A4, A5, A6, A7>(
        generator: (
            a1: A1,
            a2: A2,
            a3: A3,
            a4: A4,
            a5: A5,
            a6: A6,
            a7: A7
        ) => IterableIterator<any>
    ): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7) => Promise<any>;
    <A1, A2, A3, A4, A5, A6, A7, A8>(
        generator: (
            a1: A1,
            a2: A2,
            a3: A3,
            a4: A4,
            a5: A5,
            a6: A6,
            a7: A7,
            a8: A8
        ) => IterableIterator<any>
    ): (
        a1: A1,
        a2: A2,
        a3: A3,
        a4: A4,
        a5: A5,
        a6: A6,
        a7: A7,
        a8: A8
    ) => Promise<any>;
};

• Deprecated

  has been renamed to flow().

function protect

protect: (target: IAnyStateTreeNode) => void;

• The inverse of unprotect.

  Parameter target

function recordActions

recordActions: (
    subject: IAnyStateTreeNode,
    filter?: (
        action: ISerializedActionCall,
        actionContext: IActionContext | undefined
    ) => boolean
) => IActionRecorder;

• 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:

  Example:

  export interface IActionRecorder {
       // the recorded actions
       actions: ISerializedActionCall[]
       // true if currently recording
       recording: boolean
       // stop recording actions
       stop(): void
       // resume recording actions
       resume(): void
       // apply all the recorded actions on the given object
       replay(target: IAnyStateTreeNode): void
  }

  The optional filter function allows to skip recording certain actions.

  Parameter subject

  Returns

function recordPatches

recordPatches: (
    subject: IAnyStateTreeNode,
    filter?: (
        patch: IJsonPatch,
        inversePatch: IJsonPatch,
        actionContext: IActionContext | undefined
    ) => boolean
) => IPatchRecorder;

• Small abstraction around onPatch and applyPatch, attaches a patch listener to a tree and records all the patches. Returns a recorder object with the following signature:

  Example:

  export interface IPatchRecorder {
       // the recorded patches
       patches: IJsonPatch[]
       // the inverse of the recorded patches
       inversePatches: IJsonPatch[]
       // true if currently recording
       recording: boolean
       // stop recording patches
       stop(): void
       // resume recording patches
       resume(): void
       // apply all the recorded patches on the given target (the original subject if omitted)
       replay(target?: IAnyStateTreeNode): void
       // reverse apply the recorded patches on the given target  (the original subject if omitted)
       // stops the recorder if not already stopped
       undo(): void
  }

  The optional filter function allows to skip recording certain patches.

  Parameter subject

  Parameter filter

  Returns

function resolveIdentifier

resolveIdentifier: <IT extends IAnyModelType>(
    type: IT,
    target: IAnyStateTreeNode,
    identifier: ReferenceIdentifier
) => IT['Type'] | undefined;

• 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.

  Parameter type

  Parameter target

  Parameter identifier

  Returns

function resolvePath

resolvePath: (target: IAnyStateTreeNode, path: string) => any;

• Resolves a path relatively to a given object. Returns undefined if no value can be found.

  Parameter target

  Parameter path

  escaped json path

  Returns

function setLivelinessChecking

setLivelinessChecking: (mode: LivelinessMode) => void;

• Defines what MST should do when running into reads / writes to objects that have died. By default it will print a warning. Use the "error" option to easy debugging to see where the error was thrown and when the offending read / write took place

  Parameter mode

  "warn", "error" or "ignore"

function setLivelynessChecking

setLivelynessChecking: (mode: LivelinessMode) => void;

• Parameter mode

  "warn", "error" or "ignore"

  Deprecated

  use setLivelinessChecking instead

  Defines what MST should do when running into reads / writes to objects that have died. By default it will print a warning. Use the "error" option to easy debugging to see where the error was thrown and when the offending read / write took place

function splitJsonPath

splitJsonPath: (path: string) => string[];

• Splits and decodes a json path into several parts.

  Parameter path

  Returns

function toGenerator

toGenerator: <R>(p: Promise<R>) => Generator<Promise<R>, R, R>;

• experimental api - might change on minor/patch releases

  Convert a promise to a generator yielding that promise This is intended to allow for usage of yield* in async actions to retain the promise return type.

  Example:

  function getDataAsync(input: string): Promise<number> { ... }
  
  const someModel.actions(self => ({
    someAction: flow(function*() {
      // value is typed as number
      const value = yield* toGenerator(getDataAsync("input value"));
      ...
    })
  }))

  Modifiers

  • @experimental

function toGeneratorFunction

toGeneratorFunction: <R, Args extends any[]>(
    p: (...args: Args) => Promise<R>
) => (...args: Args) => Generator<Promise<R>, R, R>;

• experimental api - might change on minor/patch releases

  Convert a promise-returning function to a generator-returning one. This is intended to allow for usage of yield* in async actions to retain the promise return type.

  Example:

  function getDataAsync(input: string): Promise<number> { ... }
  const getDataGen = toGeneratorFunction(getDataAsync);
  
  const someModel.actions(self => ({
    someAction: flow(function*() {
      // value is typed as number
      const value = yield* getDataGen("input value");
      ...
    })
  }))

  Modifiers

  • @experimental

function tryReference

tryReference: <N extends IAnyStateTreeNode>(
    getter: () => N | null | undefined,
    checkIfAlive?: boolean
) => N | undefined;

• Tests if a reference is valid (pointing to an existing node and optionally if alive) and returns such reference if the check passes, else it returns undefined.

  Parameter getter

  Function to access the reference.

  Parameter checkIfAlive

  true to also make sure the referenced node is alive (default), false to skip this check.

  Returns

function tryResolve

tryResolve: (target: IAnyStateTreeNode, path: string) => any;

• Try to resolve a given path relative to a given node.

  Parameter target

  Parameter path

  Returns

function typecheck

typecheck: <IT extends IAnyType>(type: IT, value: ExtractCSTWithSTN<IT>) => void;

• Run's the typechecker for the given type on the given value, which can be a snapshot or an instance. Throws if the given value is not according the provided type specification. Use this if you need typechecks even in a production build (by default all automatic runtime type checks will be skipped in production builds)

  Parameter type

  Type to check against.

  Parameter value

  Value to be checked, either a snapshot or an instance.

function unescapeJsonPath

unescapeJsonPath: (path: string) => string;

• Unescape slashes and backslashes.

function unprotect

unprotect: (target: IAnyStateTreeNode) => void;

• 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, traceability, 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.

  Example:

  const Todo = types.model({
      done: false
  }).actions(self => ({
      toggle() {
          self.done = !self.done
      }
  }))
  
  const todo = Todo.create()
  todo.done = true // throws!
  todo.toggle() // OK
  unprotect(todo)
  todo.done = false // OK

function walk

walk: (
    target: IAnyStateTreeNode,
    processor: (item: IAnyStateTreeNode) => void
) => void;

• Performs a depth first walk through a tree.