mobx-value

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

Usage no npm install needed!

<script type="module">
  import mobxValue from 'https://cdn.skypack.dev/mobx-value';
</script>

README

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.

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 Work with Mobx > 6.0.0.

Statements

Branches

Functions

Lines

Installation

npm install -S mobx mobx-value
// or yarn
yarn add mobx mobx-value

Api

setter

  • Example
import { setter } from 'mobx-value'

const counter = setter({ value: 1 })
counter.value // 1
counter.set(2)
counter.value // 2
counter.restore()
counter.value // 1
  • Parameters type MobxSetterOption
interface MobxSetterOption<Data> {
  value: Data,

  /**
   * mobx `makeObservable` annotation option for `value`
   * @default observable
   * */
  annotation?: observable | observable.shallow
    | observable.struct | observable.deep
    | observable.ref | true

  /**
   * auto run restore when leave observer context
   * @default false
   * */
  autoRestoreOnBecomeUnobserved?: boolean
}
  • Return type MobxSetterValue
interface MobxSetterValue<Data> {
  value: Data
  set: (v: Data) => void
  restore: () => void
}

boolean

Extends from setter, is a specifically for bool value.

  • Example
import { boolean } from 'mobx-value'

const modal = boolean()
modal.value // false
modal.setTrue() // true
modal.setFalse // false
modal.toggle() // true
modal.restore() // false
  • Parameters type MobxBooleanOption
interface MobxBooleanOption {
  /**
    * @default false
    */
  value?: boolean,

  /**
   * auto run restore when leave observer context
   * @default false
   * */
  autoRestoreOnBecomeUnobserved?: boolean
}
  • Return type MobxBooleanValue
interface MobxBooleanValue {
  value: boolean
  set: (v: boolean) => void
  restore: () => void
  setTrue: () => void
  setFalse: () => void
  toggle: () => void
}

request

Extends from setter, all setter properties are available.

  • Example
import { request } from 'mobx-value'

const user = request({
  value: { name: '' },
  request: () => Promise.resolve({ name: 'abc' }),
})

user.value.name // ''
user.loading // false
await user.request() // when requesting, user.loading is true
user.loading // false
user.value.name // 'abc'
user.restore()
user.value.name // ''

user.request()
user.cancel() // cancel last request

// only request once
user.request() // auto debounce
user.request() // when last request not complete
user.request() // new request will be debounced
  • Parameters type MobxRequestOption
interface MobxRequestOption<Data> {
  value: Data,
  annotation?: observable | observable.shallow
    | observable.struct | observable.deep
    | observable.ref | true
  request: (args?: any) => Promise<Data>

  /**
    * set to true, prevent next request when loading, default false
    */
  parallel?: boolean

  /**
   * auto run restore when leave observer context
   * @default false
   * */
  autoRestoreOnBecomeUnobserved?: boolean

  /**
   * auto cancle request when not observed and loading is not complete
   * @default false
   * */
  autoCancelOnBecomeUnobserved?: boolean
}
  • Return type MobxRequestValue
interface MobxRequestValue<Data, Request extends (args?: any) => Promise<Data>> {
  value: Data
  set: (v: Data) => void
  restore: () => void
  request: (...args: Parameters<Request>) => CancellablePromise<Data>
  // cancel request only when loading status
  cancel: () => void
  loading: boolean
  /**
    * request again with last parameters
    */
  refresh: () => CancellablePromise<Data>
}

lazy

extends from request, all request properties are available.

  • Example
import { lazy } from 'mobx-value'

const user = lazy({ value: { name: '' }, request: () => Promise.resolve({ name: 'abc' })})

// Noticeļ¼Œthe lazy value must be in observer context, such as autorun, reaction
// outside observer context, use lazy value will not trigger request
autorun(() => {
  console.log(user.value.name)
})

user.loading // default false, true when requesting data
user.restore()
user.value.name // ''
  • Parameters type MobxLazyOption, same with MobxRequestOption
interface MobxLazyOption<Data> {
  value: Data,
  annotation?: observable | observable.shallow
    | observable.struct | observable.deep
    | observable.ref | true
  request: (args?: any) => Promise<Data>

  /**
   * request default prevent next request when last request is loading
   * set to true to allow next request when loading
   * @default false
   * */
  parallel?: boolean

  /**
   * auto run restore when leave observer context
   * @default false
   * */
  autoRestoreOnBecomeUnobserved?: boolean

  /**
   * auto cancle request when not observed and loading is not complete
   * @default false
   * */
  autoCancelOnBecomeUnobserved?: boolean
}
  • Return type MobxLazyValue
interface MobxLazyValue<Data, Request extends RequestFunction> {
  value: Data
  set: (v: Data) => void
  restore: () => void
  request: (...args: Parameters<Request>) => CancellablePromise<Data>
  cancel: () => void
  loading: boolean

  /**
   * status tag, do not modify it
   * @readonly
   */
  requested: boolean
  cancel(): void

  /**
   * last request ready promise
   * when need some operate after this data is loaded
   * use `await lazy.ready`
   * * */
  ready: Promise<Data>
  refresh(): void

  /**
   * restore value also reset all request status to initial
   * when next time it enter mobx observer context
   * it will request again
   * */
  reset(): void
}

Alias

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

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

Example

A good example is a better doc.

This repo source code also includes examples.

Play it with the following steps.

git clone https://github.com/superwf/mobx-value.git
cd mobx-value
yarn
yarn start

Work with React

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

import { observer } from 'mobx-react-lite'
import type { FC } from 'react'
import { render } from 'react-dom'
import { setter } from 'mobx-value'

const counter = setter({
  value: 1,
})

export const Example: FC = observer(() => (
  <div>
    Counter: {counter.value}
    <button type="primary" onClick={() => counter.set(counter.value + 1)}>
      Counter ++
    </button>
  </div>
))

render(<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 optional name parameter, to show debug information.

  • [] add delay time for loading debounce.