Have ideas to improve npm?Join in the discussion! »

    mst-effect
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    mst-effect

    GitHub license NPM version Bundle size Coverage Status Discord

    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

    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'

    Install

    npm i mst-effect

    DownloadsWeekly Downloads

    229

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    97.9 kB

    Total Files

    104

    Last publish

    Collaborators

    • avatar