Mobx Value

mobx-value is a simple and small data management lib, with it data decouple from component.

The most outstanding of mobx-value is, you do not have to create much structure layer code, as reducer or action or dispatch.

• MobxValue
  • Overview
  • Installation
  • API
    • Setter
    • Boolean
    • Request
    • Lazy
    • Alias
    • SetMobx
  • Example
    • Work with React
    • Hooks
  • CDN
  • Build doc
  • TODO

Overview

If you feel redux(or other libs similar to redux) is reduant, and have strong need of data management out of component. Try this one.

By mobx-value, just create a data by setter(or request or boolean or lazy), use it in a component, wrap the component with observer from mobx-react-lite, it works.

Note: mobx-value only works with Mobx > 6.0.0.

Installation

1npm install -S mobx mobx-value
2// or yarn
3yarn add mobx mobx-value

Api

setter

• Example

1import { setter } from 'mobx-value'
2
3const counter = setter({ value: 1 })
4counter.value // 1
5counter.set(2)
6counter.value // 2
7counter.set(n => n + 1) // support function from version 1.5
8counter.value // 3
9counter.restore()
10counter.value // 1
11
12const o = setter({
13  value: {n: 1},
14})
15o.merge({ m: 2 }) // add `merge` method from version 1.7
16o.value // { n: 1, m: 2 }

• Parameters type MobxSetterOption

1interface MobxSetterOption<Data> {
2  value: Data,
3
4  /**
5   * mobx `makeObservable` annotation option for `value`
6   * @default observable
7   * */
8  annotation?: observable | observable.shallow
9    | observable.struct | observable.deep
10    | observable.ref | true
11
12  /**
13   * auto run restore when leave observer context
14   * @default false
15   * */
16  autoRestoreOnBecomeUnobserved?: boolean
17
18  /**
19   * alias of `autoRestoreOnBecomeUnobserved`
20   * @default false
21   * added version 1.8.0
22   * */
23  autoRestore?: boolean
24
25  /**
26   * mobx debug name
27   * */
28   name?: string // support from version 1.6
29}

• Return type MobxSetterValue

1interface MobxSetterValue<Data> {
2  value: Data
3  set: (v: Data | ((current: Data) => Data)) => void
4  restore: () => void
5  /** only works when value is an object, shallow merge properties */
6  merge: (v: Record<string, any>) => void
7}

boolean

Extends from setter, is a specifically for bool value.

• Example

1import { boolean } from 'mobx-value'
2
3const modal = boolean()
4modal.value // false
5modal.setTrue() // true
6modal.setFalse // false
7modal.toggle() // true
8modal.restore() // false

• Parameters type MobxBooleanOption

1interface MobxBooleanOption {
2  /**
3    * @default false
4    */
5  value?: boolean,
6
7  /**
8   * auto run restore when leave observer context
9   * @default false
10   * */
11  autoRestoreOnBecomeUnobserved?: boolean
12
13  /**
14   * alias of `autoRestoreOnBecomeUnobserved`
15   * @default false
16   * added version 1.8.0
17   * */
18  autoRestore?: boolean
19
20  /**
21   * mobx debug name
22   * */
23   name?: string
24}

• Return type MobxBooleanValue

1interface MobxBooleanValue {
2  value: boolean
3  set: (v: boolean | ((current: boolean) => boolean)) => void
4  restore: () => void
5  setTrue: () => void
6  setFalse: () => void
7  toggle: () => void
8}

request

Extends from setter, all setter properties are available.

• Example

1import { request } from 'mobx-value'
2
3const user = request({
4  value: { name: '' },
5  request: () => Promise.resolve({ name: 'abc' }),
6})
7
8user.value.name // ''
9user.loading // false
10await user.request() // when requesting, user.loading is true
11user.loading // false
12user.value.name // 'abc'
13user.restore()
14user.value.name // ''
15
16user.request()
17user.cancel() // cancel last request
18
19// only request once
20user.request() // auto debounce
21user.request() // when last request not complete
22user.request() // new request will be debounced

• Parameters type MobxRequestOption

1interface MobxRequestOption<Data> {
2  value: Data,
3  annotation?: observable | observable.shallow
4    | observable.struct | observable.deep
5    | observable.ref | true
6  request: (args?: any) => Promise<Data>
7
8  /**
9    * set to true, prevent next request when loading, default false
10    */
11  parallel?: boolean
12
13  /**
14   * auto run restore when leave observer context
15   * @default false
16   * */
17  autoRestoreOnBecomeUnobserved?: boolean
18
19  /**
20   * alias of `autoRestoreOnBecomeUnobserved`
21   * @default false
22   * added version 1.8.0
23   * */
24  autoRestore?: boolean
25
26  /**
27   * auto cancle request when not observed and loading is not complete
28   * @default false
29   * */
30  autoCancelOnBecomeUnobserved?: boolean
31
32  /**
33   * mobx debug name
34   * */
35   name?: string
36}

• Return type MobxRequestValue

1interface MobxRequestValue<Data, Request extends (args?: any) => Promise<Data>> {
2  value: Data
3  set: (v: Data | ((current: Data) => Data)) => void
4  restore: () => void
5  request: (...args: Parameters<Request>) => CancellablePromise<Data>
6  // cancel request only when loading status
7  cancel: () => void
8  loading: boolean
9  /**
10    * request again with last parameters
11    */
12  refresh: () => CancellablePromise<Data>
13  /** get last call args */
14  getLastArgs: () => any[]
15}

lazy

extends from request, all request properties are available.

• Example

1import { lazy } from 'mobx-value'
2
3const user = lazy({ value: { name: '' }, request: () => Promise.resolve({ name: 'abc' })})
4
5// Notice，the lazy value must be in observer context, such as autorun, reaction
6// outside observer context, use lazy value will not trigger request
7autorun(() => {
8  console.log(user.value.name)
9})
10
11user.loading // default false, true when requesting data
12user.restore()
13user.value.name // ''

• Parameters type MobxLazyOption, same with MobxRequestOption

1interface MobxLazyOption<Data> {
2  value: Data,
3  annotation?: observable | observable.shallow
4    | observable.struct | observable.deep
5    | observable.ref | true
6  request: (args?: any) => Promise<Data>
7
8  /**
9   * request default prevent next request when last request is loading
10   * set to true to allow next request when loading
11   * @default false
12   * */
13  parallel?: boolean
14
15  /**
16   * auto run restore when leave observer context
17   * @default false
18   * */
19  autoRestoreOnBecomeUnobserved?: boolean
20
21  /**
22   * alias of `autoRestoreOnBecomeUnobserved`
23   * @default false
24   * added version 1.8.0
25   * */
26  autoRestore?: boolean
27
28  /**
29   * auto cancle request when not observed and loading is not complete
30   * @default false
31   * */
32  autoCancelOnBecomeUnobserved?: boolean
33
34  /**
35   * mobx debug name
36   * */
37   name?: string
38}

• Return type MobxLazyValue

1interface MobxLazyValue<Data, Request extends RequestFunction> {
2  value: Data
3  set: (v: Data | ((current: Data) => Data)) => void
4  restore: () => void
5  request: (...args: Parameters<Request>) => CancellablePromise<Data>
6  cancel: () => void
7  loading: boolean
8
9  /**
10   * status tag, do not modify it
11   * @readonly
12   */
13  requested: boolean
14  cancel(): void
15
16  /**
17   * last request ready promise
18   * when need some operate after this data is loaded
19   * use `await lazy.ready`
20   * * */
21  ready: Promise<Data>
22  refresh(): void
23
24  /**
25   * restore value also reset all request status to initial
26   * when next time it enter mobx observer context
27   * it will request again
28   * */
29  reset(): void
30}

Alias

At early version, the export method is mobxSetter, mobxBoolean, mobxRequest and mobxLazy.

From v1.1, add short alias setter, boolean, request and lazy.

setMobx

From v1.4.2, add setMobx to set mobx instance for mobx-value.

When there are more than one mobx instances work togather. Use this can manually set which should be used by mobx-value.

1import * as otherVersionMobx from 'mobx-v60'
2import { setMobx } from 'mobx-value'
3
4setMobx(otherVersionMobx)
5

Example

A good example is a better doc.

This repo source code also includes examples.

Play it with the following steps.

1git clone https://github.com/superwf/mobx-value.git
2cd mobx-value
3yarn
4yarn start

Work with React

To work with React, use observer in mobx-react-lite with React component.

1import { observer } from 'mobx-react-lite'
2import type { FC } from 'react'
3import { render } from 'react-dom'
4import { setter } from 'mobx-value'
5
6const counter = setter({
7  value: 1,
8})
9
10export const Example: FC = observer(() => (
11  <div>
12    Counter: {counter.value}
13    <button type="primary" onClick={() => counter.set(counter.value + 1)}>
14      Counter ++
15    </button>
16  </div>
17))
18
19render(<Example />, document.querySelector('#app'))

Hooks

Use useMobxValue instead wrap component with observer.

1import type { FC } from 'react'
2import { render } from 'react-dom'
3import { setter, useMobxValue } from 'mobx-value'
4
5const counter = setter({
6  value: 1,
7})
8
9export const Example: FC = () => {
10  const n = useMobxValue(counter)
11  return <div>
12    Counter: {n}
13    <button type="primary" onClick={() => counter.set(counter.value + 1)}>
14      Counter ++
15    </button>
16  </div>
17}
18
19render(<Example />, document.querySelector('#app'))

CDN

• Use mobx-value by from cdn, Global variable name is window.mobxValue

<script type="javascript" src="https://unpkg.com/mobx-value/dist/index.js"></script>

Build doc

BUILD.md

TODO

Something to be inproved in future.

• [] add delay time for loading debounce.