mst-effect is designed to be used with MobX-State-Tree to create asynchronous actions using RxJS. In case you haven't used them before:

MobX-State-Tree is a full-featured reactive state management library that can structure the state model super intuitively. RxJS is a library for composing asynchronous and event-based programs that provides the best practice to manage async codes.

If you are still hesitant about learning RxJS, check the examples below and play around with them. I assure you that you'll be amazed by what it can do and how clean the code could be.

Already using MobX-State-Tree? Awesome! mst-effect is 100% compatible with your current project.

Examples

• Fetch data
• Fetch with token
• Handle user input
• Mutually exclusive actions
• Back pressure

Installation

mst-effect has peer dependencies of mobx, mobx-state-tree and rxjs, which will have to be installed as well.

Using yarn:

yarn add mst-effect

Or via npm:

npm install mst-effect --save

Basics

effect is the core method of mst-effect. It can automatically manage subscriptions and execute the emitted actions. For example:

import { types, effect, action } from 'mst-effect'
import { map, switchMap } from 'rxjs/operators'

const Model = types
  .model({
    value: types.string,
  })
  .actions((self) => ({
    fetch: effect<string>(self, (payload$) => {
      function setValue(value: string) {
        self.value = value
      }

      return payload$.pipe(
        switchMap((url) => fetch$(url)),
        map((value) => action(setValue, value)),
      )
    }),
  }))

Import location

As you can see in the example above, types need to be imported from mst-effect(Why?).

The definition of the effect

The first parameter is the model instance, as effect needs to unsubscribe the Observable when the model is destroyed.

The second parameter, a factory function, can be thought of as the Epic of redux-observable. The factory function is called only once at model creation. It takes a stream of payloads and returns a stream of actions. — Payloads in, actions out.

Finally, effect returns a function to feed a new value to the payload$. In actual implementation code, it's just an alias to subject.next.

What is action?

action can be considered roughly as a higher-order function that takes a callback function and the arguments for the callback function. But instead of executing immediately, it returns a new function. Action will be immediately invoked when emitted.

function action(callback, ...params): EffectAction {
  return () => callback(...params)
}

API Reference

👾 effect

effect is used to manage subscriptions automatically.

type ValidEffectActions = EffectAction | EffectAction[]

type EffectDispatcher<P> = (payload: P) => void

function effect<P>(
  self: AnyInstance,
  fn: (payload$: Observable<P>) => Observable<ValidEffectActions>,
): EffectDispatcher<P>

payload$ emits data synchronously when the function returned by the effect is called. The returned Observable<ValidEffectActions> will automatically subscribed by effect

👾 dollEffect

type ValidEffectActions = EffectAction | EffectAction[]

type DollEffectDispatcher<P, S> = <SS = S>(
  payload: P,
  handler?: (resolve$: Observable<S>) => Observable<SS>,
) => Promise<SS>

type SignalDispatcher<S> = (value: S) => void

function dollEffect<P, S>(
  self: AnyInstance,
  fn: (
    payload$: Observable<P>,
    signalDispatcher: SignalDispatcher<S>,
  ) => Observable<ValidEffectActions>,
): DollEffectDispatcher<P, S>

dollEffect is almost identical with effect. The primary difference is DollEffectDispatcher will return a Promise which is useful when you want to report some message to the caller. The Promise will fulfill when SignalDispatcher being invoked (example). Also, you can use the handler to control when and what the Promise should resolve (example).

👾 signal

export function signal<P, R = P>(
  self: AnyInstance,
  fn?: (payload$: Observable<P>) => Observable<R>,
): [Observable<R>, (payload: P) => void]

signal is an encapsulation of the Subject. You can use the second parameter to do some processing of the output data.

👾 reaction$

export function reaction$<T>(
  expression: (r: IReactionPublic) => T,
  opts?: IReactionOptions,
): Observable<{ current: T; prev: T; r: IReactionPublic }>

reaction$ encapsulates the reaction method from mobx. When the returned value changes, it will emit the corresponding data to the returned Observable.

Recipes

Error Handling

When an error occurred in Observable, effect will re-subscribe the Observable (will not re-run the factory function). The common practice is to use the catchError operator for error handling. Check fetch data example for more detail.

Cancellation

You can combine signal and takeUntil() operator to cancel an Observable. Check mutually exclusive actions example for more detail.

FAQ

Why we need to import types from mst-effect

Currently, mobx-state-tree does not support modifying the model outside of actions. mst-effect overrides types.model so that the model can be modified in an asynchronous process. Because mst-effect re-export all the variables and types in mobx-state-tree, you can simply change the import location to mst-effect.

- import { types, Instance } from 'mobx-state-tree'
+ import { types, Instance } from 'mst-effect'