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.
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
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)),
)
}),
}))
As you can see in the example above, types
need to be imported from mst-effect
(Why?).
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
.
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)
}
πΎ 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
.
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.
You can combine signal
and takeUntil()
operator to cancel an Observable
. Check mutually exclusive actions example for more detail.
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'